@xema/omni-protocol 0.1.82 → 0.1.84

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { RECORDING_ACTIONS, 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, INTERACTION_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") {
@@ -57,7 +57,7 @@ const BREAK_APPROVALS = membersOf({
 const TEAM_AVAILABILITIES = membersOf({
     ready: true, "on-task": true, "on-break": true, reserved: true, "signed-out": true,
 });
-const HANDLING_STEPS = membersOf({
+const INTERACTION_STEPS = membersOf({
     queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
 });
 const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
@@ -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) {
@@ -446,7 +522,8 @@ export function validateManifest(manifest, path = "manifest") {
     if (manifest.runningStepReports !== undefined) {
         into.require(manifest.runningStepReports === true, "manifest.runningStepReports", `${path}.runningStepReports`, "runningStepReports is declared by presence, as true; a provider that takes begin and end only omits it");
     }
-    into.require(typeof manifest.disposalSettleMs === "number" && Number.isInteger(manifest.disposalSettleMs) && manifest.disposalSettleMs > 0, "manifest.disposalSettleMs", `${path}.disposalSettleMs`, "disposalSettleMs is how long after an applied disposal the task-ended is owed, a positive whole number of milliseconds, stated by every provider");
+    into.require(!Object.hasOwn(manifest, "disposalSettleMs"), "manifest.completionSettleMs.renamed", `${path}.disposalSettleMs`, "use completionSettleMs; the former field is not accepted");
+    into.require(typeof manifest.completionSettleMs === "number" && Number.isInteger(manifest.completionSettleMs) && manifest.completionSettleMs > 0, "manifest.completionSettleMs", `${path}.completionSettleMs`, "completionSettleMs is how long after an applied completion the task-ended is owed, a positive whole number of milliseconds, stated by every provider");
     if (manifest.orgLevels !== undefined) {
         if (!Array.isArray(manifest.orgLevels)) {
             into.add("manifest.orgLevels.shape", `${path}.orgLevels`, "orgLevels must be an array when present");
@@ -803,81 +880,82 @@ function validateTaskAttributes(value, path, into, levels) {
         }
     });
 }
-function validateHandlingHistory(value, path, into, task = {}) {
+function validateInteractionHistory(value, path, into, task = {}) {
     if (value === undefined)
         return;
     if (!isPlainObject(value)) {
-        into.add("task.handlingHistory.shape", path, "handlingHistory must be an object with its steps when present");
+        into.add("task.interactionHistory.shape", path, "interactionHistory must be an object with its steps when present");
         return;
     }
     // What the record adds up to before this agent: each total present when the provider knows it
     // and absent when it does not, never a plausible nought.
-    for (const field of ["handleSeconds", "holdSeconds", "queueSeconds"]) {
+    into.require(!Object.hasOwn(value, "handleSeconds"), "task.interactionHistory.interactionSeconds.renamed", `${path}.handleSeconds`, "use interactionSeconds; the former field is not accepted");
+    for (const field of ["interactionSeconds", "holdSeconds", "queueSeconds"]) {
         if (value[field] !== undefined) {
-            into.require(isDurationSeconds(value[field]), `task.handlingHistory.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
+            into.require(isDurationSeconds(value[field]), `task.interactionHistory.${field}`, `${path}.${field}`, `${field} must be a whole number of seconds, zero or more, or omitted when unknown`);
         }
     }
     if (value.transfers !== undefined) {
-        into.require(typeof value.transfers === "number" && Number.isInteger(value.transfers) && value.transfers >= 0, "task.handlingHistory.transfers", `${path}.transfers`, "transfers must be a whole number, zero or more, or omitted when unknown");
+        into.require(typeof value.transfers === "number" && Number.isInteger(value.transfers) && value.transfers >= 0, "task.interactionHistory.transfers", `${path}.transfers`, "transfers must be a whole number, zero or more, or omitted when unknown");
     }
     if (!Array.isArray(value.steps)) {
-        into.add("task.handlingHistory.steps.shape", `${path}.steps`, "handlingHistory carries its steps as an array, empty when the task has had none");
+        into.add("task.interactionHistory.steps.shape", `${path}.steps`, "interactionHistory carries its steps as an array, empty when the task has had none");
         return;
     }
     let previous;
     value.steps.forEach((entry, index) => {
         const at = `${path}.steps[${index}]`;
         if (!isPlainObject(entry)) {
-            into.add("task.handlingHistory.entry", at, "each handling step must be an object");
+            into.add("task.interactionHistory.entry", at, "each interaction step must be an object");
             return;
         }
-        into.oneOf(entry.step, HANDLING_STEPS, "task.handlingHistory.step", `${at}.step`);
-        if (into.timestamp(entry.at, "task.handlingHistory.at", `${at}.at`)) {
+        into.oneOf(entry.step, INTERACTION_STEPS, "task.interactionHistory.step", `${at}.step`);
+        if (into.timestamp(entry.at, "task.interactionHistory.at", `${at}.at`)) {
             // The record is one entry per occurrence, oldest first: a second hold is a second entry
             // after the first, never a revision of it or an entry filed out of its turn.
             const instant = Date.parse(entry.at);
             if (previous !== undefined && instant < previous) {
-                into.add("task.handlingHistory.order", `${at}.at`, "handling steps are oldest first; this entry is earlier than the one before it");
+                into.add("task.interactionHistory.order", `${at}.at`, "interaction steps are oldest first; this entry is earlier than the one before it");
             }
             previous = instant;
         }
         if (entry.seconds !== undefined) {
             // Omitted while a leg is still running. Nought is a claim that it took no time.
-            into.require(isDurationSeconds(entry.seconds) && entry.seconds > 0, "task.handlingHistory.seconds", `${at}.seconds`, "seconds must be a positive whole number; omit it while the step is still running");
+            into.require(isDurationSeconds(entry.seconds) && entry.seconds > 0, "task.interactionHistory.seconds", `${at}.seconds`, "seconds must be a positive whole number; omit it while the step is still running");
         }
         else {
             // An open leg is one still running, and the task says whether it can be: a hold runs only while
             // the task is paused, and a mute only while its media is up. An open entry after that is a leg
             // nobody closed, which reads exactly like a leg running now.
             if (entry.step === "held") {
-                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`);
+                into.require(task.phase === "paused", "task.interactionHistory.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.interactionHistory.muted.open", `${at}.seconds`, "a muted entry without seconds is still running, but this interaction'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.
         // And it names the agent: the host has exactly one, the provider knows who, so an unattributed
         // muted leg is a record that dropped a fact it held rather than one it could not establish.
         if (entry.step === "muted") {
-            into.oneOf(entry.mutedBy, MUTED_BY, "task.handlingHistory.mutedBy", `${at}.mutedBy`);
-            into.require(entry.by !== undefined, "task.handlingHistory.muted.by", `${at}.by`, "a muted leg is attributed to the login's agent: the host reported it, and the provider knows who the host's agent is");
+            into.oneOf(entry.mutedBy, MUTED_BY, "task.interactionHistory.mutedBy", `${at}.mutedBy`);
+            into.require(entry.by !== undefined, "task.interactionHistory.muted.by", `${at}.by`, "a muted leg is attributed to the login's agent: the host reported it, and the provider knows who the host's agent is");
         }
-        else if (HANDLING_STEPS.includes(entry.step)) {
-            into.require(entry.mutedBy === undefined, "task.handlingHistory.mutedBy.unexpected", `${at}.mutedBy`, "only a muted step says who silenced the microphone");
+        else if (INTERACTION_STEPS.includes(entry.step)) {
+            into.require(entry.mutedBy === undefined, "task.interactionHistory.mutedBy.unexpected", `${at}.mutedBy`, "only a muted step says who silenced the microphone");
         }
         if (entry.by !== undefined) {
-            into.require(isUserId(entry.by), "task.handlingHistory.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
+            into.require(isUserId(entry.by), "task.interactionHistory.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
             // On `queued` nobody takes part, so there is nothing to name.
-            into.require(entry.step !== "queued", "task.handlingHistory.by.unexpected", `${at}.by`, "a queued step names nobody");
+            into.require(entry.step !== "queued", "task.interactionHistory.by.unexpected", `${at}.by`, "a queued step names nobody");
         }
         // A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
-        const dialled = typeof entry.step === "string" && HANDLING_STEPS_THAT_DIAL.includes(entry.step);
+        const dialled = typeof entry.step === "string" && INTERACTION_STEPS_THAT_DIAL.includes(entry.step);
         for (const field of ["dialId", "destinationId"]) {
             if (entry[field] === undefined)
                 continue;
-            if (into.filled(entry[field], `task.handlingHistory.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
-                into.require(dialled, `task.handlingHistory.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred, conferenced, or unanswered`);
+            if (into.filled(entry[field], `task.interactionHistory.${field}`, `${at}.${field}`, `${field} must not be empty when present`)) {
+                into.require(dialled, `task.interactionHistory.${field}.unexpected`, `${at}.${field}`, `${describeValue(entry.step)} dialled nothing; ${field} belongs on transferred, conferenced, or unanswered`);
             }
         }
     });
@@ -885,9 +963,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 +975,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"];
@@ -1043,6 +1121,7 @@ function validateTaskInto(task, context, path, into) {
         into.add("task.shape", path, "a task must be an object");
         return;
     }
+    into.require(!Object.hasOwn(task, "handlingHistory"), "task.interactionHistory.renamed", `${path}.handlingHistory`, "use interactionHistory; the former field is not accepted");
     into.require(isTaskId(task.id), "task.id", `${path}.id`, "a task needs a non-empty id");
     into.require(isAllocationId(task.allocationId), "task.allocationId", `${path}.allocationId`, "a task names this life of itself: an allocation id minted once per offer, never reused for the life of the login");
     into.filled(task.title, "task.title", `${path}.title`, "a task needs a title");
@@ -1063,7 +1142,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`);
@@ -1129,19 +1208,16 @@ function validateTaskInto(task, context, path, into) {
     }
     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 });
+    validateInteractionHistory(task.interactionHistory, `${path}.interactionHistory`, 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 interaction, not the continuing caller journey.
+    // Once the interaction's media ends or it enters wrap, its live room is cleared. Other
+    // channels may remain connected under another interaction 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 interaction 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 interaction 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 +1311,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 +1671,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 +1712,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 : {};
@@ -1904,34 +2132,34 @@ export function validateHostGuarantees(guarantees, path = "host.guarantees") {
  * a task, a step, when it began, how long so far if the host says, and an explicit end that
  * carries the final duration.
  */
-export function validateHandlingReport(report, path = "handlingReport", manifest) {
+export function validateInteractionReport(report, path = "interactionReport", manifest) {
     const into = new Collector();
     if (!isPlainObject(report)) {
-        into.add("handlingReport.shape", path, "a handling report must be an object");
+        into.add("interactionReport.shape", path, "an interaction report must be an object");
         return into.violations;
     }
-    into.require(isTaskId(report.taskId), "handlingReport.taskId", `${path}.taskId`, "a report names the task");
-    into.require(isAllocationId(report.allocationId), "handlingReport.allocationId", `${path}.allocationId`, "a report names the task's allocation, so a late one never lands on the next life of the id");
-    into.oneOf(report.step, HANDLING_STEPS, "handlingReport.step", `${path}.step`);
-    into.timestamp(report.at, "handlingReport.at", `${path}.at`);
+    into.require(isTaskId(report.taskId), "interactionReport.taskId", `${path}.taskId`, "a report names the task");
+    into.require(isAllocationId(report.allocationId), "interactionReport.allocationId", `${path}.allocationId`, "a report names the task's allocation, so a late one never lands on the next life of the id");
+    into.oneOf(report.step, INTERACTION_STEPS, "interactionReport.step", `${path}.step`);
+    into.timestamp(report.at, "interactionReport.at", `${path}.at`);
     // A muted leg says whose the silence was; no other leg has anyone to name for it.
     if (report.step === "muted")
-        into.oneOf(report.mutedBy, MUTED_BY, "handlingReport.mutedBy", `${path}.mutedBy`);
-    else if (HANDLING_STEPS.includes(report.step)) {
-        into.require(report.mutedBy === undefined, "handlingReport.mutedBy.unexpected", `${path}.mutedBy`, "only a muted leg says who silenced the microphone");
+        into.oneOf(report.mutedBy, MUTED_BY, "interactionReport.mutedBy", `${path}.mutedBy`);
+    else if (INTERACTION_STEPS.includes(report.step)) {
+        into.require(report.mutedBy === undefined, "interactionReport.mutedBy.unexpected", `${path}.mutedBy`, "only a muted leg says who silenced the microphone");
     }
     if (report.seconds !== undefined) {
-        into.require(isDurationSeconds(report.seconds) && report.seconds > 0, "handlingReport.seconds", `${path}.seconds`, "seconds must be a positive whole number; omit it rather than report nought");
+        into.require(isDurationSeconds(report.seconds) && report.seconds > 0, "interactionReport.seconds", `${path}.seconds`, "seconds must be a positive whole number; omit it rather than report nought");
     }
     if (report.ended !== undefined) {
-        if (into.require(report.ended === true, "handlingReport.ended", `${path}.ended`, "ended is declared by presence, as true; a running leg omits it")) {
-            into.require(report.seconds !== undefined, "handlingReport.ended.seconds", `${path}.seconds`, "an ended leg states its final duration");
+        if (into.require(report.ended === true, "interactionReport.ended", `${path}.ended`, "ended is declared by presence, as true; a running leg omits it")) {
+            into.require(report.seconds !== undefined, "interactionReport.ended.seconds", `${path}.seconds`, "an ended leg states its final duration");
         }
     }
     else if (report.seconds !== undefined && manifest !== undefined) {
         // A running report crosses only to a provider that asked for one: begin and end are the whole
         // of what the rest receive.
-        into.require(isPlainObject(manifest) && manifest.runningStepReports === true, "handlingReport.running.unexpected", `${path}.seconds`, "this provider takes begin and end only; a running report was never asked for");
+        into.require(isPlainObject(manifest) && manifest.runningStepReports === true, "interactionReport.running.unexpected", `${path}.seconds`, "this provider takes begin and end only; a running report was never asked for");
     }
     return into.violations;
 }
@@ -2020,6 +2248,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 interaction/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 interaction 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 interaction");
+    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
@@ -2044,6 +2288,36 @@ export function validateTaskCommand(command, task, path = "command", taskContext
     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":
@@ -2141,9 +2415,9 @@ export function validateTaskCommand(command, task, path = "command", taskContext
     };
     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.
-    const handling = () => inPhase("command.phase.handling", "in-progress", "paused");
+    // to act on yet, and in completing this agent's interaction has ended. The caller and other
+    // channels may continue elsewhere; this task's phase no longer permits these controls.
+    const interaction = () => inPhase("command.phase.interaction", "in-progress", "paused");
     // A destination is one the directory offered: the id Omni sends is the id the provider published.
     const listed = (name) => {
         const declared = capabilities[name];
@@ -2166,11 +2440,11 @@ export function validateTaskCommand(command, task, path = "command", taskContext
         case "resume":
         case "pause":
             offered("hold");
-            handling();
+            interaction();
             break;
         case "end-call":
             offered("endCall");
-            handling();
+            interaction();
             break;
         case "recording": {
             if (!offered("recording"))
@@ -2179,11 +2453,11 @@ export function validateTaskCommand(command, task, path = "command", taskContext
             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();
+                interaction();
                 into.require(task.media === "started", "recording.request.phase", path, "capture needs live media");
             }
             else
-                inPhase("command.phase.handling", "in-progress", "paused", "completing");
+                inPhase("command.phase.interaction", "in-progress", "paused", "completing");
             break;
         }
         case "connect-back":
@@ -2191,7 +2465,7 @@ export function validateTaskCommand(command, task, path = "command", taskContext
             inPhase("command.phase.completing", "completing");
             break;
         case "transfer":
-            handling();
+            interaction();
             if (command.action === "cold") {
                 if (offered("coldTransfer"))
                     listed("coldTransfer");
@@ -2205,7 +2479,7 @@ export function validateTaskCommand(command, task, path = "command", taskContext
             }
             break;
         case "lead-assist":
-            handling();
+            interaction();
             if (command.action === "request" || command.action === "cancel") {
                 offered("leadAssist");
                 if (command.action === "cancel") {
@@ -2217,7 +2491,7 @@ export function validateTaskCommand(command, task, path = "command", taskContext
             }
             break;
         case "conference": {
-            handling();
+            interaction();
             const conferencing = offered("conference");
             if (conferencing && command.action === "add")
                 listed("conference");
@@ -2327,6 +2601,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) {