@xema/omni-protocol 0.1.80 → 0.1.81

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** The protocol version implemented by this package. */
-export declare const OMNI_PROTOCOL_VERSION: 1;
+export declare const OMNI_PROTOCOL_VERSION: 2;
 /** Every version this package can interoperate with. */
 export declare const OMNI_SUPPORTED_PROTOCOL_VERSIONS: readonly number[];
 /**
@@ -427,7 +427,93 @@ export type HostAudioOutput =
  */
 /** What Omni's own chrome shows of a task browser's URL: nothing, the domain, or all of it. */
 export type UrlVisibility = "full" | "domain" | "hidden";
+/** Independent recorder owners. A command never targets both. */
+export type RecordingSource = "provider" | "host";
+export type RecordingAction = "start" | "pause" | "resume" | "stop" | "cancel";
+export declare const RECORDING_ACTIONS: readonly ["start", "pause", "resume", "stop", "cancel"];
+/** Cancel's captured-audio disposition is explicit; stop always retains captured audio. */
+export type RecordingCancelEffect = "retain" | "discard";
+export interface RecordingActions {
+    start?: true;
+    pause?: true;
+    resume?: true;
+    stop?: true;
+    cancel?: {
+        effect: RecordingCancelEffect;
+    };
+}
+/** Per-task permission, not a provider-wide recording switch. Absence grants nothing. */
+export interface TaskRecordingPolicy {
+    provider?: RecordingActions;
+    host?: RecordingActions & {
+        destinationId: 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;
+} & ({
+    status: "inactive";
+    recordingId?: never;
+} | {
+    status: "active" | "paused";
+    recordingId: string;
+}));
+/** Opaque IDs are scoped by login, task and recorder owner; preserved across pause/resume. */
+export type RecordingCommand = {
+    type: "recording";
+    source: RecordingSource;
+    requestId: string;
+    /** Compare-and-set against current evidence; never act on a replacement recording. */
+    observationId: string;
+} & ({
+    action: "start";
+    recordingId?: never;
+    cancelEffect?: never;
+} | {
+    action: "pause" | "resume" | "stop";
+    recordingId: string;
+    cancelEffect?: never;
+} | {
+    action: "cancel";
+    recordingId: string;
+    cancelEffect: RecordingCancelEffect;
+});
+export interface HostRecordingReport {
+    taskId: TaskId;
+    allocationId: AllocationId;
+    state: RecordingState;
+}
+/** Host declaration in ConnectContext, not the provider-owned Manifest. */
+export interface HostRecording {
+    actions: RecordingAction[];
+    cancelEffects: RecordingCancelEffect[];
+    /** Explicitly provisioned destinations. A task chooses one; no upload/storage fallback. */
+    destinationIds: string[];
+    execute(request: HostRecordingRequest): Promise<RecordingCommandResult>;
+}
+/** Recording applies or fails; it never dials. Rejection without result means unknown. */
+export type RecordingCommandResult = Exclude<TaskCommandResult, {
+    status: "dialling";
+}>;
+export interface HostRecordingRequest {
+    taskId: TaskId;
+    allocationId: AllocationId;
+    command: RecordingCommand & {
+        source: "host";
+    };
+}
 export interface HostReport {
+    /** Full current host-owned recording view; never provider-owned state. */
+    recordings?: HostRecordingReport[];
     /** Whether the host has a network interface up. Not a claim that anything is reachable: the adapter knows its own platform's reachability better than the host does. */
     online: boolean;
     audio?: {
@@ -449,6 +535,8 @@ export interface HostGuarantees {
     personConsent?: true;
 }
 export interface Host {
+    /** Voice softphone recording support; policy and destination remain per task. */
+    recording?: HostRecording;
     guarantees: HostGuarantees;
     /** What pressing Mute does on this host. Stated on a softphone login, where the host holds the microphone; absent on a desk phone and off voice. */
     mute?: HostMute;
@@ -494,6 +582,7 @@ export type ConnectContext = {
     phone?: "deskPhone";
     host: {
         mute?: never;
+        recording?: never;
     };
 });
 export type TransportStatus = "connecting" | "active" | "error";
@@ -581,7 +670,7 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
     /** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.leadAssist`. */
     leadAssist?: Lockable<true>;
     conference?: Lockable<DestinationDirectory>;
-    recording?: Lockable<true>;
+    recording?: Lockable<TaskRecordingPolicy>;
 } : C extends "chat" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
@@ -888,12 +977,16 @@ export type Task<C extends Channel = Channel> = {
     attributes?: TaskAttribute[];
     handlingHistory?: TaskHandlingHistory;
 } & TaskCompletion & (C extends "voice" ? {
+    recording?: {
+        provider?: RecordingState;
+    };
     onCall?: OnCall[];
     leadAssist?: TaskLeadAssist;
     assisting?: TaskAssisting;
     monitoring?: TaskMonitoring;
     media?: TaskMediaState;
 } : {
+    recording?: never;
     onCall?: never;
     leadAssist?: never;
     assisting?: never;
@@ -1040,10 +1133,9 @@ export type VoiceTaskCommand = {
     action: "remove";
     party: true;
     destinationId?: never;
-} | {
-    type: "recording";
-    action: "start" | "pause" | "resume" | "stop";
-} | ({
+} | (RecordingCommand & {
+    source: "provider";
+}) | ({
     type: "complete";
 } & DispositionPayload);
 export type ChatTaskCommand = {

package/dist/index.js

@@ -2,7 +2,7 @@
 //
 // Where this file and guide.md disagree, the guide is right and this is a defect.
 /** The protocol version implemented by this package. */
-export const OMNI_PROTOCOL_VERSION = 1;
+export const OMNI_PROTOCOL_VERSION = 2;
 /** Every version this package can interoperate with. */
 export const OMNI_SUPPORTED_PROTOCOL_VERSIONS = [OMNI_PROTOCOL_VERSION];
 /**
@@ -29,6 +29,7 @@ export const IDLE_CAPABILITY_UI = {
 export const MONITOR_MODES = ["monitor", "whisper", "barge"];
 export const MUTED_BY = ["host", "station"];
 export const HOST_MUTES = ["stream", "station"];
+export const RECORDING_ACTIONS = ["start", "pause", "resume", "stop", "cancel"];
 // ---------------------------------------------------------------------------
 // Task workspace.
 // ---------------------------------------------------------------------------

package/dist/testing.d.ts

@@ -220,6 +220,7 @@ export declare function stillHost(report: HostReport, guarantees: HostGuarantees
 };
 export declare function stillHost(report?: HostReport, guarantees?: HostGuarantees): Host & {
     mute?: never;
+    recording?: never;
 };
 /** One provider as the host sees it when freezing the providers a break attempt asks. */
 export interface BreakCandidate {

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, validateHostRecording, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -267,6 +267,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // audio and reports it; on a desk phone, or off voice, there is none for it to report.
         violations.push(...validatePhone(context.phone, adapter.manifest, "context.phone"));
         const softphone = adapter.manifest.channel === "voice" && context.phone === "softphone";
+        violations.push(...validateHostRecording(context.host.recording, softphone));
         const first = context.host.report();
         violations.push(...validateHostReport(first, "context.host"));
         const hasAudio = isRecord(first) && first.audio !== undefined;
@@ -291,6 +292,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // The wrapped host carries the mute kind the test's host stated, so the arms of ConnectContext still hold.
         const host = {
             guarantees: context.host.guarantees,
+            ...(context.host.recording === undefined ? {} : { recording: context.host.recording }),
             ...(context.host.mute === undefined ? {} : { mute: context.host.mute }),
             report: () => { consulted.report = true; return context.host.report(); },
             subscribe: listener => { consulted.subscribe = true; return context.host.subscribe(listener); },

package/dist/validation.d.ts

@@ -1,4 +1,4 @@
-import { type ProtocolViolation, type UserCapabilities, type UserId } from "./index.js";
+import { type RecordingState, 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[];
@@ -135,3 +135,22 @@ 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;
+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. */
+export declare function validateRecordingRequest(request: unknown, task: unknown, context: {
+    source: "provider" | "host";
+    now: number | undefined;
+    host?: unknown;
+    hostReport?: unknown;
+    softphone?: boolean;
+}, path?: string): ProtocolViolation[];
+/** Check recording-specific result semantics against the owner's confirming observations. */
+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 { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, MONITORING_BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HANDLING_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, ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, MONITORING_BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, HANDLING_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") {
@@ -1116,6 +1116,17 @@ 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`));
+        }
+    }
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
@@ -1181,6 +1192,9 @@ function validateTaskInto(task, context, path, into) {
             continue;
         }
         switch (name) {
+            case "recording":
+                into.violations.push(...validateRecordingPolicy(declared, `${path}.capabilities.recording`));
+                break;
             case "dispositions":
                 validateDispositions(declared, `${path}.capabilities.dispositions`, into);
                 break;
@@ -1946,6 +1960,7 @@ export function validateHostReport(report, path = "host") {
         return into.violations;
     }
     into.require(typeof report.online === "boolean", "host.online", `${path}.online`, "a host report says whether it has a network");
+    into.violations.push(...validateHostRecordings(report.recordings, `${path}.recordings`));
     if (report.audio === undefined)
         return into.violations;
     if (!isPlainObject(report.audio)) {
@@ -2005,7 +2020,6 @@ export function validateHostReport(report, path = "host") {
 const TRANSFER_ACTIONS = ["cold", "warm", "complete", "cancel"];
 const LEAD_ASSIST_ACTIONS = ["request", "cancel", "take-over", "leave"];
 const CONFERENCE_ACTIONS = ["add", "remove"];
-const RECORDING_ACTIONS = ["start", "pause", "resume", "stop"];
 /**
  * What a command needs to be issuable, checked against the task it names: the capability the
  * guide's table gates it on, the phase it belongs to, and the state that has to stand -- a
@@ -2068,7 +2082,7 @@ export function validateTaskCommand(command, task, path = "command") {
             }
             break;
         case "recording":
-            into.oneOf(command.action, RECORDING_ACTIONS, "command.recording.action", `${path}.action`);
+            into.violations.push(...validateRecordingCommandShape(command, "provider", path));
             break;
         case "complete":
             if (command.disposition !== undefined)
@@ -2158,10 +2172,19 @@ export function validateTaskCommand(command, task, path = "command") {
             offered("endCall");
             handling();
             break;
-        case "recording":
+        case "recording": {
             offered("recording");
-            handling();
+            const policy = isPlainObject(capabilities.recording) ? capabilities.recording.provider : undefined;
+            const state = isPlainObject(task.recording) ? task.recording.provider : undefined;
+            into.violations.push(...validateRecordingCommandState(command, policy, state, path));
+            if (command.action === "start" || command.action === "resume") {
+                handling();
+                into.require(task.media === "started", "recording.request.phase", path, "capture needs live media");
+            }
+            else
+                inPhase("command.phase.handling", "in-progress", "paused", "completing");
             break;
+        }
         case "connect-back":
             offered("connectBack");
             inPhase("command.phase.completing", "completing");
@@ -2563,3 +2586,251 @@ export function validateAuthenticationState(state, path = "authentication", cont
     }
     return into.violations;
 }
+// Independent current recording evidence and dispatch validation.
+const object = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const filled = (v) => typeof v === "string" && v.trim().length > 0;
+const effects = ["retain", "discard"];
+function collector() {
+    const violations = [];
+    const check = (ok, rule, path, message) => {
+        ruleEvaluated(`recording.${rule}`);
+        if (!ok)
+            violations.push({ rule: `recording.${rule}`, path, message });
+        return Boolean(ok);
+    };
+    const keys = (v, allowed, path) => {
+        for (const key of Object.keys(v))
+            check(allowed.includes(key), "field", `${path}.${key}`, "field is not permitted in this recording variant");
+    };
+    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") {
+    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);
+        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");
+    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)) {
+        check(false, "policy.shape", path, "expected per-task provider/host action policy; true is no longer supported");
+        return violations;
+    }
+    keys(value, ["provider", "host"], path);
+    check(value.provider !== undefined || value.host !== undefined, "policy.empty", path, "declare at least one recording path");
+    for (const source of ["provider", "host"]) {
+        const policy = value[source];
+        if (policy === undefined)
+            continue;
+        const at = `${path}.${source}`;
+        if (!object(policy)) {
+            check(false, "policy.shape", at, "expected permitted actions");
+            continue;
+        }
+        keys(policy, [...RECORDING_ACTIONS, ...(source === "host" ? ["destinationId"] : [])], at);
+        check(RECORDING_ACTIONS.some(action => policy[action] !== undefined), "policy.empty", at, "omit paths offering no actions");
+        for (const action of RECORDING_ACTIONS) {
+            if (policy[action] === undefined)
+                continue;
+            if (action === "cancel") {
+                const cancel = policy.cancel;
+                check(object(cancel) && effects.includes(cancel.effect), "cancel.effect", `${at}.cancel`, "cancel explicitly retains or discards this recording's captured audio");
+                if (object(cancel))
+                    keys(cancel, ["effect"], `${at}.cancel`);
+            }
+            else
+                check(policy[action] === true, "policy.action", `${at}.${action}`, "permission is true or absent");
+        }
+        if (source === "host")
+            check(filled(policy.destinationId), "destination", `${at}.destinationId`, "host storage destination must be explicit per task");
+    }
+    return violations;
+}
+export function validateHostRecording(value, softphone, path = "host.recording") {
+    if (value === undefined)
+        return [];
+    const { violations, check, keys } = collector();
+    check(softphone, "host.channel", path, "initial host recording requires voice softphone media");
+    if (!object(value)) {
+        check(false, "host.shape", path, "expected host recording declaration and executor");
+        return violations;
+    }
+    keys(value, ["actions", "cancelEffects", "destinationIds", "execute"], path);
+    for (const [key, allowed] of [["actions", RECORDING_ACTIONS], ["cancelEffects", effects], ["destinationIds", undefined]]) {
+        const list = value[key];
+        if (!Array.isArray(list)) {
+            check(false, "host.list", `${path}.${key}`, "expected explicit array");
+            continue;
+        }
+        check(new Set(list).size === list.length, "host.duplicate", `${path}.${key}`, "duplicate declaration");
+        check(list.every(item => filled(item) && (allowed === undefined || allowed.includes(item))), "host.list", `${path}.${key}`, "unsupported or empty declaration");
+        if (key !== "cancelEffects")
+            check(list.length > 0, "host.empty", `${path}.${key}`, "declare at least one supported value");
+    }
+    if (Array.isArray(value.actions) && Array.isArray(value.cancelEffects)) {
+        check(value.actions.includes("cancel") === (value.cancelEffects.length > 0), "host.cancel", path, "cancel support and explicit effects must agree");
+        check(value.actions.includes("pause") === value.actions.includes("resume"), "host.pause", path, "a pausable host supports resume; task permissions may independently restrict it");
+    }
+    check(typeof value.execute === "function", "host.execute", `${path}.execute`, "host recording requires its own executor");
+    return violations;
+}
+export function validateHostRecordings(value, path = "host.recordings") {
+    if (value === undefined)
+        return [];
+    const { violations, check, keys } = collector();
+    if (!Array.isArray(value)) {
+        check(false, "reports.shape", path, "expected full host recording report array");
+        return violations;
+    }
+    const seen = new Set();
+    value.forEach((report, i) => {
+        const at = `${path}[${i}]`;
+        if (!object(report)) {
+            check(false, "report.shape", at, "expected scoped report");
+            return;
+        }
+        keys(report, ["taskId", "allocationId", "state"], at);
+        check(filled(report.taskId) && filled(report.allocationId), "report.scope", at, "report identifies task and allocation");
+        const key = JSON.stringify([report.taskId, report.allocationId]);
+        check(!seen.has(key), "report.duplicate", at, "one host state per task allocation");
+        seen.add(key);
+        violations.push(...validateRecordingState(report.state, `${at}.state`));
+    });
+    return violations;
+}
+export function validateRecordingCommandShape(value, source, path = "command") {
+    const { violations, check, keys } = collector();
+    if (!object(value)) {
+        check(false, "command.shape", path, "expected recording command");
+        return violations;
+    }
+    keys(value, ["type", "source", "requestId", "observationId", "action", ...(value.action === "start" ? [] : ["recordingId"]), ...(value.action === "cancel" ? ["cancelEffect"] : [])], 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 ["requestId", "observationId", ...(value.action === "start" ? [] : ["recordingId"])])
+        check(filled(value[key]), "command.identity", `${path}.${key}`, "expected nonempty scoped identity");
+    if (value.action === "cancel")
+        check(effects.includes(value.cancelEffect), "cancel.effect", `${path}.cancelEffect`, "explicit captured-audio disposition required");
+    return violations;
+}
+/** Structural/state permission check. Dispatch MUST also call validateRecordingRequest for scope and freshness. */
+export function validateRecordingCommandState(command, policy, state, path = "command") {
+    const { violations, check } = collector();
+    if (!object(command))
+        return violations;
+    check(object(policy) && policy[command.action] !== undefined, "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");
+        return violations;
+    }
+    const allowed = command.action === "start" ? ["inactive"] : command.action === "pause" ? ["active"] : command.action === "resume" ? ["paused"] : ["active", "paused"];
+    check(allowed.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");
+    if (command.action === "cancel" && object(policy))
+        check(object(policy.cancel) && command.cancelEffect === policy.cancel.effect, "command.cancelEffect", path, "cancel disposition must match task policy");
+    return violations;
+}
+/** Validate immediately before dispatch using current task, host report and trusted observer-domain time. */
+export function validateRecordingRequest(request, task, context, path = "request") {
+    const { violations, check, keys } = collector();
+    if (!object(request) || !object(task)) {
+        check(false, "request.shape", path, "request and current task required");
+        return violations;
+    }
+    violations.push(...validateTask(task, { channel: "voice" }, `${path}.task`));
+    keys(request, ["taskId", "allocationId", "command"], path);
+    check(filled(request.taskId) && filled(request.allocationId) && request.taskId === task.id && request.allocationId === task.allocationId, "request.scope", path, "task allocation changed or scope missing");
+    check(task.channel === "voice", "request.channel", path, "recording is voice-only");
+    violations.push(...validateRecordingCommandShape(request.command, context.source, `${path}.command`));
+    if (!object(request.command))
+        return violations;
+    const command = request.command;
+    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;
+    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.taskId === task.id && r.allocationId === task.allocationId)?.state : undefined;
+        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.destinationIds) && context.host.destinationIds.includes(policy.destinationId), "host.destination", path, "task destination is not provisioned by this host");
+            if (command.action === "cancel")
+                check(Array.isArray(context.host.cancelEffects) && context.host.cancelEffects.includes(command.cancelEffect), "host.cancelEffect", path, "host does not support cancel disposition");
+        }
+    }
+    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`));
+    const opening = command.action === "start" || command.action === "resume";
+    check(opening ? ["in-progress", "paused"].includes(task.phase) && task.media === "started" : ["in-progress", "paused", "completing"].includes(task.phase), "request.phase", path, "capture needs live task media; terminal controls may finish recordings during wrap-up");
+    return violations;
+}
+/** Check recording-specific result semantics against the owner's confirming observations. */
+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");
+        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.
+    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");
+    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");
+    }
+    else if (result.status === "applied") {
+        const expected = command.action === "pause" ? "paused" : command.action === "start" || command.action === "resume" ? "active" : "inactive";
+        check(after.status === expected, "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");
+        const origin = command.action === "start" ? ["inactive"] : command.action === "pause" ? ["active"] : command.action === "resume" ? ["paused"] : ["active", "paused"];
+        check(origin.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");
+    }
+    return violations;
+}

package/guide.md

@@ -58,7 +58,7 @@ transport, a task, a break and a call each have a word of their own:
 
 ### `OMNI_PROTOCOL_VERSION`
 
-The exact protocol version implemented by this package. The current value is `1`.
+The exact protocol version implemented by this package. The current value is `2`. Version 2 replaces the broad recording flag and untargeted recording command; version 1 is not negotiated by this package. Hosts and adapters must explicitly migrate together or retain their own version-1 implementation.
 
 ### `Manifest.supportedProtocolVersions`
 
@@ -289,7 +289,57 @@ type HostAudioOutput =
 
 type UrlVisibility = "full" | "domain" | "hidden";
 
+type RecordingSource = "provider" | "host";
+type RecordingAction = "start" | "pause" | "resume" | "stop" | "cancel";
+const RECORDING_ACTIONS = ["start", "pause", "resume", "stop", "cancel"] as const satisfies readonly RecordingAction[];
+type RecordingCancelEffect = "retain" | "discard";
+interface RecordingActions {
+  start?: true;
+  pause?: true;
+  resume?: true;
+  stop?: true;
+  cancel?: { effect: RecordingCancelEffect };
+}
+interface TaskRecordingPolicy {
+  provider?: RecordingActions;
+  host?: RecordingActions & { destinationId: 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;
+  requestId: string;
+  observationId: string;
+} & (
+  | { action: "start"; recordingId?: never; cancelEffect?: never }
+  | { action: "pause" | "resume" | "stop"; recordingId: string; cancelEffect?: never }
+  | { action: "cancel"; recordingId: string; cancelEffect: RecordingCancelEffect }
+);
+interface HostRecordingReport {
+  taskId: TaskId;
+  allocationId: AllocationId;
+  state: RecordingState;
+}
+interface HostRecording {
+  actions: RecordingAction[];
+  cancelEffects: RecordingCancelEffect[];
+  destinationIds: string[];
+  execute(request: HostRecordingRequest): Promise<RecordingCommandResult>;
+}
+type RecordingCommandResult = Exclude<TaskCommandResult, { status: "dialling" }>;
+interface HostRecordingRequest {
+  taskId: TaskId;
+  allocationId: AllocationId;
+  command: RecordingCommand & { source: "host" };
+}
+
 type HostReport = {
+  recordings?: HostRecordingReport[];
   online: boolean;
   audio?: {
     input: HostAudioInput;
@@ -303,6 +353,7 @@ type HostGuarantees = {
 };
 
 type Host = {
+  recording?: HostRecording;
   guarantees: HostGuarantees;
   mute?: HostMute;
   report(): HostReport;
@@ -327,7 +378,7 @@ type ConnectContext = {
   log?: (entry: unknown) => void;
 } & (
   | { phone: "softphone"; host: { mute: HostMute } }
-  | { phone?: "deskPhone"; host: { mute?: never } }
+  | { phone?: "deskPhone"; host: { mute?: never; recording?: never } }
 );
 
 type TransportStatus = "connecting" | "active" | "error";
@@ -511,7 +562,7 @@ type TaskCapabilities<C extends Channel = Channel> =
         warmTransfer?: Lockable<DestinationDirectory>;
         leadAssist?: Lockable<true>;
         conference?: Lockable<DestinationDirectory>;
-        recording?: Lockable<true>;
+        recording?: Lockable<TaskRecordingPolicy>;
       }
     : C extends "chat"
       ? SharedTaskCapabilities & { decline?: Lockable<true>; hold?: Lockable<true> }
@@ -686,8 +737,8 @@ type Task<C extends Channel = Channel> = {
   handlingHistory?: TaskHandlingHistory;
 } & TaskCompletion & (
   C extends "voice"
-    ? { onCall?: OnCall[]; leadAssist?: TaskLeadAssist; assisting?: TaskAssisting; monitoring?: TaskMonitoring; media?: TaskMediaState }
-    : { onCall?: never; leadAssist?: never; assisting?: never; monitoring?: never; media?: never }
+    ? { recording?: { provider?: RecordingState }; onCall?: OnCall[]; leadAssist?: TaskLeadAssist; assisting?: TaskAssisting; monitoring?: TaskMonitoring; media?: TaskMediaState }
+    : { recording?: never; onCall?: never; leadAssist?: never; assisting?: never; monitoring?: never; media?: never }
 );
 
 type PreviewDeadline = "calls" | "expires";
@@ -753,7 +804,7 @@ type VoiceTaskCommand =
   | { type: "conference"; action: "add"; dialId: DialId; destinationId: string }
   | { type: "conference"; action: "remove"; destinationId: string; party?: never }
   | { type: "conference"; action: "remove"; party: true; destinationId?: never }
-  | { type: "recording"; action: "start" | "pause" | "resume" | "stop" }
+  | (RecordingCommand & { source: "provider" })
   | ({ type: "complete" } & DispositionPayload);
 
 type ChatTaskCommand =
@@ -2994,7 +3045,7 @@ See **Which commands need a capability**.
 | `warmTransfer` | Secondary menu item: Warm transfer | Omni may park the customer and call a destination first, then hand the customer over or cancel back. See **Warm transfer**. |
 | `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist**. |
 | `conference` | Secondary button: Conference | Omni may dial a destination into the active call, and remove one person from it -- a conferenced entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
-| `recording` | Overflow menu item: Recording | Omni may expose start, pause, resume, and stop recording controls. |
+| `recording` | Overflow menu item: Recording | Per-task provider and host policies expose only their permitted recording actions; each has independent state and routing. |
 | `dispositions` | Primary button: Complete | Omni may request task disposal with a provider disposition and notes. |
 
 ### Publishing codes and destinations
@@ -4216,7 +4267,7 @@ capability's `notes` setting. A task publishing no codes still receives `complet
 
 Every command reaches the provider through `execute`, with no branch at the call site, and every
 command asks the provider to **perform** something: `hold`, `transfer`, `conference`, `end-call`,
-`recording` and the rest act on the platform's own call leg, its bridge, or its record of the
+Provider-targeted `recording` commands and the rest act on the platform's own call leg, its bridge, or its record of the
 task. Nothing has happened until the provider applies them, and `failed` means nothing happened.
 
 **The provider performs every action; the host only offers it.** A control drawn on the host is
@@ -4325,7 +4376,7 @@ declared:
 | Everything else | Its own named capability. |
 
 **A control on the contact belongs to the handling phases**, `in-progress` and `paused`:
-`hold`, `resume` and `pause`, `end-call`, `recording`, every `transfer` and `conference` action, and
+`hold`, `resume` and `pause`, `end-call`, every `transfer` and `conference` action, and
 every `lead-assist` action. Each acts on the call or the conversation, and only while there is one.
 Before `in-progress` nothing has been placed or opened; in `completing` the handling has ended -- a
 call with nobody on it, a conversation closed -- and a wrap-up that still shows Transfer shows it
@@ -4940,3 +4991,100 @@ belongs in this contract is the boundary. A provider says what a control **is**
 capabilities and what its work is **called** through `phaseLabels` and `taskTypePresentation`; how
 any of it is drawn is Omni's. A task cannot select a design language, inject a component, or
 override the agent's theme and font preferences.
+
+## Independent task recording (protocol 2)
+
+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 host publishes its own full scoped view in `HostReport.recordings`.
+A provider task update cannot replace host 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 host
+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. Host support is declared on `ConnectContext.host.recording`,
+not the provider-owned manifest. The task chooses an explicitly provisioned host destination;
+unknown destinations or unsupported actions are refused visibly, never redirected to provider
+recording or a default upload location. Initial host support requires voice softphone media and
+capture of both local and remote audio; a host unable to capture either must refuse start/resume.
+This package declares that contract; it supplies no recorder, media 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 with the explicitly declared captured-audio disposition |
+
+Cancel must declare retain or discard in task policy and echo that exact effect in the command.
+Retain abandons further capture while preserving captured audio; discard additionally requires
+confirmed disposal of that recording's audio under the recorder's storage contract. Neither
+means cancelling an in-flight start request or deleting arbitrary past recordings. A recorder
+unable to guarantee the offered effect must not advertise it. Stop can be applied only after
+finalization/retention succeeds; cancel-discard only after cessation and disposition succeed.
+Partial success (capture stopped but storage outcome unknown) cannot return failed with a claim
+of no effect. It rejects with unknown outcome, reports the failure visibly and publishes whatever
+current capture state is actually known. Retention is not a promise of sample-perfect audio.
+
+Provider commands go exclusively to `Connection.execute`; host commands go exclusively to
+`HostRecording.execute`. Both include task, allocation, request 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 reallocation only where the same recorder confirms continuity;
+commands always name the current allocation. 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, transfer to another recorder, or stop on task hold/disconnect.
+Task removal does not prove recording stopped: outstanding host recorders remain tracked by the
+host until its executor reconciles/finishes them, with visible unresolved cleanup failures.
+
+Only start/resume require an in-progress or paused task with started media. 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 handling 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 must invalidate their clock 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 allocation 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 host commands also supply the current host declaration,
+full host 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 durably correlates request identity with scope, action and outcome: an exact retry refers to the
+same operation; reuse with different contents is refused. It never silently retries an ambiguous
+operation. Implementations without reliable request correlation must refuse controls.
+
+Keep command progress in host UI separately from authoritative state. Applied means the requested
+transition and disposition actually completed; publish the confirming task or host 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/host views, not replayed provider events. These current-state fields
+create no handling-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 declare protocol 2 only after implementing
+these semantics. Existing version-1 adapters are refused by negotiation rather than silently mapped.
+This change does not publish a package or enable recording in any existing host/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/disposal or source truth from a status flag; those remain executor obligations.
+
+Host destination selection binds storage 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 destination rather than moving or discarding another binding.
+Action permission does not authorize unattended invocation: host controls require the agent's explicit
+act, and provider authorization remains enforced at its authenticated command boundary.

package/package.json

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