@xema/omni-protocol 0.1.67 → 0.1.68

package/dist/index.d.ts

@@ -26,6 +26,14 @@ export type IsoTimestamp = string;
 export type UserId = string;
 /** A non-empty, opaque task identifier unique within one provider. Scope it with `taskKey()`. */
 export type TaskId = string;
+/**
+ * One life of a task on the wire. A platform retires a task id minutes after closing it and a
+ * requeue takes seconds, so the same `TaskId` comes back for another customer while a late dial
+ * outcome or a late handling report for the first is still in flight. The allocation id is minted
+ * once per offer and never reused for the life of the login, and every event, command and report
+ * that names a task names its allocation too, so nothing lands on the next life of the id.
+ */
+export type AllocationId = string;
 /**
  * The host's identity for one dial, minted before the command leaves and unique across the
  * installation. A dial is the one command whose outcome arrives later and apart, so the provider
@@ -770,6 +778,7 @@ export interface TaskAssisting {
 export interface TaskMonitoring {
     memberId: UserId;
     taskId: TaskId;
+    allocationId: AllocationId;
     mode: MonitorMode;
     since: IsoTimestamp;
 }
@@ -826,6 +835,8 @@ export type CapabilitySource = "queue" | "ungoverned" | "undetermined";
 export declare const CAPABILITY_SOURCES: readonly ["queue", "ungoverned", "undetermined"];
 export type Task<C extends Channel = Channel> = {
     id: TaskId;
+    /** This life of the task: minted once per offer, never reused for the life of the login. See `AllocationId`. */
+    allocationId: AllocationId;
     title: string;
     channel: C;
     /** The provider's own name for a category of work. Finer-grained than a channel. */
@@ -1035,6 +1046,7 @@ export interface CustomTaskCommand {
 export type TaskCommand<C extends Channel = Channel> = (C extends "voice" ? VoiceTaskCommand : C extends "chat" ? ChatTaskCommand : EmailTaskCommand) | CustomTaskCommand;
 export interface TaskCommandRequest<C extends Channel = Channel> {
     taskId: TaskId;
+    allocationId: AllocationId;
     command: TaskCommand<C>;
 }
 /**
@@ -1182,6 +1194,7 @@ export interface LeadRequest {
     id: string;
     memberId: UserId;
     taskId: TaskId;
+    allocationId: AllocationId;
     note?: string;
     since: IsoTimestamp;
 }
@@ -1280,6 +1293,7 @@ export interface VoiceMediaSession {
 }
 export interface OpenMediaRequest {
     taskId: TaskId;
+    allocationId: AllocationId;
     /** The agent's microphone as Omni captured it, `HostReport.audio.input.localAudio`; absent while that input is `unavailable`. */
     localAudio?: MediaStream;
 }
@@ -1339,6 +1353,7 @@ export type SetPreferenceRequest = {
  */
 export type HandlingReport = {
     taskId: TaskId;
+    allocationId: AllocationId;
     at: IsoTimestamp;
 } & (
 /** A muted leg says whose the silence was: the host's own Mute, or the station's slider or system. */
@@ -1427,12 +1442,15 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-media-started";
     taskId: TaskId;
+    allocationId: AllocationId;
 } | {
     type: "task-media-ended";
     taskId: TaskId;
+    allocationId: AllocationId;
 } | {
     type: "task-ended";
     taskId: TaskId;
+    allocationId: AllocationId;
     outcome: TaskOutcome;
 }
 /**
@@ -1447,6 +1465,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     dialId: DialId;
     outcome: DialOutcome;
     taskId?: TaskId;
+    allocationId?: AllocationId;
     destinationId?: string;
     reason?: string;
 } | {
@@ -1463,6 +1482,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
     expected: string;
     observed: string;
     taskId?: TaskId;
+    allocationId?: AllocationId;
 } | {
     type: "team-updated";
     team: TeamRoster;
@@ -1603,6 +1623,8 @@ export interface BrowserSessionKeyInput {
     /** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
     providerId: string;
     taskId: TaskId;
+    /** The task's allocation: a task-scoped session lives one life of the task, never the next customer's under a reused id. */
+    allocationId: AllocationId;
     /** `Task.taskType`. */
     taskType: string;
     browser: TaskBrowser;

package/dist/index.js

@@ -196,7 +196,7 @@ export function sameCapabilities(a, b) {
  * cannot collide with a provider called `a` and a tab called `b`.
  */
 export function browserSessionKey(input) {
-    const { providerId, taskId, taskType, browser } = input;
+    const { providerId, allocationId, taskType, browser } = input;
     if (browser.sharedSession !== true)
         return undefined;
     // `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
@@ -204,7 +204,7 @@ export function browserSessionKey(input) {
     const part = (value) => encodeURIComponent(value).replaceAll(".", "%2E");
     switch (browser.isolationScheme) {
         case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_ID__TAB_NAME:
-            return `${part(providerId)}.${part(taskId)}.${part(browser.name)}`;
+            return `${part(providerId)}.${part(allocationId)}.${part(browser.name)}`;
         case BROWSER_ISOLATION_SCHEMES.TAB_NAME:
             return part(browser.name);
         case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME:

package/dist/testing.d.ts

@@ -135,10 +135,18 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
 export declare class TaskStream {
     private readonly tasks;
+    private readonly allocations;
+    private readonly endedAllocations;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
     private noteDials;
+    /**
+     * 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.
+     */
+    private namesTheOpenLife;
     /** How many tasks the stream currently holds open. */
     openCount(): number;
     /** 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. */

package/dist/testing.js

@@ -305,6 +305,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             requireMethod(live, "recordStep", "the login is on a softphone, whose microphone the host mutes");
         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 => {
@@ -312,7 +313,12 @@ 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)}` });
             }
@@ -422,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,
             }));
         }
     }
@@ -817,6 +823,11 @@ const REACHABLE_PHASES = {
 };
 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.
@@ -838,6 +849,23 @@ 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. */
@@ -876,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) {
@@ -884,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);
         }
     }
@@ -920,19 +951,27 @@ export class TaskStream {
                 }
                 this.seed(event.snapshot);
                 break;
-            case "task-offered":
-                ruleEvaluated("stream.taskOffered.duplicate");
+            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.handlingHistory", "stream.taskMediaEnded.follow", "stream.taskUpdated.media", "stream.taskUpdated.stage");
+                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;
@@ -943,6 +982,11 @@ 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
@@ -993,13 +1037,15 @@ export class TaskStream {
                 this.noteDials(event.task);
                 break;
             case "task-media-started":
-                ruleEvaluated("stream.taskMediaStarted.unknown", "stream.taskMediaStarted.beforeWork", "stream.taskMediaStarted.duplicate");
+                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 (!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`);
                 }
@@ -1009,13 +1055,15 @@ export class TaskStream {
                 known.media = "started";
                 break;
             case "task-media-ended":
-                ruleEvaluated("stream.taskMediaEnded.unknown", "stream.taskMediaEnded.beforeWork", "stream.taskMediaEnded.silent");
+                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`);
                 }
@@ -1025,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);
@@ -1088,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();
@@ -1104,6 +1165,7 @@ 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.
@@ -1124,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.
@@ -1158,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
@@ -1165,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));
@@ -1178,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`);
@@ -1197,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;
@@ -1212,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)}`);
@@ -1261,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)}`);
@@ -1291,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;
@@ -1305,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.js

@@ -131,6 +131,7 @@ const isDurationSeconds = (value) => typeof value === "number" && Number.isInteg
 /** Opaque, non-empty, provider-issued. Never parsed and never compared across providers. */
 const isUserId = isFilled;
 const isTaskId = isFilled;
+const isAllocationId = isFilled;
 const ruleListeners = new Set();
 /**
  * Hears every rule a validator evaluates, pass or fail, until the returned function is called. A
@@ -941,6 +942,7 @@ function validateMonitoring(value, channel, path, into) {
     }
     into.require(isUserId(value.memberId), "task.monitoring.memberId", `${path}.memberId`, "a monitored call names the member on it");
     into.require(isTaskId(value.taskId), "task.monitoring.taskId", `${path}.taskId`, "a monitored call names the member's task");
+    into.require(isAllocationId(value.allocationId), "task.monitoring.allocationId", `${path}.allocationId`, "a monitored call names the member's task by its allocation too");
     into.oneOf(value.mode, MONITOR_MODES, "task.monitoring.mode", `${path}.mode`);
     into.timestamp(value.since, "task.monitoring.since", `${path}.since`);
 }
@@ -955,6 +957,7 @@ function validateTaskInto(task, context, path, into) {
         return;
     }
     into.require(isTaskId(task.id), "task.id", `${path}.id`, "a task needs a non-empty id");
+    into.require(isAllocationId(task.allocationId), "task.allocationId", `${path}.allocationId`, "a task names this life of itself: an allocation id minted once per offer, never reused for the life of the login");
     into.filled(task.title, "task.title", `${path}.title`, "a task needs a title");
     into.filled(task.taskType, "task.taskType", `${path}.taskType`, "a task needs a task type");
     if (into.oneOf(task.phase, TASK_PHASES, "task.phase", `${path}.phase`) && task.phase === "preview") {
@@ -1234,6 +1237,7 @@ function validateTeamRosterInto(roster, path, context, into) {
                     into.require(request.memberId !== context.self, "team.request.self", `${at}.memberId`, "the roster carries the reader's own ask: an agent's request for a lead goes to whoever leads them");
                 }
                 into.require(isTaskId(request.taskId), "team.request.taskId", `${at}.taskId`, "a request names the task the lead would join");
+                into.require(isAllocationId(request.allocationId), "team.request.allocationId", `${at}.allocationId`, "a request names the task by its allocation too");
                 if (request.note !== undefined)
                     into.filled(request.note, "team.request.note", `${at}.note`, "a note must not be empty when present");
                 into.timestamp(request.since, "team.request.since", `${at}.since`);
@@ -1522,12 +1526,15 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");
+            into.require(isAllocationId(event.allocationId), "event.taskMediaStarted.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             break;
         case "task-media-ended":
             into.require(isTaskId(event.taskId), "event.taskMediaEnded.taskId", `${at}.taskId`, "a task id is required");
+            into.require(isAllocationId(event.allocationId), "event.taskMediaEnded.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             break;
         case "task-ended":
             into.require(isTaskId(event.taskId), "event.taskEnded.taskId", `${at}.taskId`, "a task id is required");
+            into.require(isAllocationId(event.allocationId), "event.taskEnded.allocationId", `${at}.allocationId`, "an event about a task names its allocation");
             validateTaskOutcome(event.outcome, `${at}.outcome`, into);
             break;
         case "dial-outcome": {
@@ -1539,6 +1546,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             if (event.taskId !== undefined)
                 into.require(isTaskId(event.taskId), "event.dialOutcome.taskId", `${at}.taskId`, "taskId must be a task id when present");
+            allocationWithTask(event, "event.dialOutcome", at, into);
             if (event.destinationId !== undefined)
                 into.filled(event.destinationId, "event.dialOutcome.destinationId", `${at}.destinationId`, "a destinationId must not be empty when present");
             if (event.reason !== undefined)
@@ -1559,6 +1567,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             into.filled(event.observed, "event.diagnostic.observed", `${at}.observed`, "a diagnostic states what was observed instead");
             if (event.taskId !== undefined)
                 into.require(isTaskId(event.taskId), "event.diagnostic.taskId", `${at}.taskId`, "taskId must be a task id when present");
+            allocationWithTask(event, "event.diagnostic", at, into);
             break;
         case "queue-summary":
             validateQueueSummary(event.summary, `${at}.summary`, into);
@@ -1744,6 +1753,7 @@ export function validateHandlingReport(report, path = "handlingReport", manifest
         return into.violations;
     }
     into.require(isTaskId(report.taskId), "handlingReport.taskId", `${path}.taskId`, "a report names the task");
+    into.require(isAllocationId(report.allocationId), "handlingReport.allocationId", `${path}.allocationId`, "a report names the task's allocation, so a late one never lands on the next life of the id");
     into.oneOf(report.step, HANDLING_STEPS, "handlingReport.step", `${path}.step`);
     into.timestamp(report.at, "handlingReport.at", `${path}.at`);
     // A muted leg says whose the silence was; no other leg has anyone to name for it.
@@ -1776,6 +1786,15 @@ function validateMutedBy(device, rule, path, into) {
         into.require(device.mutedBy === undefined, `${rule}.mutedBy.unexpected`, `${path}.mutedBy`, "mutedBy says who silenced a device that is not flowing; a flowing one names nobody");
     }
 }
+/** An event that may name a task names its allocation with it, and never an allocation alone. */
+function allocationWithTask(event, rule, at, into) {
+    if (event.taskId !== undefined) {
+        into.require(isAllocationId(event.allocationId), `${rule}.allocationId`, `${at}.allocationId`, "an event that names a task names its allocation too");
+    }
+    else {
+        into.require(event.allocationId === undefined, `${rule}.allocationId.unexpected`, `${at}.allocationId`, "an allocation is named with its task, never alone");
+    }
+}
 export function validateHostReport(report, path = "host") {
     const into = new Collector();
     if (!isPlainObject(report)) {

package/guide.md

@@ -97,6 +97,7 @@ the semantic name in every contract field rather than repeating the primitive ty
 type IsoTimestamp = string;
 type UserId = string;
 type TaskId = string;
+type AllocationId = string;
 type DialId = string;
 type DurationSeconds = number;
 ```
@@ -396,7 +397,7 @@ type SetPreferenceRequest =
   | { id: PreferenceId; enabled: boolean }
   | { id: PreferenceId; inherit: true };
 
-type HandlingReport = { taskId: TaskId; at: IsoTimestamp } & (
+type HandlingReport = { taskId: TaskId; allocationId: AllocationId; at: IsoTimestamp } & (
   | { step: "muted"; mutedBy: MutedBy }
   | { step: Exclude<HandlingStep, "muted">; mutedBy?: never }
 ) & (
@@ -552,6 +553,7 @@ type PersonalBrowser = Browser;
 type BrowserSessionKeyInput = {
   providerId: string;
   taskId: TaskId;
+  allocationId: AllocationId;
   taskType: string;
   browser: TaskBrowser;
 };
@@ -643,6 +645,7 @@ type TaskAssisting = {
 type TaskMonitoring = {
   memberId: UserId;
   taskId: TaskId;
+  allocationId: AllocationId;
   mode: MonitorMode;
   since: IsoTimestamp;
 };
@@ -667,6 +670,7 @@ type CapabilitySource = "queue" | "ungoverned" | "undetermined";
 
 type Task<C extends Channel = Channel> = {
   id: TaskId;
+  allocationId: AllocationId;
   title: string;
   channel: C;
   taskType: string;
@@ -772,6 +776,7 @@ type TaskCommand<C extends Channel = Channel> =
 
 type TaskCommandRequest<C extends Channel = Channel> = {
   taskId: TaskId;
+  allocationId: AllocationId;
   command: TaskCommand<C>;
 };
 
@@ -924,6 +929,7 @@ type LeadRequest = {
   id: string;
   memberId: UserId;
   taskId: TaskId;
+  allocationId: AllocationId;
   note?: string;
   since: IsoTimestamp;
 };
@@ -1003,6 +1009,7 @@ type OpenMediaResult =
 
 type OpenMediaRequest = {
   taskId: TaskId;
+  allocationId: AllocationId;
   localAudio?: MediaStream;
 };
 ```
@@ -1033,13 +1040,13 @@ type ProviderEvent =
       allocationExpiresAt?: IsoTimestamp;
     }
   | { type: "task-updated"; task: Task }
-  | { type: "task-media-started"; taskId: TaskId }
-  | { type: "task-media-ended"; taskId: TaskId }
-  | { type: "task-ended"; taskId: TaskId; outcome: TaskOutcome }
-  | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; taskId?: TaskId; destinationId?: string; reason?: string }
+  | { type: "task-media-started"; taskId: TaskId; allocationId: AllocationId }
+  | { type: "task-media-ended"; taskId: TaskId; allocationId: AllocationId }
+  | { type: "task-ended"; taskId: TaskId; allocationId: AllocationId; outcome: TaskOutcome }
+  | { type: "dial-outcome"; dialId: DialId; outcome: DialOutcome; taskId?: TaskId; allocationId?: AllocationId; destinationId?: string; reason?: string }
   | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
   | { type: "queue-summary"; summary: QueueSummary }
-  | { type: "diagnostic"; expected: string; observed: string; taskId?: TaskId }
+  | { type: "diagnostic"; expected: string; observed: string; taskId?: TaskId; allocationId?: AllocationId }
   | { type: "team-updated"; team: TeamRoster }
   | { type: "contacts-updated"; contacts: Contact[] }
   | { type: "calendar-updated"; scheduledActivities: ScheduledActivity[] };
@@ -2221,7 +2228,8 @@ time. Runtime conformance checks also require the task channel to match its prov
 
 | Field | Contract |
 | --- | --- |
-| `id` | Required `TaskId`, unique within the provider. Omni scopes it with the provider ID. |
+| `id` | Required `TaskId`, the platform's own identity for the task. Unique among the tasks open at once; a platform retires an id minutes after closing it, so the same id comes back for another customer. Omni scopes it with the provider ID. |
+| `allocationId` | Required `AllocationId`: this life of the task, minted once per offer and never reused for the life of the login, whatever the id does. Every event, command and report that names a task names its allocation too, so a late dial outcome or a late handling report for the first customer never lands on the next under the same id. The stream refuses an offer reusing one (`stream.taskOffered.allocation`), an update restating another life of the id (`stream.taskUpdated.allocation`), and a media or ending event naming a life that has ended or that nobody has seen (`stream.allocation.ended`, `.unknown`); a `dial-outcome` may name an ended life, since a dial placed late routinely outlives its call, and the host routes it there. See **A task's life on the wire**. |
 | `title` | Agent-facing task title. |
 | `channel` | Channel handling this task. It must equal the source provider's manifest channel. |
 | `taskType` | Required provider-defined source or category of work, such as a voice `Queue Name`, `Mailbox Folder`, `Chat Source`, `Support`, `Billing`, or `Returns`. |
@@ -2287,6 +2295,24 @@ The canonical task transitions are:
 | `completing` | Agent connects back to the party (`connect-back`) | `in-progress` |
 | Any phase | Provider emits `task-ended` | Removed |
 
+#### A task's life on the wire
+
+A task id is the platform's, and platforms reuse them: a closed id is retired minutes later, a
+requeue takes seconds, and on one platform a call was offered twice, thirteen seconds apart, under
+one id, through a close and a re-offer. Everything that names a task after the fact -- a dial
+outcome, a media event, an ending, a handling report, a command -- would land on whichever life of
+the id is open when it arrives. So every offer mints an `allocationId`, unique for the life of the
+login, and every one of those names it beside the `taskId`. The host keys its state on the pair, a
+late event finds the life it belongs to or is refused, and a task-scoped browser session
+(`PROVIDER_NAME__TASK_ID__TAB_NAME`) lives one allocation, never the next customer's cookies under
+a reused id. A dial the host placed was already safe, since its outcome is placed by the host's own
+`dialId`; where the allocation earns its place is everything the host does not mint --
+`task-media-started`, `task-media-ended`, `task-ended`, a `recordStep` naming a task -- any of which
+would otherwise find the new task under the old id and act on it. The allocation is part of the task
+the adapter keeps, not a field held in memory beside it: a rebuilt adapter comes back with the same
+allocation on the same task, or every late event it was minted to catch mismatches
+(`drive.reload.allocation`).
+
 Allocation, acceptance, and progress are distinct. Acceptance follows `autoAcceptTasks` and the
 task's `acceptance`, moving the task from `pending` to `confirmed`. The provider reports
 subsequent transitions to `preview` or `in-progress`; Omni does not infer them from the acceptance
@@ -2603,11 +2629,12 @@ writes it into its record as it writes every other leg:
 ```ts
 declare const connection: Connection<"voice">;
 declare const taskId: TaskId;
+declare const allocationId: AllocationId;
 declare const at: IsoTimestamp;
 
-void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host" });                          // the moment the agent mutes
-void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host", seconds: 15 });             // still running, if the host chooses to say
-void connection.recordStep?.({ taskId, step: "muted", at, mutedBy: "host", seconds: 42, ended: true }); // the moment they unmute
+void connection.recordStep?.({ taskId, allocationId, step: "muted", at, mutedBy: "host" });                          // the moment the agent mutes
+void connection.recordStep?.({ taskId, allocationId, step: "muted", at, mutedBy: "host", seconds: 15 });             // still running, if the host chooses to say
+void connection.recordStep?.({ taskId, allocationId, step: "muted", at, mutedBy: "host", seconds: 42, ended: true }); // the moment they unmute
 ```
 
 The entry is keyed by `step` and `at`, so every report about one leg names the same instant. The
@@ -2724,7 +2751,7 @@ The supported `BrowserIsolationScheme` values, declared under **Shapes**, key as
 
 | Enum member | Example session key |
 | --- | --- |
-| `PROVIDER_NAME__TASK_ID__TAB_NAME` | `mailflow.EMAIL-829102.CRM` |
+| `PROVIDER_NAME__TASK_ID__TAB_NAME` | `mailflow.EMAIL-829102%2Ea1.CRM` -- the task's allocation, so one life of the id, never the next customer's cookies |
 | `TAB_NAME` | `CRM` |
 | `PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME` | `mailflow.Support.CRM` |
 | `PROVIDER_NAME__TAB_NAME` | `mailflow.CRM` |
@@ -3085,15 +3112,16 @@ across the installation, and it travels four ways so no leg is a lookup:
 ```ts
 declare const connection: Connection<"voice">;
 declare const taskId: TaskId;
+declare const allocationId: AllocationId;
 
 // 1. Out, minted by the host.
-const result = await connection.execute({ taskId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
+const result = await connection.execute({ taskId, allocationId, command: { type: "conference", action: "add", dialId: "dial-7f2", destinationId: "tier2" } });
 
 // 2. Back on the result, restated, so the host compares and confirms.
 expect(result).toEqual({ status: "dialling", dialId: "dial-7f2" });
 
 // 3. On the outcome, however late, against the task it belonged to.
-const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", taskId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
+const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", taskId, allocationId, destinationId: "tier2", outcome: "no-answer", reason: "No route to destination" };
 
 // 4. In the record, so a dial made before a transfer is placeable by whoever holds the task now.
 const step: TaskHandlingStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", destinationId: "tier2" };
@@ -3769,7 +3797,7 @@ executeTeamMonitor({ command: { type: "monitor", memberId: "A-1" } })
 
 // 2. The lead's own task arrives -- task-offered with `automatic`, as a joined call does -- and
 //    carries `monitoring`; the task id is the lead's, the member's call is named inside it.
-//    monitoring: { memberId: "A-1", taskId: "call-42", mode: "monitor", since }
+//    monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-42", mode: "monitor", since }
 
 // 3. The lead changes how they are heard; the provider restates the task with the new mode.
 executeTeamMonitor({ command: { type: "whisper" } })
@@ -3806,7 +3834,7 @@ const monitoringLead = {
   channel: "voice",
   capabilities: {},
   phase: "in-progress",
-  monitoring: { memberId: "A-1", taskId: "call-42", mode: "whisper", since: "2026-08-21T09:04:00Z" },
+  monitoring: { memberId: "A-1", taskId: "call-42", allocationId: "alloc-42", mode: "whisper", since: "2026-08-21T09:04:00Z" },
 } satisfies Pick<Task<"voice">, "channel" | "capabilities" | "phase" | "monitoring">;
 ```
 
@@ -4438,7 +4466,8 @@ when a lead who joined it leaves -- see **Lead assist**.
 A successful `complete` or `transfer` command does not clear the task. Omni waits for `task-ended`.
 The `task-media-ended` event and the `completing` phase are likewise non-terminal. A replacement
 snapshot that no longer contains the task also clears it. Repeated `task-ended` delivery with the
-same envelope ID is harmless.
+same envelope ID is harmless, and a `task-ended` naming an allocation that has already ended is
+recognised as the late event it is, never applied to the life now open under the same id.
 
 ### `dial-outcome`
 
@@ -4475,7 +4504,7 @@ fails loudly rather than passing with a note. A task published under `capability
 | --- | --- |
 | `expected` | Required. The rule that was broken, as a sentence a person can read. |
 | `observed` | Required. What the platform answered instead. |
-| `taskId` | Optional. The task concerned, where there is one. |
+| `taskId` | Optional. The task concerned, where there is one, with its `allocationId` beside it: a task is named with its life, and an allocation never alone. |
 
 ### `queue-summary`
 

package/package.json

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