@xema/omni-protocol 0.1.66 → 0.1.68

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateHostMute, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -154,6 +154,8 @@ function observeEvent(envelope, seen) {
  * asynchronous one — which would let a non-conforming async adapter pass.
  */
 export async function exerciseAdapter(adapter, context, options = {}) {
+    const rulesEvaluated = new Set();
+    const stopObserving = observeRules(rule => { rulesEvaluated.add(rule); });
     const violations = [...validateManifest(adapter.manifest)];
     const events = [];
     const seen = new Set();
@@ -198,7 +200,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             self: current().identity.id,
             capabilities: current().capabilities,
             loginId: context.loginId,
-            autoAcceptTasks: context.autoAcceptTasks ?? true,
+            autoAcceptTasks: context.autoAcceptTasks,
         });
         // 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
@@ -301,7 +303,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // record of that leg is the provider's to take; on a desk phone the host holds no microphone.
         if (softphone)
             requireMethod(live, "recordStep", "the login is on a softphone, whose microphone the host mutes");
-        const eventIds = new Set();
+        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 => {
@@ -309,21 +313,48 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
             // A diagnostic is informational to a host and a failure to a conformance run: the platform
             // under test broke a rule the adapter relies on, and a green result must not paper over it.
-            if (isRecord(envelope?.event) && envelope.event.type === "diagnostic") {
+            // A reload in life has no first connection: the page is gone. The drive keeps its first
+            // connection up while the second reads, so a platform that pushes the open task to the new
+            // 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) {
                 violations.push({ rule: "diagnostic.raised", path: "event.diagnostic",
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
-            // Cross-event rules apply once the stream has a beginning: the connect snapshot.
-            if (seeded)
-                violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
+            // Work is pulled, never pushed: an offer before the host stated capacity is an allocation
+            // against nothing, and an offer beyond the count is one too many -- unless the task is the
+            // host's own dial arriving, which counts against nothing.
+            if (isRecord(envelope?.event) && envelope.event.type === "task-offered") {
+                if (capacityStated === undefined) {
+                    violations.push({ rule: "stream.taskOffered.beforeCapacity", path: "event.task",
+                        message: "a task was offered before the host stated any capacity: work is pulled, and nothing is allocated against a capacity nobody stated" });
+                }
+                else if (seeded && stream.openCount() >= capacityStated && !TaskStream.carriesDial(envelope.event.task)) {
+                    violations.push({ rule: "stream.taskOffered.overCapacity", path: "event.task",
+                        message: `a task was offered with ${stream.openCount()} already open against a stated capacity of ${capacityStated}` });
+                }
+            }
+            // A re-delivered envelope is harmless and applied once; the same id carrying a different
+            // payload is a reused id, which no dedupe can make harmless, and is named.
             if (typeof envelope?.id === "string") {
-                if (eventIds.has(envelope.id))
+                const payload = JSON.stringify(envelope.event);
+                const earlier = eventPayloads.get(envelope.id);
+                if (earlier !== undefined) {
+                    if (earlier !== payload) {
+                        violations.push({ rule: "event.id.reused", path: "event.id",
+                            message: `envelope ${envelope.id} was delivered again with a different event: an id names one event for the life of the login` });
+                    }
                     return;
-                eventIds.add(envelope.id);
+                }
+                eventPayloads.set(envelope.id, payload);
             }
+            // Cross-event rules apply once the stream has a beginning: the connect snapshot.
+            if (seeded)
+                violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
             events.push(envelope);
             for (const waiter of waiters)
                 waiter(envelope);
@@ -336,8 +367,26 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         breaks.seed(snapshot);
         seeded = true;
         requireCapabilityMethods(live, current().capabilities);
-        if (publishesUserIds(snapshot))
+        if (publishesUserIds(snapshot)) {
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
+            // Required by presence is not enough: the names the snapshot published are looked up, and what
+            // comes back is held to the shape -- an empty answer to a roster of colleagues is named.
+            const named = userIdsIn(snapshot);
+            if (typeof live.describeUsers === "function" && named.length > 0) {
+                let described;
+                try {
+                    described = await live.describeUsers(named);
+                    violations.push(...validateDescribedUsers(described, named, "connection.describeUsers"));
+                    if (Array.isArray(described) && described.length === 0) {
+                        violations.push({ rule: "connection.describeUsers.empty", path: "connection.describeUsers",
+                            message: `asked about ${named.join(", ")}, whom the snapshot itself named, the provider described nobody` });
+                    }
+                }
+                catch (error) {
+                    violations.push({ rule: "connection.describeUsers.rejected", path: "connection.describeUsers", message: `describeUsers rejected rather than answered: ${String(error)}` });
+                }
+            }
+        }
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection
         // that will not accept one is a connection nothing can be given to.
         // The guide's obligation on a voice adapter: consult the host before declaring the agent
@@ -349,7 +398,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 message: "a voice adapter consults the host's report before declaring the agent ready, and this one never asked",
             });
         }
-        const capacity = await connection.setCapacity({ count: 1 });
+        capacityStated = 1;
+        const capacity = await connection.setCapacity({ count: capacityStated });
         const malformed = validateResult(capacity, "setCapacity", "connection.setCapacity");
         violations.push(...malformed);
         // The provider republishes the agent's day: once connected, the identity carries the zone the
@@ -378,7 +428,7 @@ 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,
+                context: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held, reloading,
             }));
         }
     }
@@ -425,6 +475,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     }
     if (!options.collectOnly)
         assertNoViolations(violations);
+    stopObserving();
     return {
         events: events,
         authenticationState: authenticationState,
@@ -432,6 +483,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         notExercised: CONTRACT_SUBJECTS.filter(subject => !seen.has(subject)),
         disconnectWasClean,
         violations,
+        rulesEvaluated,
     };
 }
 /**
@@ -448,6 +500,42 @@ function publishesUserIds(snapshot) {
         return false;
     return snapshot.tasks.some(taskNamesUsers);
 }
+/** Every UserId a snapshot publishes: on the record, the room, a lead request, an imposed break, the roster. */
+function userIdsIn(snapshot) {
+    const ids = new Set();
+    const add = (value) => { if (typeof value === "string" && value.length > 0)
+        ids.add(value); };
+    add(snapshot?.break?.imposed?.by);
+    const team = snapshot?.team;
+    if (isRecord(team)) {
+        for (const member of Array.isArray(team.members) ? team.members : [])
+            if (isRecord(member))
+                add(member.id);
+        for (const request of Array.isArray(team.requests) ? team.requests : [])
+            if (isRecord(request))
+                add(request.memberId);
+    }
+    for (const task of Array.isArray(snapshot?.tasks) ? snapshot.tasks : []) {
+        const t = task;
+        if (isRecord(t.handlingHistory) && Array.isArray(t.handlingHistory.steps))
+            for (const step of t.handlingHistory.steps)
+                if (isRecord(step))
+                    add(step.by);
+        if (Array.isArray(t.onCall))
+            for (const entry of t.onCall)
+                if (isRecord(entry))
+                    add(entry.userId);
+        if (isRecord(t.leadAssist))
+            add(t.leadAssist.leadId);
+        if (isRecord(t.assisting))
+            add(t.assisting.memberId);
+        if (isRecord(t.monitoring)) {
+            add(t.monitoring.memberId);
+            add(t.monitoring.agentId);
+        }
+    }
+    return [...ids];
+}
 const teamNamesUsers = (team) => isRecord(team) && (some(team.members) || some(team.requests));
 const taskNamesUsers = (task) => isRecord(task) && ((isRecord(task.handlingHistory) && Array.isArray(task.handlingHistory.steps) && task.handlingHistory.steps.some(step => isRecord(step) && step.by !== undefined)) ||
     (isRecord(task.leadAssist) && task.leadAssist.leadId !== undefined) ||
@@ -720,9 +808,26 @@ export function assertDeniedAndRetriedBreak(approvals) {
 // completing or ending, never a phase the audio decided.
 // ---------------------------------------------------------------------------
 const WORK_BEGUN = new Set(["in-progress", "paused", "completing"]);
+/** Where audio can arrive: a task at work. A completing task's call is over; a connect-back returns it to in-progress before any media. */
+const AT_WORK = new Set(["in-progress", "paused"]);
 /** What a stream has said about the tasks it carries, and the rules across events. */
+const TASK_PHASES_ORDERED = ["pending", "confirmed", "preview", "in-progress", "paused", "completing"];
+/** Where a task may be next, by the guide's transition table, closed over the phases between two publications. */
+const REACHABLE_PHASES = {
+    pending: new Set(["pending", "confirmed", "preview", "in-progress", "paused", "completing"]),
+    confirmed: new Set(["confirmed", "preview", "in-progress", "paused", "completing"]),
+    preview: new Set(["preview", "in-progress", "paused", "completing"]),
+    "in-progress": new Set(["in-progress", "paused", "completing"]),
+    paused: new Set(["paused", "in-progress", "completing"]),
+    completing: new Set(["completing"]),
+};
 export class TaskStream {
     tasks = new Map();
+    // Every allocation this login has seen, and the ones whose task has ended: an offer never reuses
+    // one, an event about a task names the life that is open, and a late event for a life that ended
+    // is recognised as that rather than landing on the next customer under the same id.
+    allocations = new Set();
+    endedAllocations = new Set();
     // 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 transfer is known
     // to whoever holds the task now. `answered` or `ended` once its outcome arrived, since it comes once.
@@ -744,6 +849,36 @@ export class TaskStream {
                 this.dialled(entry.dialId);
         }
     }
+    /**
+     * Whether an event about a task names the life that is open under its id. One naming a life that
+     * has ended is the late event the allocation exists to catch; one naming a life nobody has seen is
+     * a different fault. Either way it is not applied to the open task.
+     */
+    namesTheOpenLife(event, known, at, refuse) {
+        const named = event.allocationId;
+        if (typeof named !== "string" || named === known.allocation)
+            return true;
+        if (this.endedAllocations.has(named)) {
+            refuse("stream.allocation.ended", `${at}.allocationId`, `${String(event.type)} names allocation ${named}, a life of ${String(event.taskId)} that has ended; the life open under that id is ${known.allocation}, and a late event lands on the life it names, never the next`);
+        }
+        else {
+            refuse("stream.allocation.unknown", `${at}.allocationId`, `${named} is not an allocation this login has seen`);
+        }
+        return false;
+    }
+    /** How many tasks the stream currently holds open. */
+    openCount() { return this.tasks.size; }
+    /** Whether an offered task is a dial arriving -- the host's own call, a connect-back -- which counts against no capacity: an entry on its call carrying a dial. */
+    static carriesDial(task) {
+        if (!isRecord(task) || !Array.isArray(task.onCall))
+            return false;
+        return task.onCall.some(entry => isRecord(entry) && typeof entry.dialId === "string");
+    }
+    /** Whether the update shows the party being dialled again -- a connect-back, a platform's callback -- the one thing that brings a completing task back. */
+    static partyDialled(task) {
+        return isRecord(task) && Array.isArray(task.onCall)
+            && task.onCall.some(entry => isRecord(entry) && entry.role === "party" && typeof entry.stage === "string");
+    }
     /** The entries of a task's record, each by step and instant, or undefined where the task carries no record. */
     static record(task) {
         if (!isRecord(task) || !isRecord(task.handlingHistory) || !Array.isArray(task.handlingHistory.steps))
@@ -769,7 +904,7 @@ export class TaskStream {
                     stages.set(entry.dialId, entry.stage);
             }
         }
-        return { phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task) };
+        return { 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) };
     }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
@@ -777,8 +912,11 @@ export class TaskStream {
         if (!isRecord(snapshot) || !Array.isArray(snapshot.tasks))
             return;
         for (const task of snapshot.tasks) {
-            if (isRecord(task) && typeof task.id === "string")
+            if (isRecord(task) && typeof task.id === "string") {
                 this.tasks.set(task.id, TaskStream.stated(task));
+                if (typeof task.allocationId === "string")
+                    this.allocations.add(task.allocationId);
+            }
             this.noteDials(task);
         }
     }
@@ -794,6 +932,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) => {
@@ -812,17 +951,27 @@ export class TaskStream {
                 }
                 this.seed(event.snapshot);
                 break;
-            case "task-offered":
+            case "task-offered": {
+                ruleEvaluated("stream.taskOffered.duplicate", "stream.taskOffered.allocation");
                 if (id === undefined)
                     break;
                 if (known !== undefined)
                     refuse("stream.taskOffered.duplicate", `${at}.task.id`, `${id} is already on the stream; an offer introduces a task once`);
+                const allocation = isRecord(event.task) ? event.task.allocationId : undefined;
+                if (typeof allocation === "string") {
+                    if (this.allocations.has(allocation)) {
+                        refuse("stream.taskOffered.allocation", `${at}.task.allocationId`, `${allocation} was already an allocation on this login: an allocation is minted once per offer and never reused, whatever the task id does`);
+                    }
+                    this.allocations.add(allocation);
+                }
                 this.tasks.set(id, TaskStream.stated(event.task));
                 this.noteDials(event.task);
                 break;
+            }
             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");
                 if (known === undefined) {
                     refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
                     break;
@@ -833,6 +982,27 @@ export class TaskStream {
                 if ((known.source === "queue" || known.source === "ungoverned") && isRecord(event.task) && event.task.capabilitySource === "undetermined") {
                     refuse("stream.taskUpdated.capabilitySource", `${at}.task.capabilitySource`, `${id} was published under ${known.source} terms and now says undetermined: terms once read stay read, and a re-read that fails is a diagnostic, not a republish`);
                 }
+                // An update is of the life that is open. One carrying another allocation is a copy of a
+                // different life of this id -- a stale republish of the last customer's call, or the next one's.
+                if (isRecord(event.task) && String(event.task.allocationId) !== known.allocation) {
+                    refuse("stream.taskUpdated.allocation", `${at}.task.allocationId`, `${id} is open as allocation ${known.allocation} and the update says ${String(event.task.allocationId)}: an update restates the life that is open, never another`);
+                }
+                // A task does not go backwards. The stream sees publications, not transitions, and a task may
+                // pass through a phase between two, so what is refused is a phase unreachable from the last
+                // one read by the guide's table: back to pending, back to confirmed once work began, out of
+                // completing except through a connect-back -- which the update itself shows, the party
+                // carrying the host's dial.
+                {
+                    const from = known.phase;
+                    const to = isRecord(event.task) ? String(event.task.phase) : "";
+                    const reachable = REACHABLE_PHASES[from];
+                    if (reachable !== undefined && TASK_PHASES_ORDERED.includes(to) && !reachable.has(to)) {
+                        const connectingBack = from === "completing" && TaskStream.partyDialled(event.task) && (to === "in-progress" || to === "paused");
+                        if (!connectingBack) {
+                            refuse("stream.taskUpdated.phase", `${at}.task.phase`, `${id} was ${from} and the update says ${to}: a task does not go backwards, and ${from === "completing" ? "only the party being dialled again, a connect-back or a callback, with its stage on the call, brings a completing task back" : `${to} is not reachable from ${from}`}`);
+                        }
+                    }
+                }
                 // A record once read is not unread: an update restates it whole, or with more, never with less.
                 {
                     const lost = TaskStream.lost(known.record, TaskStream.record(event.task));
@@ -867,13 +1037,16 @@ export class TaskStream {
                 this.noteDials(event.task);
                 break;
             case "task-media-started":
+                ruleEvaluated("stream.taskMediaStarted.unknown", "stream.taskMediaStarted.beforeWork", "stream.taskMediaStarted.duplicate", "stream.allocation.ended", "stream.allocation.unknown");
                 if (id === undefined)
                     break;
                 if (known === undefined) {
                     refuse("stream.taskMediaStarted.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
                     break;
                 }
-                if (!WORK_BEGUN.has(known.phase)) {
+                if (!this.namesTheOpenLife(event, known, at, refuse))
+                    break;
+                if (!AT_WORK.has(known.phase)) {
                     refuse("stream.taskMediaStarted.beforeWork", `${at}.taskId`, `media cannot arrive on ${id} while it is ${known.phase}: a task is never its audio, and its work has not begun`);
                 }
                 if (known.media === "started") {
@@ -882,12 +1055,15 @@ export class TaskStream {
                 known.media = "started";
                 break;
             case "task-media-ended":
+                ruleEvaluated("stream.taskMediaEnded.unknown", "stream.taskMediaEnded.beforeWork", "stream.taskMediaEnded.silent", "stream.allocation.ended", "stream.allocation.unknown");
                 if (id === undefined)
                     break;
                 if (known === undefined) {
                     refuse("stream.taskMediaEnded.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
                     break;
                 }
+                if (!this.namesTheOpenLife(event, known, at, refuse))
+                    break;
                 if (!WORK_BEGUN.has(known.phase)) {
                     refuse("stream.taskMediaEnded.beforeWork", `${at}.taskId`, `media cannot end on ${id} while it is ${known.phase}: a task is never its audio, and its work has not begun`);
                 }
@@ -897,15 +1073,27 @@ export class TaskStream {
                 known.media = "ended";
                 break;
             case "task-ended":
+                ruleEvaluated("stream.taskEnded.unknown", "stream.allocation.ended", "stream.allocation.unknown");
                 if (id === undefined)
                     break;
-                if (known === undefined)
+                if (known === undefined) {
                     refuse("stream.taskEnded.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
+                    break;
+                }
+                // A late ending for a life that is over must not end the life that is open under the same id.
+                if (!this.namesTheOpenLife(event, known, at, refuse))
+                    break;
+                this.endedAllocations.add(known.allocation);
                 this.tasks.delete(id);
                 break;
             case "dial-outcome": {
                 // An outcome ends a dial somebody placed, once. The task it names may already have ended;
-                // a dial placed late routinely outlives its call, which is why the dial has its own identity.
+                // a dial placed late routinely outlives its call, which is why the dial has its own identity,
+                // and why the outcome names the allocation: the host routes it to that life, ended or not.
+                ruleEvaluated("stream.allocation.unknown");
+                if (typeof event.allocationId === "string" && !this.allocations.has(event.allocationId)) {
+                    refuse("stream.allocation.unknown", `${at}.allocationId`, `${event.allocationId} is not an allocation this login has seen`);
+                }
                 if (typeof event.dialId !== "string")
                     break;
                 const dial = this.dials.get(event.dialId);
@@ -960,6 +1148,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");
         let again;
         try {
             again = drive.rebuild();
@@ -976,7 +1165,17 @@ async function driveOneCall(drive) {
                 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 });
+            // 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();
+            found.push(...validateAuthenticationState(restored, "drive.reload.login"));
+            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)}`);
+                return;
+            }
             second = await again.connect(drive.context);
             const snapshot = await second.snapshot();
             // The second adapter's snapshot is held to everything a first one is.
@@ -987,6 +1186,10 @@ async function driveOneCall(drive) {
                 refuse("drive.reload.snapshot", "drive.reload.snapshot", `a second adapter built from the same login does not carry ${taskId} on its snapshot, and the task is still open`);
                 return;
             }
+            // The allocation is part of the task, not memory beside it: a reload brings the same life back.
+            if (carried.allocationId !== allocationOf()) {
+                refuse("drive.reload.allocation", "drive.reload.allocation", `a second adapter built from the same login carries ${taskId} as allocation ${String(carried.allocationId)}; the first published ${allocationOf()}, and a life does not change its name on a reload`);
+            }
             const history = carried.handlingHistory;
             const steps = isRecord(history) && Array.isArray(history.steps) ? history.steps : [];
             // A record once read is not unread across a reload either: every entry the first adapter published is here.
@@ -1021,6 +1224,7 @@ async function driveOneCall(drive) {
             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
@@ -1028,6 +1232,7 @@ async function driveOneCall(drive) {
     // inherited by the next offer of the same id, since a platform retires an id minutes after closing it.
     let retainedAtEnd;
     const storeReleased = async () => {
+        ruleEvaluated("drive.store.retained");
         await Promise.resolve();
         await Promise.resolve();
         const retained = [...drive.held].filter(key => key.includes(taskId));
@@ -1041,6 +1246,7 @@ async function driveOneCall(drive) {
     const nothingLate = () => {
         if (retainedAtEnd === undefined)
             return;
+        ruleEvaluated("drive.store.late");
         const late = [...drive.held].filter(key => key.includes(taskId) && !retainedAtEnd.has(key));
         if (late.length > 0) {
             refuse("drive.store.late", "drive.store", `${taskId} had ended with its keys gone, and the login's store now holds ${late.join(", ")}: something wrote about the task after its end`);
@@ -1060,6 +1266,7 @@ async function driveOneCall(drive) {
         cursor = offered.at;
     }
     const taskId = task.id;
+    const allocationOf = () => String(latestTask().allocationId);
     const latestTask = () => task;
     const updated = (until, what) => waitFor(what, envelope => {
         const event = envelope.event;
@@ -1075,14 +1282,16 @@ async function driveOneCall(drive) {
         return event.type === "task-ended" && event.taskId === taskId ? event : undefined;
     }, cursor);
     // Every command the drive sends is validated against the task as published, and its answer for its method.
+    ruleEvaluated("drive.timeout");
     const send = async (command, dialId) => {
+        ruleEvaluated("drive.command.rejected", "drive.command.failed");
         const own = validateTaskCommand(command, latestTask(), `drive.command.${String(command.type)}`);
         found.push(...own);
         if (own.length > 0)
             return undefined;
         let result;
         try {
-            result = await drive.connection.execute({ taskId, command });
+            result = await drive.connection.execute({ taskId, allocationId: allocationOf(), command });
         }
         catch (error) {
             refuse("drive.command.rejected", `drive.command.${String(command.type)}`, `execute rejected rather than answered: ${String(error)}`);
@@ -1124,10 +1333,11 @@ async function driveOneCall(drive) {
     // control still declared: a host holds it back (command.phase.handling), and an adapter that
     // receives it anyway must refuse it -- so the drive sends it past the validator and expects failed.
     const holdRefusedOutsideHandling = async () => {
+        ruleEvaluated("drive.command.rejected", "drive.command.handling");
         const phase = String(latestTask().phase);
         let answer;
         try {
-            answer = await drive.connection.execute({ taskId, command: { type: "hold" } });
+            answer = await drive.connection.execute({ taskId, allocationId: allocationOf(), command: { type: "hold" } });
         }
         catch (error) {
             refuse("drive.command.rejected", "drive.command.hold", `execute rejected rather than answered: ${String(error)}`);
@@ -1154,7 +1364,7 @@ async function driveOneCall(drive) {
                 return found;
             cursor = Math.max(cursor, started.at);
         }
-        const opened = await drive.connection.openMedia?.({ taskId, localAudio: drive.localAudio });
+        const opened = await drive.connection.openMedia?.({ taskId, allocationId: allocationOf(), localAudio: drive.localAudio });
         found.push(...validateResult(opened, "openMedia", "drive.openMedia"));
         if (isRecord(opened) && opened.status === "opened")
             session = opened.session;
@@ -1168,8 +1378,9 @@ async function driveOneCall(drive) {
     if (session !== undefined && typeof session.setMuted === "function" && typeof drive.connection.recordStep === "function") {
         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, step: "muted", at, mutedBy: "host", ...body };
+            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)

package/dist/validation.d.ts

@@ -6,6 +6,14 @@ export declare class ProtocolConformanceError extends Error {
 }
 /** Throws `ProtocolConformanceError` when any violation is present. */
 export declare function assertNoViolations(violations: readonly ProtocolViolation[], summary?: string): void;
+/**
+ * Hears every rule a validator evaluates, pass or fail, until the returned function is called. A
+ * green run can then say which rules it looked at rather than only which subjects it reached: a
+ * rule never evaluated is a visible gap, not a pass. The harness registers one for each exercise.
+ */
+export declare function observeRules(listener: (rule: string) => void): () => void;
+/** Says a rule was evaluated, for code that decides outside a collector: the stream, the drive. */
+export declare function ruleEvaluated(...rules: readonly string[]): void;
 /** Every field is optional, so this checks what is present rather than what is missing. */
 export declare function validateContact(contact: unknown, path?: string): ProtocolViolation[];
 export declare function validateScheduledActivity(activity: unknown, path?: string): ProtocolViolation[];
@@ -20,7 +28,7 @@ export interface TaskValidationContext {
     channel: string;
     /** The level ids in force, from the manifest. The defaults when absent. */
     levels?: readonly string[];
-    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
+    /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
     /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
     dialOutcomesDeclared?: boolean;
@@ -45,7 +53,7 @@ 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;
-    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
+    /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
 }
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
@@ -94,6 +102,12 @@ export declare function isTimeZone(value: unknown): value is string;
 export declare function sameTimeZone(a: unknown, b: unknown): boolean;
 /** The zone a host sends at connect: required, and an IANA name. */
 export declare function validateTimeZone(value: unknown, path?: string): ProtocolViolation[];
+/**
+ * What `describeUsers(ids)` answered: an array of users, each one asked for, each a valid identity.
+ * The provider may answer fewer than asked, which is what "unknown to it" looks like; it never
+ * answers somebody nobody asked about.
+ */
+export declare function validateDescribedUsers(users: unknown, asked: readonly string[], path?: string): ProtocolViolation[];
 /** What a login is validated against beyond its own shape. */
 export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */