@xema/omni-protocol 0.1.62 → 0.1.63

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;
@@ -376,6 +374,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,
             }));
         }
     }
@@ -956,6 +955,70 @@ 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)}`);
+            }
+        }
+    };
     // 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 +1176,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")) {

package/guide.md

@@ -4590,7 +4590,17 @@ 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. 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.63",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",