@xema/omni-protocol 0.1.70 → 0.1.72

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;
     }
@@ -1012,7 +1055,7 @@ export class TaskStream {
             case "task-updated":
                 if (id === undefined)
                     break;
-                ruleEvaluated("stream.taskUpdated.unknown", "stream.taskUpdated.capabilitySource", "stream.taskUpdated.phase", "stream.taskUpdated.allocation", "stream.taskUpdated.handlingHistory", "stream.taskMediaEnded.follow", "stream.taskUpdated.media", "stream.taskUpdated.stage");
+                ruleEvaluated("stream.taskUpdated.unknown", "stream.taskUpdated.capabilitySource", "stream.taskUpdated.phase", "stream.taskUpdated.allocation", "stream.taskUpdated.mediaOpen", "stream.taskUpdated.handlingHistory", "stream.taskMediaEnded.follow", "stream.taskUpdated.media", "stream.taskUpdated.stage");
                 if (known === undefined) {
                     refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
                     break;
@@ -1051,6 +1094,15 @@ export class TaskStream {
                         refuse("stream.taskUpdated.handlingHistory", `${at}.task.handlingHistory`, `${id}'s record lost ${lost.join(", ")} on the update: an entry read by the host stays in the record until the task ends`);
                     }
                 }
+                // A task completes after its media ends, never around it: an update that moves a task to
+                // completing while the stream holds its audio as started is a call whose audio never ended,
+                // whoever caused the ending -- the drive's end-call, a transfer, the provider's own hand.
+                {
+                    const to = isRecord(event.task) ? String(event.task.phase) : "";
+                    if (to === "completing" && known.media === "started" && known.phase !== "completing") {
+                        refuse("stream.taskUpdated.mediaOpen", `${at}.task.phase`, `${id} moves to completing with its media still started: the audio ends first, on task-media-ended, and a wrap-up with the call still up is audio that never ended`);
+                    }
+                }
                 if (known.media === "ended") {
                     const phase = isRecord(event.task) ? String(event.task.phase) : "";
                     if (phase !== "completing") {
@@ -1189,7 +1241,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 +1250,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 +1268,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 +1311,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 +1508,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")) {
@@ -1474,11 +1528,18 @@ async function driveOneCall(drive) {
     // 5. End the call, where the agent may.
     if (drive.channel === "voice" && latestTask().phase === "in-progress" && offers("endCall")) {
         if (await send({ type: "end-call" }) !== undefined) {
+            // A task that completes with its audio still up is refused by the stream as it passes
+            // (stream.taskUpdated.mediaOpen); the drive does not also wait out the clock for an ending
+            // that is not coming, so the run reads by the rule and not by its timeout.
             const mediaEnded = await waitFor("task-media-ended after end-call", envelope => {
                 const event = envelope.event;
-                return event.type === "task-media-ended" && event.taskId === taskId ? event : undefined;
+                if (event.type === "task-media-ended" && event.taskId === taskId)
+                    return "ended";
+                if (event.type === "task-updated" && isTask(event.task) && event.task.id === taskId && event.task.phase === "completing")
+                    return "completing";
+                return undefined;
             }, cursor);
-            if (mediaEnded !== undefined)
+            if (mediaEnded?.found === "ended")
                 cursor = mediaEnded.at;
             if (await updated(t => t.phase === "completing", "the task completing after its media ended") !== undefined && offers("hold")) {
                 await holdRefusedOutsideHandling();

package/dist/validation.js

@@ -1021,6 +1021,12 @@ function validateTaskInto(task, context, path, into) {
     // The room is who is on the call now, and a task outlives its call by the whole of wrap-up: a
     // task whose call has ended -- completing, or media ended -- carries nobody, or the last thing the
     // wire said about the call stays true for ever. Empty and absent both say nobody.
+    // A completing task's call is over: its media has ended, or it never started. Audio still stated
+    // as started on a task in wrap-up is a call whose audio never ended -- the customer heard through
+    // the agent's notes -- and a task stating it contradicts itself.
+    if (task.phase === "completing" && task.media === "started") {
+        into.add("task.media.completing", `${path}.media`, "a completing task's media has ended or never started: the call is over, and media still started is audio that never ended");
+    }
     if (Array.isArray(task.onCall) && task.onCall.length > 0 && (task.phase === "completing" || task.media === "ended")) {
         into.add("task.onCall.ended", `${path}.onCall`, `the call has ended (${task.phase === "completing" ? "the task is completing" : "its media ended"}) and onCall still names people on it: the room is who is on the call now, and now nobody is`);
     }

package/guide.md

@@ -2854,7 +2854,12 @@ which the update itself shows: the party on the call carrying a `stage`. A compl
 republished as `in-progress` from a stale copy carries no such stage, and that is the ending the
 agent never saw. Audio arrives only on a task at work: `task-media-started` on a `completing` task
 is refused as it is on a pending one (`stream.taskMediaStarted.beforeWork`), since a connect-back
-returns the task to `in-progress` before any media.
+returns the task to `in-progress` before any media. And a task completes after its audio ends,
+never around it: an update moving a task to `completing` while the stream holds its media as
+started is refused (`stream.taskUpdated.mediaOpen`), whoever caused the ending, and a task stating
+`completing` with `media: "started"` contradicts itself on any snapshot or update
+(`task.media.completing`). The consequence the rule exists for is concrete: the customer's audio
+keeps playing through the agent's wrap-up.
 
 What the agent is told differs by source, and only one source tells them anything. Under `queue`
 and `ungoverned` the agent sees controls and nothing about where they came from: both are facts,
@@ -4641,7 +4646,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 +4717,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.72",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",