@xema/omni-protocol 0.1.63 → 0.1.65

package/dist/testing.js

@@ -272,7 +272,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // What the host's Mute does is stated where the host holds a microphone, and nowhere else.
         violations.push(...validateHostMute(context.host.mute, softphone, "context.host.mute"));
         // The login's store is the host's to provide: an adapter that composes a record keeps in it what its platform cannot.
-        violations.push(...validateLoginStore(context.store, "context.store"));
+        const storeShape = validateLoginStore(context.store, "context.store");
+        violations.push(...storeShape);
+        // The harness watches the store it hands over, so what an adapter leaves behind is seen rather than asked for.
+        const watched = storeShape.length === 0 ? watchStore(context.store) : { store: context.store, held: new Set() };
         unsubscribeHost = context.host.subscribe(report => {
             violations.push(...validateHostReport(report, "context.host"));
         });
@@ -284,7 +287,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             report: () => { consulted = true; return context.host.report(); },
             subscribe: listener => { consulted = true; return context.host.subscribe(listener); },
         };
-        connection = await adapter.connect({ ...context, host });
+        const connected = { ...context, host, store: watched.store };
+        connection = await adapter.connect(connected);
         const live = connection;
         // Dial is declared by presence: the capability object carries a destination policy rather
         // than an `enabled` flag, so its presence is the declaration.
@@ -374,7 +378,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...await driveOneCall({
                 connection: live, manifest: adapter.manifest, channel: adapter.manifest.channel, softphone, snapshot, events, waiters, stream, localAudio,
                 timeoutMs: options.driveTimeoutMs ?? 5000,
-                context, secrets: authenticationSecrets, reader, rebuild: options.rebuild,
+                context: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held,
             }));
         }
     }
@@ -1019,6 +1023,29 @@ async function driveOneCall(drive) {
             }
         }
     };
+    // A task's keys are gone with the task. A task-scoped key carries the task id, so the watched
+    // store says which keys were the task's; one still held after task-ended is a key about to be
+    // inherited by the next offer of the same id, since a platform retires an id minutes after closing it.
+    let retainedAtEnd;
+    const storeReleased = async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+        const retained = [...drive.held].filter(key => key.includes(taskId));
+        retainedAtEnd = new Set(retained);
+        if (retained.length > 0) {
+            refuse("drive.store.retained", "drive.store", `${taskId} has ended and the login's store still holds ${retained.join(", ")}: a task's keys go with the task, or the next offer of the same id inherits them`);
+        }
+    };
+    // A key written about the task after its end -- a persist hung off a timer, a late command -- is the
+    // same hazard arriving later, so the store is read once more when the drive is done.
+    const nothingLate = () => {
+        if (retainedAtEnd === undefined)
+            return;
+        const late = [...drive.held].filter(key => key.includes(taskId) && !retainedAtEnd.has(key));
+        if (late.length > 0) {
+            refuse("drive.store.late", "drive.store", `${taskId} had ended with its keys gone, and the login's store now holds ${late.join(", ")}: something wrote about the task after its end`);
+        }
+    };
     // The task, as first seen: on the snapshot, or on the first offer.
     let cursor = 0;
     let task = isRecord(drive.snapshot) && Array.isArray(drive.snapshot.tasks) ? drive.snapshot.tasks.find(isTask) : undefined;
@@ -1224,11 +1251,12 @@ async function driveOneCall(drive) {
         if (isRecord(dispositions) && dispositions.required === true && Array.isArray(dispositions.codes) && isRecord(dispositions.codes[0])) {
             command.disposition = dispositions.codes[0].id;
         }
-        if (await send(command) !== undefined)
-            await ended();
+        if (await send(command) !== undefined && await ended() !== undefined)
+            await storeReleased();
     }
     else if (latestTask().phase === "completing") {
-        await ended();
+        if (await ended() !== undefined)
+            await storeReleased();
     }
     // The record kept by the provider has the leg the host reported, wherever the provider restated it.
     if (mutedLeg !== undefined && latestTask() !== mutedLeg.task) {
@@ -1244,6 +1272,9 @@ async function driveOneCall(drive) {
             }
         }
     }
+    // A timer fires after the microtasks: one turn of the loop is what a late persist needs to show itself.
+    await new Promise(resolve => setTimeout(resolve, 0));
+    nothingLate();
     return found;
 }
 // A request goes not-requested -> awaiting-decision | granted; a commit goes granted ->
@@ -1323,6 +1354,18 @@ export function assertMediaFollowsTheTask(envelopes, snapshot) {
     envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
     assertNoViolations(found, "The media follows the task");
 }
+/** The store as handed to the adapter, and the keys it holds at any moment, seen rather than reported. */
+function watchStore(store) {
+    const held = new Set();
+    return {
+        held,
+        store: {
+            get: key => store.get(key),
+            set: async (key, value) => { await store.set(key, value); held.add(key); },
+            delete: async (key) => { await store.delete(key); held.delete(key); },
+        },
+    };
+}
 /** A login store that lives in memory for the test: what most adapter tests hand `exerciseAdapter` as `context.store`. */
 export function memoryStore() {
     const kept = new Map();

package/guide.md

@@ -1946,7 +1946,7 @@ Creates one live provider connection for the signed-in agent.
 | `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login. Treated as `true` when omitted. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
 | `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the identity. See **The agent's day**. |
 | `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. The type ties `host.mute` to it: a `softphone` login's host states what its Mute does, and a desk-phone or conversation login's host cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the host's**. |
-| `store` | The login's operational store, kept by the host for the life of the login, across a reload of the host, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the handling legs a host reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store a host may clear aggressively. The harness requires it of every connection (`store.shape`, `store.get`, `.set`, `.delete`). |
+| `store` | The login's operational store, kept by the host for the life of the login, across a reload of the host, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the handling legs a host reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store a host may clear aggressively. **A task's keys carry the task id and go with the task**: a key written about a task names the task's id in the key, and is deleted before the task's end is published, because a platform retires a task id minutes after closing it and a requeue takes seconds, so a key that outlives its task is inherited by the next offer of the same id -- a record with legs the host never reported against it. A login-scoped key carries no task id and outlives any task. The harness requires the store of every connection (`store.shape`, `store.get`, `.set`, `.delete`), watches the one it hands over, and names a task's key still held after `task-ended` (`drive.store.retained`) or written about the task after its end -- a persist hung off a timer that saw the task as it was (`drive.store.late`). The ordinary late write is the host's, not the adapter's: a host reports a leg without waiting for the answer, so an unmute can follow `complete` by a tick, and the adapter answers a report about a task that has ended `failed` with `omni.task-not-found` and writes nothing -- the host ends its own open legs at the task's end, so such a report is the host's error to see, never a record to keep; an adapter that names no task in its keys gets no cleanup check, which is a gap rather than a pass, never an exemption: the obligation is that nothing of a closed task survives its ending, and an adapter that keeps every open task in one login-scoped value owes exactly that inside the value, where the harness cannot look. One key per task, named for it, is the shape the harness can hold, and the shape to reach for. The store lists nothing, so an adapter that needs to find its tasks keeps a login-scoped index of ids beside them; at the task's end it deletes the body first and reindexes after, since a crash between the two then leaves an index naming a task with no body, which a reader skips, where the other order leaves a body for a task that has ended, which is the hazard itself. A reader of the index tolerates an id with no body as an ending that was underway, not as corruption. |
 | `host` | The host's report of the agent's station — devices, permissions, network — to consult before declaring the agent ready to the platform, and on every change. See **The host reports, the adapter decides**. |
 | `signal` | Optional cancellation signal. Stop startup promptly when aborted and do not begin new work. |
 | `log` | Optional structured logging callback. Never include credentials, tokens, or sensitive contact data. |
@@ -4599,7 +4599,13 @@ adapter is held to what the first was: the same provider (`drive.reload.manifest
 stands as any snapshot must, and a record that lost none of the entries the first had published --
 a record once read is not unread across a reload either. A reconnect on the same adapter object
 would prove nothing, since an in-process adapter's memory survives it; only a second object
-separates kept-in-the-store from never-lost. Outside the
+separates kept-in-the-store from never-lost. The second adapter opens its session from the same
+`secrets`, so the reload is a restore before it is anything else: an adapter that holds a session
+has already put what would rebuild it into the secrets store, from the moment it was handed one,
+not only when a flow completes -- the session is the adapter's, the store is the host's, and a
+host reload is exactly when no flow will run. And once the task has ended, the store the drive
+handed the adapter holds no key carrying the task's id (`drive.store.retained`): a task's keys go
+with the task, or the next offer of the same id inherits them. Outside the
 handling phases with `hold` still declared -- in
 `confirmed`, where the provider publishes it, and in `completing` once the call has ended -- the
 drive sends `hold` past the validator that would hold it back, and expects `failed`: the adapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",