@xema/omni-protocol 0.1.73 → 0.1.75

package/dist/testing.d.ts

@@ -57,6 +57,13 @@ export interface ExerciseAdapterOptions {
      * memory has nothing, and is named. Without it the store is required and never read.
      */
     rebuild?: () => Adapter<Channel>;
+    /**
+     * The values the queue locks on this login's tasks -- a party's number or email -- as the run's
+     * author knows them. A task whose party stands locked may carry none of them anywhere else
+     * (`task.locked.leak`). Required once any task locks a party field: a run that cannot ask the
+     * question is not a pass, and says so by throwing rather than passing.
+     */
+    lockedValues?: readonly string[];
 }
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,
@@ -133,6 +140,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,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const stream = new TaskStream();
     const breaks = new BreakStream();
     let seeded = false;
+    const duringRead = [];
+    let lockedPartySeen = false;
     const storedSecrets = new Map();
     const authenticationSecrets = {
         get: async (key) => storedSecrets.get(key),
@@ -203,6 +205,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             capabilities: current().capabilities,
             loginId: context.loginId,
             autoAcceptTasks: context.autoAcceptTasks,
+            locked: options.lockedValues,
         });
         // The optional methods are optional only until something declares a need for them. Each
         // check pairs a method with the declaration that requires it, as the guide's Live-connection
@@ -340,6 +343,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
+            lockedPartySeen ||= eventTasks(envelope).some(locksParty);
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
             // Work is pulled, never pushed: an offer before the host stated capacity is an allocation
@@ -369,9 +373,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);
@@ -423,9 +430,36 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 tellRefused({ artefact: "snapshot", violations: broken });
         }
         violations.push(...undeterminedTasks(Array.isArray(snapshot?.tasks) ? snapshot.tasks : [], "snapshot.tasks"));
+        lockedPartySeen ||= (Array.isArray(snapshot?.tasks) ? snapshot.tasks : []).some(locksParty);
         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");
@@ -557,6 +591,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             message: "an unsubscribe, disconnect(), or close() threw during shutdown",
         });
     }
+    // A task locked a party field and the run was not told the value: task.locked.leak was never
+    // asked, and a result that cannot say is not returned as one that passed.
+    if (lockedPartySeen && options.lockedValues === undefined) {
+        stopObserving();
+        throw new TypeError("a task locks its party's number or email and the run states no lockedValues: task.locked.leak cannot be evaluated; pass the values the queue locked in options.lockedValues");
+    }
     if (!options.collectOnly)
         assertNoViolations(violations);
     stopObserving();
@@ -697,6 +737,13 @@ export function assertAuthenticationRestoreAndExpiry(states) {
     }
 }
 /** The tasks an envelope carries: the one a task event names, or a snapshot event's list. */
+/** Whether a task's party stands locked on its number or email, which is what obliges a run to state the locked values. */
+function locksParty(task) {
+    if (!isRecord(task) || !isRecord(task.party))
+        return false;
+    const locked = (value) => isRecord(value) && value.lockedBy !== undefined;
+    return locked(task.party.number) || locked(task.party.email);
+}
 function eventTasks(envelope) {
     if (!isRecord(envelope) || !isRecord(envelope.event))
         return [];
@@ -905,6 +952,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 +1520,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 +1581,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 +1607,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 +1665,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.d.ts

@@ -32,6 +32,12 @@ export interface TaskValidationContext {
     autoAcceptTasks?: boolean;
     /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
     dialOutcomesDeclared?: boolean;
+    /**
+     * The values the queue locked on this login's tasks -- a party's number or email -- as whoever
+     * runs the validator knows them. Where a task's party stands locked, no other field of it may
+     * carry one of these. Unknown to a host, which never sees the value, and then unchecked.
+     */
+    locked?: readonly string[];
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
 /**
@@ -53,6 +59,12 @@ export interface ReaderContext {
     levels?: readonly string[];
     /** The login's `loginId`. A snapshot or event naming another belongs to a login that is gone. */
     loginId?: string;
+    /**
+     * The values the queue locked on this login's tasks, as whoever runs the validator knows them:
+     * a conformance run states them, a host never has them. Where a task's party stands locked, no
+     * other field of it may carry one (`task.locked.leak`). Absent, unchecked.
+     */
+    locked?: readonly string[];
     /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
 }

package/dist/validation.js

@@ -598,6 +598,53 @@ const PERSON_SETTABLE = /^(hold|skill:.+)$/;
 const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
 /** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
 const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
+/**
+ * What the queue locks is locked on the whole task. Given the locked values, every other field an
+ * agent reads -- the title, the reference, an attribute, a custom control's label, a browser URL the
+ * desk shows -- is held to carrying none of them. A number is compared by its digits, so no
+ * formatting hides it; anything else by its text, case aside.
+ */
+function validateNothingLeaksInto(task, locked, path, into) {
+    ruleEvaluated("task.locked.leak");
+    const carries = (text, value) => {
+        if (typeof text !== "string")
+            return false;
+        const digits = value.replace(/[\s+().-]/g, "");
+        if (/^\d+$/.test(digits))
+            return text.replace(/\D/g, "").includes(digits);
+        return text.toLowerCase().includes(value.trim().toLowerCase());
+    };
+    const hold = (text, at) => {
+        for (const value of locked) {
+            if (carries(text, value))
+                into.add("task.locked.leak", at, "carries a value the queue locked: what the queue locks is locked on the whole task, and appears nowhere the agent reads");
+        }
+    };
+    hold(task.title, `${path}.title`);
+    hold(task.reference, `${path}.reference`);
+    if (Array.isArray(task.attributes)) {
+        task.attributes.forEach((attribute, index) => {
+            if (!isPlainObject(attribute))
+                return;
+            hold(attribute.label, `${path}.attributes[${index}].label`);
+            hold(attribute.value, `${path}.attributes[${index}].value`);
+            if (isPlainObject(attribute.party)) {
+                hold(attribute.party.number, `${path}.attributes[${index}].party.number`);
+                hold(attribute.party.email, `${path}.attributes[${index}].party.email`);
+            }
+        });
+    }
+    const custom = isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
+    if (Array.isArray(custom))
+        custom.forEach((control, index) => { if (isPlainObject(control))
+            hold(control.label, `${path}.capabilities.custom[${index}].label`); });
+    if (Array.isArray(task.browsers)) {
+        task.browsers.forEach((browser, index) => {
+            if (isPlainObject(browser) && browser.urlVisibility !== "hidden")
+                hold(browser.url, `${path}.browsers[${index}].url`);
+        });
+    }
+}
 /** `lockedBy`: a declared level other than `person`, who never locks their own value. */
 function validateLockedByInto(value, rule, path, levels, into) {
     if (!into.filled(value, rule, path, "lockedBy names the level that locked it"))
@@ -779,7 +826,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.
@@ -1015,6 +1062,9 @@ function validateTaskInto(task, context, path, into) {
     }
     if (task.party !== undefined)
         validateContactInto(task.party, `${path}.party`, into, context.levels);
+    if (context.locked !== undefined && isPlainObject(task.party) && (isLocked(task.party.number) || isLocked(task.party.email))) {
+        validateNothingLeaksInto(task, context.locked, path, into);
+    }
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
@@ -1308,7 +1358,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         let assisting;
         let monitoring;
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${path}.tasks[${index}]`, into);
             // A lead assists one call at a time, and listens to one at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
@@ -1520,7 +1570,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
@@ -1529,7 +1579,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.timestamp(event.allocationExpiresAt, "event.taskOffered.allocationExpiresAt", `${at}.allocationExpiresAt`);
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");

package/guide.md

@@ -831,7 +831,14 @@ lock, so nothing that can be locked — a directory, a number — may carry that
 contact's number and email are the same, since each identifies a person: where the queue says
 the agent may not see it, the provider sends `{ lockedBy }` in its place — the last digits or
 nothing — and a CRM link carries a token, never the value with a flag the desk is asked to honour.
-A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
+**What the queue locks is locked on the whole task.** A number the agent may not see appears
+nowhere else they read — not in the title, the reference, an attribute, a custom control's label,
+or a browser URL the desk shows; a browser whose URL must carry it says `urlVisibility: "hidden"`.
+The adapter is the one that knows the value, so it is the one held to it: given the values the
+queue locked, the validator refuses any other field carrying one, digits compared as digits so no
+formatting hides them (`task.locked.leak`), and a conformance run whose tasks lock a party's number
+or email states those values in `lockedValues`, since a run that cannot ask the question is not a
+pass. A host never has the value and never asks. A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
 controls — is content, and is never locked.
 
 **A lead sets the team's policy from their roster.** A login that declares
@@ -2064,9 +2071,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 +2553,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 +4366,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
 
@@ -4608,7 +4631,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | Function | Validates |
 | --- | --- |
 | `validateManifest(manifest)` | Identity, protocol-version interoperability, authentication methods, and idle-capability shapes. |
-| `validateTask(task, { channel })` | Identity, channel agreement, phase, wrap allowance, capability shapes, custom controls, and browsers. |
+| `validateTask(task, { channel, locked? })` | Identity, channel agreement, phase, wrap allowance, capability shapes, custom controls, and browsers. Given `locked`, the values the queue locked, a task whose party stands locked carries none of them anywhere else (`task.locked.leak`). |
 | `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, the stated `taskCount` reconciled against the tasks carried, and every task, contact, and activity, including idle-capability gating both ways: a contribution the manifest never declared is refused, and one it declares is required, `[]` included. |
 | `validateEventEnvelope(envelope, manifest)` | Envelope identity, timestamp, and the payload for each event type. |
 | `validateContact(contact)` | Contact field shapes and attribute keys. Every field is optional, so this checks what is present rather than what is missing. |
@@ -4725,8 +4748,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.75",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",