@xema/omni-protocol 0.1.70 → 0.1.71

package/dist/testing.js

@@ -168,8 +168,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         set: async (key, value) => { storedSecrets.set(key, value); },
         delete: async (key) => { storedSecrets.delete(key); },
     };
-    const authentication = await adapter.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
+    let authentication = await adapter.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
     let connection;
+    /** Whether the run holds a client at all: false between a reload's first client going down and its second standing, and after a reload that failed. */
+    let clientLive = true;
     let unsubscribe;
     let unsubscribeAuthentication;
     let unsubscribeHost;
@@ -318,10 +320,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             requireMethod(live, "recordStep", "the login is on a softphone, whose microphone the host mutes");
         const eventPayloads = new Map();
         let capacityStated;
-        const reloading = { now: false };
         // The drive waits on events: each waiter is offered every envelope as it lands.
         const waiters = new Set();
-        unsubscribe = connection.subscribe(envelope => {
+        const onEnvelope = (envelope) => {
             observeEvent(envelope, seen);
             const broken = validateEventEnvelope(envelope, adapter.manifest, "event", reader());
             violations.push(...broken);
@@ -334,7 +335,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             // client pushes it to the old one too, and an adapter that calls a re-offer of answered work a
             // defect is right to. That diagnostic is the drive's own artefact, and is not counted while the
             // second adapter is up; every other moment it is.
-            if (isRecord(envelope?.event) && envelope.event.type === "diagnostic" && !reloading.now) {
+            if (isRecord(envelope?.event) && envelope.event.type === "diagnostic") {
                 violations.push({ rule: "diagnostic.raised", path: "event.diagnostic",
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
@@ -374,7 +375,45 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             events.push(envelope);
             for (const waiter of waiters)
                 waiter(envelope);
-        });
+        };
+        unsubscribe = connection.subscribe(onEnvelope);
+        // A host reload is the first client dying and a second coming up in its place. The drive hands
+        // the run over: the first connection is unsubscribed, disconnected and its session closed before
+        // the second connects, and the run continues on the second -- so there is no first client for a
+        // platform to push the open task back to, and nothing to exempt.
+        const handOver = {
+            isLive: () => clientLive,
+            down: async () => {
+                let clean = true;
+                try {
+                    unsubscribe?.();
+                }
+                catch {
+                    clean = false;
+                }
+                unsubscribe = undefined;
+                try {
+                    await connection?.disconnect();
+                }
+                catch {
+                    clean = false;
+                }
+                try {
+                    await authentication.close();
+                }
+                catch {
+                    clean = false;
+                }
+                clientLive = false;
+                return clean;
+            },
+            up: (session, second) => {
+                authentication = session;
+                connection = second;
+                unsubscribe = second.subscribe(onEnvelope);
+                clientLive = true;
+            },
+        };
         const snapshot = await connection.snapshot();
         observeSnapshot(snapshot, seen);
         {
@@ -449,7 +488,8 @@ 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, reloading,
+                context: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held, handOver,
+                streams: { stream, breaks },
             }));
         }
         // Capacity supersedes rather than accumulates, so a decrease is as ordinary as an increase: the
@@ -459,9 +499,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // capacity is elsewhere, and the provider allocates nothing and refuses nothing for it. Any offer
         // after a lower count is caught against it (stream.taskOffered.overCapacity).
         ruleEvaluated("connection.setCapacity.lowered", "connection.setCapacity.zero");
-        for (const count of [2, 1, 0]) {
+        for (const count of clientLive ? [2, 1, 0] : []) {
             capacityStated = count;
-            const restated = await live.setCapacity({ count });
+            const restated = await connection.setCapacity({ count });
             const shape = validateResult(restated, "setCapacity", "connection.setCapacity");
             violations.push(...shape);
             if (shape.length === 0 && restated.status === "failed") {
@@ -493,17 +533,20 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         catch {
             clean = false;
         }
-        try {
-            await connection?.disconnect();
-        }
-        catch {
-            clean = false;
-        }
-        try {
-            await authentication.close();
-        }
-        catch {
-            clean = false;
+        // A run whose reload took the first client down and stood no second holds nothing to close.
+        if (clientLive) {
+            try {
+                await connection?.disconnect();
+            }
+            catch {
+                clean = false;
+            }
+            try {
+                await authentication.close();
+            }
+            catch {
+                clean = false;
+            }
         }
         disconnectWasClean = clean;
     }
@@ -1189,7 +1232,7 @@ async function driveOneCall(drive) {
         drive.waiters.add(waiter);
     });
     const recordSurvivesReload = async (at) => {
-        ruleEvaluated("drive.reload.rejected", "drive.reload.manifest", "drive.reload.login", "drive.reload.snapshot", "drive.reload.allocation", "drive.reload.history");
+        ruleEvaluated("drive.reload.rejected", "drive.reload.manifest", "drive.reload.login", "drive.reload.snapshot", "drive.reload.allocation", "drive.reload.history", "drive.reload.handover");
         let again;
         try {
             again = drive.rebuild();
@@ -1198,16 +1241,17 @@ async function driveOneCall(drive) {
             refuse("drive.reload.rejected", "drive.reload", `building the adapter again threw: ${String(error)}`);
             return;
         }
-        let session;
-        let second;
+        // 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;
+        }
+        // The first client dies first, as it does on a reload: from here the run has no connection until the second stands.
+        if (!await drive.handOver.down()) {
+            refuse("drive.reload.handover", "drive.reload", "taking the first client down threw: an unsubscribe, disconnect() or close() failed");
+        }
         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;
-            }
-            drive.reloading.now = true;
-            session = await again.createAuthenticationSession({ ...drive.context, secrets: drive.secrets });
+            const session = await again.createAuthenticationSession({ ...drive.context, secrets: drive.secrets });
             // The reload is a restore before it is anything else: the second session stands authenticated
             // as the same person, from the secrets alone, or nothing it reads afterwards is this login's.
             const restored = await session.state();
@@ -1215,12 +1259,22 @@ async function driveOneCall(drive) {
             const same = isRecord(restored) && restored.status === "authenticated" && isRecord(restored.identity) && restored.identity.id === drive.reader().self;
             if (!same) {
                 refuse("drive.reload.login", "drive.reload.login", `a second adapter built from the same login and secrets did not restore it: the session says ${String(isRecord(restored) ? restored.status : restored)}${isRecord(restored) && isRecord(restored.identity) ? ` as ${String(restored.identity.id)}` : ""}, and the login is ${String(drive.reader().self)}`);
+                // A reload that cannot restore the login is a sign-in screen, not a connection: the run ends here.
+                try {
+                    await session.close();
+                }
+                catch { /* the session that would not restore is closed as far as it can be */ }
                 return;
             }
-            second = await again.connect(drive.context);
+            const second = await again.connect(drive.context);
+            // From here the second client is the run's connection: what it publishes is validated as before.
+            drive.handOver.up(session, second);
+            drive.connection = second;
             const snapshot = await second.snapshot();
-            // The second adapter's snapshot is held to everything a first one is.
+            // The second adapter's snapshot is held to everything a first one is, and the streams take it as the state now.
             found.push(...validateSnapshot(snapshot, again.manifest, "drive.reload.snapshot", drive.reader()));
+            drive.streams.stream.seed(snapshot);
+            drive.streams.breaks.seed(snapshot);
             const carried = isRecord(snapshot) && Array.isArray(snapshot.tasks)
                 ? snapshot.tasks.find(task => isRecord(task) && task.id === taskId) : undefined;
             if (carried === undefined) {
@@ -1248,25 +1302,12 @@ async function driveOneCall(drive) {
             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`);
             }
+            // The drive goes on with the task as the reloaded client holds it.
+            task = carried;
         }
         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)}`);
-            }
-            drive.reloading.now = false;
-        }
     };
     // 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
@@ -1458,8 +1499,12 @@ async function driveOneCall(drive) {
         // 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)
+        if (drive.rebuild !== undefined) {
             await recordSurvivesReload(at);
+            // A reload that stood no client ends the run: there is nothing left to drive.
+            if (!drive.handOver.isLive())
+                return found;
+        }
     }
     // 4. Hold and resume, where offered.
     if (latestTask().phase === "in-progress" && offers("hold")) {

package/guide.md

@@ -4641,7 +4641,9 @@ A refusal has an aftermath on the desk and a report to the provider, and both ar
   vanish from the desk while the call is up.
 - **A refused event is dropped and counted.** The state the host holds does not move for it. The
   provider is told, and may republish a corrected state or raise a `diagnostic`; the host retries
-  nothing.
+  nothing. The desk shows nothing for it: the view kept moving for every other event, so "last
+  update refused" would be false of it, and a chip that said nothing would be right about the
+  transport. Counted, and the provider told, is all a host can truthfully do for one event.
 - **The provider is told, every time.** `refused(report)` carries the artefact, the envelope id for
   an event, and every violation with its rule and path. An adapter logs it at error and treats it as
   its own defect until shown otherwise: what the host refused never reached the agent, and a
@@ -4710,15 +4712,19 @@ the drive mutes it for one second and reports the leg through `recordStep`, begu
 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`). 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
+does, the drive reloads the host as a reload happens: the first client is unsubscribed,
+disconnected and its session closed (`drive.reload.handover`), and only then is a second adapter
+built and connected for the same login with the same context and the same `store`; its snapshot
+must carry the task with that leg and the host's word, and the run goes on with the second as its
+connection to the end. 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. And because the
+first client is gone before the second connects, there is no client for the platform to push the
+open task back to, and nothing about the reload is exempt from any rule. 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

package/package.json

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