@xema/omni-protocol 0.1.110 → 0.1.112

package/dist/index.d.ts

@@ -1662,6 +1662,12 @@ export type HistoryReport = {
     ended?: never;
     seconds?: DurationSeconds;
 });
+/**
+ * `at` is the provider's instant for the leg, on its own clock, assigned when the provider writes
+ * the leg into its record and never an echo of the host's: the host keeps the answer as the leg's
+ * identity from then on, and names it on the closing report. A provider that echoes the host's
+ * instant has assigned nothing, and the drive names it (`drive.recordStep.identity`).
+ */
 export type HistoryReportResult = {
     status: "recorded";
     at: IsoTimestamp;

package/dist/testing.d.ts

@@ -151,6 +151,14 @@ export declare class TaskStream {
     private readonly endedAssignments;
     /** Every assignment a `task-offered` introduced, as against one a snapshot carried: each is owed its ending. */
     private readonly offered;
+    /** The last seconds-left value the stream read per task and field, with the provider instant it was published at. */
+    private readonly countdowns;
+    /**
+     * A seconds-left value is the provider's arithmetic at the instant of the publication, never a
+     * value copied from an earlier one: between two publications the countdown loses at least the
+     * seconds the provider's own clock says passed, within a second of rounding.
+     */
+    private holdCountdowns;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;

package/dist/testing.js

@@ -515,8 +515,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 unsubscribeAuthentication = session.subscribe(onAuthenticationState);
                 unsubscribe = second.subscribe(onEnvelope);
                 clientLive = true;
+                // The second client has been told nothing: the switch is per connection, and the reader
+                // holds its connect snapshot to no team until it is sent again, after its capacity.
+                leadFeaturesOn = false;
                 const restated = await second.setCapacity({ count: capacityStated ?? 1 });
                 violations.push(...validateResult(restated, "setCapacity", "drive.reload.setCapacity"));
+                await switchOnLeadFeatures(second, "drive.reload");
             },
         };
         // Every snapshot the run reads, the connect snapshot and a reloaded client's, is read the same
@@ -619,40 +623,44 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         }
         // The provider assumes nothing of the team feature: the application says on every connect,
         // and once it has said on, the whole team is owed, once. Before that nothing of the team
-        // reaches the lead, which the reader held the connect snapshot to.
-        if (current().capabilities.lead === true && typeof live.executeTeam === "function") {
+        // reaches the lead, which the reader held the connect snapshot to. A reloaded client is a
+        // connect too: it is told again, after its capacity, and held the same way.
+        const switchOnLeadFeatures = async (on, at) => {
+            if (current().capabilities.lead !== true || typeof on.executeTeam !== "function")
+                return;
             const from = events.length;
             let switched;
             // On from the moment the application says so: the provider may answer with the team at once.
             leadFeaturesOn = true;
             try {
-                switched = await live.executeTeam({ command: { type: "lead-features", enabled: true } });
+                switched = await on.executeTeam({ command: { type: "lead-features", enabled: true } });
             }
             catch (error) {
                 leadFeaturesOn = false;
-                violations.push({ rule: "team.switch.rejected", path: "connection.executeTeam", message: `lead-features on was rejected: ${String(error)}` });
+                violations.push({ rule: "team.switch.rejected", path: `${at}.executeTeam`, message: `lead-features on was rejected: ${String(error)}` });
             }
-            if (switched !== undefined) {
-                violations.push(...validateResult(switched, "executeTeam", "connection.executeTeam"));
-                ruleEvaluated("team.required");
-                const ms = options.driveTimeoutMs ?? 5000;
-                const isBaseline = (envelope) => isRecord(envelope?.event) && envelope.event.type === "team-updated";
-                const baseline = events.slice(from).some(isBaseline) || await new Promise(resolve => {
-                    const timer = setTimeout(() => { waiters.delete(waiter); resolve(false); }, ms);
-                    const waiter = (envelope) => {
-                        if (!isBaseline(envelope))
-                            return;
-                        clearTimeout(timer);
-                        waiters.delete(waiter);
-                        resolve(true);
-                    };
-                    waiters.add(waiter);
-                });
-                if (!baseline)
-                    violations.push({ rule: "team.required", path: "event.team",
-                        message: `the application switched the team feature on and no team-updated followed within ${ms}ms: the whole team is owed once it is on, members: [] when nobody is in it` });
-            }
-        }
+            if (switched === undefined)
+                return;
+            violations.push(...validateResult(switched, "executeTeam", `${at}.executeTeam`));
+            ruleEvaluated("team.required");
+            const ms = options.driveTimeoutMs ?? 5000;
+            const isBaseline = (envelope) => isRecord(envelope?.event) && envelope.event.type === "team-updated";
+            const baseline = events.slice(from).some(isBaseline) || await new Promise(resolve => {
+                const timer = setTimeout(() => { waiters.delete(waiter); resolve(false); }, ms);
+                const waiter = (envelope) => {
+                    if (!isBaseline(envelope))
+                        return;
+                    clearTimeout(timer);
+                    waiters.delete(waiter);
+                    resolve(true);
+                };
+                waiters.add(waiter);
+            });
+            if (!baseline)
+                violations.push({ rule: "team.required", path: "event.team",
+                    message: `the application switched the team feature on and no team-updated followed within ${ms}ms: the whole team is owed once it is on, members: [] when nobody is in it` });
+        };
+        await switchOnLeadFeatures(live, "connection");
         if (options.drive) {
             const localAudio = isRecord(first) && isRecord(first.audio) && isRecord(first.audio.input) && first.audio.input.status === "available"
                 ? first.audio.input.localAudio : undefined;
@@ -1131,6 +1139,36 @@ export class TaskStream {
     endedAssignments = new Set();
     /** Every assignment a `task-offered` introduced, as against one a snapshot carried: each is owed its ending. */
     offered = new Set();
+    /** The last seconds-left value the stream read per task and field, with the provider instant it was published at. */
+    countdowns = new Map();
+    /**
+     * A seconds-left value is the provider's arithmetic at the instant of the publication, never a
+     * value copied from an earlier one: between two publications the countdown loses at least the
+     * seconds the provider's own clock says passed, within a second of rounding.
+     */
+    holdCountdowns(id, task, publishedAt, at, refuse) {
+        const atMs = typeof publishedAt === "string" ? Date.parse(publishedAt) : Number.NaN;
+        if (!isRecord(task) || Number.isNaN(atMs))
+            return;
+        const known = this.countdowns.get(id) ?? new Map();
+        for (const field of ["expiresInSeconds", "previewEndsInSeconds", "wrapEndsInSeconds"]) {
+            const value = task[field];
+            if (typeof value !== "number") {
+                known.delete(field);
+                continue;
+            }
+            const before = known.get(field);
+            if (before !== undefined) {
+                ruleEvaluated("stream.countdown.copied");
+                const elapsed = Math.floor((atMs - before.atMs) / 1000);
+                if (elapsed > 0 && value > before.value - elapsed + 1) {
+                    refuse("stream.countdown.copied", `${at}.${field}`, `${id} said ${field} ${before.value} at ${new Date(before.atMs).toISOString()} and ${value} at ${new Date(atMs).toISOString()}: ${elapsed}s passed on the provider's clock and the countdown lost fewer; seconds left are worked out at each publication, never copied from the one before`);
+                }
+            }
+            known.set(field, { value, atMs });
+        }
+        this.countdowns.set(id, known);
+    }
     // Every dial the stream can place an outcome against: one the host said it placed, or one a
     // task carried on `onCall` or in its record -- which is how a dial made before a take-over is known
     // to whoever holds the task now. `answered` or `ended` once its outcome arrived, since it comes once.
@@ -1232,6 +1270,11 @@ export class TaskStream {
             snapshot.tasks.forEach((task, index) => {
                 if (!isRecord(task) || typeof task.assignmentId !== "string")
                     return;
+                // A snapshot from a provider with a clock is a publication at providerTime; the countdowns it carries are held to it.
+                if (typeof snapshot.providerTime === "string")
+                    this.holdCountdowns(task.assignmentId, task, snapshot.providerTime, `${at}.tasks[${index}]`, refuse);
+                else
+                    this.countdowns.delete(task.assignmentId);
                 const was = this.tasks.get(task.assignmentId);
                 if (was === undefined)
                     return;
@@ -1300,6 +1343,7 @@ export class TaskStream {
                 this.offered.add(id);
                 this.tasks.set(id, TaskStream.stated(event.task));
                 this.noteDials(event.task);
+                this.holdCountdowns(id, event.task, isRecord(envelope) ? envelope.occurredAt : undefined, `${at}.task`, refuse);
                 break;
             }
             case "task-updated":
@@ -1311,6 +1355,7 @@ export class TaskStream {
                     break;
                 }
                 // The rules about a known task are evaluated only once there is one.
+                this.holdCountdowns(id, event.task, isRecord(envelope) ? envelope.occurredAt : undefined, `${at}.task`, refuse);
                 ruleEvaluated("stream.taskUpdated.capabilitySource", "stream.taskUpdated.phase", "stream.taskUpdated.audioOpen", "stream.taskUpdated.history", "stream.taskAudioEnded.follow", "stream.taskUpdated.audio", "stream.taskUpdated.stage", "stream.taskUpdated.stage.lingering");
                 // Terms once read stay read. A re-read that fails is not a new fact about the task, so the
                 // last statement stands and the failure is a diagnostic; not-yet-read is a place a task
@@ -1662,16 +1707,16 @@ async function driveOneCall(drive) {
         task = offered.found;
         cursor = offered.at;
     }
-    const taskId = task.assignmentId;
+    let taskId = task.assignmentId;
     const latestTask = () => task;
-    const updated = (until, what) => waitFor(what, envelope => {
+    const updated = (until, what, within) => waitFor(what, envelope => {
         const event = envelope.event;
         if ((event.type === "task-updated" || event.type === "task-offered") && isTask(event.task) && event.task.assignmentId === taskId) {
             task = event.task;
             return until(event.task) ? event.task : undefined;
         }
         return undefined;
-    }, cursor).then(hit => { if (hit)
+    }, cursor, within).then(hit => { if (hit)
         cursor = hit.at; return hit; });
     const ended = (within) => waitFor("a task-ended for the driven task", envelope => {
         const event = envelope.event;
@@ -1714,6 +1759,40 @@ async function driveOneCall(drive) {
     // Audio may arrive any time after the accept, before or after the task's own update says
     // in-progress: the event is the provider's word that the audio should attach, never a reply to
     // openAudio, so the drive looks for it from the accept rather than from the last update it read.
+    // 0. A deadline stated is a deadline kept. Where the first offer says how long it has, within
+    // what the drive will wait, the drive leaves it alone and expects the provider to end it expired
+    // when it runs out; the next offer is the one driven. Offers with no deadline, or a longer one,
+    // leave this rule unreached, and the result says so.
+    const settleMs = Number(drive.manifest.settleMs);
+    const lapse = latestTask().phase === "pending" ? latestTask().expiresInSeconds : undefined;
+    if (typeof lapse === "number" && lapse * 1000 <= drive.timeoutMs) {
+        ruleEvaluated("drive.offer.expired");
+        const lapsedId = taskId;
+        let missed = false;
+        const ending = await waitFor(`the expired ending of ${lapsedId}`, envelope => {
+            const event = envelope.event;
+            return event.type === "task-ended" && event.assignmentId === lapsedId ? event : undefined;
+        }, cursor, { ms: lapse * 1000 + settleMs, onExpiry: () => { missed = true; } });
+        if (ending === undefined) {
+            if (missed)
+                refuse("drive.offer.expired", "drive.offer", `${lapsedId} was offered with ${lapse}s to answer and ${lapse * 1000 + settleMs}ms later it has not ended: a deadline stated is a deadline kept, and the offer ends expired naming pending`);
+            return found;
+        }
+        const outcome = isRecord(ending.found.outcome) ? ending.found.outcome : {};
+        if (!(outcome.type === "expired" && outcome.phase === "pending")) {
+            refuse("drive.offer.expired", "drive.offer", `${lapsedId} lapsed unanswered and ended ${String(outcome.type)}: an offer nobody answered before its deadline ends expired naming pending`);
+        }
+        // The next offer is the one driven; a provider with nothing more to offer ends the drive here.
+        const next = await waitFor("a task-offered after the lapsed one", envelope => {
+            const event = envelope.event;
+            return event.type === "task-offered" && isTask(event.task) && event.task.assignmentId !== lapsedId ? event.task : undefined;
+        }, ending.at);
+        if (next === undefined)
+            return found;
+        task = next.found;
+        cursor = next.at;
+        taskId = task.assignmentId;
+    }
     const acceptedAt = drive.events.length;
     // 1. Accept the offer, if it is one.
     if (latestTask().phase === "pending") {
@@ -1722,13 +1801,47 @@ async function driveOneCall(drive) {
         if (await updated(t => t.phase !== "pending", "the task leaving pending after it was accepted") === undefined)
             return found;
     }
-    // 2. A preview: press Call, which is a dial.
+    // 2. A preview: press Call, which is a dial. Where the preview says how long it has, within what
+    // the drive will wait, the deadline is kept to its atDeadline first: under provider-dials the
+    // provider dials when it runs out and the drive presses nothing; under host-dials and waits the
+    // preview stands until then, and the drive presses Call at zero as the desk would.
     if (latestTask().phase === "preview") {
-        const dialId = `drive-${taskId}`;
-        drive.stream.dialled(dialId);
-        if (await send({ type: "dial", dialId }, dialId) === undefined)
-            return found;
-        if (await updated(t => t.phase === "in-progress" || t.phase === "completing", "the task leaving preview after Call") === undefined)
+        const left = latestTask().previewEndsInSeconds;
+        const atDeadline = latestTask().atDeadline;
+        // Under provider-dials the provider places the call, and the desk presses nothing.
+        let pressCall = true;
+        if (typeof left === "number" && left * 1000 <= drive.timeoutMs && typeof atDeadline === "string") {
+            ruleEvaluated("drive.preview.deadline");
+            const ringing = (t) => t.phase !== "preview"
+                || (Array.isArray(t.onCall) && t.onCall.some(who => isRecord(who) && who.role === "party" && who.stage === "ringing"));
+            if (atDeadline === "provider-dials") {
+                let missed = false;
+                const dialled = await updated(ringing, "the provider dialling at the preview's deadline", { ms: left * 1000 + settleMs, onExpiry: () => { missed = true; } });
+                if (dialled === undefined) {
+                    if (!missed)
+                        return found;
+                    refuse("drive.preview.deadline", "drive.preview", `${taskId} is a preview under provider-dials with ${left}s left, and the provider did not dial when it ran out: the party rings on onCall, or the task leaves preview`);
+                    return found;
+                }
+                pressCall = false;
+            }
+            else {
+                // Nothing may move the preview before its deadline under host-dials or waits: the drive
+                // waits the seconds out and expects the task where it left it.
+                const moved = await updated(t => t.phase !== "preview", "nothing", { ms: left * 1000, onExpiry: () => undefined });
+                if (moved !== undefined) {
+                    refuse("drive.preview.deadline", "drive.preview", `${taskId} is a preview under ${atDeadline} with ${left}s left, and the provider moved it to ${String(moved.found.phase)} before the deadline: under ${atDeadline} the preview stands until the desk dials, or for as long as the agent needs`);
+                    return found;
+                }
+            }
+        }
+        if (pressCall && latestTask().phase === "preview") {
+            const dialId = `drive-${taskId}`;
+            drive.stream.dialled(dialId);
+            if (await send({ type: "dial", dialId }, dialId) === undefined)
+                return found;
+        }
+        if (latestTask().phase === "preview" && await updated(t => t.phase === "in-progress" || t.phase === "completing", pressCall ? "the task leaving preview after Call" : "the task leaving preview after the provider's dial") === undefined)
             return found;
     }
     // The other direction of step 4, wherever the task stands outside the interaction phases with the

package/guide/agent.md

@@ -588,8 +588,13 @@ as it begins and ends, and takes the provider's published entry as the closed ac
 it does not reopen the leg, replace the provider's timestamp, or overwrite the provider's final
 duration with a later report. A later agent mute is a new leg, never a reopening of the ended one.
 
-Correlate the provider-published `muted` entry using the provider-selected `at` acknowledged
-for the current report key; a final `seconds` closes that leg under the history contract.
+**The provider assigns the instant.** `HistoryReportResult.at` is the provider's own instant for the
+leg, on its own clock, written when the provider takes the leg into its record, never an echo of
+the `at` the host reported: the host keeps the answer as the leg's identity from then on and names
+it on the closing report, and a provider that echoes the host's instant has assigned nothing
+(`drive.recordStep.identity`). Correlate the provider-published `muted` entry using that
+provider-selected `at` acknowledged for the current report key; a final `seconds` closes that leg
+under the history contract.
 This is identity matching, not reconciliation between clocks. An old closed entry, an unrelated
 task, or a stale connection cannot end a newer local mute. If publication precedes the acknowledgment,
 retain the current provider view and apply the matching closure once correlation is available;

package/guide.md

@@ -2414,6 +2414,25 @@ and no count. A provider that publishes any of these instants therefore declares
 (`manifest.timeCheck.required`) and states `providerTime` on every snapshot
 (`snapshot.providerTime`). Two screens then differ by their delay and nothing else.
 
+**Seconds left are worked out at each publication.** `expiresInSeconds`, `previewEndsInSeconds`,
+`wrapEndsInSeconds` and `expectedEndsInSeconds` are each the provider's arithmetic at the instant
+of the publication that carries them, never a value copied from an earlier one. A provider that
+builds the next publication by spreading the last one forward hands a reloaded desk a countdown
+already spent -- sixty seconds shown beside a lead's screen showing twenty -- and the stream
+names it: between two publications of one countdown the value loses at least the seconds the
+provider's own clock says passed, within a second of rounding (`stream.countdown.copied`, on an
+update against the last publication, and on a snapshot from a provider with a clock against its
+`providerTime`). Under `agent-command` the wrap's value reaches `0` and stays there while the agent
+overruns; that is the true value, not a copy.
+
+**A deadline stated is a deadline kept.** The provider that says how long an offer has ends it
+`expired` when it runs out, and the drive holds it to that: where the first offer carries
+`expiresInSeconds` within the drive's timeout, the drive leaves that offer unanswered and expects
+the `expired` ending within the seconds plus `settleMs`, then drives the next offer
+(`drive.offer.expired`). A preview's deadline is held to its `atDeadline` the same way: under
+`provider-dials` the provider dials when it runs out, under `host-dials` and `waits` the preview
+stands until the desk dials (`drive.preview.deadline`).
+
 #### Optional periodic provider time checks and agent application estimates
 
 A provider may declare `Manifest.timeCheck: true` and implement `Connection.checkTime(request)`.
@@ -2976,7 +2995,10 @@ complete it with an outcome where the agent completes -- and holds every step to
 agent application holds a provider to. Each command is validated against the task as published
 (`drive.command.*`), each answer for its method, a refusal of a control the task offered is a
 violation (`drive.command.failed`), and an event the provider owes and never sends is one too
-(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). Around the drive the exercise holds
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). A first offer that says how long it has is left to
+lapse and expected to end `expired`, and a preview's deadline is held to its `atDeadline`
+(`drive.offer.expired`, `drive.preview.deadline`); see **Every screen counts from the provider's
+clock**. Around the drive the exercise holds
 the run to what an agent application holds a provider to between commands: an offer before the agent application stated
 capacity, or beyond the count with nothing dialled on it, is named
 (`stream.taskOffered.beforeCapacity`, `.overCapacity`); every user the snapshot names is looked up

package/package.json

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