ultravisor 1.0.23 → 1.0.24

package/docs/queue-followups/03-config-migration.md

@@ -0,0 +1,123 @@
+# Follow-up: Migrate per-action config into `BeaconActionDefault`
+
+**Status:** deferred — table and service are live; rows need populating.
+
+## Why this exists
+
+Per-action defaults (timeout, retry policy, priority, expected-wait
+baseline) live in scattered Fable settings today. The queueing work
+introduced a durable `BeaconActionDefault` table and a resolver
+([`Ultravisor-Beacon-ActionDefaults.cjs`](../../source/services/Ultravisor-Beacon-ActionDefaults.cjs))
+that an operator can tune live, without a hub restart.
+
+The resolver already falls back in this order:
+
+1. Per-request `Settings` override (`maxRetries`, `timeoutMs`, etc.)
+2. Per-action row (`Capability`, `Action`)
+3. Per-capability wildcard row (`Capability`, `Action=""`)
+4. Fable-setting compatibility shim
+   (`UltravisorBeaconWorkItemTimeoutMs`,
+   `UltravisorBeaconHeartbeatMs`)
+5. Hard defaults in `HARD_DEFAULTS`
+
+So today everything still works via step 4–5. This follow-up replaces
+the shim with real rows and retires the Fable settings.
+
+## What's in the table today
+
+Schema at [`Ultravisor-BeaconQueue.json`](../../source/datamodel/Ultravisor-BeaconQueue.json)
+(the `BeaconActionDefault` entry). Columns:
+
+| Column | Notes |
+|---|---|
+| `Capability` | required |
+| `Action` | `""` = wildcard for the capability |
+| `TimeoutMs` | overrides `UltravisorBeaconWorkItemTimeoutMs` |
+| `MaxAttempts` | 1 = no retry |
+| `RetryBackoffMs` | multiplied by attempt number |
+| `DefaultPriority` | scheduler sort key |
+| `ExpectedWaitP95Ms` | powers the `queue_wait` dimension of the health score |
+| `HeartbeatExpectedMs` | powers the `event_freshness` dimension |
+| `MinSamplesForBaseline` | min samples before `ActionDefaults.recomputeWaitBaseline` commits a p95 |
+
+## Work to do
+
+### 1. Inventory today's scattered settings
+
+Grep the ultravisor tree for the settings that currently drive
+per-action behavior:
+
+```sh
+grep -rn 'UltravisorBeaconWorkItemTimeoutMs\|UltravisorBeaconHeartbeatMs\|UltravisorBeaconAffinityTTLMs' \
+  /Users/steven/Code/retold/modules/apps/ultravisor/source
+```
+
+Also check the consumer code for per-action constants in task-type
+definitions (`source/services/tasks/**`) and capability providers
+(`source/beacon/providers/**`).
+
+### 2. Seed the table at startup
+
+Write `source/services/tasks/extension/Ultravisor-BeaconActionDefault-Seed.cjs`
+(or similar) that runs once on hub boot and upserts a row per
+(Capability, Action) pair the hub knows about. Source of truth is
+the action catalog on the coordinator
+([`Ultravisor-Beacon-Coordinator.cjs`](../../source/services/Ultravisor-Beacon-Coordinator.cjs)
+`_ActionCatalog`) — iterate it and call
+`store.upsertActionDefault({ Capability, Action, ...hard_defaults })`
+only when no row exists. Use `getActionDefault` first so operator-set
+rows aren't clobbered on every restart.
+
+The seed should **not** overwrite existing rows — it's a bootstrap,
+not a reset.
+
+### 3. Admin endpoints (optional, small)
+
+If the `/queue` UI wants live knobs, add:
+
+- `GET /Beacon/ActionDefaults` → `store.listActionDefaults()`
+- `PUT /Beacon/ActionDefaults/:Capability/:Action` → upsert
+  (call `store.upsertActionDefault` + `defaults.invalidate()`)
+
+Both gated by `_requireSession`.
+
+### 4. Wire up the wait-baseline learner
+
+`ActionDefaults.recomputeWaitBaseline(cap, action)` is implemented
+but not called anywhere yet. Trigger it on a slow interval (every 5
+minutes) from the scheduler, iterating capabilities that have seen
+≥ `MinSamplesForBaseline` completions since last recompute. Add a
+counter on the coordinator to track completions per capability so we
+don't recompute on no new data.
+
+Rough hook point: end of `UltravisorBeaconScheduler._summaryTick`, or
+a dedicated slower interval.
+
+### 5. Retire the Fable-setting shim
+
+Once (2) has been in place for at least one production cycle, remove
+the `_fableSettingFallback` in
+[`Ultravisor-Beacon-ActionDefaults.cjs`](../../source/services/Ultravisor-Beacon-ActionDefaults.cjs).
+Grep-clean the retired setting names from the codebase in the same PR
+so nobody reintroduces them. This is the step that makes the
+migration irreversible — don't do it in the same PR as the seeder.
+
+## Verification
+
+1. Wipe `~/.local/share/ultravisor/beacon/beacon-queue.sqlite` (or
+   wherever the store's DB path resolves for the deployment).
+2. Boot the hub. Confirm `BeaconActionDefault` has one row per known
+   `Capability:Action` pair with the expected defaults.
+3. `UPDATE BeaconActionDefault SET TimeoutMs = 1 WHERE Capability =
+   'Shell'`. Enqueue a Shell work item. The next
+   `BeaconActionDefaults._Cache` window (≤ 10s) flips it; next
+   work item picks up `TimeoutMs=1` without a hub restart.
+4. Run 30 Shell work items with genuinely varying queue waits; confirm
+   `ExpectedWaitP95Ms` updates on its own after the baseline learner
+   tick.
+
+## Non-goals
+
+- UI for editing action defaults (defer until the `/queue` view is
+  shipped and operators are asking for it).
+- Multi-tenant defaults (single-ultravisor-instance only).

package/docs/queue-followups/04-direct-dispatch-phase-emission.md

@@ -0,0 +1,128 @@
+# Follow-up: Phase emission for `/Beacon/Work/Dispatch` (sync path)
+
+**Status:** deferred — the synchronous dispatch path bypasses the
+scheduler and therefore never populates `Settings.QueueMetadata`.
+Workers routed via `/Beacon/Work/Dispatch` still write their own
+phases, but the hub-owned `queue_wait` / `worker_spinup` /
+`asset_capture` records are skipped.
+
+## Background
+
+There are three dispatch paths in the hub today:
+
+| Path | Route | Queue/metadata? | Phases? |
+|---|---|---|---|
+| Async queue | `POST /Beacon/Work/Enqueue` | Yes (via Scheduler) | Yes — beacon-side emits all three |
+| Polling claim | `POST /Beacon/Work/Poll` | Yes (Coordinator stamps metadata in `_sanitizeWorkItemForBeacon`) | Yes — same |
+| **Direct dispatch** | `POST /Beacon/Work/Dispatch` | **No** — calls `Coordinator.dispatchAndWait` which builds the work item inline and blocks the caller on the response | **No** — Settings.QueueMetadata is never set |
+
+The direct-dispatch path is used for synchronous RPC-style calls
+where the caller wants the result inline. It's rare but real — a
+handful of retold-labs call sites and any external integration that
+chose the sync contract for simplicity.
+
+## Why this is separate from the main work
+
+`dispatchAndWait` constructs the work item in a hot request handler
+and resolves to the caller via `_DirectDispatchCallbacks`. It
+intentionally skips the scheduler tick because the caller is
+blocked waiting. Retrofitting it requires either:
+
+1. Routing it through the same scheduler pass (adds latency — the
+   whole point of direct dispatch is "don't queue"), or
+2. Populating `QueueMetadata` inline in the Coordinator when building
+   the work item and calling the beacon-side phase emit path directly.
+
+Option 2 is correct. The queue wait for this path is near-zero by
+definition, so the `queue_wait` record will almost always be `0ms`,
+but the `worker_spinup` and `asset_capture` records still have
+real durations worth capturing.
+
+## Work to do
+
+### 1. Populate `QueueMetadata` inline in `dispatchAndWait`
+
+**File:** [`Ultravisor-Beacon-Coordinator.cjs`](../../source/services/Ultravisor-Beacon-Coordinator.cjs)
+
+Find `dispatchAndWait` (search for the method definition). Where it
+constructs the work item, set `Settings.QueueMetadata` the same way
+`_sanitizeWorkItemForBeacon` does it now, but with the sync-path
+timestamps:
+
+```javascript
+let tmpNowIso = new Date().toISOString();
+tmpWorkItem.EnqueuedAt = tmpNowIso;
+tmpWorkItem.DispatchedAt = tmpNowIso;
+tmpWorkItem.QueueWaitMs = 0;
+tmpWorkItem.AttemptNumber = 1;
+tmpWorkItem.RunID = pWorkItemInfo.RunID || '';
+tmpWorkItem.Settings = tmpWorkItem.Settings || {};
+tmpWorkItem.Settings.QueueMetadata = {
+  RunID: tmpWorkItem.RunID,
+  WorkItemHash: tmpWorkItem.WorkItemHash,
+  EnqueuedAt: tmpNowIso,
+  DispatchedAt: tmpNowIso,
+  QueueWaitMs: 0,
+  AttemptNumber: 1,
+  HubInstanceID: (this.fable.settings && this.fable.settings.UltravisorHubInstanceID) || '',
+  DispatchPath: 'sync'
+};
+```
+
+Note the extra `DispatchPath: 'sync'` marker — useful for analytics
+that want to separate sync-call latency from async-queue latency.
+
+### 2. Stream the same metadata through `DispatchStream`
+
+**File:** [`Ultravisor-API-Server.cjs`](../../source/web_server/Ultravisor-API-Server.cjs)
+
+`POST /Beacon/Work/DispatchStream` is the binary-framed variant. It
+calls the coordinator's streaming-dispatch machinery, which also
+builds a work item inline. Same fix pattern: set `QueueMetadata` on
+the work item before the first beacon frame is sent. Look for the
+method that parallels `dispatchAndWait` for streams (grep for
+`_StreamDispatchHandlers`).
+
+### 3. Add a `POST /Beacon/Work/Dispatch` body field for `RunID`
+
+The sync path doesn't call `/Beacon/Run/Start` before dispatching —
+it's a one-shot. Either:
+
+- Accept an optional `RunID` in the request body; if absent, mint one
+  on the fly via `RunManager.startRun({ SubmitterTag: 'sync' })` so
+  the sync call still lands in `BeaconRun` for observability; **or**
+- Skip run registration for sync calls entirely and emit phases with
+  `RunID=""`.
+
+The first option keeps the `/queue` UI's event stream complete. Lean
+toward (a).
+
+### 4. Accept that retold-labs capability handlers already DTRT
+
+Once (1) lands, `Settings.QueueMetadata` is populated on every work
+item regardless of dispatch path.
+[`RetoldLabs-BeaconSetup.cjs`](../../../retold-labs/source/RetoldLabs-BeaconSetup.cjs)
+already checks `pWorkItem.Settings.QueueMetadata` before emitting;
+the sync path will automatically start producing phases with no
+retold-labs changes needed.
+
+## Verification
+
+1. Issue `POST /Beacon/Work/Dispatch` with `{ Capability: "Shell",
+   Action: "Execute", Settings: { Command: "sleep 1" } }`.
+2. The response comes back synchronously (same as today).
+3. In the beacon's staging dir, the resulting `phases.jsonl`
+   contains `queue_wait` (duration ≤ 5ms), `worker_spinup`,
+   worker-emitted `run_start` / `phase` / `run_end`, and
+   `asset_capture`.
+4. The `BeaconRun` table has a new row with `SubmitterTag='sync'`.
+5. The `BeaconWorkItemEvent` table has the `dispatched` event
+   with `Payload.Path='sync'` (add this marker in step 1 if you want
+   to separate it from poll-path dispatches in analytics).
+
+## Non-goals
+
+- Retrofitting existing direct-dispatch callers to switch to async
+  enqueue. Sync contracts exist for a reason — let callers choose.
+- Differentiating `queue_wait` reason for sync vs. async in the UI.
+  0ms queue waits tell the right story on their own.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.23",
+    "version": "1.0.24",
     "description": "Cyclic process execution with ai integration.",
     "main": "source/Ultravisor.cjs",
     "bin": {
@@ -27,6 +27,7 @@
     },
     "homepage": "https://github.com/stevenvelozo/ultravisor#readme",
     "dependencies": {
+        "better-sqlite3": "^11.10.0",
         "cron": "^4.4.0",
         "orator": "^6.0.4",
         "orator-authentication": "^1.0.0",
@@ -35,6 +36,7 @@
         "pict-service-commandlineutility": "^1.0.19",
         "pict-serviceproviderbase": "^1.0.4",
         "ultravisor-beacon": "^0.0.11",
+        "ultravisor-file-stream": "^0.0.1",
         "ws": "^8.20.0"
     },
     "devDependencies": {

package/source/Ultravisor.cjs

@@ -8,6 +8,10 @@ module.exports = (
 		HypervisorState: require('./services/Ultravisor-Hypervisor-State.cjs'),
 		Hypervisor: require('./services/Ultravisor-Hypervisor.cjs'),
 		BeaconCoordinator: require('./services/Ultravisor-Beacon-Coordinator.cjs'),
+		BeaconQueueStore: require('./services/persistence/Ultravisor-Beacon-QueueStore.cjs'),
+		BeaconRunManager: require('./services/Ultravisor-Beacon-RunManager.cjs'),
+		BeaconActionDefaults: require('./services/Ultravisor-Beacon-ActionDefaults.cjs'),
+		BeaconScheduler: require('./services/Ultravisor-Beacon-Scheduler.cjs'),
 		BeaconService: require('ultravisor-beacon'),
 		BeaconCapabilityProvider: require('ultravisor-beacon/source/Ultravisor-Beacon-CapabilityProvider.cjs'),
 		BeaconProviderRegistry: require('ultravisor-beacon/source/Ultravisor-Beacon-ProviderRegistry.cjs'),

package/source/datamodel/Ultravisor-BeaconQueue.json

@@ -0,0 +1,165 @@
+{
+	"Tables":
+	{
+		"BeaconRun":
+		{
+			"TableName": "BeaconRun",
+			"Domain": "Default",
+			"Description": "Hub-owned run lifecycle record. One row per submitter-visible run; work items link back via RunID.",
+			"Columns":
+			[
+				{ "Column": "IDBeaconRun", "DataType": "ID" },
+				{ "Column": "GUIDBeaconRun", "DataType": "GUID", "Size": "36" },
+				{ "Column": "CreateDate", "DataType": "DateTime" },
+				{ "Column": "CreatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "UpdateDate", "DataType": "DateTime" },
+				{ "Column": "UpdatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "Deleted", "DataType": "Boolean" },
+				{ "Column": "DeleteDate", "DataType": "DateTime" },
+				{ "Column": "DeletingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "RunID", "DataType": "String", "Size": "128" },
+				{ "Column": "IdempotencyKey", "DataType": "String", "Size": "256" },
+				{ "Column": "SubmitterTag", "DataType": "String", "Size": "256" },
+				{ "Column": "State", "DataType": "String", "Size": "32" },
+				{ "Column": "StartedAt", "DataType": "DateTime" },
+				{ "Column": "EndedAt", "DataType": "DateTime" },
+				{ "Column": "CanceledAt", "DataType": "DateTime" },
+				{ "Column": "CancelReason", "DataType": "String", "Size": "512" },
+				{ "Column": "Metadata", "DataType": "String", "Size": "8192" }
+			]
+		},
+		"BeaconWorkItem":
+		{
+			"TableName": "BeaconWorkItem",
+			"Domain": "Default",
+			"Description": "Mutable work item state — one row per dispatchable unit of work. Event history lives in BeaconWorkItemEvent.",
+			"Columns":
+			[
+				{ "Column": "IDBeaconWorkItem", "DataType": "ID" },
+				{ "Column": "GUIDBeaconWorkItem", "DataType": "GUID", "Size": "36" },
+				{ "Column": "CreateDate", "DataType": "DateTime" },
+				{ "Column": "CreatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "UpdateDate", "DataType": "DateTime" },
+				{ "Column": "UpdatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "Deleted", "DataType": "Boolean" },
+				{ "Column": "DeleteDate", "DataType": "DateTime" },
+				{ "Column": "DeletingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "WorkItemHash", "DataType": "String", "Size": "256" },
+				{ "Column": "RunID", "DataType": "String", "Size": "128" },
+				{ "Column": "RunHash", "DataType": "String", "Size": "256" },
+				{ "Column": "NodeHash", "DataType": "String", "Size": "256" },
+				{ "Column": "OperationHash", "DataType": "String", "Size": "256" },
+				{ "Column": "Capability", "DataType": "String", "Size": "128" },
+				{ "Column": "Action", "DataType": "String", "Size": "128" },
+				{ "Column": "Settings", "DataType": "String", "Size": "65535" },
+				{ "Column": "AffinityKey", "DataType": "String", "Size": "256" },
+				{ "Column": "Priority", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "Status", "DataType": "String", "Size": "32" },
+				{ "Column": "AssignedBeaconID", "DataType": "String", "Size": "128" },
+				{ "Column": "TimeoutMs", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "MaxAttempts", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "AttemptNumber", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "RetryBackoffMs", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "EnqueuedAt", "DataType": "DateTime" },
+				{ "Column": "AssignedAt", "DataType": "DateTime" },
+				{ "Column": "DispatchedAt", "DataType": "DateTime" },
+				{ "Column": "StartedAt", "DataType": "DateTime" },
+				{ "Column": "CompletedAt", "DataType": "DateTime" },
+				{ "Column": "CanceledAt", "DataType": "DateTime" },
+				{ "Column": "CancelRequested", "DataType": "Boolean" },
+				{ "Column": "CancelReason", "DataType": "String", "Size": "512" },
+				{ "Column": "LastError", "DataType": "String", "Size": "4096" },
+				{ "Column": "LastEventAt", "DataType": "DateTime" },
+				{ "Column": "QueueWaitMs", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "Health", "DataType": "String", "Size": "32" },
+				{ "Column": "HealthLabel", "DataType": "String", "Size": "16" },
+				{ "Column": "HealthReason", "DataType": "String", "Size": "128" },
+				{ "Column": "HealthComputedAt", "DataType": "DateTime" },
+				{ "Column": "Result", "DataType": "String", "Size": "65535" }
+			]
+		},
+		"BeaconWorkItemEvent":
+		{
+			"TableName": "BeaconWorkItemEvent",
+			"Domain": "Default",
+			"Description": "Append-only audit trail of state transitions for a work item. Each row is one transition.",
+			"Columns":
+			[
+				{ "Column": "IDBeaconWorkItemEvent", "DataType": "ID" },
+				{ "Column": "CreateDate", "DataType": "DateTime" },
+				{ "Column": "CreatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "WorkItemHash", "DataType": "String", "Size": "256" },
+				{ "Column": "RunID", "DataType": "String", "Size": "128" },
+				{ "Column": "EventType", "DataType": "String", "Size": "32" },
+				{ "Column": "FromStatus", "DataType": "String", "Size": "32" },
+				{ "Column": "ToStatus", "DataType": "String", "Size": "32" },
+				{ "Column": "BeaconID", "DataType": "String", "Size": "128" },
+				{ "Column": "Payload", "DataType": "String", "Size": "8192" }
+			]
+		},
+		"BeaconWorkItemAttempt":
+		{
+			"TableName": "BeaconWorkItemAttempt",
+			"Domain": "Default",
+			"Description": "One row per execution attempt. On retry a new attempt row is created and WorkItem.AttemptNumber increments.",
+			"Columns":
+			[
+				{ "Column": "IDBeaconWorkItemAttempt", "DataType": "ID" },
+				{ "Column": "CreateDate", "DataType": "DateTime" },
+				{ "Column": "CreatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "UpdateDate", "DataType": "DateTime" },
+				{ "Column": "UpdatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "WorkItemHash", "DataType": "String", "Size": "256" },
+				{ "Column": "AttemptNumber", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "BeaconID", "DataType": "String", "Size": "128" },
+				{ "Column": "DispatchedAt", "DataType": "DateTime" },
+				{ "Column": "StartedAt", "DataType": "DateTime" },
+				{ "Column": "CompletedAt", "DataType": "DateTime" },
+				{ "Column": "Outcome", "DataType": "String", "Size": "32" },
+				{ "Column": "ErrorMessage", "DataType": "String", "Size": "4096" },
+				{ "Column": "DurationMs", "DataType": "Numeric", "Size": "int" }
+			]
+		},
+		"BeaconAffinityBinding":
+		{
+			"TableName": "BeaconAffinityBinding",
+			"Domain": "Default",
+			"Description": "Affinity lock — routes future work with the same AffinityKey to a specific beacon until TTL expires.",
+			"Columns":
+			[
+				{ "Column": "IDBeaconAffinityBinding", "DataType": "ID" },
+				{ "Column": "CreateDate", "DataType": "DateTime" },
+				{ "Column": "CreatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "UpdateDate", "DataType": "DateTime" },
+				{ "Column": "UpdatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "AffinityKey", "DataType": "String", "Size": "256" },
+				{ "Column": "BeaconID", "DataType": "String", "Size": "128" },
+				{ "Column": "ExpiresAt", "DataType": "DateTime" },
+				{ "Column": "ClearedAt", "DataType": "DateTime" }
+			]
+		},
+		"BeaconActionDefault":
+		{
+			"TableName": "BeaconActionDefault",
+			"Domain": "Default",
+			"Description": "Per-capability/action defaults — timeout, retry, priority, expected-wait baseline. Replaces scattered Fable settings.",
+			"Columns":
+			[
+				{ "Column": "IDBeaconActionDefault", "DataType": "ID" },
+				{ "Column": "CreateDate", "DataType": "DateTime" },
+				{ "Column": "CreatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "UpdateDate", "DataType": "DateTime" },
+				{ "Column": "UpdatingIDUser", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "Capability", "DataType": "String", "Size": "128" },
+				{ "Column": "Action", "DataType": "String", "Size": "128" },
+				{ "Column": "TimeoutMs", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "MaxAttempts", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "RetryBackoffMs", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "DefaultPriority", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "ExpectedWaitP95Ms", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "HeartbeatExpectedMs", "DataType": "Numeric", "Size": "int" },
+				{ "Column": "MinSamplesForBaseline", "DataType": "Numeric", "Size": "int" }
+			]
+		}
+	}
+}

package/source/services/Ultravisor-Beacon-ActionDefaults.cjs

@@ -0,0 +1,174 @@
+/**
+ * Ultravisor Beacon Action Defaults
+ *
+ * Resolves per-action runtime defaults (timeout, retry policy, priority,
+ * expected-wait baseline) from the BeaconActionDefault table.  Live
+ * config changes land here instead of in Fable settings, which means
+ * an operator can tune a slow capability without restarting the hub.
+ *
+ * Fallback order for any single field: per-request Settings → per-action
+ * row → per-capability row (Action="") → Fable setting → hard default.
+ * The last two levels are the compatibility shim while we migrate the
+ * scattered settings into rows.
+ *
+ * @module Ultravisor-Beacon-ActionDefaults
+ */
+
+const libPictService = require('pict-serviceproviderbase');
+
+const HARD_DEFAULTS = {
+	TimeoutMs: 300000,
+	MaxAttempts: 1,
+	RetryBackoffMs: 5000,
+	DefaultPriority: 0,
+	ExpectedWaitP95Ms: 0,
+	HeartbeatExpectedMs: 60000,
+	MinSamplesForBaseline: 20
+};
+
+class UltravisorBeaconActionDefaults extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+		this.serviceType = 'UltravisorBeaconActionDefaults';
+		this._Cache = {};
+		this._CacheTTLMs = 10000;
+	}
+
+	_getStore()
+	{
+		let tmpMap = this.fable.servicesMap && this.fable.servicesMap.UltravisorBeaconQueueStore;
+		if (!tmpMap) return null;
+		let tmpStore = Object.values(tmpMap)[0];
+		return (tmpStore && tmpStore.isEnabled()) ? tmpStore : null;
+	}
+
+	_cacheKey(pCap, pAction)
+	{
+		return `${pCap}||${pAction || ''}`;
+	}
+
+	_fableSettingFallback(pKey)
+	{
+		let tmpSettings = this.fable.settings || {};
+		// Legacy settings names kept during the migration period.
+		if (pKey === 'TimeoutMs' && tmpSettings.UltravisorBeaconWorkItemTimeoutMs)
+		{
+			return tmpSettings.UltravisorBeaconWorkItemTimeoutMs;
+		}
+		if (pKey === 'HeartbeatExpectedMs' && tmpSettings.UltravisorBeaconHeartbeatMs)
+		{
+			return tmpSettings.UltravisorBeaconHeartbeatMs;
+		}
+		return null;
+	}
+
+	invalidate()
+	{
+		this._Cache = {};
+	}
+
+	resolve(pCapability, pAction)
+	{
+		let tmpKey = this._cacheKey(pCapability, pAction);
+		let tmpCached = this._Cache[tmpKey];
+		let tmpNow = Date.now();
+		if (tmpCached && (tmpNow - tmpCached.At) < this._CacheTTLMs)
+		{
+			return tmpCached.Value;
+		}
+
+		let tmpStore = this._getStore();
+		let tmpSpecific = null;
+		let tmpWildcard = null;
+		if (tmpStore)
+		{
+			tmpSpecific = tmpStore.getActionDefault(pCapability, pAction || '');
+			if (!tmpSpecific && pAction)
+			{
+				tmpWildcard = tmpStore.getActionDefault(pCapability, '');
+			}
+		}
+
+		let tmpResolved = {};
+		for (let tmpField of Object.keys(HARD_DEFAULTS))
+		{
+			let tmpVal = null;
+			if (tmpSpecific && tmpSpecific[tmpField] != null && tmpSpecific[tmpField] !== 0)
+			{
+				tmpVal = tmpSpecific[tmpField];
+			}
+			else if (tmpWildcard && tmpWildcard[tmpField] != null && tmpWildcard[tmpField] !== 0)
+			{
+				tmpVal = tmpWildcard[tmpField];
+			}
+			else
+			{
+				tmpVal = this._fableSettingFallback(tmpField);
+			}
+			if (tmpVal == null) tmpVal = HARD_DEFAULTS[tmpField];
+			tmpResolved[tmpField] = tmpVal;
+		}
+
+		this._Cache[tmpKey] = { At: tmpNow, Value: tmpResolved };
+		return tmpResolved;
+	}
+
+	applyToWorkItem(pWorkItem, pRequestSettings)
+	{
+		let tmpResolved = this.resolve(pWorkItem.Capability, pWorkItem.Action);
+		let tmpSettings = pRequestSettings || {};
+
+		pWorkItem.TimeoutMs = pWorkItem.TimeoutMs
+			|| parseInt(tmpSettings.timeoutMs, 10)
+			|| parseInt(tmpSettings.TimeoutMs, 10)
+			|| tmpResolved.TimeoutMs;
+
+		pWorkItem.MaxAttempts = pWorkItem.MaxAttempts
+			|| parseInt(tmpSettings.maxRetries, 10)
+			|| parseInt(tmpSettings.MaxAttempts, 10)
+			|| tmpResolved.MaxAttempts;
+
+		pWorkItem.RetryBackoffMs = pWorkItem.RetryBackoffMs
+			|| parseInt(tmpSettings.retryBackoffMs, 10)
+			|| parseInt(tmpSettings.RetryBackoffMs, 10)
+			|| tmpResolved.RetryBackoffMs;
+
+		if (pWorkItem.Priority == null)
+		{
+			let tmpPri = parseInt(tmpSettings.priority, 10);
+			if (isNaN(tmpPri)) tmpPri = parseInt(tmpSettings.Priority, 10);
+			if (isNaN(tmpPri)) tmpPri = tmpResolved.DefaultPriority;
+			pWorkItem.Priority = tmpPri;
+		}
+
+		return pWorkItem;
+	}
+
+	/**
+	 * Compute a live p95 estimate from the last N completed samples.
+	 * Used when no ExpectedWaitP95Ms is set on the row yet.  Stored
+	 * back into the row so future lookups are fast.
+	 */
+	recomputeWaitBaseline(pCapability, pAction, pMinSamples)
+	{
+		let tmpStore = this._getStore();
+		if (!tmpStore) return null;
+		let tmpMin = pMinSamples || HARD_DEFAULTS.MinSamplesForBaseline;
+		let tmpSamples = tmpStore.queueWaitSamples(pCapability, pAction || '', 500);
+		if (tmpSamples.length < tmpMin) return null;
+		tmpSamples.sort((a, b) => a - b);
+		let tmpIdx = Math.max(0, Math.floor(tmpSamples.length * 0.95) - 1);
+		let tmpP95 = tmpSamples[tmpIdx];
+		tmpStore.upsertActionDefault({
+			Capability: pCapability,
+			Action: pAction || '',
+			ExpectedWaitP95Ms: tmpP95
+		});
+		this.invalidate();
+		return tmpP95;
+	}
+}
+
+module.exports = UltravisorBeaconActionDefaults;