@xema/omni-protocol 0.1.117 → 0.1.119

package/dist/index.d.ts

@@ -513,40 +513,61 @@ export interface TaskRecordingPolicy {
         storageId: string;
     };
 }
-/** Current evidence only. Expiry/disconnect means unknown, never a historical stop. */
-export type RecordingState = {
-    status: "unknown";
-    observationId?: never;
-    observedAt?: never;
-    validUntil?: never;
-    recordingId?: never;
-} | ({
-    observationId: string;
-    observedAt: IsoTimestamp;
-    validUntil: IsoTimestamp;
+/** Whose side of the call a recording captures: the party's channel, or the agent's own. */
+export type RecordingSide = "party" | "agent";
+export declare const RECORDING_SIDES: readonly ["party", "agent"];
+/**
+ * Where a recording stands, as its recorder last stated it. `starting` is asked for and not yet
+ * confirmed. A stop or a pause in flight stays `recording` until the recorder confirms it, since
+ * telling the agent they are not recorded when they may be is the one thing this must never say.
+ */
+export type RecordingStatus = "starting" | "recording" | "paused" | "not-recording" | "unknown";
+export declare const RECORDING_STATUSES: readonly ["starting", "recording", "paused", "not-recording", "unknown"];
+/** Why a recording is paused: someone asked, or the platform paused it while sensitive details are taken. */
+export type RecordingPausedReason = "requested" | "sensitive-details";
+export declare const RECORDING_PAUSED_REASONS: readonly ["requested", "sensitive-details"];
+/** Why a recording's state is unknown: its recorder cannot be reached, or a command could not be settled either way. */
+export type RecordingUnknownReason = "recorder-unreachable" | "unsettled";
+export declare const RECORDING_UNKNOWN_REASONS: readonly ["recorder-unreachable", "unsettled"];
+/**
+ * One recording of one side of the call, published whenever it changes and restated whole with
+ * every publication of the task and on every snapshot. Nothing expires: the mark stands as last
+ * stated until its recorder says otherwise. `id` is the recorder's, minted when the start is
+ * accepted -- before the recorder has answered -- and kept through pause and resume; a later
+ * start is a new recording with a new id.
+ */
+export type Recording = {
+    id: string;
+    follows: RecordingSide;
 } & ({
-    status: "inactive";
-    recordingId?: never;
+    status: "starting" | "recording" | "not-recording";
+    reason?: never;
 } | {
-    status: "active" | "paused";
-    recordingId: string;
-}));
-/** Opaque IDs are scoped by login, task and recorder owner; preserved across pause/resume. */
+    status: "paused";
+    reason: RecordingPausedReason;
+} | {
+    status: "unknown";
+    reason: RecordingUnknownReason;
+});
+/**
+ * A start names the side to record; every other action names the recording by its id, and the
+ * recorder refuses one that no longer stands where the action needs it.
+ */
 export type RecordingCommand = {
     type: "recording";
     source: RecordingSource;
-    /** Compare-and-set against current evidence; never act on a replacement recording. */
-    observationId: string;
 } & ({
     action: "start";
+    follows: RecordingSide;
     recordingId?: never;
 } | {
     action: "pause" | "resume" | "stop" | "cancel";
     recordingId: string;
+    follows?: never;
 });
 export interface HostRecordingReport {
     assignmentId: AssignmentId;
-    state: RecordingState;
+    recordings: Recording[];
 }
 /** Host declaration in ConnectContext, not the provider-owned Manifest. */
 export interface HostRecording {
@@ -834,7 +855,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     type: "timestamp";
     at: IsoTimestamp;
 });
-export type HistoryStep = "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered";
+export type HistoryStep = "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered" | "callback-requested";
 /**
  * The call record: the steps that brought the task here, one entry per occurrence and oldest
  * first, and what they add up to before this agent -- stated by the provider from its own record,
@@ -869,8 +890,9 @@ export interface TaskHistoryStep {
      */
     seconds?: DurationSeconds;
     /**
-     * Who took part. Absent on `queued`, where nobody does; absent on any other step means the
-     * provider could not attribute it, which is a different claim and a legitimate one.
+     * Who took part. Absent on `queued`, where nobody does; absent on `callback-requested`, where the
+     * caller chose it in the queue, and present there when an agent arranged it; absent on any other
+     * step means the provider could not attribute it, which is a different claim and a legitimate one.
      */
     by?: UserId;
     /** On a `muted` step, and only there: whose the silence was, as the host reported it. */
@@ -1064,15 +1086,13 @@ export type Task<C extends Channel = Channel> = {
     attributes?: TaskAttribute[];
     history?: TaskHistory;
 } & TaskCompletion & (C extends "voice" ? {
-    recording?: {
-        provider?: RecordingState;
-    };
+    recordings?: Recording[];
     onCall?: OnCall[];
     leadAssist?: TaskLeadAssist;
     takenOver?: TaskTakenOver;
     audio?: TaskAudioState;
 } : {
-    recording?: never;
+    recordings?: never;
     onCall?: never;
     leadAssist?: never;
     takenOver?: never;
@@ -1878,7 +1898,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.break-forced-by-provider"];
+export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.assignment-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed", "omni.recording-unsettled", "omni.on-hold", "omni.break-forced-by-provider"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 /**
  * What the host refused, told to the adapter that published it: a snapshot the host would not
@@ -2022,7 +2042,10 @@ export declare const assignmentKey: (providerId: string, assignmentId: Assignmen
  * same provider; anything wider goes through this.
  */
 export declare const userKey: (providerId: string, userId: UserId) => string;
-/** Every history step somebody takes part in. `queued` is the one nobody does. */
+/**
+ * Every history step somebody from the provider takes part in. `queued` is the one nobody does, and
+ * `callback-requested` is the caller's choice unless an agent arranged it, so neither is here.
+ */
 export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];
 /** The steps a dial writes, and so the only ones that carry a `dialId` and a `destinationId`. */
 export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "conferenced", "unanswered"];

package/dist/index.js

@@ -32,6 +32,10 @@ export const LISTENING_MODES = ["listen", "coach", "join-call"];
 export const MUTED_BY = ["host", "station"];
 export const HOST_MUTES = ["stream", "station"];
 export const RECORDING_ACTIONS = ["start", "pause", "resume", "stop", "cancel"];
+export const RECORDING_SIDES = ["party", "agent"];
+export const RECORDING_STATUSES = ["starting", "recording", "paused", "not-recording", "unknown"];
+export const RECORDING_PAUSED_REASONS = ["requested", "sensitive-details"];
+export const RECORDING_UNKNOWN_REASONS = ["recorder-unreachable", "unsettled"];
 // ---------------------------------------------------------------------------
 // Task workspace.
 // ---------------------------------------------------------------------------
@@ -107,6 +111,8 @@ export const OMNI_FAILURE_CODES = [
     "omni.break-already-committed",
     /** A recording command the provider could not settle either way: no start, stop, pause or resume it can vouch for. */
     "omni.recording-unsettled",
+    /** Refused because the caller is on hold: the host's Mute, or end-call, waits for resume. */
+    "omni.on-hold",
     /** A lead asked to lift a break the platform itself imposed; the platform lifts its own. */
     "omni.break-forced-by-provider",
 ];
@@ -158,7 +164,10 @@ export const assignmentKey = (providerId, assignmentId) => `${encodeURIComponent
  * same provider; anything wider goes through this.
  */
 export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
-/** Every history step somebody takes part in. `queued` is the one nobody does. */
+/**
+ * Every history step somebody from the provider takes part in. `queued` is the one nobody does, and
+ * `callback-requested` is the caller's choice unless an agent arranged it, so neither is here.
+ */
 export const HISTORY_STEPS_WITH_A_PERSON = [
     "offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered",
 ];

package/dist/testing.d.ts

@@ -160,8 +160,13 @@ export declare class TaskStream {
      */
     private holdCountdowns;
     private readonly dials;
+    private readonly placedHere;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
+    /** A dial the test placed itself and the provider answered dialling: it is owed exactly one outcome. */
+    placedByTest(dialId: string): void;
+    /** The dials the test placed that never got their outcome. */
+    dialsWithoutOutcome(): string[];
     private noteDials;
     /**
      * Why an event names no open task: the assignment ended, so this is the late event that must not
@@ -210,8 +215,6 @@ export declare class TeamStream {
     private static ids;
     /** A snapshot carrying a team is the team whole; one carrying none leaves the lead with none. */
     seed(snapshot: unknown): void;
-    /** Whether the team currently carries this member, as the events left it. */
-    has(id: string): boolean;
     apply(envelope: unknown, path?: string): ProtocolViolation[];
 }
 export declare class BreakStream {
@@ -250,6 +253,15 @@ export declare function stillHost(report?: HostReport, guarantees?: HostGuarante
     mute?: never;
     recording?: never;
 };
+/**
+ * One call's history as it reaches a second task: an earlier agent's task and a later one of the same
+ * call -- a hand-over, a take-over, a callback. The later task restates every earlier step, in order,
+ * as the earlier task had it: the same step, instant, person, dial and destination, and the same
+ * duration wherever the earlier task had already stated one (a leg still open there may be closed
+ * here). Throws on the first step that disagrees, and when either task carries no history, since
+ * two absent records agree about nothing.
+ */
+export declare function assertHistoryAgreesAcrossTasks(earlier: Task, later: Task): void;
 /** One provider as the host sees it when freezing the providers a break attempt asks. */
 export interface BreakCandidate {
     id: string;

package/dist/testing.js

@@ -689,6 +689,12 @@ export async function testAdapter(adapter, context, options = {}) {
                 violations.push({ rule: "stream.taskOffered.unended", path: "event.task-ended",
                     message: `${id} was offered and never ended: every offer is owed a task-ended, whatever became of the call` });
             }
+            // Every dial the test placed, and the provider answered dialling, is owed exactly one outcome.
+            ruleTested("stream.dialOutcome.missing");
+            for (const id of stream.dialsWithoutOutcome()) {
+                violations.push({ rule: "stream.dialOutcome.missing", path: "event.dial-outcome",
+                    message: `${id} was answered dialling and never got its dial-outcome: every dial ends in exactly one, however it ended` });
+            }
         }
         // Capacity supersedes rather than accumulates, so a decrease is as ordinary as an increase: the
         // host raises it, lowers it, and takes it away, and the provider takes each as the ceiling it is.
@@ -915,6 +921,10 @@ export function assertAuthenticationRestoreAndExpiry(states) {
     }
 }
 /** The tasks an envelope carries: the one a task event names, or a snapshot event's list. */
+/** The failure code of a failed answer, as the provider stated it. */
+function failureCode(answer) {
+    return isRecord(answer.failure) ? answer.failure.code : undefined;
+}
 /** Whether a published state ends the session, so its stored secrets must already be gone. */
 function sessionEnded(state) {
     return state.status === "signed-out" || state.status === "terminated"
@@ -1189,11 +1199,19 @@ export class TaskStream {
     // task carried on `onCall` or in its record -- which is how a dial made before a take-over is known
     // to whoever holds the task now. `answered` or `ended` once its outcome arrived, since it comes once.
     dials = new Map();
+    placedHere = new Set();
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId) {
         if (!this.dials.has(dialId))
             this.dials.set(dialId, "placed");
     }
+    /** A dial the test placed itself and the provider answered dialling: it is owed exactly one outcome. */
+    placedByTest(dialId) {
+        this.dialled(dialId);
+        this.placedHere.add(dialId);
+    }
+    /** The dials the test placed that never got their outcome. */
+    dialsWithoutOutcome() { return [...this.placedHere].filter(id => this.dials.get(id) === "placed"); }
     noteDials(task) {
         if (!isRecord(task))
             return;
@@ -1856,6 +1874,7 @@ async function testOneCall(call) {
             call.stream.dialled(dialId);
             if (await send({ type: "dial", dialId }, dialId) === undefined)
                 return found;
+            call.stream.placedByTest(dialId);
         }
         if (latestTask().phase === "preview" && await updated(t => t.phase === "in-progress" || t.phase === "completing", pressCall ? "the task leaving preview after Call" : "the task leaving preview after the provider's dial") === undefined)
             return found;
@@ -1992,6 +2011,9 @@ async function testOneCall(call) {
         if (isRecord(answer) && answer.status !== "failed") {
             refuse("test.recordStep.held", "test.recordStep", "the provider recorded the host's mute begun with the caller on hold: the Mute waits for resume, and the adapter is the second gate");
         }
+        else if (isRecord(answer) && failureCode(answer) !== "omni.on-hold") {
+            refuse("test.recordStep.held", "test.recordStep", `the provider refused the mute begun on hold as ${String(failureCode(answer))}: a refusal because the caller is on hold answers omni.on-hold, so the agent application can say resume first`);
+        }
     };
     // Ending my part from hold would leave the caller in the hold with nobody coming back to them: a
     // host holds it back (command.endCall.held), and an adapter that receives it anyway must refuse
@@ -2011,6 +2033,9 @@ async function testOneCall(call) {
             // Applied, the task leaves paused; the run reads where the adapter put it rather than resuming a call it ended.
             await updated(t => t.phase !== "paused", "the task after an end-call applied from hold");
         }
+        else if (isRecord(answer) && failureCode(answer) !== "omni.on-hold") {
+            refuse("test.command.held", "test.command.end-call", `the provider refused end-call on hold as ${String(failureCode(answer))}: a refusal because the caller is on hold answers omni.on-hold, so the agent application can say resume first`);
+        }
     };
     // 4. Hold and resume, where offered.
     if (latestTask().phase === "in-progress" && offers("hold")) {
@@ -2210,8 +2235,6 @@ export class TeamStream {
     seed(snapshot) {
         this.members = TeamStream.ids(isRecord(snapshot) ? snapshot.team : undefined);
     }
-    /** Whether the team currently carries this member, as the events left it. */
-    has(id) { return this.members?.has(id) === true; }
     apply(envelope, path = "event") {
         const event = isRecord(envelope) ? envelope.event : undefined;
         if (!isRecord(event))
@@ -2343,6 +2366,39 @@ export function memoryStore() {
 export function stillHost(report = { online: true }, guarantees = {}, mute) {
     return { guarantees, ...(mute === undefined ? {} : { mute }), report: () => report, subscribe: () => () => undefined };
 }
+/**
+ * One call's history as it reaches a second task: an earlier agent's task and a later one of the same
+ * call -- a hand-over, a take-over, a callback. The later task restates every earlier step, in order,
+ * as the earlier task had it: the same step, instant, person, dial and destination, and the same
+ * duration wherever the earlier task had already stated one (a leg still open there may be closed
+ * here). Throws on the first step that disagrees, and when either task carries no history, since
+ * two absent records agree about nothing.
+ */
+export function assertHistoryAgreesAcrossTasks(earlier, later) {
+    const steps = (task, which) => {
+        const history = task.history;
+        if (history === undefined || !Array.isArray(history.steps)) {
+            throw new Error(`The ${which} task ${task.assignmentId} carries no history to compare`);
+        }
+        return history.steps;
+    };
+    const before = steps(earlier, "earlier");
+    const after = steps(later, "later");
+    if (after.length < before.length) {
+        throw new Error(`${later.assignmentId} restates ${after.length} step(s) of the call and ${earlier.assignmentId} already had ${before.length}: a later task carries every earlier step`);
+    }
+    before.forEach((step, index) => {
+        const restated = after[index];
+        for (const field of ["step", "at", "by", "dialId", "destinationId", "mutedBy"]) {
+            if (step[field] !== restated[field]) {
+                throw new Error(`steps[${index}].${field} is ${String(step[field])} on ${earlier.assignmentId} and ${String(restated[field])} on ${later.assignmentId}: one call has one history`);
+            }
+        }
+        if (step.seconds !== undefined && restated.seconds !== step.seconds) {
+            throw new Error(`steps[${index}].seconds is ${step.seconds} on ${earlier.assignmentId} and ${String(restated.seconds)} on ${later.assignmentId}: a stated duration does not change`);
+        }
+    });
+}
 const usableLogin = (status) => status === "authenticated" || status === "refreshing";
 /**
  * A break one provider forces stops the agent everywhere: the host states a capacity of zero on

package/dist/validation.d.ts

@@ -1,4 +1,4 @@
-import { type RecordingState, type Channel, type Phone, type ProtocolViolation, type UserCapabilities, type UserId } from "./index.js";
+import { type Channel, type Phone, type ProtocolViolation, type UserCapabilities, type UserId } from "./index.js";
 export type { ProtocolViolation } from "./index.js";
 export declare class ProtocolConformanceError extends Error {
     readonly violations: readonly ProtocolViolation[];
@@ -198,24 +198,34 @@ export declare function validateAuthenticationFailure(failure: unknown, path?: s
  */
 export declare function validateAuthenticationResult(result: unknown, method: "start" | "complete", path?: string, context?: LoginValidationContext): ProtocolViolation[];
 export declare function validateAuthenticationState(state: unknown, path?: string, context?: LoginValidationContext): ProtocolViolation[];
-export declare function validateRecordingState(value: unknown, path?: string): ProtocolViolation[];
-/** Supply a trusted current instant in the observer's clock domain. Undefined means clock unknown. */
-export declare function effectiveRecordingState(state: RecordingState | undefined, now: number | undefined): RecordingState;
+/**
+ * One recorder's recordings for one task, as published: each with its id, the side it follows,
+ * its status, and a reason where it is paused or unknown; ids unique, and at most one recording
+ * live on each side at once.
+ */
+export declare function validateRecordings(value: unknown, path?: string): ProtocolViolation[];
 export declare function validateRecordingPolicy(value: unknown, path?: string): ProtocolViolation[];
 export declare function validateHostRecording(value: unknown, softphone: boolean, path?: string): ProtocolViolation[];
 export declare function validateHostRecordings(value: unknown, path?: string): ProtocolViolation[];
 export declare function validateRecordingCommandShape(value: unknown, source: "provider" | "host", path?: string): ProtocolViolation[];
-/** Structural/state permission check. Dispatch MUST also call validateRecordingRequest for scope and freshness. */
-export declare function validateRecordingCommandState(command: unknown, policy: unknown, state: unknown, path?: string): ProtocolViolation[];
-/** Validate immediately before dispatch using current task, host report and trusted observer-domain time. */
+/**
+ * Whether the action is permitted on this recorder, and whether the recordings as last published
+ * let it act: a start on a side with nothing capturing, every other action on the recording it
+ * names, standing where the action needs it. Dispatch MUST also call validateRecordingRequest.
+ */
+export declare function validateRecordingCommandState(command: unknown, policy: unknown, recordings: unknown, path?: string): ProtocolViolation[];
+/** Validate immediately before dispatch, against the current task and, for the host's recorder, its declaration and report. */
 export declare function validateRecordingRequest(request: unknown, task: unknown, context: {
     source: "provider" | "host";
-    now: number | undefined;
     host?: unknown;
     hostReport?: unknown;
     softphone?: boolean;
     /** The same provider/task context used to validate the published task. */
     taskContext?: Omit<TaskValidationContext, "channel">;
 }, path?: string): ProtocolViolation[];
-/** Check recording-specific result semantics against the owner's confirming observations. */
+/**
+ * A recording command's answer against the recordings published before and after it: applied
+ * means the recorder confirmed what was asked -- a new recording on the side for a start, the
+ * same recording in its new status for anything else -- and failed means nothing changed there.
+ */
 export declare function validateRecordingOutcome(command: unknown, before: unknown, after: unknown, result: unknown, path?: string): ProtocolViolation[];

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { RECORDING_ACTIONS, SHIFT_EVENT_KINDS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
+import { RECORDING_ACTIONS, SHIFT_EVENT_KINDS, RECORDING_SIDES, RECORDING_STATUSES, RECORDING_PAUSED_REASONS, RECORDING_UNKNOWN_REASONS, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HISTORY_STEPS_THAT_DIAL, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, TASK_COMMAND_NAMES, negotiateProtocolVersion, DEFAULT_LEVELS, effectiveLevels, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -59,6 +59,7 @@ const TEAM_AVAILABILITIES = membersOf({
 });
 const HISTORY_STEPS = membersOf({
     queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
+    "callback-requested": true,
 });
 const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
 const CUSTOM_UI_PLACEMENTS = membersOf({ primary: true, secondary: true, overflow: true });
@@ -1214,16 +1215,11 @@ function validateTaskInto(task, context, path, into) {
     if (context.locked !== undefined && isPlainObject(task.party) && (isLocked(task.party.number) || isLocked(task.party.email))) {
         validateNothingLeaksInto(task, context.locked, path, into);
     }
-    if (task.recording !== undefined) {
-        into.require(context.channel === "voice", "recording.task.channel", `${path}.recording`, "recording is voice-only");
-        if (!isPlainObject(task.recording))
-            into.add("recording.task.shape", `${path}.recording`, "expected provider recording state");
-        else {
-            for (const key of Object.keys(task.recording))
-                into.require(key === "provider", "recording.task.owner", `${path}.recording.${key}`, "host state belongs in HostReport, never provider task updates");
-            if (task.recording.provider !== undefined)
-                into.violations.push(...validateRecordingState(task.recording.provider, `${path}.recording.provider`));
-        }
+    // The provider's own recordings, a list; the host's are on its report, never on a provider's task.
+    into.require(task.recording === undefined, "recording.task.renamed", `${path}.recording`, "a task carries the provider's recordings as recordings, a list with the side each follows; the former recording state is not accepted");
+    if (task.recordings !== undefined) {
+        into.require(context.channel === "voice", "recording.task.channel", `${path}.recordings`, "recording is voice-only");
+        into.violations.push(...validateRecordings(task.recordings, `${path}.recordings`));
     }
     if (context.member !== true)
         validateBrowsers(task.browsers, `${path}.browsers`, into);
@@ -2786,7 +2782,7 @@ export function validateTaskCommand(command, task, path = "command", taskContext
             if (!offered("recording"))
                 break;
             const policy = isPlainObject(capabilities.recording) ? capabilities.recording.provider : undefined;
-            const state = isPlainObject(task.recording) ? task.recording.provider : undefined;
+            const state = task.recordings ?? [];
             into.violations.push(...validateRecordingCommandState(command, policy, state, path));
             if (command.action === "start" || command.action === "resume") {
                 interaction();
@@ -3163,7 +3159,7 @@ export function validateAuthenticationState(state, path = "authentication", cont
     }
     return into.violations;
 }
-// Independent current recording evidence and dispatch validation.
+// Recordings: published on change, restated whole, never expiring; and dispatch validation.
 const object = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const filled = (v) => typeof v === "string" && v.trim().length > 0;
 function collector() {
@@ -3180,40 +3176,49 @@ function collector() {
     };
     return { violations, check, keys };
 }
-/** Recording observations use canonical UTC millisecond instants, never native capture boundaries. */
-function instant(v) {
-    if (typeof v !== "string" || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(v))
-        return false;
-    const n = Date.parse(v);
-    return Number.isFinite(n) && new Date(n).toISOString() === v;
-}
-export function validateRecordingState(value, path = "recording") {
+/** A recording that is, or may be, capturing: its side has no room for a second start. */
+const LIVE_RECORDING = ["starting", "recording", "paused", "unknown"];
+/**
+ * One recorder's recordings for one task, as published: each with its id, the side it follows,
+ * its status, and a reason where it is paused or unknown; ids unique, and at most one recording
+ * live on each side at once.
+ */
+export function validateRecordings(value, path = "recordings") {
     const { violations, check, keys } = collector();
-    if (!object(value)) {
-        check(false, "state.shape", path, "expected recording state");
-        return violations;
-    }
-    if (value.status === "unknown") {
-        keys(value, ["status"], path);
+    if (!Array.isArray(value)) {
+        check(false, "list.shape", path, "recordings are a list, empty when nothing has been recorded");
         return violations;
     }
-    check(["inactive", "active", "paused"].includes(value.status), "state.status", `${path}.status`, "expected unknown, inactive, active or paused");
-    keys(value, ["status", "observationId", "observedAt", "validUntil", ...(value.status === "inactive" ? [] : ["recordingId"])], path);
-    check(filled(value.observationId), "observationId", `${path}.observationId`, "a confirming observation has an opaque identity");
-    check(instant(value.observedAt), "observedAt", `${path}.observedAt`, "expected canonical UTC millisecond observation instant");
-    check(instant(value.validUntil), "validUntil", `${path}.validUntil`, "expected canonical UTC millisecond expiry instant");
-    if (instant(value.observedAt) && instant(value.validUntil))
-        check(value.observedAt < value.validUntil, "expiry", path, "expiry must be strictly after observation");
-    if (value.status !== "inactive")
-        check(filled(value.recordingId), "recordingId", `${path}.recordingId`, "active and paused states identify the actual recording");
+    const ids = new Set();
+    const live = new Set();
+    value.forEach((entry, index) => {
+        const at = `${path}[${index}]`;
+        if (!object(entry)) {
+            check(false, "shape", at, "a recording is an object");
+            return;
+        }
+        keys(entry, ["id", "follows", "status", "reason"], at);
+        check(filled(entry.id), "id", `${at}.id`, "a recording names itself by its recorder's id");
+        check(!ids.has(entry.id), "id.unique", `${at}.id`, "two recordings share an id");
+        ids.add(entry.id);
+        check(RECORDING_SIDES.includes(entry.follows), "follows", `${at}.follows`, "a recording follows the party's side or the agent's");
+        if (!check(RECORDING_STATUSES.includes(entry.status), "status", `${at}.status`, "a recording is starting, recording, paused, not-recording or unknown"))
+            return;
+        const reasons = entry.status === "paused" ? RECORDING_PAUSED_REASONS
+            : entry.status === "unknown" ? RECORDING_UNKNOWN_REASONS : undefined;
+        if (reasons !== undefined) {
+            check(reasons.includes(entry.reason), "reason", `${at}.reason`, `a ${String(entry.status)} recording says why: ${reasons.join(", ")}`);
+        }
+        else {
+            check(entry.reason === undefined, "reason.unexpected", `${at}.reason`, "only a paused or unknown recording carries a reason");
+        }
+        if (LIVE_RECORDING.includes(entry.status)) {
+            check(!live.has(entry.follows), "follows.live", `${at}.follows`, `the ${String(entry.follows)} side already has a recording that is, or may be, capturing`);
+            live.add(entry.follows);
+        }
+    });
     return violations;
 }
-/** Supply a trusted current instant in the observer's clock domain. Undefined means clock unknown. */
-export function effectiveRecordingState(state, now) {
-    if (state === undefined || validateRecordingState(state).length || state.status === "unknown" || now === undefined || !Number.isFinite(now))
-        return { status: "unknown" };
-    return Date.parse(state.observedAt) <= now && now < Date.parse(state.validUntil) ? state : { status: "unknown" };
-}
 export function validateRecordingPolicy(value, path = "capabilities.recording") {
     const { violations, check, keys } = collector();
     if (!object(value)) {
@@ -3286,12 +3291,12 @@ export function validateHostRecordings(value, path = "host.recordings") {
             check(false, "report.shape", at, "expected scoped report");
             return;
         }
-        keys(report, ["assignmentId", "state"], at);
+        keys(report, ["assignmentId", "recordings"], at);
         check(filled(report.assignmentId), "report.scope", at, "report identifies the assignment");
         const key = JSON.stringify([report.assignmentId]);
-        check(!seen.has(key), "report.duplicate", at, "one host state per assignment");
+        check(!seen.has(key), "report.duplicate", at, "one host report per assignment");
         seen.add(key);
-        violations.push(...validateRecordingState(report.state, `${at}.state`));
+        violations.push(...validateRecordings(report.recordings, `${at}.recordings`));
     });
     return violations;
 }
@@ -3301,50 +3306,62 @@ export function validateRecordingCommandShape(value, source, path = "command") {
         check(false, "command.shape", path, "expected recording command");
         return violations;
     }
-    keys(value, ["type", "source", "observationId", "action", ...(value.action === "start" ? [] : ["recordingId"])], path);
+    const starting = value.action === "start";
+    keys(value, ["type", "source", "action", starting ? "follows" : "recordingId"], path);
     check(value.type === "recording" && value.source === source, "command.source", path, `this executor accepts only ${source} recording commands`);
     check(RECORDING_ACTIONS.includes(value.action), "command.action", `${path}.action`, "unsupported recording action");
-    for (const key of ["observationId", ...(value.action === "start" ? [] : ["recordingId"])])
-        check(filled(value[key]), "command.identity", `${path}.${key}`, "expected nonempty scoped identity");
+    if (starting)
+        check(RECORDING_SIDES.includes(value.follows), "command.follows", `${path}.follows`, "a start names the side to record: party or agent");
+    else
+        check(filled(value.recordingId), "command.identity", `${path}.recordingId`, "every action but start names the recording by its id");
     return violations;
 }
 /** One transition table shared by dispatch checks and outcome checks. */
 const RECORDING_TRANSITIONS = {
-    start: { from: ["inactive"], to: "active" },
-    pause: { from: ["active"], to: "paused" },
-    resume: { from: ["paused"], to: "active" },
-    stop: { from: ["active", "paused"], to: "inactive" },
-    cancel: { from: ["active", "paused"], to: "inactive" },
+    pause: { from: ["recording"], to: "paused" },
+    resume: { from: ["paused"], to: "recording" },
+    stop: { from: ["recording", "paused"], to: "not-recording" },
+    cancel: { from: ["recording", "paused"], to: "not-recording" },
 };
 function recordingTransition(action) {
     return typeof action === "string" && Object.hasOwn(RECORDING_TRANSITIONS, action)
         ? RECORDING_TRANSITIONS[action] : undefined;
 }
-/** Structural/state permission check. Dispatch MUST also call validateRecordingRequest for scope and freshness. */
-export function validateRecordingCommandState(command, policy, state, path = "command") {
+const entries = (value) => Array.isArray(value) ? value.filter(object) : [];
+/**
+ * Whether the action is permitted on this recorder, and whether the recordings as last published
+ * let it act: a start on a side with nothing capturing, every other action on the recording it
+ * names, standing where the action needs it. Dispatch MUST also call validateRecordingRequest.
+ */
+export function validateRecordingCommandState(command, policy, recordings, path = "command") {
     const { violations, check } = collector();
     if (!object(command)) {
         check(false, "command.shape", path, "expected recording command");
         return violations;
     }
-    const transition = recordingTransition(command.action);
-    if (transition === undefined) {
+    if (!RECORDING_ACTIONS.includes(command.action)) {
         check(false, "command.action", `${path}.action`, "unsupported recording action");
         return violations;
     }
     const permitted = object(policy) && policy[command.action] === true;
     check(permitted, "command.permission", path, "task does not permit this action on this recorder");
-    if (!object(state) || validateRecordingState(state).length) {
-        check(false, "command.state", path, "no validated current recorder observation");
+    if (recordings !== undefined && validateRecordings(recordings).length) {
+        check(false, "command.state", path, "the recordings as published are malformed");
+        return violations;
+    }
+    const list = entries(recordings);
+    if (command.action === "start") {
+        check(!list.some(entry => entry.follows === command.follows && LIVE_RECORDING.includes(entry.status)), "command.state", path, `the ${String(command.follows)} side already has a recording that is, or may be, capturing`);
         return violations;
     }
-    check(transition.from.includes(state.status), "command.state", path, "action is invalid in the observed recorder state");
-    check(command.observationId === state.observationId, "command.stale", path, "observation changed; reconcile before acting");
-    if (command.action !== "start")
-        check(command.recordingId === state.recordingId, "command.recordingId", path, "command targets another recording");
+    const target = list.find(entry => entry.id === command.recordingId);
+    if (!check(target !== undefined, "command.recordingId", path, "no recording on this task has that id"))
+        return violations;
+    const transition = recordingTransition(command.action);
+    check(transition.from.includes(target.status), "command.state", path, `${String(command.action)} needs the recording ${transition.from.join(" or ")}, and it is ${String(target.status)}`);
     return violations;
 }
-/** Validate immediately before dispatch using current task, host report and trusted observer-domain time. */
+/** Validate immediately before dispatch, against the current task and, for the host's recorder, its declaration and report. */
 export function validateRecordingRequest(request, task, context, path = "request") {
     const { violations, check, keys } = collector();
     if (!object(request) || !object(task)) {
@@ -3362,58 +3379,69 @@ export function validateRecordingRequest(request, task, context, path = "request
     const caps = object(task.capabilities) ? task.capabilities.recording : undefined;
     violations.push(...validateRecordingPolicy(caps)); // a locked or missing capability cannot dispatch
     const policy = object(caps) ? caps[context.source] : undefined;
-    let state = object(task.recording) ? task.recording.provider : undefined;
+    let recordings = task.recordings ?? [];
     if (context.source === "host") {
         violations.push(...validateHostRecording(context.host, context.softphone === true));
         check(object(context.host), "host.required", path, "host did not declare recording support");
         const reports = object(context.hostReport) ? context.hostReport.recordings : undefined;
         violations.push(...validateHostRecordings(reports));
-        state = Array.isArray(reports) ? reports.find(r => object(r) && r.assignmentId === task.assignmentId)?.state : undefined;
+        const report = Array.isArray(reports) ? reports.find(r => object(r) && r.assignmentId === task.assignmentId) : undefined;
+        recordings = object(report) ? report.recordings : [];
         if (object(context.host)) {
             check(Array.isArray(context.host.actions) && context.host.actions.includes(command.action), "host.action", path, "host does not support action");
             check(object(policy) && Array.isArray(context.host.storageIds) && context.host.storageIds.includes(policy.storageId), "host.storage", path, "task storage is not one this host provisions");
         }
     }
-    const fresh = effectiveRecordingState(state, context.now);
-    check(fresh.status !== "unknown", "request.freshness", path, "current state or trusted observer time unavailable/expired");
-    violations.push(...validateRecordingCommandState(command, policy, fresh, `${path}.command`));
+    violations.push(...validateRecordingCommandState(command, policy, recordings, `${path}.command`));
     const opening = command.action === "start" || command.action === "resume";
     check(opening ? ["in-progress", "paused"].includes(task.phase) && task.audio === "started" : ["in-progress", "paused", "completing"].includes(task.phase), "request.phase", path, "capture needs live task audio; terminal controls may finish recordings during wrap-up");
     return violations;
 }
-/** Check recording-specific result semantics against the owner's confirming observations. */
+/**
+ * A recording command's answer against the recordings published before and after it: applied
+ * means the recorder confirmed what was asked -- a new recording on the side for a start, the
+ * same recording in its new status for anything else -- and failed means nothing changed there.
+ */
 export function validateRecordingOutcome(command, before, after, result, path = "recordingOutcome") {
     const { violations, check } = collector();
-    violations.push(...validateRecordingState(before, `${path}.before`), ...validateRecordingState(after, `${path}.after`));
-    if (!object(command) || !object(before) || !object(after)) {
-        check(false, "outcome.shape", path, "command and both observations required");
+    violations.push(...validateRecordings(before, `${path}.before`), ...validateRecordings(after, `${path}.after`));
+    if (!object(command) || !Array.isArray(before) || !Array.isArray(after)) {
+        check(false, "outcome.shape", path, "command and both lists of recordings required");
         return violations;
     }
     violations.push(...validateRecordingCommandShape(command, command.source === "host" ? "host" : "provider", `${path}.command`));
-    // A rejected promise has no result: any independently evidenced state may follow it.
+    // A rejected promise has no result: any state its recorder publishes may follow it.
     if (result === undefined)
         return violations;
     violations.push(...validateResult(result, "execute", `${path}.result`));
     if (!object(result))
         return violations;
     check(result.status === "applied" || result.status === "failed", "outcome.result", path, "recording never returns a dialling result");
+    const prior = entries(before);
+    const next = entries(after);
+    if (command.action === "start") {
+        const fresh = next.filter(entry => entry.follows === command.follows && !prior.some(old => old.id === entry.id));
+        if (result.status === "applied") {
+            check(fresh.some(entry => entry.status === "recording"), "outcome.state", path, "an applied start shows a new recording on that side, recording");
+            check(!prior.some(entry => entry.follows === command.follows && LIVE_RECORDING.includes(entry.status)), "outcome.origin", path, "applied cannot claim a start on a side already capturing");
+        }
+        else if (result.status === "failed") {
+            check(!fresh.some(entry => LIVE_RECORDING.includes(entry.status)), "outcome.noEffect", path, "a failed start leaves nothing capturing on that side");
+        }
+        return violations;
+    }
+    const was = prior.find(entry => entry.id === command.recordingId);
+    const now = next.find(entry => entry.id === command.recordingId);
     if (result.status === "failed") {
-        check(before.status !== "unknown" && after.status === before.status && after.recordingId === before.recordingId, "outcome.noEffect", path, "failed promises confirmed no effect; ambiguous or partial effects have no result");
+        check(was !== undefined && now !== undefined && now.status === was.status, "outcome.noEffect", path, "failed confirms no effect: the recording stands as it was; a partial effect is unknown, unsettled");
     }
     else if (result.status === "applied") {
         const transition = recordingTransition(command.action);
         if (transition === undefined)
             return violations; // shape validation already reported the unknown action
-        check(after.status === transition.to, "outcome.state", path, "applied requires the confirming requested state");
-        check(after.observationId !== before.observationId, "outcome.observation", path, "an applied transition needs new confirming evidence");
-        check(before.observationId === command.observationId, "outcome.stale", path, "command must act against its named observation");
-        check(transition.from.includes(before.status), "outcome.origin", path, "applied cannot claim an impossible transition");
-        if (command.action !== "start")
-            check(command.recordingId === before.recordingId, "outcome.recordingId", path, "command must target the prior recording");
-        if (command.action === "pause" || command.action === "resume")
-            check(after.recordingId === before.recordingId, "outcome.continuity", path, "pause/resume preserves recording identity");
-        if (instant(before.observedAt) && instant(after.observedAt))
-            check(after.observedAt >= before.observedAt, "outcome.order", path, "clock discontinuity requires reconciliation, not a reversed confirmation");
+        check(now !== undefined, "outcome.continuity", path, "the recording keeps its id through the action");
+        check(now?.status === transition.to, "outcome.state", path, `applied requires the recording ${transition.to}`);
+        check(was !== undefined && transition.from.includes(was.status), "outcome.origin", path, "applied cannot claim an impossible transition");
     }
     return violations;
 }

package/guide/agent.md

@@ -384,6 +384,9 @@ Migration from the earlier spellings:
 | the phone unspoken | `PhoneState` -- the device, its mute, its channels -- on `Snapshot.phone`, `phone-updated` and `TeamMember.phone`, from a manifest declaring `phoneStatus` (`snapshot.phone.required`, `.unexpected`, `phone.*`, `phone.channel.*`, `event.phone.capability`) |
 | the agent's readiness for the next call read into setCapacity | the agent's own queue: `capabilities.nextCall`, `requestNextCall`/`cancelNextCall`/`releaseLinedUp`, `Snapshot.nextCall` and `linedUp`, the `next-call` and `lined-up` events (`snapshot.nextCall.idle`, `nextCall.*`, `linedUp.*`) |
 | a harness that exercised an adapter, drove a call and evaluated rules | the harness reads as a test: `testAdapter`, `withCall`, `timeoutMs`, `notTested`, `rulesTested`, rules `test.*` (`test.timeout`, `test.offer.expired`, `test.preview.deadline`, ...) |
+| a `callback-requested` step, and a callback task starting its history afresh | a `callback-requested` step (`by` when an agent arranged it); a callback's task carries the earlier call's steps, oldest first |
+| a recording state with an observation id, an observation instant and a validity window, and the helpers that aged it | `recordings` on the task and on `HostRecordingReport`: a list, each recording with `id`, `follows` (`party` or `agent`), `status` (`starting`, `recording`, `paused`, `not-recording`, `unknown`) and a `reason` where paused or unknown; nothing expires; commands name `follows` for a start and `recordingId` otherwise; `validateRecordings` (`recording.task.renamed` refuses the former field) |
+| a refusal on hold under `omni.command-not-permitted` | `omni.on-hold` |
 | an `end-call` while the caller was on hold | refused: a `paused` task is resumed first (`command.endCall.held`), the agent computer shows End call disabled on hold, the provider answers `failed`, and the test names an adapter that ends from hold (`test.command.held`); `terminate-call` is not gated, it ends the caller's channel too |
 | the handset spelled by its place on a desk | `hardphone`, on the manifest's `phones` and the login's `phone`; the former spelling is refused |
 | the desk | the agent computer, in the guide's prose |
@@ -426,7 +429,20 @@ something else, which will arrive under its own name and must not be folded in h
 It rides in the snapshot and is replaced whole like everything else there.
 
 Steps are `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
-`unanswered`, and each is defined on `TaskHistoryStep`.
+`unanswered`, `callback-requested`, and each is defined on `TaskHistoryStep`.
+
+**A callback carries the call it comes back to.** When a caller asks to be called back, or an agent
+arranges it, the provider writes a `callback-requested` step: `by` names the agent who arranged it, and
+is absent when the caller chose it in the queue. The callback reaches an agent as a new task, and that
+task's history carries the earlier call's steps, oldest first, the `callback-requested` step among them,
+then the callback's own -- as a hand-over carries the steps before it. The agent opening a callback
+sees that the caller waited and asked, or whose promise they are keeping, and a second try reads as
+one, the way contact-centre platforms keep a callback with its original contact.
+
+**One call has one history.** Every task the call reaches restates the earlier steps exactly as they
+stood: the same step, instant, person, dial and destination, and a duration once stated never
+changes. `assertHistoryAgreesAcrossTasks(earlier, later)` holds two tasks of one call to that, for an
+adopter's own test that drives a hand-over, take-over or callback.
 
 **The record is one entry per occurrence, oldest first.** Each hold is its own `held` entry — `at`
 when it began, `seconds` once it ended and omitted while it runs — and a second hold is a second
@@ -1099,6 +1115,7 @@ react rather than only display the message:
 | `omni.unavailable` | The provider is temporarily unable to serve the action, including any command sent while `transport-status` is not `active`. |
 | `omni.break-already-committed` | Cancellation lost the commit/cancel race; Omni must finish commit recovery. |
 | `omni.recording-unsettled` | A recording command the provider could not settle either way: a settled `failed`, never a promise left unresolved. See **Independent task recording** in `guide/voice.md`. |
+| `omni.on-hold` | Refused because the caller is on hold: the agent application's own Mute begun on a `paused` task, or `end-call` there. The agent application says resume first. The test expects this code on both (`test.recordStep.held`, `test.command.held`). |
 | `omni.break-forced-by-provider` | A lead asked to lift a break the platform imposed; the platform lifts its own. See **Forced breaks** in `guide/breaks.md`. |
 
 They are published as `OMNI_FAILURE_CODES`.

package/guide/phone.md

@@ -238,7 +238,7 @@ softphone the agent application's own Mute is unavailable while the task is `pau
 promised at login (`muteUnavailableOnHold`): mute then hold is ordinary, and the muted leg runs on
 across the held one; hold then mute is not, and a `muted` leg with `mutedBy: "host"` beginning on a
 paused task is held back by the agent application (`historyReport.muted.held`) and refused by a
-provider that receives one anyway. The test sends one past the validator while the task is held
+provider that receives one anyway, `failed` with `omni.on-hold`. The test sends one past the validator while the task is held
 and names an adapter that records it (`test.recordStep.held`). A station mute the agent
 application observes on hold -- the headset's slider, the operating system -- is a fact, reported
 with `mutedBy: "station"`, and stands. The agent application reports every such period

package/guide/voice.md

@@ -262,7 +262,7 @@ provider decides: another IVR, a queue, a survey, or the end of the call. Gated
 with nobody coming back to them, and the provider's path for a caller who continues never begins.
 So the caller is taken off hold first: the agent computer holds the command back while the task is `paused`
 (`command.endCall.held`) and shows End call disabled on hold, and a provider that receives it
-anyway answers `failed`. Resume, then end. `terminate-call` needs no such gate: it ends the
+anyway answers `failed` with `omni.on-hold`, so the agent application can say resume first. Resume, then end. `terminate-call` needs no such gate: it ends the
 caller's channel with the rest, held or not, and nobody is left waiting.
 
 **`terminate-call` ends the whole call.** Every channel on it ends at the provider: the agent's,
@@ -463,114 +463,120 @@ agent's.
 ## Independent task recording
 
 Recording is voice-only. A task can arrive already recording, including while pending, and offer
-no recording controls. The provider publishes only its own current state on
-the provider field of the task’s `recording` state. The agent application publishes its own full scoped view in `HostReport.recordings`.
-A provider task update cannot replace agent application state. Neither a capability nor an accepted command
-establishes recording. Missing state, lost recorder observation, transport loss and expired
-observation mean unknown; they never mean stopped. Paused means a recording remains open without
-capturing. Task hold, task pause and recording pause are independent.
-
-The per-task policy is `Task.capabilities.recording`, with independently optional provider and agent application
-action sets. The outer capability may be locked. Absence grants no permission, and a state may
-exist without any permission. A provider may offer only stop for a recording started automatically,
-or withdraw a control on a later task update. There is no global recording mode and no automatic
-start from a capability declaration. Agent application support is declared on `ConnectContext.host.recording`,
-not the provider-owned manifest. The task names one of the storage places the agent application provisioned, by `storageId`;
-an unknown storage place or an unsupported action is refused visibly, never redirected to provider
-recording or a default upload location. Initial agent application support requires voice softphone audio and
-capture of both local and remote audio; an agent application unable to capture either must refuse start/resume.
-This package declares that contract; it supplies no recorder, audio mixing, storage or upload.
-
-| Action | Required current recording state | Confirmed outcome |
-| --- | --- | --- |
-| start | inactive | active with a new recording identity |
-| pause | active | paused, preserving recording identity and captured audio |
-| resume | paused | active with the same recording identity |
-| stop | active or paused | inactive; finish and retain captured audio |
-| cancel | active or paused | inactive; abandon and discard captured audio |
-
-Stop finishes the recording and retains captured audio. Cancel abandons the recording and discards
-its captured audio; the task policy offers it with `cancel: true`. There is no configurable cancel
-effect. A recorder that cannot confirm completion must not offer Cancel; it can offer Stop instead.
-Cancel never means cancelling an in-flight start request or deleting arbitrary past recordings.
-Stop can be applied only after finalization/retention succeeds; Cancel only after both cessation
-and completion of this recording's audio succeed under the recorder's storage contract.
-Partial success -- capture stopped but the storage outcome unknown, a start the recorder cannot
-vouch for either way -- is a settled `failed`, under the code `omni.recording-unsettled`: the
-command did not do what it promised, and the state the provider publishes with it is whatever
-capture state is actually known. It is never `applied`, and never an unsettled promise the agent
-application would be left to resync, since the provider knows exactly what it could not settle.
-There is no request identity on a recording command: the outcome is the state, and what the
-agent sees is the state. Retention is not a promise of sample-perfect audio.
-
-Provider commands go exclusively to `Connection.execute`; agent application commands go exclusively to
-`HostRecording.execute`. Both include the assignment and observation identities; all
-non-start commands identify the particular recording. IDs are opaque and scoped by provider login,
-task and recorder owner. They are never inferred from filenames or current agent identity. A
-recording ID survives pause/resume and reassignment only where the same recorder confirms continuity;
-commands always name the current assignment. A later start gets a different ID. Reconnect does not
-create a new recording or fresh evidence. After lost continuity, use unknown until reconciled.
-There is no automatic restart, hand-over to another recorder, or stop on task hold/disconnect.
-Task removal does not prove recording stopped: outstanding agent application recorders remain tracked by the
-agent application until its executor reconciles/finishes them, with visible unresolved cleanup failures.
-
-Only start/resume require an in-progress or paused task with started audio. Pause/stop/cancel may
-also finish an independently observed recorder while the task is completing. A pending task may
-show active recording, but agent controls wait until interaction begins. The two recording paths may
-both be active. A command to either path has no implied effect on the other.
-
-Each confirmed observation has a fresh opaque observation identity, a canonical UTC millisecond
-observation instant and an exclusive expiry. These times describe current evidence, never historical
-capture boundaries. A trusted observer-domain current time must satisfy observedAt <= now < validUntil.
-Use `effectiveRecordingState` with that explicitly trusted time; an unavailable clock yields unknown.
-Receipt, replay and task publication never extend freshness. Clock discontinuity invalidates evidence;
-consumers using the explicit recording-expiry clock-estimation exception must invalidate that
-estimate and use monotonic aging so clock rollback cannot
-revive expired evidence. The executor compares observation identity and recording identity against
-its latest state atomically before I/O. An intervening observation or assignment change refuses the
-stale command; it never acts on a replacement recorder. Providers lacking trustworthy current-state
-identity or observation time publish unknown and offer no issuable controls.
-
-Use `validateTask` and `validateTaskCommand` for published shape and static permissions.
-Immediately before dispatch, additionally use `validateRecordingRequest` against the full current
-task and explicit observer-domain time. For agent application commands also supply the current agent application declaration,
-full agent application report and softphone context. The same checks must run at the executing boundary;
-client validation alone is not authorization. The executor serializes operations on each recorder
-and compares `observationId` and `recordingId` against its latest evidence before acting: a
-command against superseded evidence is refused, and nothing is retried on the executor's own
-account.
-
-Keep command progress in agent application UI separately from authoritative state. Applied means the requested
-recording transition and any retain/discard effect actually completed; publish the confirming task or agent application report before
-resolving applied. Failed means confirmed no effect. Rejected promise means outcome unknown:
-show the failure, reconcile that path and do not automatically retry or pretend inactive. Authoritative
-updates remain full current task/agent application views, not replayed provider events. These current-state fields
-create no interaction-history entries and infer no actors, durations or historical capture boundaries.
-
-Migration is explicit: replace the old true recording capability with per-path action policies,
-replace untargeted commands with scoped commands, and retain protocol version 1. During pre-release
-development, hosts and adapters must align their recording contracts; negotiation does not detect
-differences between package revisions that share that protocol number. No legacy-shape fallback is provided.
-This change does not publish a package or enable recording in any existing agent application/provider by itself.
-
-`validateRecordingOutcome` checks confirming observations against recording-specific applied/failed
-semantics, including pause/resume identity and rejection of a dialling result. It cannot prove audio
-retention/completion or source truth from a status flag; those remain executor obligations.
-
-The storage place named on the task is bound when start actually creates a recording. Existing recordings
-keep that binding through pause/resume/stop/cancel; a later policy cannot redirect their stored audio.
-The executor rejects a mismatched storage place rather than moving or discarding another binding.
-Action permission does not authorize unattended invocation: agent application controls require the agent's explicit
-act, and provider authorization remains enforced at its authenticated command boundary.
-
-
-Recording dispatch must receive the same known task-validation context as the published task.
-Pass organisation levels and other known restrictions through the optional fourth argument of
-`validateTaskCommand`, and through `taskContext` in `validateRecordingRequest`. This keeps a valid
-custom organisation lock from being rejected against the default ladder, and prevents known
-capability restrictions from disappearing at dispatch. The standalone `validateRecordingCommandState`
-requires an affirmative permission; false, malformed permission declarations and unknown actions grant nothing.
+no recording controls. **Each recorder publishes its own recordings, as a list, whenever one
+changes.** The provider's are the task's `recordings`, restated whole on every publication of the task
+and on every snapshot. The agent application's are on its `HostReport.recordings`, one entry per
+assignment, never on a provider's task. A provider task update cannot replace the agent
+application's recordings, and a command to one recorder has no effect on the other.
+
+```json
+"recordings": [
+  { "id": "rec-7", "follows": "party", "status": "recording" },
+  { "id": "rec-8", "follows": "agent", "status": "paused", "reason": "sensitive-details" },
+  { "id": "rec-3", "follows": "party", "status": "not-recording" }
+]
+```
 
+**A recording follows one side of the call.** `follows` says whose channel it captures: the
+`party`'s, or the `agent`'s own. The two are separate captures on most platforms, and the agent
+computer needs to know which: a recording that follows the party keeps capturing hold music
+while the agent talks to a colleague, and only one that follows the agent says whether the
+agent's own voice is on it. Each side has at most one recording that is, or may be, capturing at
+once -- `starting`, `recording`, `paused` or `unknown` (`recording.follows.live`) -- and any number
+that have finished.
+
+**Nothing expires.** A recording stands as its recorder last stated it until the recorder says
+otherwise. There is no observation time, no validity window and no clock to compare: everything
+the agent computer shows comes from the wire, and a recording mark that went dark when a recorder
+check ran late, then came back, was a fault reported from the floor. The recorder publishes on
+change and restates the whole list on connect and resume.
+
+| Status | Meaning |
+| --- | --- |
+| `starting` | Asked for and not yet confirmed by the recorder. |
+| `recording` | Capturing. A pause or a stop still in flight stays `recording` until the recorder confirms it: telling the agent they are not recorded when they may be is the one thing this must never say. |
+| `paused` | Open but not capturing, with a `reason`: `requested`, someone asked for it, or `sensitive-details`, the platform paused it while card or account details are taken. |
+| `not-recording` | Finished, or never started on that side; captured audio is kept or discarded as its stop or cancel said. |
+| `unknown` | The recorder cannot say, with a `reason`: `recorder-unreachable`, or `unsettled`, a command whose effect it could not establish either way. Never shown as stopped. |
+
+A mark that is not lit says why: `paused` and `unknown` carry a reason from those closed lists, and
+nothing else carries one (`recording.reason`, `.reason.unexpected`). Task hold, task pause and
+recording pause are independent.
+
+**Permission is per task.** The policy is `Task.capabilities.recording`, with independently
+optional provider and agent application action sets. The outer capability may be locked. Absence
+grants no permission, and a recording may exist without any permission. A provider may offer only
+stop for a recording started automatically, or withdraw a control on a later task update. There is
+no global recording mode and no automatic start from a capability declaration. Agent application
+support is declared on `ConnectContext.host.recording`, not the provider-owned manifest. The task
+names one of the storage places the agent application provisioned, by `storageId`; an unknown
+storage place or an unsupported action is refused visibly, never redirected to provider recording
+or a default upload location. Initial agent application support requires voice softphone audio and
+capture of both local and remote audio; an agent application unable to capture either must refuse
+start/resume. This package declares that contract; it supplies no recorder, audio mixing, storage
+or upload.
+
+**A command names what it acts on.** A start names the side, `follows`; every other action names
+the recording by its `recordingId`. The recorder mints the id when it accepts the start, before
+the recorder has answered, publishes the recording `starting` under it, and keeps it through pause
+and resume; a later start is a new recording with a new id. The recorder serializes the operations
+on each recording and refuses an action the recording no longer stands for: a pause on a recording
+that is not `recording`, a stop on one already `not-recording`, a start on a side already
+capturing, a recording the task does not carry (`recording.command.state`,
+`.command.recordingId`). Nothing is retried on the recorder's own account.
+
+| Action | The recording before | Confirmed outcome |
+| --- | --- | --- |
+| start | none live on that side | a new recording on that side, `recording` |
+| pause | `recording` | the same recording, `paused`, captured audio kept |
+| resume | `paused` | the same recording, `recording` |
+| stop | `recording` or `paused` | the same recording, `not-recording`; captured audio finished and kept |
+| cancel | `recording` or `paused` | the same recording, `not-recording`; captured audio discarded |
+
+Stop finishes the recording and retains captured audio. Cancel abandons it and discards captured
+audio; the task policy offers it with `cancel: true`, and there is no configurable cancel effect.
+A recorder that cannot confirm completion must not offer Cancel; it can offer Stop instead. Cancel
+never means cancelling an in-flight start or deleting past recordings. Stop is applied only after
+finalization and retention succeed; Cancel only after both cessation and discarding succeed.
+**Applied means confirmed**: the recorder publishes the confirming list before it answers
+`applied`. Failed means confirmed no effect. Partial success -- capture stopped but the storage
+outcome unknown, a start the recorder cannot vouch for either way -- is a settled `failed` under
+`omni.recording-unsettled`, and the recording is published `unknown` with the reason `unsettled`.
+A rejected promise means the outcome is unknown: show the failure, reconcile, and do not retry or
+pretend `not-recording`. There is no request identity on a recording command: the outcome is the
+recording, and what the agent sees is the recording. Retention is not a promise of sample-perfect
+audio.
+
+Provider commands go only to `Connection.execute`; agent application commands go only to
+`HostRecording.execute`. Both name the assignment. Ids are opaque and scoped by provider login,
+task and recorder; they are never inferred from filenames or the current agent. Reconnect creates
+no recording; the recorder restates its list. There is no automatic restart, hand-over to another
+recorder, or stop on task hold or disconnect. Task removal does not prove recording stopped:
+outstanding agent application recordings stay tracked by the agent application until its recorder
+finishes them, with unresolved cleanup failures visible.
+
+Only start and resume need an `in-progress` or `paused` task with started audio. Pause, stop and
+cancel may also finish a recording while the task is `completing`. A pending task may show a
+recording, but agent controls wait until interaction begins.
+
+Use `validateTask` and `validateTaskCommand` for the published shape and static permissions.
+Immediately before dispatch, also use `validateRecordingRequest` against the full current task;
+for agent application commands supply the current declaration, full report and softphone context.
+The same checks run at the recorder; client validation alone is not authorization.
+`validateRecordings` checks one recorder's list, and `validateRecordingOutcome` checks an answer
+against the lists published before and after it: an applied start shows a new recording on its side,
+anything else the same recording in its new status, and a failed one nothing changed there. It
+cannot prove retention or source truth from a status; those remain the recorder's obligations. The
+storage place named on the task is bound when start creates a recording, and later policy cannot
+redirect it.
+
+Recording dispatch receives the same known task-validation context as the published task: pass
+organisation levels and other known restrictions through the optional fourth argument of
+`validateTaskCommand`, and through `taskContext` in `validateRecordingRequest`, so a valid custom
+organisation lock is not rejected against the default ladder. Migration is explicit: the former
+`recording` state with its observation and validity window is refused on a task
+(`recording.task.renamed`), and a command carries no observation id. Protocol version 1 stays;
+there is no legacy-shape fallback.
 
 ### Agent application recording announcements to the caller
 
@@ -590,7 +596,7 @@ cancel, they hear that recording stopped. If pause/resume is supported, say paus
 pause is not presented as a finished recording. Announcements follow actual capture transitions,
 not button clicks, accepted requests or task-policy changes. When attaching to an already-active
 agent application recording, announce that recording is active, without inventing its original start time.
-Repeated observations of the same state do not repeat announcements. Unknown or expired evidence
+Restating the same status does not repeat an announcement. A recording that is `unknown`
 must never produce a stopped announcement.
 
 A local sound, UI indicator, screen-reader message to the agent, or sound leaking through the

package/guide.md

@@ -83,7 +83,7 @@ user IDs, returned user details and directory requirements are unchanged.
 
 ### `OMNI_PROTOCOL_VERSION`
 
-The exact protocol version implemented by this package. The current value remains `1` during pre-release development. Recording contract changes do not introduce a new protocol version. Hosts and adapters adopt the current declarations together; this does not provide compatibility mapping for older recording shapes.
+The exact protocol version implemented by this package. The current value remains `1` during pre-release development. Recording contract changes do not introduce a new protocol version. Hosts and adapters adopt the current declarations together; there is no compatibility mapping for older recording shapes.
 
 ### `Manifest.supportedProtocolVersions`
 
@@ -343,23 +343,22 @@ interface TaskRecordingPolicy {
   provider?: RecordingActions;
   host?: RecordingActions & { storageId: string };
 }
-type RecordingState =
-  | { status: "unknown"; observationId?: never; observedAt?: never; validUntil?: never; recordingId?: never }
-  | ({ observationId: string; observedAt: IsoTimestamp; validUntil: IsoTimestamp } & (
-      | { status: "inactive"; recordingId?: never }
-      | { status: "active" | "paused"; recordingId: string }
-    ));
-type RecordingCommand = {
-  type: "recording";
-  source: RecordingSource;
-  observationId: string;
-} & (
-  | { action: "start"; recordingId?: never }
-  | { action: "pause" | "resume" | "stop" | "cancel"; recordingId: string }
+type RecordingSide = "party" | "agent";
+type RecordingStatus = "starting" | "recording" | "paused" | "not-recording" | "unknown";
+type RecordingPausedReason = "requested" | "sensitive-details";
+type RecordingUnknownReason = "recorder-unreachable" | "unsettled";
+type Recording = { id: string; follows: RecordingSide } & (
+  | { status: "starting" | "recording" | "not-recording"; reason?: never }
+  | { status: "paused"; reason: RecordingPausedReason }
+  | { status: "unknown"; reason: RecordingUnknownReason }
+);
+type RecordingCommand = { type: "recording"; source: RecordingSource } & (
+  | { action: "start"; follows: RecordingSide; recordingId?: never }
+  | { action: "pause" | "resume" | "stop" | "cancel"; recordingId: string; follows?: never }
 );
 interface HostRecordingReport {
   assignmentId: AssignmentId;
-  state: RecordingState;
+  recordings: Recording[];
 }
 interface HostRecording {
   announcesToCaller?: true;
@@ -694,7 +693,8 @@ type HistoryStep =
   | "muted"
   | "transferred"
   | "conferenced"
-  | "unanswered";
+  | "unanswered"
+  | "callback-requested";
 
 type TaskHistory = {
   steps: TaskHistoryStep[];
@@ -777,8 +777,8 @@ type Task<C extends Channel = Channel> = {
   history?: TaskHistory;
 } & TaskCompletion & (
   C extends "voice"
-    ? { recording?: { provider?: RecordingState }; onCall?: OnCall[]; leadAssist?: TaskLeadAssist; takenOver?: TaskTakenOver; audio?: TaskAudioState }
-    : { recording?: never; onCall?: never; leadAssist?: never; takenOver?: never; audio?: never }
+    ? { recordings?: Recording[]; onCall?: OnCall[]; leadAssist?: TaskLeadAssist; takenOver?: TaskTakenOver; audio?: TaskAudioState }
+    : { recordings?: never; onCall?: never; leadAssist?: never; takenOver?: never; audio?: never }
 );
 
 type PreviewDeadline = "provider-dials" | "host-dials" | "waits";
@@ -1345,6 +1345,7 @@ const OMNI_FAILURE_CODES = [
   "omni.unavailable",
   "omni.break-already-committed",
   "omni.recording-unsettled",
+  "omni.on-hold",
   "omni.break-forced-by-provider",
 ] as const;
 type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
@@ -2415,8 +2416,6 @@ The current exceptions and their reasons are:
 | --- | --- |
 | Agent application display of provider deadlines (`expiresInSeconds`, `previewEndsInSeconds`, `wrapEndsInSeconds`) | Each is seconds from the publication that carried it, counted down on the agent computer from receipt: the provider's own arithmetic, so no clock is compared and the transport delay is the only error. The countdown estimates the display only; it does not establish that the provider acted. Without usable time, show timing uncertainty. |
 | Agent application-triggered preview end | The agent computer counts `previewEndsInSeconds` down from receipt and issues `dial` when it reaches zero: the provider owns the deadline and the agent computer owns the trigger. It does not dial before the countdown has run out, and a reload restarts it from the next publication. |
-| Recording evidence expiry | A bounded observer-domain clock estimate with monotonic aging may assess freshness because observation and expiry belong to the recorder's clock. If time cannot be trusted, recording state is unknown; never renew evidence from receipt or replay. |
-| Unknown recording state | `observedAt` and `validUntil` are absent because there is no confirmed observation. The containing provider event still has its own `occurredAt`; that publication is not a recorder observation. |
 | Direct snapshot reads and method requests/results | These are reads/operations, not event envelopes, and their current types have no general event timestamp. A snapshot event still carries `occurredAt`; embedded source instants remain unchanged. Do not treat a method result or read completion time as an occurrence boundary. |
 | Agent application-provided provider-clock estimate | Best-effort ISO time may be supplied by the agent application for optional comparisons; it is not a source observation or accuracy guarantee. The reason is that the agent application does not own the provider clock. |
 | Provider receipt timestamps | The provider may use its own receipt instant for final records of receipt/processing because agent application timestamps are untrusted advisory input. Receipt must not be presented as an earlier action or capture boundary. |
@@ -2524,14 +2523,13 @@ A provider need not trust or adopt any agent application-supplied timestamp. It
 message using its own clock at receipt and use that for its own processing/accounting. The reason
 for this exception is that agent application clocks and agent application estimates are not authoritative at the provider.
 Receipt time must be described as receipt/observation time, not relabeled as the original agent application
-action, recorder capture boundary, or proof an operation applied. An existing field with a
+action, a recording's start or stop, or proof an operation applied. An existing field with a
 specific occurrence meaning still requires that evidence; this option does not silently redefine
 it. Agent application-only instants remain advisory input; the provider owns its authoritative publication.
 
 This agent application estimate is another explicit timestamp exception: it helps optional displays and
 provider-clock comparisons when the agent application lacks that clock directly. It is not a source occurrence,
-may not replace event/history timestamps, and alone cannot authorize deadline actions or prove
-recording freshness. Uses requiring a trustworthy bound still need independently established
+may not replace event/history timestamps, and alone cannot authorize deadline actions. Uses requiring a trustworthy bound still need independently established
 clock accuracy/drift assumptions. It neither synchronizes the operating-system clock nor changes
 ISO timestamps already published by the provider.
 
@@ -2550,7 +2548,9 @@ a backend that does not know the session yet — yields no snapshot, and the ada
 
 A snapshot must account for **everything the adapter has emitted before it resolves**, not merely
 everything emitted when it was requested. Omni drops the state-replacing events held during the
-read on that promise, and applies the rest after it (see **`Connection.snapshot()`**); an adapter
+read on that promise, and applies the rest after it (see **`Connection.snapshot()`**). Which kinds a
+snapshot restates, and so supersedes, is exported from the testing module as
+`SUPERSEDED_BY_A_SNAPSHOT`, so an agent application and the harness drop the same ones; an adapter
 that serves a stale snapshot and then lets an earlier event through will have Omni apply state the
 snapshot already superseded. The harness reads its connect snapshot the same way, and holds the
 snapshot to accounting for every task event it superseded: a task published during the read and
@@ -2713,7 +2713,9 @@ snapshots until it ends.
 with `task-ended` and an outcome, whatever became of the call: answered and completed, declined,
 withdrawn, abandoned in the ring, lapsed, taken over. An offer that is simply never mentioned
 again leaves the agent computer holding a task nobody will close, and the test names it
-(`stream.taskOffered.unended`).
+(`stream.taskOffered.unended`). **Every dial is owed its outcome** the same way: a dial the test
+placed and the provider answered `dialling` with no `dial-outcome` by the end of the run is named
+(`stream.dialOutcome.missing`).
 
 ### `task-updated`
 
@@ -2935,6 +2937,9 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateProviderTimeEstimate(estimate, scope)` | Optional agent application estimate shape and provider/login scope; no accuracy guarantee. |
 | `validateHistoryReport(report, path?, manifest?, task?)` | What the agent application reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. Given the task, the agent application's own mute beginning on a `paused` task is refused (`historyReport.muted.held`): the Mute waits for resume. |
 | `validateHostReport(report)` | The agent application's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever agent application a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateNextCall(value)` | The agent's standing ask for the next call, on its own as `next-call` and `Snapshot.nextCall` carry it: since when, and nothing else (`nextCall.since`, `nextCall.field`). |
+| `validateLinedUp(value, path?, levels?)` | A call lined up in the agent's own queue, on its own as `lined-up` and `Snapshot.linedUp` carry it: the caller under the same contact rules as a task's party, the queue's label, the waits, and `release` by presence (`linedUp.*`). |
+| `validatePhoneState(value, path?, context?)` | The phone as the platform sees it, on its own as `phone-updated` and `Snapshot.phone` carry it: its status, its one active channel, its mute where a hardphone's is observed (`phone.*`). |
 | `validateHostMute(mute, softphone)` | What the agent application's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the agent application holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
 | `validateLoginStore(store)` | The login's store the agent application hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
 | `validateCapacity(capacity)` | What the agent application states as capacity: a whole number of zero or more (`capacity.count`), zero being agent application-stopped. The harness states one on connect and two, one and zero after the test, each answered `applied`, and holds any offer to the count in force (`stream.taskOffered.overCapacity`). |
@@ -3144,6 +3149,7 @@ cannot be established from TypeScript structure alone.
 | `TaskStream`, `BreakStream` | The cross-event models the harness applies after the connect snapshot, exported for an agent application that wants the same rules at its boundary: `seed(snapshot)`, then `apply(envelope)` returns the violations. |
 | `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a forced break arriving in effect with `forced`. The harness applies the same rules after the connect snapshot. |
 | `assertAudioFollowsTheTask(envelopes, snapshot?)` | The audio follows the task and never decides it: every task is introduced once, `task-audio-started` and `task-audio-ended` alternate on work that has begun, audio ends only where it arrived, and what follows the audio ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no audio satisfies it by never testing it — pair it with the assertion that the audio end is present. |
+| `assertHistoryAgreesAcrossTasks(earlier, later)` | Two tasks of one call -- a hand-over, a take-over, a callback: the later restates every earlier step in order, with the same step, instant, person, dial and destination, and any duration already stated unchanged. Throws when either carries no history. |
 | `assertBreakAttemptProviders(candidates, asked)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
 | `assertForcedBreakStopsTheRest(forcedOn, candidates, stopped)` | A forced break on one provider stops the agent everywhere else: capacity zero stated on every other usable provider holding capacity, nothing on the forcing one, nothing on a dead login. See **Forced breaks** in `guide/breaks.md`. |
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `on-break` only once nothing is outstanding — never beside a task, never later than the step that has none. |

package/package.json

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