@xema/omni-protocol 0.1.81 → 0.1.83

package/dist/validation.js

@@ -85,7 +85,7 @@ const MEMBER_BREAKS = membersOf({
 const OFFERABLE_PHASES = membersOf({
     pending: true,
 });
-const PREVIEW_DEADLINES = membersOf({ calls: true, expires: true });
+const PREVIEW_DEADLINES = membersOf({ calls: true, "host-calls": true, waits: true });
 const PHONES = membersOf({ softphone: true, deskPhone: true });
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, leadAssistControl: true, policyControl: true, monitorControl: true });
 const MONITOR_MODES = membersOf({ monitor: true, whisper: true, barge: true });
@@ -395,6 +395,78 @@ export function validatePhone(value, manifest, path = "context.phone") {
 function manifestDials(manifest) {
     return isPlainObject(manifest) ? Array.isArray(manifest.dialOutcomes) : undefined;
 }
+/** Undefined explicitly means unavailable; a returned estimate is not a clock guarantee. */
+export function validateProviderTimeEstimate(value, scope, path = "estimate") {
+    const into = new Collector();
+    if (!isPlainObject(scope)) {
+        into.add("timeEstimate.scope", path, "provider/login scope is required");
+        return into.violations;
+    }
+    for (const key of ["providerId", "loginId"])
+        into.filled(scope[key], "timeEstimate.scope", `scope.${key}`, "explicit provider/login scope is required");
+    if (value === undefined)
+        return into.violations;
+    if (!isPlainObject(value)) {
+        into.add("timeEstimate.shape", path, "expected a provider time estimate or undefined");
+        return into.violations;
+    }
+    for (const key of ["providerId", "loginId"])
+        into.require(value[key] === scope[key], "timeEstimate.scope", `${path}.${key}`, "estimate must match the requested provider/login");
+    into.timestamp(value.at, "timeEstimate.at", `${path}.at`);
+    into.filled(value.clockId, "timeEstimate.clock", `${path}.clockId`, "estimate must identify its clock domain");
+    if (value.uncertaintyMs !== undefined)
+        into.require(typeof value.uncertaintyMs === "number" && Number.isFinite(value.uncertaintyMs) && value.uncertaintyMs >= 0, "timeEstimate.uncertainty", `${path}.uncertaintyMs`, "estimated uncertainty must be finite and nonnegative");
+    for (const key of Object.keys(value))
+        into.require(["providerId", "loginId", "at", "clockId", "uncertaintyMs"].includes(key), "timeEstimate.field", `${path}.${key}`, "unsupported estimate field");
+    return into.violations;
+}
+/** Validate host-local periodic clock-check configuration. Omission disables checking. */
+export function validateProviderTimeCheckPolicy(value, path = "timeCheck") {
+    const into = new Collector();
+    if (value === undefined)
+        return into.violations;
+    if (!isPlainObject(value)) {
+        into.add("timeCheck.policy.shape", path, "expected an explicit clock-check policy");
+        return into.violations;
+    }
+    for (const field of ["intervalMs", "timeoutMs", "maxRoundTripMs", "maxSampleAgeMs"]) {
+        into.require(typeof value[field] === "number" && Number.isSafeInteger(value[field]) && value[field] > 0, "timeCheck.policy.duration", `${path}.${field}`, "expected positive safe integer milliseconds");
+    }
+    for (const key of Object.keys(value))
+        into.require(["intervalMs", "timeoutMs", "maxRoundTripMs", "maxSampleAgeMs"].includes(key), "timeCheck.policy.field", `${path}.${key}`, "unsupported policy field");
+    if (!into.violations.length)
+        into.require(value.maxRoundTripMs <= value.timeoutMs && value.timeoutMs <= value.intervalMs, "timeCheck.policy.order", path, "maxRoundTripMs <= timeoutMs <= intervalMs is required");
+    return into.violations;
+}
+export function validateProviderTimeCheckRequest(value, path = "request") {
+    const into = new Collector();
+    if (!isPlainObject(value)) {
+        into.add("timeCheck.request.shape", path, "expected a clock-check request");
+        return into.violations;
+    }
+    into.filled(value.requestId, "timeCheck.request.id", `${path}.requestId`, "a check needs a fresh request ID");
+    for (const key of Object.keys(value))
+        into.require(key === "requestId", "timeCheck.request.field", `${path}.${key}`, "unsupported request field");
+    return into.violations;
+}
+/** Checks response shape/correlation, not source-clock accuracy, round-trip delay or freshness. */
+export function validateProviderTimeCheckResult(value, request, loginId, path = "result") {
+    const into = new Collector();
+    into.violations.push(...validateProviderTimeCheckRequest(request));
+    into.filled(loginId, "timeCheck.login", "loginId", "current authenticated login is required");
+    if (!isPlainObject(value)) {
+        into.add("timeCheck.result.shape", path, "expected a clock-check response");
+        return into.violations;
+    }
+    into.filled(value.requestId, "timeCheck.result.id", `${path}.requestId`, "response must identify its request");
+    into.require(isPlainObject(request) && value.requestId === request.requestId, "timeCheck.result.request", `${path}.requestId`, "response must match the outstanding check");
+    into.require(value.loginId === loginId, "timeCheck.result.login", `${path}.loginId`, "response belongs to the current login");
+    into.filled(value.clockId, "timeCheck.result.clock", `${path}.clockId`, "provider clock domain/incarnation is required");
+    into.timestamp(value.providerTime, "timeCheck.result.time", `${path}.providerTime`);
+    for (const key of Object.keys(value))
+        into.require(["requestId", "loginId", "clockId", "providerTime"].includes(key), "timeCheck.result.field", `${path}.${key}`, "unsupported response field");
+    return into.violations;
+}
 export function validateManifest(manifest, path = "manifest") {
     const into = new Collector();
     if (!isPlainObject(manifest)) {
@@ -430,6 +502,10 @@ export function validateManifest(manifest, path = "manifest") {
     }
     if (channelValid)
         validateIdleCapabilities(manifest.idleCapabilities, manifest.channel, `${path}.idleCapabilities`, into);
+    if (manifest.timestampAuthority !== undefined)
+        into.require(manifest.timestampAuthority === "provider", "manifest.timestampAuthority", `${path}.timestampAuthority`, "provider timestamp authority must be explicit; omission makes no trust promise");
+    if (manifest.timeCheck !== undefined)
+        into.require(manifest.timeCheck === true, "manifest.timeCheck", `${path}.timeCheck`, "declare true or omit unsupported clock checks");
     validateDialOutcomes(manifest, `${path}.dialOutcomes`, into);
     validatePhones(manifest, `${path}.phones`, into);
     if (manifest.phaseLabels !== undefined) {
@@ -853,7 +929,7 @@ function validateHandlingHistory(value, path, into, task = {}) {
                 into.require(task.phase === "paused", "task.handlingHistory.held.open", `${at}.seconds`, `a held entry without seconds is a hold still running, and the task is ${describeValue(task.phase)}: the hold has ended, and its duration is stated`);
             }
             if (entry.step === "muted") {
-                into.require(task.media !== "ended" && task.phase !== "completing", "task.handlingHistory.muted.open", `${at}.seconds`, "a muted entry without seconds is a mute still running, and the call is over: the provider closes every open leg at the instant the media ends, and the duration is stated");
+                into.require(task.media !== "ended" && task.phase !== "completing", "task.handlingHistory.muted.open", `${at}.seconds`, "a muted entry without seconds is still running, but this handling's media has ended: the provider closes its open leg and states the duration; other channels may continue");
             }
         }
         // A muted entry carries whose the silence was, as the host reported it; no other step has it.
@@ -885,9 +961,9 @@ function validateHandlingHistory(value, path, into, task = {}) {
 /** Present only while consulting, and only on voice: elsewhere there is nobody to consult. */
 const TASK_MEDIA_STATES = membersOf({ started: true, ended: true });
 /** Real-time media is a voice affair, and its state is one of two words. */
-/** Whether a host dial is ringing the party: the party entry carries `stage: "ringing"` and the host's `dialId`. */
-function partyRingingByHost(task) {
-    return Array.isArray(task.onCall) && task.onCall.some(entry => isPlainObject(entry) && entry.role === "party" && entry.stage === "ringing" && typeof entry.dialId === "string");
+/** A host dial, or explicitly provider-triggered preview dial, is ringing the party. */
+function partyRingingBeforeWork(task) {
+    return Array.isArray(task.onCall) && task.onCall.some(entry => isPlainObject(entry) && entry.role === "party" && entry.stage === "ringing" && (isFilled(entry.dialId) || (task.phase === "preview" && task.atDeadline === "calls" && entry.dialId === undefined)));
 }
 function validateTaskMedia(task, value, channel, phase, path, into) {
     if (value === undefined)
@@ -897,9 +973,9 @@ function validateTaskMedia(task, value, channel, phase, path, into) {
     if (into.oneOf(value, TASK_MEDIA_STATES, "task.media", path)) {
         // Nothing is acquired while pending, and a preview has placed no call: media names a task whose
         // work has begun, on a snapshot as on the event, or a host would open the microphone on an offer.
-        // The one task not yet at work that has audio is one whose party the host is dialling: ring-back
-        // is audio, and every host-placed dial's media starts on dialling.
-        into.require(!WORK_NOT_BEGUN.includes(phase) || partyRingingByHost(task), "task.media.beforeWork", path, `a ${describeValue(phase)} task has no media: audio arrives once its work has begun, or once the host is dialling its party`);
+        // Ring-back may precede answer for a host dial or an explicitly provider-triggered preview.
+        // A deadline alone is never evidence that media started.
+        into.require(!WORK_NOT_BEGUN.includes(phase) || partyRingingBeforeWork(task), "task.media.beforeWork", path, `a ${describeValue(phase)} task has no media: audio arrives once its work has begun, or once an evidenced host/provider preview dial is ringing its party`);
     }
 }
 const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
@@ -1063,7 +1139,7 @@ function validateTaskInto(task, context, path, into) {
             into.timestamp(task.previewEndsAt, "task.preview.previewEndsAt", `${path}.previewEndsAt`);
         }
         if (task.atDeadline === undefined) {
-            into.add("task.preview.atDeadline.required", `${path}.atDeadline`, "a preview with a deadline says what the system does at it: calls, or expires -- an agent counting down has to know which");
+            into.add("task.preview.atDeadline.required", `${path}.atDeadline`, "a preview with a deadline says what happens at it: provider calls, host calls, or waits for the agent -- an agent counting down has to know which");
         }
         else {
             into.oneOf(task.atDeadline, PREVIEW_DEADLINES, "task.preview.atDeadline", `${path}.atDeadline`);
@@ -1131,17 +1207,14 @@ function validateTaskInto(task, context, path, into) {
     validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
     validateOnCall(task.onCall, context.channel, `${path}.onCall`, into);
-    // The room is who is on the call now, and a task outlives its call by the whole of wrap-up: a
-    // task whose call has ended -- completing, or media ended -- carries nobody, or the last thing the
-    // wire said about the call stays true for ever. Empty and absent both say nobody.
-    // A completing task's call is over: its media has ended, or it never started. Audio still stated
-    // as started on a task in wrap-up is a call whose audio never ended -- the customer heard through
-    // the agent's notes -- and a task stating it contradicts itself.
+    // Media and onCall describe this agent's handling, not the continuing caller journey.
+    // Once the handling's media ends or it enters wrap, its live room is cleared. Other
+    // channels may remain connected under another handling or in IVR/queue stages.
     if (task.phase === "completing" && task.media === "started") {
-        into.add("task.media.completing", `${path}.media`, "a completing task's media has ended or never started: the call is over, and media still started is audio that never ended");
+        into.add("task.media.completing", `${path}.media`, "a completing task's handling media has ended or never started; it cannot still be started during wrap");
     }
     if (Array.isArray(task.onCall) && task.onCall.length > 0 && (task.phase === "completing" || task.media === "ended")) {
-        into.add("task.onCall.ended", `${path}.onCall`, `the call has ended (${task.phase === "completing" ? "the task is completing" : "its media ended"}) and onCall still names people on it: the room is who is on the call now, and now nobody is`);
+        into.add("task.onCall.ended", `${path}.onCall`, `this handling is no longer connected (${task.phase === "completing" ? "the task is completing" : "its media ended"}); clear its onCall view without implying that other channels ended`);
     }
     validateTaskMedia(task, task.media, context.channel, task.phase, `${path}.media`, into);
     validateLeadAssist(task.leadAssist, context.channel, `${path}.leadAssist`, into);
@@ -1235,6 +1308,184 @@ function validateImposedBreak(value, path, into) {
         into.add("break.imposed.endsAutomatically", `${path}.endsAutomatically`, "an imposed break must say whether it ends automatically");
     }
 }
+/** Checks break status against the full currently retained task set, after a transaction. */
+export function validateBreakStatus(state, tasks, path = "snapshot") {
+    const into = new Collector();
+    validateBreakState(state, `${path}.break`, into);
+    into.require(Array.isArray(tasks), "break.tasks.shape", `${path}.tasks`, "the complete current task list is required");
+    if (Array.isArray(tasks))
+        tasks.forEach((task, index) => {
+            into.require(isPlainObject(task), "break.task.shape", `${path}.tasks[${index}]`, "each retained task must be an object");
+        });
+    // A break in effect begins when the work ends, so it holds no task. A snapshot reporting both
+    // describes a state the agent cannot be in, whichever half is stale. The one exception is a
+    // lead listening to a call during a break that is work of another sort -- coaching,
+    // administrative, training -- and on no other.
+    // The converse: a committed break with nothing outstanding has begun. starting-after-task beside
+    // no task is a break waiting on work that does not exist, and an empty list reading as "still
+    // finishing" is the plausible nought.
+    ruleEvaluated("break.starting-after-task.tasks");
+    if (isPlainObject(state) && state.approval === "starting-after-task"
+        && Array.isArray(tasks) && tasks.length === 0) {
+        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is in-effect");
+    }
+    if (isPlainObject(state) && state.approval === "in-effect"
+        && Array.isArray(tasks) && tasks.length > 0) {
+        const listening = tasks.every((task) => isPlainObject(task) && task.monitoring !== undefined);
+        if (!listening) {
+            into.add("break.in-effect.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
+        }
+        else {
+            const reasons = Array.isArray(state.reasons) ? state.reasons : [];
+            const active = reasons.find((reason) => isPlainObject(reason) && reason.id === state.activeReasonId);
+            const kind = isPlainObject(active) ? active.kind : undefined;
+            into.require(typeof kind === "string" && MONITORING_BREAK_KINDS.includes(kind), "snapshot.monitoring.break", `${path}.tasks`, `a lead listens during a ${MONITORING_BREAK_KINDS.join(", ")} break and no other; the active reason is ${kind === undefined ? "unstated" : describeValue(kind)}`);
+        }
+    }
+    return into.violations;
+}
+/**
+ * Checks lead break dispatch using current authentication, transport, roster (`team`) and,
+ * for place/release, the target's full `memberBreak`. The provider must authorize the target
+ * and recheck the decision atomically; a roster is not authority to act after it has changed.
+ */
+export function validateTeamBreakCommand(request, context, path = "teamBreakCommand") {
+    const into = new Collector();
+    if (!isPlainObject(context) || !isPlainObject(request) || !isPlainObject(request.command)) {
+        into.add("team.break.command.shape", path, "a command and current authentication/transport/team context are required");
+        return into.violations;
+    }
+    const auth = isPlainObject(context.authentication) ? context.authentication : {};
+    into.violations.push(...validateAuthenticationState(auth, `${path}.authentication`));
+    const caps = isPlainObject(auth.capabilities) ? auth.capabilities : {};
+    into.require((auth.status === "authenticated" || auth.status === "refreshing") && context.transport === "active", "team.break.command.connection", path, "lead commands require a live login and active transport");
+    into.require(isPlainObject(caps.team) && caps.team.breakControl === true, "team.break.command.capability", path, "the login must declare team.breakControl");
+    const command = request.command;
+    const allowed = {
+        decide: ["type", "memberId", "decision", "reason"], policy: ["type", "policy"],
+        place: ["type", "memberId", "reasonId", "reason"], release: ["type", "memberId"],
+    };
+    const fields = typeof command.type === "string" && Object.hasOwn(allowed, command.type) ? allowed[command.type] : undefined;
+    if (!fields) {
+        into.add("team.break.command.type", path, "unknown lead break command");
+        return into.violations;
+    }
+    for (const key of Object.keys(request))
+        into.require(key === "command", "team.break.request.field", `${path}.${key}`, "only command is supported");
+    for (const key of Object.keys(command))
+        into.require(fields.includes(key), "team.break.command.field", `${path}.${key}`, "field is not supported for this command");
+    if (command.reason !== undefined)
+        into.filled(command.reason, "team.break.command.reason", path, "reason must not be empty");
+    if (command.type === "policy") {
+        into.require(["ask", "auto-approve", "suspended"].includes(command.policy), "team.break.command.policy", path, "unknown break policy");
+        return into.violations;
+    }
+    into.filled(command.memberId, "team.break.command.member", path, "name the target member");
+    const team = isPlainObject(context.team) ? context.team : {};
+    const members = Array.isArray(team.members) ? team.members : [];
+    const member = members.find((m) => isPlainObject(m) && m.id === command.memberId);
+    const self = isPlainObject(auth.identity) ? auth.identity.id : undefined;
+    into.require(isPlainObject(member) && command.memberId !== self, "team.break.command.member", path, "the target must be another member of the current authorized roster");
+    if (command.type === "decide") {
+        into.require(command.decision === "granted" || command.decision === "denied", "team.break.command.decision", path, "decide granted or denied");
+        into.require(isPlainObject(member) && member.break === "awaiting-decision", "team.break.command.awaiting", path, "decide only a currently awaiting-decision request");
+    }
+    else {
+        validateBreakState(context.memberBreak, `${path}.memberBreak`, into);
+        const state = isPlainObject(context.memberBreak) ? context.memberBreak : {};
+        if (command.type === "release")
+            into.require(state.imposed !== undefined && (state.approval === "in-effect" || state.approval === "starting-after-task"), "team.break.command.release", path, "release a currently imposed break");
+        if (command.type === "place") {
+            if (command.reasonId !== undefined)
+                into.filled(command.reasonId, "team.break.command.reasonId", path, "reasonId must not be empty");
+            const reasons = Array.isArray(state.reasons) ? state.reasons : [];
+            into.require(state.reasons === undefined ? command.reasonId === undefined : reasons.some((r) => isPlainObject(r) && r.id === command.reasonId), "team.break.command.reasonId", path, "place uses the target's currently published reason codes");
+        }
+    }
+    return into.violations;
+}
+/**
+ * Validate immediately before dispatch against current provider state. Context must contain
+ * the current authentication and transport. This cannot fence a concurrent backend change;
+ * the provider must recheck atomically. Result validation never replaces authoritative state.
+ */
+export function validateBreakCommand(method, request, state, context, path = "breakCommand") {
+    const into = new Collector();
+    validateBreakState(state, `${path}.state`, into);
+    if (!isPlainObject(context)) {
+        into.add("break.command.context", path, "current authentication and transport are required");
+        return into.violations;
+    }
+    into.violations.push(...validateAuthenticationState(context.authentication, `${path}.authentication`));
+    const auth = isPlainObject(context.authentication) ? context.authentication : {};
+    into.require(auth.status === "authenticated" || auth.status === "refreshing", "break.command.authentication", path, "break commands require a live authenticated login");
+    into.require(isPlainObject(auth.capabilities) && auth.capabilities.breaks === true, "break.command.capability", path, "the login must declare breaks");
+    into.require(context.transport === "active", "break.command.transport", path, "break commands require active transport");
+    if (!["requestBreak", "commitBreak", "cancelBreak", "endBreak"].includes(method)) {
+        into.add("break.command.method", path, "unknown break method");
+        return into.violations;
+    }
+    if (!isPlainObject(state) || into.violations.length)
+        return into.violations;
+    const approval = state.approval;
+    if (method === "requestBreak") {
+        into.require(approval === "not-requested", "break.command.request.pending", path, "a new request starts only from not-requested");
+        if (!isPlainObject(request)) {
+            into.add("break.request.shape", path, "requestBreak takes a request object");
+            return into.violations;
+        }
+        for (const key of Object.keys(request))
+            into.require(key === "reason" || key === "reasonId", "break.request.field", `${path}.${key}`, "a break request carries only reason and reasonId");
+        for (const key of ["reason", "reasonId"])
+            if (request[key] !== undefined)
+                into.filled(request[key], `break.request.${key}`, `${path}.${key}`, "a supplied reason must not be empty");
+        const reasons = Array.isArray(state.reasons) ? state.reasons : [];
+        const selected = reasons.find((r) => isPlainObject(r) && r.id === request.reasonId);
+        if (state.reasons !== undefined)
+            into.require(selected !== undefined, "break.request.reasonId", path, "choose a currently published reasonId; free text is not a substitute");
+        else
+            into.require(request.reasonId === undefined, "break.request.reasonId.unexpected", path, "no reason codes were published");
+        into.require(state.mayAsk === true || (isPlainObject(selected) && selected.alwaysAvailable === true), "break.request.mayAsk", path, "asking is disabled except for the selected alwaysAvailable reason");
+    }
+    else {
+        into.require(request === undefined, "break.command.arguments", path, "this break method takes no arguments");
+        if (method === "commitBreak")
+            into.require(approval === "granted" || approval === "starting-after-task" || approval === "in-effect", "break.command.commit.grant", path, "commit requires a grant; repeated committed state is idempotent");
+        if (method === "cancelBreak")
+            into.require(approval === "awaiting-decision" || approval === "granted", "break.command.cancel.precommit", path, "cancel only a pre-commit request; a raced commit requires commit recovery");
+        if (method === "endBreak") {
+            into.require(approval === "starting-after-task" || approval === "in-effect", "break.command.end.started", path, "end a committed break, including a returning provider still finishing work");
+            into.require(state.imposed === undefined, "break.command.end.imposed", path, "an agent cannot end an imposed break; an authorized lead releases it");
+        }
+    }
+    return into.violations;
+}
+/**
+ * Checks two complete break states within one provider/login's ordered event stream.
+ * Call before replacing accepted state; report violations and reconcile on failure.
+ * This is not a freshness check: validate a fresh authoritative snapshot separately and
+ * use it as a new baseline, never as an event transition. Source ordering and connection
+ * fencing remain required; neither timestamps nor approval rank identify a break attempt.
+ */
+export function validateBreakTransition(before, after, path = "break") {
+    const into = new Collector();
+    validateBreakState(before, `${path}.before`, into);
+    validateBreakState(after, `${path}.after`, into);
+    if (into.violations.length || !isPlainObject(before) || !isPlainObject(after))
+        return into.violations;
+    const from = before.approval;
+    const to = after.approval;
+    const committed = to === "starting-after-task" || to === "in-effect";
+    if (committed && (from === "not-requested" || from === "awaiting-decision") && after.imposed === undefined) {
+        into.add("stream.breakState.commitBeforeGrant", `${path}.after.approval`, `${to} follows a commit, and a commit follows granted; the break stood at ${from}`);
+    }
+    const backwards = (from === "in-effect" && (to === "awaiting-decision" || to === "granted" || to === "starting-after-task")) ||
+        (from === "starting-after-task" && (to === "awaiting-decision" || to === "granted")) ||
+        (from === "granted" && to === "awaiting-decision");
+    if (backwards)
+        into.add("stream.breakState.backwards", `${path}.after.approval`, `a break does not go from ${from} back to ${to}; a new request passes through not-requested`);
+    return into.violations;
+}
 function validateBreakState(value, path, into) {
     if (!isPlainObject(value)) {
         into.add("break.shape", path, "break state must be an object");
@@ -1417,7 +1668,6 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         && context.loginId !== undefined) {
         into.require(snapshot.loginId === context.loginId, "snapshot.loginId.mismatch", `${path}.loginId`, `a snapshot for session ${describeValue(snapshot.loginId)} on a login whose session is ${context.loginId}`);
     }
-    validateBreakState(snapshot.break, `${path}.break`, into);
     // The count is the provider's confirmation of how much work it answered with. Stated, never
     // inferred: an unanswered or blank state lacks it, and cannot pass as a confirmed empty.
     if (into.require(typeof snapshot.taskCount === "number" && Number.isInteger(snapshot.taskCount) && snapshot.taskCount >= 0, "snapshot.taskCount", `${path}.taskCount`, "a snapshot states its task count: a whole number, zero or more")
@@ -1459,32 +1709,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
             }
         });
     }
-    // A break in effect begins when the work ends, so it holds no task. A snapshot reporting both
-    // describes a state the agent cannot be in, whichever half is stale. The one exception is a
-    // lead listening to a call during a break that is work of another sort -- coaching,
-    // administrative, training -- and on no other.
-    // The converse: a committed break with nothing outstanding has begun. starting-after-task beside
-    // no task is a break waiting on work that does not exist, and an empty list reading as "still
-    // finishing" is the plausible nought.
-    ruleEvaluated("break.starting-after-task.tasks");
-    if (isPlainObject(snapshot.break) && snapshot.break.approval === "starting-after-task"
-        && Array.isArray(snapshot.tasks) && snapshot.tasks.length === 0) {
-        into.add("break.starting-after-task.tasks", `${path}.break.approval`, "a break starting after the task waits on a task, and the snapshot carries none: with nothing outstanding the break is in-effect");
-    }
-    if (isPlainObject(snapshot.break) && snapshot.break.approval === "in-effect"
-        && Array.isArray(snapshot.tasks) && snapshot.tasks.length > 0) {
-        const listening = snapshot.tasks.every((task) => isPlainObject(task) && task.monitoring !== undefined);
-        if (!listening) {
-            into.add("break.in-effect.tasks", `${path}.tasks`, "a break in effect holds no task: it begins when the work ends, and until then the state is starting-after-task");
-        }
-        else {
-            const state = snapshot.break;
-            const reasons = Array.isArray(state.reasons) ? state.reasons : [];
-            const active = reasons.find((reason) => isPlainObject(reason) && reason.id === state.activeReasonId);
-            const kind = isPlainObject(active) ? active.kind : undefined;
-            into.require(typeof kind === "string" && MONITORING_BREAK_KINDS.includes(kind), "snapshot.monitoring.break", `${path}.tasks`, `a lead listens during a ${MONITORING_BREAK_KINDS.join(", ")} break and no other; the active reason is ${kind === undefined ? "unstated" : describeValue(kind)}`);
-        }
-    }
+    into.violations.push(...validateBreakStatus(snapshot.break, snapshot.tasks, path));
     // Presence is the permission, and it cuts both ways: data a provider never declared a
     // capability for is data Omni would show against a control the agent does not have.
     const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
@@ -2020,6 +2245,22 @@ 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"];
+/** Validate the exact handling/allocation target before provider command dispatch. */
+export function validateTaskCommandRequest(request, task, path = "request", taskContext) {
+    const into = new Collector();
+    if (!isPlainObject(request) || !isPlainObject(task)) {
+        into.add("command.request.shape", path, "a request and the current published task are required");
+        return into.violations;
+    }
+    into.filled(request.taskId, "command.request.taskId", `${path}.taskId`, "name the handling task");
+    into.filled(request.allocationId, "command.request.allocationId", `${path}.allocationId`, "name its allocation");
+    into.require(request.taskId === task.id, "command.request.taskId.mismatch", `${path}.taskId`, "the command must target this exact handling");
+    into.require(request.allocationId === task.allocationId, "command.request.allocationId.mismatch", `${path}.allocationId`, "the command must target this exact allocation");
+    for (const key of Object.keys(request))
+        into.require(["taskId", "allocationId", "command"].includes(key), "command.request.field", `${path}.${key}`, "unsupported task command request field");
+    into.violations.push(...validateTaskCommand(request.command, task, `${path}.command`, taskContext));
+    return into.violations;
+}
 /**
  * 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
@@ -2027,7 +2268,7 @@ const CONFERENCE_ACTIONS = ["add", "remove"];
  * own shape is checked. A host validates before sending, and an adapter before acting: a command
  * for a control the task never offered is the host's error, and this names it.
  */
-export function validateTaskCommand(command, task, path = "command") {
+export function validateTaskCommand(command, task, path = "command", taskContext) {
     const into = new Collector();
     if (!isPlainObject(command)) {
         into.add("command.shape", path, "a command must be an object");
@@ -2044,6 +2285,36 @@ export function validateTaskCommand(command, task, path = "command") {
     if (type !== "custom" && !into.require(typeof type === "string" && names.includes(type), "command.type", `${path}.type`, channel === undefined ? `unsupported command: ${describeValue(type)}` : `a ${channel} task has no ${describeValue(type)} command`)) {
         return into.violations;
     }
+    // Built-in commands carry only their declared fields; custom controls own their payload.
+    // Recording already applies its action-specific field check below.
+    if (type !== "custom" && type !== "recording") {
+        let fields = ["type"];
+        switch (type) {
+            case "call":
+            case "connect-back":
+                fields.push("dialId");
+                break;
+            case "complete":
+                fields.push("disposition", "notes");
+                break;
+            case "transfer":
+                fields.push("action");
+                if (command.action === "cold" || command.action === "warm")
+                    fields.push("dialId", "destinationId");
+                break;
+            case "lead-assist":
+                fields.push("action");
+                if (command.action === "request")
+                    fields.push("note");
+                break;
+            case "conference":
+                fields.push("action", "destinationId");
+                fields.push(command.action === "add" ? "dialId" : "party");
+                break;
+        }
+        for (const key of Object.keys(command))
+            into.require(fields.includes(key), "command.field", `${path}.${key}`, "field is not supported for this command");
+    }
     const dial = (rule) => into.filled(command.dialId, rule, `${path}.dialId`, "a command that dials carries the host's dialId");
     switch (type) {
         case "call":
@@ -2100,7 +2371,7 @@ export function validateTaskCommand(command, task, path = "command") {
     // checking against a task nobody has -- so the task is validated first, and a command is held
     // only to a task that stands.
     const published = new Collector();
-    validateTaskInto(task, { channel: channel ?? "voice" }, `${path}.task`, published);
+    validateTaskInto(task, { ...taskContext, channel: channel ?? "voice" }, `${path}.task`, published);
     if (published.violations.length > 0 || !isPlainObject(task)) {
         into.add("command.task", `${path}.task`, `the task the command is held to is not one the wire published (${published.violations.map(v => v.rule).join(", ")}): pass the task as the provider sent it, or validate the command's shape alone`);
         return into.violations;
@@ -2141,8 +2412,8 @@ export function validateTaskCommand(command, task, path = "command") {
     };
     const inPhase = (rule, ...phases) => into.require(typeof task.phase === "string" && phases.includes(task.phase), rule, path, `${describeValue(type)} belongs to ${phases.join(" or ")}, and the task is ${describeValue(task.phase)}`);
     // A control on the contact acts on a contact being handled. Before in-progress there is nothing
-    // to act on yet, and in completing the handling has ended: a call with nobody on it, a
-    // conversation closed. What a capability offers, the phase decides whether there is anything to use it on.
+    // to act on yet, and in completing this agent's handling has ended. The caller and other
+    // channels may continue elsewhere; this task's phase no longer permits these controls.
     const handling = () => inPhase("command.phase.handling", "in-progress", "paused");
     // A destination is one the directory offered: the id Omni sends is the id the provider published.
     const listed = (name) => {
@@ -2173,7 +2444,8 @@ export function validateTaskCommand(command, task, path = "command") {
             handling();
             break;
         case "recording": {
-            offered("recording");
+            if (!offered("recording"))
+                break;
             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));
@@ -2326,6 +2598,8 @@ export function validateResult(result, method, path = "result", dialId) {
         else {
             into.require(result.dialId === undefined, "result.dialId.unexpected", `${path}.dialId`, `${statuses.success} dialled nothing and names no dial`);
         }
+        if (method === "recordStep")
+            into.timestamp(result.at, "result.recordStep.at", `${path}.at`);
     }
     else if (statuses.failure !== undefined && result.status === statuses.failure) {
         if (result.failure === undefined) {
@@ -2589,7 +2863,6 @@ export function validateAuthenticationState(state, path = "authentication", cont
 // 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) => {
@@ -2660,14 +2933,7 @@ export function validateRecordingPolicy(value, path = "capabilities.recording")
         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");
+            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");
@@ -2683,8 +2949,10 @@ export function validateHostRecording(value, softphone, path = "host.recording")
         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]]) {
+    keys(value, ["actions", "destinationIds", "execute", "announcesToCaller"], path);
+    if (value.announcesToCaller !== undefined)
+        check(value.announcesToCaller === true, "host.announcesToCaller", `${path}.announcesToCaller`, "caller announcement guarantee is true or absent");
+    for (const [key, allowed] of [["actions", RECORDING_ACTIONS], ["destinationIds", undefined]]) {
         const list = value[key];
         if (!Array.isArray(list)) {
             check(false, "host.list", `${path}.${key}`, "expected explicit array");
@@ -2692,11 +2960,9 @@ export function validateHostRecording(value, softphone, path = "host.recording")
         }
         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");
+        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");
+    if (Array.isArray(value.actions)) {
         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");
@@ -2732,32 +2998,47 @@ export function validateRecordingCommandShape(value, source, path = "command") {
         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);
+    keys(value, ["type", "source", "requestId", "observationId", "action", ...(value.action === "start" ? [] : ["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 ["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;
 }
+/** 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" },
+};
+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 { violations, check } = collector();
-    if (!object(command))
+    if (!object(command)) {
+        check(false, "command.shape", path, "expected recording command");
+        return violations;
+    }
+    const transition = recordingTransition(command.action);
+    if (transition === undefined) {
+        check(false, "command.action", `${path}.action`, "unsupported recording action");
         return violations;
-    check(object(policy) && policy[command.action] !== undefined, "command.permission", path, "task does not permit this action on this recorder");
+    }
+    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");
         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(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");
-    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. */
@@ -2767,7 +3048,7 @@ export function validateRecordingRequest(request, task, context, path = "request
         check(false, "request.shape", path, "request and current task required");
         return violations;
     }
-    violations.push(...validateTask(task, { channel: "voice" }, `${path}.task`));
+    violations.push(...validateTask(task, { ...context.taskContext, 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");
@@ -2788,8 +3069,6 @@ export function validateRecordingRequest(request, task, context, path = "request
         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);
@@ -2819,12 +3098,13 @@ export function validateRecordingOutcome(command, before, after, result, path =
         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");
+        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");
-        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");
+        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")