@xema/omni-protocol 0.1.76 → 0.1.77

package/dist/testing.d.ts

@@ -170,6 +170,15 @@ export declare class TaskStream {
     /** What a restated record lost of the one read before it: nothing, or the entries by step and instant. */
     private static lost;
     private static stated;
+    /**
+     * Takes a resync snapshot -- a `snapshot` event, or the read a reloaded client makes -- as the
+     * state now, and first holds it to what the stream knew. A snapshot replaces state; it does not
+     * get to forget it. A task it carries that the stream already held may not go backwards, lose an
+     * entry of its record, return to undetermined terms, or be at work without the audio the stream
+     * held up: media ends on task-media-ended and the call moves on, so a task still in-progress or
+     * paused without its media is a snapshot that lost state, not a call that ended.
+     */
+    resync(snapshot: unknown, at: string): ProtocolViolation[];
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot: unknown): void;
     /** Applies one envelope and returns what it may not say given what came before. */

package/dist/testing.js

@@ -1047,6 +1047,49 @@ export class TaskStream {
             wrapAllowance: isRecord(task) && typeof task.wrapAllowance === "number" ? task.wrapAllowance : undefined,
             phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task), allocation: String(isRecord(task) ? task.allocationId : undefined) };
     }
+    /**
+     * Takes a resync snapshot -- a `snapshot` event, or the read a reloaded client makes -- as the
+     * state now, and first holds it to what the stream knew. A snapshot replaces state; it does not
+     * get to forget it. A task it carries that the stream already held may not go backwards, lose an
+     * entry of its record, return to undetermined terms, or be at work without the audio the stream
+     * held up: media ends on task-media-ended and the call moves on, so a task still in-progress or
+     * paused without its media is a snapshot that lost state, not a call that ended.
+     */
+    resync(snapshot, at) {
+        const found = [];
+        const refuse = (rule, where, message) => found.push({ rule, path: where, message });
+        ruleEvaluated("stream.snapshot.capabilitySource", "stream.snapshot.handlingHistory", "stream.snapshot.phase", "stream.snapshot.media");
+        if (isRecord(snapshot) && Array.isArray(snapshot.tasks)) {
+            snapshot.tasks.forEach((task, index) => {
+                if (!isRecord(task) || typeof task.id !== "string")
+                    return;
+                const was = this.tasks.get(task.id);
+                if (was === undefined || was.allocation !== String(task.allocationId))
+                    return;
+                if ((was.source === "queue" || was.source === "ungoverned") && task.capabilitySource === "undetermined") {
+                    refuse("stream.snapshot.capabilitySource", `${at}.tasks[${index}].capabilitySource`, `${task.id} was published under ${was.source} terms and the snapshot says undetermined: terms once read stay read`);
+                }
+                // A record once read is not unread: a resync restates it whole, or with more, never with less.
+                const lost = TaskStream.lost(was.record, TaskStream.record(task));
+                if (lost.length > 0) {
+                    refuse("stream.snapshot.handlingHistory", `${at}.tasks[${index}].handlingHistory`, `${task.id}'s record lost ${lost.join(", ")} on the snapshot: an entry read by the host stays in the record until the task ends`);
+                }
+                const to = String(task.phase);
+                const reachable = REACHABLE_PHASES[was.phase];
+                if (reachable !== undefined && TASK_PHASES_ORDERED.includes(to) && !reachable.has(to)) {
+                    const connectingBack = was.phase === "completing" && TaskStream.partyDialled(task) && (to === "in-progress" || to === "paused");
+                    if (!connectingBack) {
+                        refuse("stream.snapshot.phase", `${at}.tasks[${index}].phase`, `${task.id} was ${was.phase} and the snapshot says ${to}: a task does not go backwards, on an update or on a resync`);
+                    }
+                }
+                if (was.media === "started" && (to === "in-progress" || to === "paused") && task.media !== "started") {
+                    refuse("stream.snapshot.media", `${at}.tasks[${index}].media`, `${task.id}'s audio was up and the snapshot carries it ${to} without it: media ends on task-media-ended and the call moves on, so a snapshot that forgets the audio lost state`);
+                }
+            });
+        }
+        this.seed(snapshot);
+        return found;
+    }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
         this.tasks.clear();
@@ -1073,24 +1116,7 @@ export class TaskStream {
         const known = id === undefined ? undefined : this.tasks.get(id);
         switch (event.type) {
             case "snapshot":
-                ruleEvaluated("stream.snapshot.capabilitySource", "stream.snapshot.handlingHistory");
-                // A snapshot replaces what is known, and still may not say a task lost terms it had read.
-                if (isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks)) {
-                    event.snapshot.tasks.forEach((task, index) => {
-                        if (!isRecord(task) || typeof task.id !== "string")
-                            return;
-                        const was = this.tasks.get(task.id);
-                        if (was !== undefined && (was.source === "queue" || was.source === "ungoverned") && task.capabilitySource === "undetermined") {
-                            refuse("stream.snapshot.capabilitySource", `${at}.snapshot.tasks[${index}].capabilitySource`, `${task.id} was published under ${was.source} terms and the snapshot says undetermined: terms once read stay read`);
-                        }
-                        // A record once read is not unread: a resync restates it whole, or with more, never with less.
-                        const lost = TaskStream.lost(was?.record, TaskStream.record(task));
-                        if (lost.length > 0) {
-                            refuse("stream.snapshot.handlingHistory", `${at}.snapshot.tasks[${index}].handlingHistory`, `${task.id}'s record lost ${lost.join(", ")} on the snapshot: an entry read by the host stays in the record until the task ends`);
-                        }
-                    });
-                }
-                this.seed(event.snapshot);
+                found.push(...this.resync(event.snapshot, `${at}.snapshot`));
                 break;
             case "task-offered": {
                 ruleEvaluated("stream.taskOffered.duplicate", "stream.taskOffered.allocation");
@@ -1346,9 +1372,11 @@ async function driveOneCall(drive) {
             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, and the streams take it as the state now.
+            // The second adapter's snapshot is held to everything a first one is, and the streams take it
+            // as the state now the way they take any resync: held to what they knew, then replaced. A reload
+            // is a place the stream's rules keep working, not one where they all stop.
             found.push(...validateSnapshot(snapshot, again.manifest, "drive.reload.snapshot", drive.reader()));
-            drive.streams.stream.seed(snapshot);
+            found.push(...drive.streams.stream.resync(snapshot, "drive.reload.snapshot"));
             drive.streams.breaks.seed(snapshot);
             const carried = isRecord(snapshot) && Array.isArray(snapshot.tasks)
                 ? snapshot.tasks.find(task => isRecord(task) && task.id === taskId) : undefined;

package/guide.md

@@ -2888,7 +2888,10 @@ last statement stands and the failure is a `diagnostic`, and a task that was pub
 `queue` or `ungoverned` never returns to `undetermined`, on an update (`stream.taskUpdated.capabilitySource`)
 or on a resync snapshot (`stream.snapshot.capabilitySource`); a record once read never loses an
 entry the same two ways (`stream.taskUpdated.handlingHistory`, `stream.snapshot.handlingHistory`);
-and a task does not go backwards (`stream.taskUpdated.phase`): the stream sees publications, not
+a snapshot carrying a task still at work does not forget the audio the stream held up, since media
+ends on `task-media-ended` and the call moves on (`stream.snapshot.media`); and a task does not go
+backwards, on an update or on a resync (`stream.taskUpdated.phase`, `stream.snapshot.phase`): the
+stream sees publications, not
 transitions, and a task may pass through a phase between two, so `pending` to `in-progress` stands
 with `confirmed` between them, and what is refused is a phase unreachable from the last one read by
 the transition table -- back to `pending`, back to `confirmed` or `preview` once work began, out of
@@ -4781,7 +4784,11 @@ built and connected for the same login with the same context and the same `store
 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
+`.rejected`). The second adapter's snapshot is taken as any resync is: held to what the stream knew
+before it replaces it, so a phase gone backwards, a record that shrank or audio forgotten on a task
+still at work is named by the stream's own rules (`stream.snapshot.phase`, `.handlingHistory`,
+`.media`) and a reload is a place those rules keep working, not one where they stop. 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

package/package.json

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