@xema/omni-protocol 0.1.62 → 0.1.64

package/dist/testing.d.ts

@@ -43,6 +43,14 @@ export interface ExerciseAdapterOptions {
     drive?: boolean;
     /** How long the drive waits for each thing the provider owes it. Defaults to 5000. */
     driveTimeoutMs?: number;
+    /**
+     * Builds the adapter again, as a host reload does: a new object with no memory, for the same
+     * login. Given it, the drive -- once the host's muted leg is recorded -- connects a second adapter
+     * with the same context and the same store and expects its snapshot to carry the task with that
+     * leg. A platform that holds the record hands it back; an adapter that composed the record in
+     * memory has nothing, and is named. Without it the store is required and never read.
+     */
+    rebuild?: () => Adapter<Channel>;
 }
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,

package/dist/testing.js

@@ -161,14 +161,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const breaks = new BreakStream();
     let seeded = false;
     const storedSecrets = new Map();
-    const authentication = await adapter.createAuthenticationSession({
-        ...context,
-        secrets: {
-            get: async (key) => storedSecrets.get(key),
-            set: async (key, value) => { storedSecrets.set(key, value); },
-            delete: async (key) => { storedSecrets.delete(key); },
-        },
-    });
+    const authenticationSecrets = {
+        get: async (key) => storedSecrets.get(key),
+        set: async (key, value) => { storedSecrets.set(key, value); },
+        delete: async (key) => { storedSecrets.delete(key); },
+    };
+    const authentication = await adapter.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
     let connection;
     let unsubscribe;
     let unsubscribeAuthentication;
@@ -274,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"));
         });
@@ -286,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.
@@ -376,6 +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: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held,
             }));
         }
     }
@@ -956,6 +959,81 @@ async function driveOneCall(drive) {
         };
         drive.waiters.add(waiter);
     });
+    const recordSurvivesReload = async (at) => {
+        let again;
+        try {
+            again = drive.rebuild();
+        }
+        catch (error) {
+            refuse("drive.reload.rejected", "drive.reload", `building the adapter again threw: ${String(error)}`);
+            return;
+        }
+        let session;
+        let second;
+        try {
+            // The same provider, built again: a different manifest is a different adapter, and proves nothing about this one.
+            if (again.manifest.id !== drive.manifest.id) {
+                refuse("drive.reload.manifest", "drive.reload.manifest", `rebuild returned an adapter for ${String(again.manifest.id)}; the reload is of ${String(drive.manifest.id)}`);
+                return;
+            }
+            session = await again.createAuthenticationSession({ ...drive.context, secrets: drive.secrets });
+            second = await again.connect(drive.context);
+            const snapshot = await second.snapshot();
+            // The second adapter's snapshot is held to everything a first one is.
+            found.push(...validateSnapshot(snapshot, again.manifest, "drive.reload.snapshot", drive.reader()));
+            const carried = isRecord(snapshot) && Array.isArray(snapshot.tasks)
+                ? snapshot.tasks.find(task => isRecord(task) && task.id === taskId) : undefined;
+            if (carried === undefined) {
+                refuse("drive.reload.snapshot", "drive.reload.snapshot", `a second adapter built from the same login does not carry ${taskId} on its snapshot, and the task is still open`);
+                return;
+            }
+            const history = carried.handlingHistory;
+            const steps = isRecord(history) && Array.isArray(history.steps) ? history.steps : [];
+            // A record once read is not unread across a reload either: every entry the first adapter published is here.
+            const before = latestTask().handlingHistory;
+            const wasRead = isRecord(before) && Array.isArray(before.steps) ? before.steps.filter(isRecord) : [];
+            const lost = wasRead.filter(entry => !steps.some(now => isRecord(now) && now.step === entry.step && now.at === entry.at))
+                .map(entry => `${String(entry.step)}@${String(entry.at)}`);
+            if (lost.length > 0) {
+                refuse("drive.reload.history", "drive.reload.history", `a second adapter built from the same login carries ${taskId} without ${lost.join(", ")}, which the first had published: a record once read is not unread`);
+            }
+            const leg = steps.find(entry => isRecord(entry) && entry.step === "muted" && entry.at === at);
+            if (leg === undefined) {
+                refuse("drive.reload.history", "drive.reload.history", `a second adapter built from the same login carries ${taskId} without the muted leg at ${at}: the record was composed in memory and died with the adapter; the login's store is where it lives`);
+            }
+            else if (leg.mutedBy !== "host") {
+                refuse("drive.reload.history", "drive.reload.history", `the reloaded record's muted leg at ${at} says mutedBy ${String(leg.mutedBy)}; the host reported host`);
+            }
+        }
+        catch (error) {
+            refuse("drive.reload.rejected", "drive.reload", `the second adapter rejected rather than answered: ${String(error)}`);
+        }
+        finally {
+            try {
+                await second?.disconnect();
+            }
+            catch (error) {
+                refuse("drive.reload.rejected", "drive.reload", `the second adapter's disconnect threw: ${String(error)}`);
+            }
+            try {
+                await session?.close();
+            }
+            catch (error) {
+                refuse("drive.reload.rejected", "drive.reload", `the second adapter's session threw on close: ${String(error)}`);
+            }
+        }
+    };
+    // 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.
+    const storeReleased = async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+        const retained = [...drive.held].filter(key => key.includes(taskId));
+        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`);
+        }
+    };
     // 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;
@@ -1113,6 +1191,11 @@ async function driveOneCall(drive) {
         setMuted(false);
         await report({ seconds: Math.round((Date.now() - began) / 1000), ended: true });
         mutedLeg = { at, task: latestTask() };
+        // 3c. A host reload destroys the adapter object and keeps the login's store. Built again from
+        // the same login, a second adapter carries the task and the leg -- from its platform, or from
+        // the store -- or it composed the record in memory and the record died with it.
+        if (drive.rebuild !== undefined)
+            await recordSurvivesReload(at);
     }
     // 4. Hold and resume, where offered.
     if (latestTask().phase === "in-progress" && offers("hold")) {
@@ -1156,11 +1239,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) {
@@ -1255,6 +1339,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`); 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. |
@@ -4590,7 +4590,23 @@ violation (`drive.command.failed`), and an event the provider owes and never sen
 the drive mutes it for one second and reports the leg through `recordStep`, begun and then ended,
 expecting each report `recorded` (`drive.recordStep.failed`, `.rejected`); and where the provider
 restates the task's record afterwards, the leg is in it or the hole is named
-(`drive.recordStep.history`). Outside the handling phases with `hold` still declared -- in
+(`drive.recordStep.history`). Given `rebuild`, a way to build the adapter again as a host reload
+does, the drive then connects a second adapter for the same login with the same context and the
+same `store`, and expects its snapshot to carry the task with that leg and the host's word: a
+platform that holds the record hands it back, and an adapter that composed the record in memory
+has nothing and is named (`drive.reload.snapshot`, `drive.reload.history`, `.rejected`). The second
+adapter is held to what the first was: the same provider (`drive.reload.manifest`), a snapshot that
+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. 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
 is the second gate on a control on the contact, and one that applies it where there is nothing to

package/package.json

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