@xema/omni-protocol 0.1.73 → 0.1.74

package/dist/testing.d.ts

@@ -133,6 +133,11 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * both.
  */
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
+/**
+ * The event kinds a snapshot restates, and so supersedes when delivered while it is read. Every
+ * other kind reports a transaction no snapshot carries, and a host applies it after the snapshot.
+ */
+export declare const SUPERSEDED_BY_A_SNAPSHOT: ReadonlySet<string>;
 export declare class TaskStream {
     private readonly tasks;
     private readonly allocations;

package/dist/testing.js

@@ -162,6 +162,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const stream = new TaskStream();
     const breaks = new BreakStream();
     let seeded = false;
+    const duringRead = [];
     const storedSecrets = new Map();
     const authenticationSecrets = {
         get: async (key) => storedSecrets.get(key),
@@ -369,9 +370,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 }
                 eventPayloads.set(envelope.id, payload);
             }
-            // Cross-event rules apply once the stream has a beginning: the connect snapshot.
+            // Cross-event rules apply once the stream has a beginning: the connect snapshot. An event
+            // delivered while that snapshot is read is held until it lands, and read then against it.
             if (seeded)
                 violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
+            else
+                duringRead.push(envelope);
             events.push(envelope);
             for (const waiter of waiters)
                 waiter(envelope);
@@ -426,6 +430,32 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         stream.seed(snapshot);
         breaks.seed(snapshot);
         seeded = true;
+        // A snapshot supersedes what it restates and nothing else. Of the events held during the read,
+        // a state-replacing kind is dropped, since the snapshot carries that state and must account for
+        // it; the rest -- a dial's outcome, a diagnostic, an announcement, a queue summary -- report
+        // transactions no snapshot carries, and are applied after it, in order.
+        ruleEvaluated("snapshot.accounts.task", "snapshot.accounts.ended");
+        const carried = new Set();
+        for (const task of Array.isArray(snapshot?.tasks) ? snapshot.tasks : []) {
+            if (isRecord(task) && typeof task.allocationId === "string")
+                carried.add(task.allocationId);
+        }
+        for (const held of duringRead) {
+            const event = held.event;
+            if (!SUPERSEDED_BY_A_SNAPSHOT.has(String(event.type))) {
+                violations.push(...stream.apply(held), ...breaks.apply(held));
+                continue;
+            }
+            if ((event.type === "task-offered" || event.type === "task-updated") && isRecord(event.task) && typeof event.task.allocationId === "string" && !carried.has(event.task.allocationId)) {
+                violations.push({ rule: "snapshot.accounts.task", path: "snapshot.tasks",
+                    message: `${String(event.task.id)} (${event.task.allocationId}) was published while the snapshot was read and the snapshot does not carry it: a snapshot accounts for everything the adapter emitted before it resolved` });
+            }
+            if (event.type === "task-ended" && typeof event.allocationId === "string" && carried.has(event.allocationId)) {
+                violations.push({ rule: "snapshot.accounts.ended", path: "snapshot.tasks",
+                    message: `${String(event.taskId)} (${event.allocationId}) ended while the snapshot was read and the snapshot still carries it: a snapshot accounts for everything the adapter emitted before it resolved` });
+            }
+        }
+        duringRead.length = 0;
         requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot)) {
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
@@ -905,6 +935,14 @@ const REACHABLE_PHASES = {
     paused: new Set(["paused", "in-progress", "completing"]),
     completing: new Set(["completing"]),
 };
+/**
+ * The event kinds a snapshot restates, and so supersedes when delivered while it is read. Every
+ * other kind reports a transaction no snapshot carries, and a host applies it after the snapshot.
+ */
+export const SUPERSEDED_BY_A_SNAPSHOT = new Set([
+    "snapshot", "transport-status", "break-state", "task-offered", "task-updated", "task-ended",
+    "task-media-started", "task-media-ended", "team-updated", "contacts-updated", "calendar-updated",
+]);
 export class TaskStream {
     tasks = new Map();
     // Every allocation this login has seen, and the ones whose task has ended: an offer never reuses
@@ -1465,46 +1503,47 @@ async function driveOneCall(drive) {
     // 3b. The microphone is the host's. With the audio open, the drive mutes it for a moment and
     // reports the leg the provider's record would otherwise miss -- begun, then ended -- and
     // expects each report recorded. If the provider restates the task's record afterwards, the leg is in it.
-    let mutedLeg;
-    if (session !== undefined && typeof session.setMuted === "function" && typeof drive.connection.recordStep === "function") {
+    const reportedLegs = [];
+    const canRecordMute = session !== undefined && typeof session.setMuted === "function" && typeof drive.connection.recordStep === "function";
+    const report = async (body) => {
+        ruleEvaluated("drive.recordStep.rejected", "drive.recordStep.failed");
+        // The drive holds its own report to the contract before it crosses, as a host must.
+        const leg = { taskId, allocationId: allocationOf(), step: "muted", mutedBy: "host", ...body };
+        const own = validateHandlingReport(leg, "drive.recordStep.report", drive.manifest);
+        found.push(...own);
+        if (own.length > 0)
+            return;
+        let answer;
+        try {
+            answer = await drive.connection.recordStep(leg);
+        }
+        catch (error) {
+            refuse("drive.recordStep.rejected", "drive.recordStep", `recordStep rejected rather than answered: ${String(error)}`);
+            return;
+        }
+        found.push(...validateResult(answer, "recordStep", "drive.recordStep.result"));
+        if (isRecord(answer) && answer.status === "failed") {
+            refuse("drive.recordStep.failed", "drive.recordStep", `the provider refused to record the host's muted leg: ${String(isRecord(answer.failure) ? answer.failure.code : answer.failure)}`);
+        }
+    };
+    const setMuted = (muted) => {
+        try {
+            session.setMuted(muted);
+        }
+        catch {
+            refuse("drive.openMedia.setMuted", "drive.openMedia", `the media session threw on setMuted(${String(muted)})`);
+        }
+    };
+    if (canRecordMute) {
         const at = new Date().toISOString();
-        const report = async (body) => {
-            ruleEvaluated("drive.recordStep.rejected", "drive.recordStep.failed");
-            // The drive holds its own report to the contract before it crosses, as a host must.
-            const leg = { taskId, allocationId: allocationOf(), step: "muted", at, mutedBy: "host", ...body };
-            const own = validateHandlingReport(leg, "drive.recordStep.report", drive.manifest);
-            found.push(...own);
-            if (own.length > 0)
-                return;
-            let answer;
-            try {
-                answer = await drive.connection.recordStep(leg);
-            }
-            catch (error) {
-                refuse("drive.recordStep.rejected", "drive.recordStep", `recordStep rejected rather than answered: ${String(error)}`);
-                return;
-            }
-            found.push(...validateResult(answer, "recordStep", "drive.recordStep.result"));
-            if (isRecord(answer) && answer.status === "failed") {
-                refuse("drive.recordStep.failed", "drive.recordStep", `the provider refused to record the host's muted leg: ${String(isRecord(answer.failure) ? answer.failure.code : answer.failure)}`);
-            }
-        };
-        const setMuted = (muted) => {
-            try {
-                session.setMuted(muted);
-            }
-            catch {
-                refuse("drive.openMedia.setMuted", "drive.openMedia", `the media session threw on setMuted(${String(muted)})`);
-            }
-        };
         const began = Date.now();
         setMuted(true);
-        await report({});
+        await report({ at });
         // A leg's duration is whole seconds and a leg shorter than one cannot be stated, so the mute holds for one.
         await new Promise(resolve => setTimeout(resolve, 1000));
         setMuted(false);
-        await report({ seconds: Math.round((Date.now() - began) / 1000), ended: true });
-        mutedLeg = { at, task: latestTask() };
+        await report({ at, seconds: Math.round((Date.now() - began) / 1000), ended: true });
+        reportedLegs.push({ 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.
@@ -1525,8 +1564,18 @@ async function driveOneCall(drive) {
             }
         }
     }
-    // 5. End the call, where the agent may.
+    // 5. End the call, where the agent may -- with the microphone muted, as agents do. The leg left
+    // open at media end is the provider's to close, since the provider knows the instant the media
+    // ended; the host's own closing report can only follow what it hears, is answered recorded, and
+    // changes nothing. So the drive mutes, does not report the end before end-call, and reports it
+    // after the media has ended.
     if (drive.channel === "voice" && latestTask().phase === "in-progress" && offers("endCall")) {
+        let openLeg;
+        if (canRecordMute) {
+            openLeg = { at: new Date().toISOString(), began: Date.now() };
+            setMuted(true);
+            await report({ at: openLeg.at });
+        }
         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
@@ -1541,6 +1590,12 @@ async function driveOneCall(drive) {
             }, cursor);
             if (mediaEnded?.found === "ended")
                 cursor = mediaEnded.at;
+            if (openLeg !== undefined) {
+                setMuted(false);
+                // Stated at the record's grain: a leg that rounds to nought is 1.
+                await report({ at: openLeg.at, seconds: Math.max(1, Math.round((Date.now() - openLeg.began) / 1000)), ended: true });
+                reportedLegs.push({ at: openLeg.at, task: latestTask() });
+            }
             if (await updated(t => t.phase === "completing", "the task completing after its media ended") !== undefined && offers("hold")) {
                 await holdRefusedOutsideHandling();
             }
@@ -1593,11 +1648,13 @@ async function driveOneCall(drive) {
         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) {
+    // The record kept by the provider has every leg the host reported, wherever the provider restated it.
+    for (const reported of reportedLegs) {
+        if (latestTask() === reported.task)
+            continue;
         const history = latestTask().handlingHistory;
         if (isRecord(history) && Array.isArray(history.steps)) {
-            const { at } = mutedLeg;
+            const { at } = reported;
             const leg = history.steps.find(entry => isRecord(entry) && entry.step === "muted" && entry.at === at);
             if (leg === undefined) {
                 refuse("drive.recordStep.history", "drive.recordStep", `the provider restated the task's record after the host reported a muted leg at ${at}, and the leg is not in it`);

package/dist/validation.js

@@ -779,7 +779,7 @@ function validateHandlingHistory(value, path, into, task = {}) {
                 into.require(task.phase === "paused", "task.handlingHistory.held.open", `${at}.seconds`, `a held entry without seconds is a hold still running, and the task is ${String(task.phase)}: the hold has ended, and its duration is stated`);
             }
             if (entry.step === "muted") {
-                into.require(task.media !== "ended" && task.phase !== "completing", "task.handlingHistory.muted.open", `${at}.seconds`, "a muted entry without seconds is a mute still running, and the call is over: the host ends its legs when the media ends, and the duration is stated");
+                into.require(task.media !== "ended" && task.phase !== "completing", "task.handlingHistory.muted.open", `${at}.seconds`, "a muted entry without seconds is a mute still running, and the call is over: the provider closes every open leg at the instant the media ends, and the duration is stated");
             }
         }
         // A muted entry carries whose the silence was, as the host reported it; no other step has it.

package/guide.md

@@ -2064,9 +2064,15 @@ report that: `granted` is a promise to honour a later commit.
 
 Returns the provider's complete authoritative state at one point in time.
 
-- Omni registers `subscribe()` before awaiting the initial snapshot and discards anything delivered
-  while the snapshot is read, because the snapshot accounts for it. Events after it are applied in
-  order.
+- Omni registers `subscribe()` before awaiting the initial snapshot. An event delivered while the
+  snapshot is read is held until it lands, and what happens to it then depends on what it is. A
+  snapshot restates state, so an event of a state-replacing kind -- `task-offered`, `task-updated`,
+  `task-ended`, `task-media-started`, `task-media-ended`, `break-state`, `team-updated`,
+  `contacts-updated`, `calendar-updated`, `transport-status`, `snapshot` -- is dropped, because the
+  snapshot accounts for it. An event that reports a transaction no snapshot carries --
+  `dial-outcome`, `diagnostic`, `announcement`, `queue-summary` -- is applied after the snapshot,
+  in order: a dial's outcome delivered during a resync still ends the dial, and **Every dial has an
+  outcome** holds through a snapshot. Events after it are applied in order.
 - `tasks` must contain every task currently owned by this agent for this provider.
 - A snapshot replaces Omni's state for this provider; it is not a partial patch.
 - The adapter may return synchronously when it already holds current live values, or
@@ -2540,7 +2546,13 @@ only while its media is up, so a `held` entry without `seconds` on a task that i
 (`task.handlingHistory.held.open`, `.muted.open`). Whoever performs the leg closes it — the
 provider whose platform parks the caller, the host whose microphone it is — by restating the entry
 with its duration, and **an entry that cannot be closed is not written**: open for ever is a
-plausible nought one level down from a total. There is no resumed step; a resume is the end of a
+plausible nought one level down from a total. **A leg still open when the media ends is closed by
+the provider**, at that instant, in the same publication that says the media ended: the provider
+is the one that knows the instant, and the host can only learn of it afterwards. Agents end calls
+muted, so the host's leg is routinely open at media end; the provider closes it with the duration
+from the leg's `at` to the media's end, and the host's own closing report for that leg, which
+follows what it hears, is answered `recorded` and changes nothing, the entry standing as the
+provider closed it. One publisher of the closed leg, and no order between them to get right. There is no resumed step; a resume is the end of a
 hold, at the entry's `at` plus its `seconds`, and nothing is lost by not naming it twice. The same goes for every step: two mutes are two
 `muted` entries, and a call that joined two queues -- a menu's, then this one -- has two `queued`
 entries, one per join. Order is enforced: an entry earlier than the one before it is refused
@@ -4347,9 +4359,13 @@ a backend that does not know the session yet — yields no snapshot, and the ada
 `connecting` holding what it holds. See **Snapshots establish state; events report transactions**.
 
 A snapshot must account for **everything the adapter has emitted before it resolves**, not merely
-everything emitted when it was requested. Omni discards events buffered during the read on that
-promise; an adapter that serves a stale snapshot and then lets an earlier event through will have
-Omni apply state the snapshot already superseded.
+everything emitted when it was requested. Omni drops the state-replacing events held during the
+read on that promise, and applies the rest after it (see **`Connection.snapshot()`**); an adapter
+that serves a stale snapshot and then lets an earlier event through will have Omni apply state the
+snapshot already superseded. The harness reads its connect snapshot the same way, and holds the
+snapshot to accounting for every task event it superseded: a task published during the read and
+missing from the snapshot, or ended during the read and still carried, is named
+(`snapshot.accounts.task`, `snapshot.accounts.ended`).
 
 #### Liveness
 
@@ -4725,8 +4741,11 @@ as each case was considered, so a test that needs a rule to have run asserts it
 inferring it from an empty `violations`, and a rule absent from it was never looked at, which is a
 gap and not a pass. With the audio open on a softphone,
 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
+expecting each report `recorded` (`drive.recordStep.failed`, `.rejected`); then it mutes again and
+ends the call muted, as agents do, so the leg is open when the media ends, the provider closes it
+in the completing publication or the open entry is refused (`task.handlingHistory.muted.open`),
+and the drive's closing report after the media ended is expected `recorded` and to change nothing.
+Where the provider restates the task's record afterwards, each 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 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

package/package.json

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