ultravisor 1.0.25 → 1.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.25",
+    "version": "1.0.26",
     "description": "Cyclic process execution with ai integration.",
     "main": "source/Ultravisor.cjs",
     "bin": {
@@ -29,20 +29,20 @@
     "dependencies": {
         "better-sqlite3": "^11.10.0",
         "cron": "^4.4.0",
-        "orator": "^6.0.4",
-        "orator-authentication": "^1.0.0",
+        "orator": "^6.1.0",
+        "orator-authentication": "^1.0.1",
         "orator-serviceserver-restify": "^2.0.10",
-        "pict": "^1.0.363",
+        "pict": "^1.0.365",
         "pict-service-commandlineutility": "^1.0.19",
         "pict-serviceproviderbase": "^1.0.4",
-        "ultravisor-beacon": "^0.0.11",
+        "ultravisor-beacon": "^0.0.13",
         "ultravisor-file-stream": "^0.0.1",
         "ws": "^8.20.0"
     },
     "devDependencies": {
         "pict-docuserve": "^0.1.5",
         "puppeteer": "^24.40.0",
-        "quackage": "^1.1.0"
+        "quackage": "^1.1.2"
     },
     "mocha": {
         "diff": true,

package/source/cli/Ultravisor-CLIProgram.cjs

@@ -18,7 +18,12 @@ const libServiceExecutionManifest = require('../services/Ultravisor-ExecutionMan
 const libServiceBeaconCoordinator = require('../services/Ultravisor-Beacon-Coordinator.cjs');
 const libServiceBeaconReachability = require('../services/Ultravisor-Beacon-Reachability.cjs');
 const libServiceBeaconQueueJournal = require('../services/persistence/Ultravisor-Beacon-QueueJournal.cjs');
+const libServiceBeaconQueueStore = require('../services/persistence/Ultravisor-Beacon-QueueStore.cjs');
+const libServiceBeaconScheduler = require('../services/Ultravisor-Beacon-Scheduler.cjs');
 const libServiceBeaconFleetStore = require('../services/persistence/Ultravisor-Beacon-FleetStore.cjs');
+const libServiceAuthBeaconBridge = require('../services/Ultravisor-AuthBeaconBridge.cjs');
+const libServiceQueuePersistenceBridge = require('../services/Ultravisor-QueuePersistenceBridge.cjs');
+const libServiceManifestStoreBridge = require('../services/Ultravisor-ManifestStoreBridge.cjs');
 const libServiceDirectoryDistributor = require('../services/Ultravisor-DirectoryDistributor.cjs');
 const libServiceFleetManager = require('../services/Ultravisor-FleetManager.cjs');
 
@@ -210,6 +215,19 @@ if (tmpQueueJournal)
 	tmpQueueJournal.initialize(_Ultravisor_Pict.fable.settings.UltravisorFileStorePath);
 }
 
+// --- Beacon queue store (SQLite-backed history + per-item events) ---
+// Distinct from the journal above: the journal is a write-ahead log for
+// crash recovery of the in-flight queue; the store is a long-lived
+// SQLite database that backs the /queue UI's history list and the
+// /Beacon/Work/:hash/Events endpoint. Both can coexist — they were
+// added in separate generations of the queue work.
+_Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists('UltravisorBeaconQueueStore', libServiceBeaconQueueStore);
+let tmpQueueStore = Object.values(_Ultravisor_Pict.fable.servicesMap['UltravisorBeaconQueueStore'])[0];
+if (tmpQueueStore)
+{
+	tmpQueueStore.initialize(_Ultravisor_Pict.fable.settings.UltravisorFileStorePath);
+}
+
 // Restore persisted work queue from journal (if any)
 let tmpCoordinator = Object.values(_Ultravisor_Pict.fable.servicesMap['UltravisorBeaconCoordinator'])[0];
 if (tmpCoordinator)
@@ -233,8 +251,52 @@ _Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists(
 _Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists(
 	'UltravisorFleetManager', libServiceFleetManager);
 
+// --- Beacon scheduler (queue.* topic broadcasts + dispatch tick) ---
+// The scheduler must exist before the APIServer wires its broadcast
+// handler — see Ultravisor-API-Server._initializeWebSocket where it
+// calls scheduler.setBroadcastHandler(...). After APIServer is up,
+// we kick off the dispatch/health/summary timers via .start().
+_Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists(
+	'UltravisorBeaconScheduler', libServiceBeaconScheduler);
+
+// --- Auth beacon bridge (consults the optional Authentication-capable
+// beacon for session validation + non-promiscuous mode admission). The
+// bridge is always installed; it just resolves to "not available" when
+// no auth beacon is connected, so the rest of the hub keeps working
+// without it. See source/services/Ultravisor-AuthBeaconBridge.cjs and
+// the matching ultravisor-auth-beacon module under modules/apps/.
+_Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists(
+	'UltravisorAuthBeaconBridge', libServiceAuthBeaconBridge);
+
+// --- Queue persistence bridge (consults the optional QueuePersistence
+// beacon for durable queue + event log storage). Like the auth bridge,
+// it's always installed and falls back to the in-process
+// UltravisorBeaconQueueStore when no beacon is connected. The
+// coordinator + scheduler call into the bridge for every persistence
+// op; switching to a beacon-backed backend is a runtime decision.
+_Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists(
+	'UltravisorQueuePersistenceBridge', libServiceQueuePersistenceBridge);
+
+// --- Manifest store bridge (consults the optional ManifestStore
+// beacon for durable execution-manifest storage). Same shape as the
+// queue bridge: always installed, falls back to the in-process
+// UltravisorExecutionManifest service when no beacon is connected.
+// Persistence calls (finalizeExecution, abandonRun) go through this
+// bridge instead of directly writing JSON files.
+_Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists(
+	'UltravisorManifestStoreBridge', libServiceManifestStoreBridge);
+
 _Ultravisor_Pict.fable.addAndInstantiateServiceTypeIfNotExists('UltravisorAPIServer', libWebServerAPIServer);
 
+// Kick the scheduler timers AFTER the API server has wired
+// setBroadcastHandler — otherwise the first summary tick has nowhere
+// to fan out to and is silently dropped.
+let tmpScheduler = Object.values(_Ultravisor_Pict.fable.servicesMap['UltravisorBeaconScheduler'])[0];
+if (tmpScheduler && typeof tmpScheduler.start === 'function')
+{
+	tmpScheduler.start();
+}
+
 // ── Service name aliases ────────────────────────────────
 // Some CLI commands access services by hyphenated names via this.fable['Name'].
 // Bridge the camelCase registration to hyphenated access.

package/source/config/Ultravisor-Default-Command-Configuration.cjs

@@ -16,5 +16,13 @@ module.exports = (
 		"UltravisorBeaconWorkItemTimeoutMs": 300000,
 		"UltravisorBeaconAffinityTTLMs": 3600000,
 		"UltravisorBeaconPollIntervalMs": 5000,
-		"UltravisorBeaconJournalCompactThreshold": 500
+		"UltravisorBeaconJournalCompactThreshold": 500,
+
+		// Optional non-promiscuous mode. When true, every BeaconRegister
+		// must present a JoinSecret that either (a) matches the bootstrap
+		// secret below, for the auth beacon's own admission, or (b) is
+		// validated by the auth beacon's AUTH_ValidateBeaconJoin action.
+		// Default false → behavior identical to pre-auth-beacon ultravisor.
+		"UltravisorNonPromiscuous": false,
+		"UltravisorBootstrapAuthSecret": ""
 	});

package/source/persistence/UltravisorPersistenceSchema.json

@@ -0,0 +1,240 @@
+{
+	"_comment": "Ultravisor persistence schema — source of truth for the four tables used when ultravisor's QueuePersistenceBridge / ManifestStoreBridge route through retold-databeacon's MeadowProxy. See modules/apps/ultravisor/docs/features/persistence-via-databeacon.md for the architectural context.",
+
+	"SchemaName": "ultravisor",
+	"Version": 1,
+
+	"Tables":
+	[
+		{
+			"Scope": "UVQueueWorkItem",
+			"DefaultIdentifier": "IDUVQueueWorkItem",
+			"Domain": "Ultravisor",
+			"Schema":
+			[
+				{ "Column": "IDUVQueueWorkItem", "Type": "AutoIdentity", "Size": "Default" },
+				{ "Column": "WorkItemHash",      "Type": "String",       "Size": "128" },
+				{ "Column": "RunID",             "Type": "String",       "Size": "128" },
+				{ "Column": "RunHash",           "Type": "String",       "Size": "128" },
+				{ "Column": "NodeHash",          "Type": "String",       "Size": "128" },
+				{ "Column": "OperationHash",    "Type": "String",       "Size": "128" },
+				{ "Column": "Capability",        "Type": "String",       "Size": "128" },
+				{ "Column": "Action",            "Type": "String",       "Size": "128" },
+				{ "Column": "Settings",          "Type": "String",       "Size": "Default" },
+				{ "Column": "AffinityKey",       "Type": "String",       "Size": "128" },
+				{ "Column": "AssignedBeaconID",  "Type": "String",       "Size": "128" },
+				{ "Column": "Status",            "Type": "String",       "Size": "32" },
+				{ "Column": "Priority",          "Type": "Integer",      "Size": "int" },
+				{ "Column": "EnqueuedAt",        "Type": "String",       "Size": "50" },
+				{ "Column": "DispatchedAt",      "Type": "String",       "Size": "50" },
+				{ "Column": "StartedAt",         "Type": "String",       "Size": "50" },
+				{ "Column": "ClaimedAt",         "Type": "String",       "Size": "50" },
+				{ "Column": "CompletedAt",       "Type": "String",       "Size": "50" },
+				{ "Column": "CanceledAt",        "Type": "String",       "Size": "50" },
+				{ "Column": "AssignedAt",        "Type": "String",       "Size": "50" },
+				{ "Column": "LastEventAt",       "Type": "String",       "Size": "50" },
+				{ "Column": "QueueWaitMs",       "Type": "Integer",      "Size": "int" },
+				{ "Column": "TimeoutMs",         "Type": "Integer",      "Size": "int" },
+				{ "Column": "Health",            "Type": "Float",        "Size": "Default" },
+				{ "Column": "HealthLabel",       "Type": "String",       "Size": "32" },
+				{ "Column": "HealthReason",      "Type": "String",       "Size": "512" },
+				{ "Column": "HealthComputedAt",  "Type": "String",       "Size": "50" },
+				{ "Column": "AttemptNumber",     "Type": "Integer",      "Size": "int" },
+				{ "Column": "MaxAttempts",       "Type": "Integer",      "Size": "int" },
+				{ "Column": "RetryBackoffMs",    "Type": "Integer",      "Size": "int" },
+				{ "Column": "RetryAfter",        "Type": "String",       "Size": "50" },
+				{ "Column": "LastError",         "Type": "String",       "Size": "Default" },
+				{ "Column": "Result",            "Type": "String",       "Size": "Default" },
+				{ "Column": "CancelRequested",   "Type": "Boolean",      "Size": "Default" },
+				{ "Column": "CancelReason",      "Type": "String",       "Size": "512" },
+				{ "Column": "CreateDate",        "Type": "CreateDate",   "Size": "Default" },
+				{ "Column": "UpdateDate",        "Type": "UpdateDate",   "Size": "Default" },
+				{ "Column": "Deleted",           "Type": "Deleted",      "Size": "Default" }
+			],
+			"DefaultObject":
+			{
+				"IDUVQueueWorkItem": 0,
+				"WorkItemHash": "",
+				"RunID": "",
+				"RunHash": "",
+				"NodeHash": "",
+				"OperationHash": "",
+				"Capability": "",
+				"Action": "",
+				"Settings": "{}",
+				"AffinityKey": "",
+				"AssignedBeaconID": "",
+				"Status": "Pending",
+				"Priority": 0,
+				"EnqueuedAt": "",
+				"DispatchedAt": "",
+				"StartedAt": "",
+				"ClaimedAt": "",
+				"CompletedAt": "",
+				"CanceledAt": "",
+				"AssignedAt": "",
+				"LastEventAt": "",
+				"QueueWaitMs": 0,
+				"TimeoutMs": 0,
+				"Health": 0,
+				"HealthLabel": "Unknown",
+				"HealthReason": "",
+				"HealthComputedAt": "",
+				"AttemptNumber": 0,
+				"MaxAttempts": 1,
+				"RetryBackoffMs": 0,
+				"RetryAfter": "",
+				"LastError": "",
+				"Result": "",
+				"CancelRequested": false,
+				"CancelReason": "",
+				"Deleted": false
+			},
+			"Indexes":
+			[
+				{ "Name": "IX_UVQueueWorkItem_Hash",      "Columns": ["WorkItemHash"], "Unique": true },
+				{ "Name": "IX_UVQueueWorkItem_Status",    "Columns": ["Status"] },
+				{ "Name": "IX_UVQueueWorkItem_RunID",     "Columns": ["RunID"] },
+				{ "Name": "IX_UVQueueWorkItem_Assigned",  "Columns": ["AssignedBeaconID", "Status"] },
+				{ "Name": "IX_UVQueueWorkItem_Dispatch",  "Columns": ["Status", "Priority", "EnqueuedAt"] }
+			]
+		},
+
+		{
+			"Scope": "UVQueueWorkItemEvent",
+			"DefaultIdentifier": "IDUVQueueWorkItemEvent",
+			"Domain": "Ultravisor",
+			"_comment": "Append-only event log per work item. EventGUID is unique for idempotency on bootstrap-flush replay.",
+			"Schema":
+			[
+				{ "Column": "IDUVQueueWorkItemEvent", "Type": "AutoIdentity", "Size": "Default" },
+				{ "Column": "EventGUID",             "Type": "String",       "Size": "36" },
+				{ "Column": "WorkItemHash",          "Type": "String",       "Size": "128" },
+				{ "Column": "EventType",             "Type": "String",       "Size": "64" },
+				{ "Column": "Payload",               "Type": "String",       "Size": "Default" },
+				{ "Column": "EmittedAt",             "Type": "String",       "Size": "50" },
+				{ "Column": "Seq",                   "Type": "Integer",      "Size": "int" },
+				{ "Column": "FromStatus",            "Type": "String",       "Size": "32" },
+				{ "Column": "ToStatus",              "Type": "String",       "Size": "32" },
+				{ "Column": "BeaconID",              "Type": "String",       "Size": "128" },
+				{ "Column": "CreateDate",            "Type": "CreateDate",   "Size": "Default" },
+				{ "Column": "Deleted",               "Type": "Deleted",      "Size": "Default" }
+			],
+			"DefaultObject":
+			{
+				"IDUVQueueWorkItemEvent": 0,
+				"EventGUID": "",
+				"WorkItemHash": "",
+				"EventType": "",
+				"Payload": "{}",
+				"EmittedAt": "",
+				"Seq": 0,
+				"FromStatus": "",
+				"ToStatus": "",
+				"BeaconID": "",
+				"Deleted": false
+			},
+			"Indexes":
+			[
+				{ "Name": "IX_UVQueueEvent_GUID", "Columns": ["EventGUID"], "Unique": true },
+				{ "Name": "IX_UVQueueEvent_Hash", "Columns": ["WorkItemHash"] }
+			]
+		},
+
+		{
+			"Scope": "UVQueueWorkItemAttempt",
+			"DefaultIdentifier": "IDUVQueueWorkItemAttempt",
+			"Domain": "Ultravisor",
+			"_comment": "One row per dispatch attempt. (WorkItemHash, AttemptNumber) is unique.",
+			"Schema":
+			[
+				{ "Column": "IDUVQueueWorkItemAttempt", "Type": "AutoIdentity", "Size": "Default" },
+				{ "Column": "WorkItemHash",            "Type": "String",       "Size": "128" },
+				{ "Column": "AttemptNumber",            "Type": "Integer",      "Size": "int" },
+				{ "Column": "BeaconID",                 "Type": "String",       "Size": "128" },
+				{ "Column": "StartedAt",                "Type": "String",       "Size": "50" },
+				{ "Column": "EndedAt",                  "Type": "String",       "Size": "50" },
+				{ "Column": "Outcome",                  "Type": "String",       "Size": "32" },
+				{ "Column": "Error",                    "Type": "String",       "Size": "Default" },
+				{ "Column": "CreateDate",               "Type": "CreateDate",   "Size": "Default" },
+				{ "Column": "Deleted",                  "Type": "Deleted",      "Size": "Default" }
+			],
+			"DefaultObject":
+			{
+				"IDUVQueueWorkItemAttempt": 0,
+				"WorkItemHash": "",
+				"AttemptNumber": 0,
+				"BeaconID": "",
+				"StartedAt": "",
+				"EndedAt": "",
+				"Outcome": "",
+				"Error": "",
+				"Deleted": false
+			},
+			"Indexes":
+			[
+				{ "Name": "IX_UVQueueAttempt_HashNum", "Columns": ["WorkItemHash", "AttemptNumber"], "Unique": true }
+			]
+		},
+
+		{
+			"Scope": "UVManifest",
+			"DefaultIdentifier": "IDUVManifest",
+			"Domain": "Ultravisor",
+			"_comment": "Execution manifests, one row per run. ManifestJSON is the full wire-safe blob produced by _cleanManifestForWire.",
+			"Schema":
+			[
+				{ "Column": "IDUVManifest",     "Type": "AutoIdentity", "Size": "Default" },
+				{ "Column": "Hash",             "Type": "String",       "Size": "128" },
+				{ "Column": "OperationHash",    "Type": "String",       "Size": "128" },
+				{ "Column": "OperationName",    "Type": "String",       "Size": "500" },
+				{ "Column": "Status",           "Type": "String",       "Size": "32" },
+				{ "Column": "RunMode",          "Type": "String",       "Size": "32" },
+				{ "Column": "Live",             "Type": "Boolean",      "Size": "Default" },
+				{ "Column": "StartTime",        "Type": "String",       "Size": "50" },
+				{ "Column": "StopTime",         "Type": "String",       "Size": "50" },
+				{ "Column": "ElapsedMs",        "Type": "Integer",      "Size": "int" },
+				{ "Column": "ManifestJSON",     "Type": "String",       "Size": "Default" },
+				{ "Column": "StagingPath",      "Type": "String",       "Size": "1024" },
+				{ "Column": "CreateDate",       "Type": "CreateDate",   "Size": "Default" },
+				{ "Column": "UpdateDate",       "Type": "UpdateDate",   "Size": "Default" },
+				{ "Column": "Deleted",          "Type": "Deleted",      "Size": "Default" }
+			],
+			"DefaultObject":
+			{
+				"IDUVManifest": 0,
+				"Hash": "",
+				"OperationHash": "",
+				"OperationName": "",
+				"Status": "",
+				"RunMode": "",
+				"Live": false,
+				"StartTime": "",
+				"StopTime": "",
+				"ElapsedMs": 0,
+				"ManifestJSON": "{}",
+				"StagingPath": "",
+				"Deleted": false
+			},
+			"Indexes":
+			[
+				{ "Name": "IX_UVManifest_Hash",      "Columns": ["Hash"], "Unique": true },
+				{ "Name": "IX_UVManifest_StatusStop","Columns": ["Status", "StopTime"] },
+				{ "Name": "IX_UVManifest_OpHash",    "Columns": ["OperationHash"] }
+			]
+		}
+	],
+
+	"_notes":
+	{
+		"meadowConventions": "Type values follow meadow column conventions. AutoIdentity → engine PK; CreateDate / UpdateDate / Deleted → meadow's auto-managed audit columns. The per-engine Meadow-Schema-<engine>.js files translate these to engine-specific DDL.",
+
+		"indexes": "Indexes here are NOT part of meadow's standard table descriptor. retold-databeacon's EnsureSchema action will issue them as CREATE INDEX IF NOT EXISTS statements after the meadow table create. Per-engine syntax differences (e.g. SQL Server's CREATE INDEX vs Postgres's CREATE INDEX IF NOT EXISTS) handled in the engine-specific path.",
+
+		"jsonColumns": "Settings (work item), Payload (event), Result, LastError, ManifestJSON are stored as opaque strings (JSON-encoded by callers). We don't use a native JSON column type because not all meadow connectors support it uniformly (mssql JSON support varies; sqlite has none). Callers are responsible for parse/stringify on the boundary.",
+
+		"floatColumns": "Health is stored as Float (0..1 score). Connector translation: REAL on sqlite, DOUBLE on mysql/postgres, FLOAT on mssql.",
+
+		"softDelete": "Deleted column matches meadow's standard soft-delete convention. The bridges' `removeManifest` etc. flip Deleted=1 rather than DROP. Hard-delete deferred to a separate retention sweep."
+	}
+}

package/source/services/Ultravisor-AuthBeaconBridge.cjs

@@ -0,0 +1,271 @@
+/**
+ * Ultravisor-AuthBeaconBridge
+ *
+ * Talks to whichever beacon advertises the `Authentication` capability
+ * via dispatchAndWait, presents a clean async surface to the rest of
+ * the hub. The bridge is the only thing that knows the auth beacon
+ * exists — every other call site (API server, coordinator non-
+ * promiscuous mode) just asks the bridge "is this session valid?"
+ * or "is this beacon allowed to join?" and gets a Promise back.
+ *
+ * Design notes
+ * ============
+ * - The bridge has NO local cache. Sessions are short-lived and
+ *   security-sensitive; caching invalidation here is more dangerous
+ *   than the extra dispatch cost. If the auth beacon becomes a
+ *   bottleneck, that's where caching should land — it owns the
+ *   lifecycle.
+ *
+ * - The bridge is OPTIONAL — when the coordinator can't find an auth
+ *   beacon, methods resolve with `{Available:false, ...}` and the
+ *   caller decides how to proceed (typically: fail-closed in non-
+ *   promiscuous mode, fall back to legacy auth in promiscuous mode).
+ *
+ * - Bridge methods all return Promises (not callbacks) because they're
+ *   meant to be awaited in async route handlers and middleware. The
+ *   underlying coordinator.dispatchAndWait is callback-based, so we
+ *   wrap it once here.
+ */
+
+const libPictService = require('pict-serviceproviderbase');
+
+// Default bridge dispatch timeout. Authentication should be FAST —
+// password hashing + DB lookup measured in single-digit ms, session
+// validation usually a Map.get(). 5s is generous.
+const DEFAULT_BRIDGE_TIMEOUT_MS = 5000;
+
+class UltravisorAuthBeaconBridge extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+		this.serviceType = 'UltravisorAuthBeaconBridge';
+		this._TimeoutMs = (pOptions && pOptions.TimeoutMs) || DEFAULT_BRIDGE_TIMEOUT_MS;
+	}
+
+	/**
+	 * Look up the BeaconID currently advertising the Authentication
+	 * capability. Returns null when no auth beacon is connected.
+	 *
+	 * If multiple beacons advertise Authentication, the FIRST one is
+	 * returned — for now we don't elect a primary. A future enhancement
+	 * could weight by tags (e.g., Tags.Role==='auth' wins).
+	 */
+	getAuthBeaconID()
+	{
+		let tmpCoord = this._coord();
+		if (!tmpCoord) return null;
+		let tmpBeacons = tmpCoord.listBeacons() || [];
+		for (let i = 0; i < tmpBeacons.length; i++)
+		{
+			let tmpCaps = tmpBeacons[i].Capabilities || [];
+			if (tmpCaps.indexOf('Authentication') >= 0)
+			{
+				return tmpBeacons[i].BeaconID;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * @returns {boolean} true iff some beacon claims Authentication
+	 */
+	isAvailable()
+	{
+		return this.getAuthBeaconID() !== null;
+	}
+
+	/**
+	 * Run a Login on the auth beacon. Returns the auth beacon's
+	 * Outputs unchanged so callers can read SessionToken / UserContext
+	 * / ExpiresAt directly.
+	 */
+	login(pUsername, pPassword, pMethod)
+	{
+		return this._dispatchAuthAction('AUTH_Login',
+		{
+			Username: pUsername,
+			Password: pPassword,
+			Method: pMethod || 'password'
+		});
+	}
+
+	validateSession(pSessionToken)
+	{
+		return this._dispatchAuthAction('AUTH_ValidateSession',
+		{
+			SessionToken: pSessionToken || ''
+		});
+	}
+
+	logout(pSessionToken)
+	{
+		return this._dispatchAuthAction('AUTH_Logout',
+		{
+			SessionToken: pSessionToken || ''
+		});
+	}
+
+	authorizeAction(pSessionToken, pCapability, pAction)
+	{
+		return this._dispatchAuthAction('AUTH_AuthorizeAction',
+		{
+			SessionToken: pSessionToken || '',
+			Capability: pCapability || '',
+			Action: pAction || ''
+		});
+	}
+
+	validateBeaconJoin(pBeaconName, pJoinSecret, pBeaconCapabilities)
+	{
+		return this._dispatchAuthAction('AUTH_ValidateBeaconJoin',
+		{
+			BeaconName: pBeaconName || '',
+			JoinSecret: pJoinSecret || '',
+			Capabilities: Array.isArray(pBeaconCapabilities) ? pBeaconCapabilities : []
+		});
+	}
+
+	/**
+	 * Generic dispatch — for callers (e.g. the orator-authentication
+	 * Beacon provider) that want to forward an arbitrary AUTH_* action
+	 * without one of the named convenience methods above. Same return
+	 * shape as the rest of the bridge: a Promise resolving to
+	 * `{Available, ...Outputs}` (or `{Available:false, Reason}` if the
+	 * auth beacon isn't reachable).
+	 */
+	dispatchAction(pAction, pSettings)
+	{
+		return this._dispatchAuthAction(pAction, pSettings || {});
+	}
+
+	// ============== User management ==============
+	//
+	// Convenience wrappers around the AUTH_*User actions. Authorization
+	// is the caller's job — these dispatch unconditionally; protect the
+	// HTTP routes (or whatever surface invokes them) with a session +
+	// role check before letting them through.
+
+	listUsers(pSelector)
+	{
+		return this._dispatchAuthAction('AUTH_ListUsers', { Selector: pSelector || null });
+	}
+
+	getUser(pUserID)
+	{
+		return this._dispatchAuthAction('AUTH_GetUser', { UserID: pUserID });
+	}
+
+	createUser(pUserSpec)
+	{
+		return this._dispatchAuthAction('AUTH_CreateUser', { UserSpec: pUserSpec || {} });
+	}
+
+	updateUser(pUserID, pUpdates)
+	{
+		return this._dispatchAuthAction('AUTH_UpdateUser',
+			{ UserID: pUserID, Updates: pUpdates || {} });
+	}
+
+	deleteUser(pUserID)
+	{
+		return this._dispatchAuthAction('AUTH_DeleteUser', { UserID: pUserID });
+	}
+
+	setUserPassword(pUserID, pNewPassword)
+	{
+		return this._dispatchAuthAction('AUTH_SetUserPassword',
+			{ UserID: pUserID, NewPassword: pNewPassword });
+	}
+
+	changePassword(pUserID, pCurrentPassword, pNewPassword)
+	{
+		return this._dispatchAuthAction('AUTH_ChangePassword',
+		{
+			UserID: pUserID,
+			CurrentPassword: pCurrentPassword,
+			NewPassword: pNewPassword
+		});
+	}
+
+	/**
+	 * One-time admin bootstrap. Dispatches AUTH_BootstrapAdmin to the
+	 * auth beacon, which validates the token and creates the admin user
+	 * atomically. Intentionally NOT gated by an admin session — that
+	 * would be a chicken-and-egg problem (no admin exists yet to
+	 * authenticate). The auth beacon's bootstrap token IS the auth.
+	 */
+	bootstrapAdmin(pToken, pUserSpec)
+	{
+		return this._dispatchAuthAction('AUTH_BootstrapAdmin',
+		{
+			Token: pToken,
+			UserSpec: pUserSpec || {}
+		});
+	}
+
+	// ============== Internals ==============
+
+	_coord()
+	{
+		// Resolve lazily — the coordinator can be added/replaced after
+		// the bridge is constructed.
+		let tmpMap = this.fable && this.fable.servicesMap
+			&& this.fable.servicesMap['UltravisorBeaconCoordinator'];
+		return tmpMap ? Object.values(tmpMap)[0] : null;
+	}
+
+	_dispatchAuthAction(pActionName, pSettings)
+	{
+		return new Promise((fResolve) =>
+		{
+			let tmpCoord = this._coord();
+			if (!tmpCoord)
+			{
+				return fResolve(
+				{
+					Available: false,
+					Reason: 'BeaconCoordinator not available'
+				});
+			}
+			let tmpAuthID = this.getAuthBeaconID();
+			if (!tmpAuthID)
+			{
+				return fResolve(
+				{
+					Available: false,
+					Reason: 'No beacon currently advertises Authentication'
+				});
+			}
+			tmpCoord.dispatchAndWait(
+			{
+				Capability: 'Authentication',
+				Action: pActionName,
+				Settings: pSettings,
+				AffinityKey: 'auth',                 // single auth beacon at a time
+				TimeoutMs: this._TimeoutMs
+			},
+			(pError, pResult) =>
+			{
+				if (pError)
+				{
+					return fResolve(
+					{
+						Available: true,
+						Error: pError.message || String(pError),
+						// Surface a sane default — most callers want a
+						// boolean Allowed/Valid/Success they can branch on.
+						Allowed: false, Valid: false, Success: false
+					});
+				}
+				// pResult.Outputs is the action's response payload.
+				// Tag Available:true so callers can distinguish "auth
+				// beacon answered no" from "auth beacon not reachable."
+				let tmpOut = (pResult && pResult.Outputs) || {};
+				return fResolve(Object.assign({ Available: true }, tmpOut));
+			});
+		});
+	}
+}
+
+module.exports = UltravisorAuthBeaconBridge;