@xema/omni-protocol 0.1.81 → 0.1.83

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** The protocol version implemented by this package. */
-export declare const OMNI_PROTOCOL_VERSION: 2;
+export declare const OMNI_PROTOCOL_VERSION: 1;
 /** Every version this package can interoperate with. */
 export declare const OMNI_SUPPORTED_PROTOCOL_VERSIONS: readonly number[];
 /**
@@ -153,6 +153,10 @@ export interface Manifest<C extends Channel = Channel> {
     supportedProtocolVersions: number[];
     authenticationMethods: AuthenticationMethod[];
     idleCapabilities?: IdleCapabilities<C>;
+    /** Optional provider-clock sampling through Connection.checkTime; absent means unsupported. */
+    timeCheck?: true;
+    /** Provider uses its own timestamps for final records; host timestamps are advisory. Omission makes no trust promise. */
+    timestampAuthority?: "provider";
     phaseLabels?: TaskPhaseLabels;
     /** Keyed by `taskType`. An entry replaces the channel default outright rather than merging. */
     taskTypePresentation?: Record<string, TaskTypePresentation>;
@@ -431,16 +435,13 @@ export type UrlVisibility = "full" | "domain" | "hidden";
 export type RecordingSource = "provider" | "host";
 export type RecordingAction = "start" | "pause" | "resume" | "stop" | "cancel";
 export declare const RECORDING_ACTIONS: readonly ["start", "pause", "resume", "stop", "cancel"];
-/** Cancel's captured-audio disposition is explicit; stop always retains captured audio. */
-export type RecordingCancelEffect = "retain" | "discard";
 export interface RecordingActions {
     start?: true;
     pause?: true;
     resume?: true;
     stop?: true;
-    cancel?: {
-        effect: RecordingCancelEffect;
-    };
+    /** Abandon this recording and discard its captured audio. */
+    cancel?: true;
 }
 /** Per-task permission, not a provider-wide recording switch. Absence grants nothing. */
 export interface TaskRecordingPolicy {
@@ -477,15 +478,9 @@ export type RecordingCommand = {
 } & ({
     action: "start";
     recordingId?: never;
-    cancelEffect?: never;
-} | {
-    action: "pause" | "resume" | "stop";
-    recordingId: string;
-    cancelEffect?: never;
 } | {
-    action: "cancel";
+    action: "pause" | "resume" | "stop" | "cancel";
     recordingId: string;
-    cancelEffect: RecordingCancelEffect;
 });
 export interface HostRecordingReport {
     taskId: TaskId;
@@ -494,8 +489,9 @@ export interface HostRecordingReport {
 }
 /** Host declaration in ConnectContext, not the provider-owned Manifest. */
 export interface HostRecording {
+    /** Audible recording status announcements to the remote party, for host-owned capture only. */
+    announcesToCaller?: true;
     actions: RecordingAction[];
-    cancelEffects: RecordingCancelEffect[];
     /** Explicitly provisioned destinations. A task chooses one; no upload/storage fallback. */
     destinationIds: string[];
     execute(request: HostRecordingRequest): Promise<RecordingCommandResult>;
@@ -534,7 +530,20 @@ export interface HostGuarantees {
     /** A `consent` offer is accepted only by the person's own explicit act, never on their behalf. */
     personConsent?: true;
 }
+export interface ProviderTimeScope {
+    providerId: string;
+    loginId: string;
+}
+/** Best-effort host estimate, never a provider observation or accuracy guarantee. The provider may ignore it and timestamp receipt itself. */
+export interface ProviderTimeEstimate extends ProviderTimeScope {
+    at: IsoTimestamp;
+    clockId: string;
+    /** Estimated uncertainty only; not a guaranteed error bound. */
+    uncertaintyMs?: number;
+}
 export interface Host {
+    /** Optional current provider-clock estimate; undefined when no usable estimate exists. */
+    estimateProviderTime?(scope: ProviderTimeScope): ProviderTimeEstimate | undefined;
     /** Voice softphone recording support; policy and destination remain per task. */
     recording?: HostRecording;
     guarantees: HostGuarantees;
@@ -623,7 +632,7 @@ export interface DispositionRules {
 /**
  * One item the queue configured for the agent to send a contact to: a button or a menu item. The
  * protocol does not say what it does -- a queue, a menu, a line -- the provider executes it when a
- * command names its `id`. Never a named agent: who takes a contact next is the queue's decision.
+ * command names its `id`. The provider may publish a queue, IVR, named agent or other supported destination; the host does not invent one.
  */
 export interface Destination {
     id: string;
@@ -660,7 +669,7 @@ export interface SharedTaskCapabilities {
 export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ? SharedTaskCapabilities & {
     decline?: Lockable<true>;
     hold?: Lockable<true>;
-    /** The agent may end the whole call: everyone leaves and the media ends, the task stays for its wrap-up. */
+    /** The provider ends the caller connection and agent-added channels owned by this handling, including inherited channels after transfer/takeover. Handling disposal remains separate. */
     endCall?: Lockable<true>;
     /** Connect back to the party while `completing`, whoever placed the call; the task returns to `in-progress`. */
     connectBack?: Lockable<true>;
@@ -726,14 +735,20 @@ export type TaskPhase =
 /** Accepted, and not yet started. */
  | "confirmed"
 /**
- * Voice only: the customer's record is on the agent's screen and no call has gone out. The agent
+ * Voice only: the customer's record is available for preparation, then dialing before answer. The agent
  * presses Call, or `previewEndsAt` arrives and `atDeadline` says what the system does instead.
  */
  | "preview" | "in-progress" | "paused"
 /** The work is over and the agent is finishing up. */
  | "completing";
 /** What the system does when a preview's deadline passes with no Call pressed. */
-export type PreviewDeadline = "calls" | "expires";
+export type PreviewDeadline = 
+/** Provider initiates dialing when preparation ends; never a host timer command. */
+"calls"
+/** Host initiates the ordinary call command when preparation ends. */
+ | "host-calls"
+/** Preparation target has elapsed; remain in preview until the agent presses Call. */
+ | "waits";
 /** Who ends the task: the agent issuing `complete`, or the provider deciding it is over. */
 export type CompletionMode = "agent-command" | "provider-automatic";
 export interface TaskAttributeBase {
@@ -966,9 +981,10 @@ export type Task<C extends Channel = Channel> = {
      */
     acceptance?: AcceptanceMode;
     /**
-     * In `preview` only, and together: when the system stops waiting for the agent to press Call,
-     * and what it does then -- `calls` places the call itself, `expires` takes the record back and
-     * the task ends `expired`. Absent, the agent has as long as they need.
+     * In `preview` only, and together: the preparation target and behavior when it elapses,
+     * and who acts then -- `calls` makes the provider initiate dialing, `host-calls` makes the
+     * host issue Call, and `waits` keeps waiting for the agent without dialing or ending the task.
+     * Absent, the agent has as long as they need, without a preparation countdown.
      */
     previewEndsAt?: IsoTimestamp;
     atDeadline?: PreviewDeadline;
@@ -1056,7 +1072,7 @@ export type VoiceTaskCommand = {
 } | {
     type: "resume";
 }
-/** End the whole call: everyone leaves and the task's media ends; the task stays for its wrap-up. Gated by `endCall`. */
+/** End the caller connection and all agent-added channels owned or inherited by this handling. Wrap/disposal remain separate. Gated by `endCall`. */
  | {
     type: "end-call";
 }
@@ -1493,6 +1509,7 @@ export type HandlingReport = {
 });
 export type HandlingReportResult = {
     status: "recorded";
+    at: IsoTimestamp;
 } | {
     status: "failed";
     failure: ProtocolFailure;
@@ -1644,7 +1661,28 @@ export interface Refusal {
     envelopeId?: string;
     violations: ProtocolViolation[];
 }
+/** Host-local opt-in configuration; no implicit interval or timeout. */
+export interface ProviderTimeCheckPolicy {
+    intervalMs: number;
+    timeoutMs: number;
+    maxRoundTripMs: number;
+    maxSampleAgeMs: number;
+}
+export interface ProviderTimeCheckRequest {
+    /** Fresh opaque correlation ID for one outstanding check, never reused on retry. */
+    requestId: string;
+}
+export interface ProviderTimeCheckResult {
+    requestId: string;
+    loginId: string;
+    /** Provider clock domain/incarnation; changes on clock discontinuity or authority replacement. */
+    clockId: string;
+    /** Provider-domain ISO instant sampled after this request arrived, before its response leaves. */
+    providerTime: IsoTimestamp;
+}
 export interface Connection<C extends Channel = Channel> {
+    /** Required only when Manifest.timeCheck is true. A read-only clock sample, never cached/replayed. */
+    checkTime?(request: ProviderTimeCheckRequest): Promise<ProviderTimeCheckResult>;
     snapshot(): Snapshot<C> | Promise<Snapshot<C>>;
     /** Delivery order must match the order the provider observes changes. Never replay. */
     subscribe(listener: (envelope: ProviderEventEnvelope<C>) => void): Unsubscribe;

package/dist/index.js

@@ -2,7 +2,7 @@
 //
 // Where this file and guide.md disagree, the guide is right and this is a defect.
 /** The protocol version implemented by this package. */
-export const OMNI_PROTOCOL_VERSION = 2;
+export const OMNI_PROTOCOL_VERSION = 1;
 /** Every version this package can interoperate with. */
 export const OMNI_SUPPORTED_PROTOCOL_VERSIONS = [OMNI_PROTOCOL_VERSION];
 /**

package/dist/testing.d.ts

@@ -190,15 +190,18 @@ export declare class TaskStream {
 }
 /** What a stream has said about the agent's break, and the moves it may not make. */
 export declare class BreakStream {
-    private approval;
-    /** Takes the break state a snapshot carries as the point the stream continues from. */
-    seed(snapshot: unknown): void;
-    /** Applies one envelope and returns the moves it may not make given where the break stood. */
+    private state;
+    private recovery;
+    /** True until a validated authoritative snapshot establishes a usable baseline. */
+    get needsRecovery(): boolean;
+    /** Caller establishes snapshot freshness/login scope separately; malformed state never replaces the baseline. */
+    seed(snapshot: unknown): ProtocolViolation[];
+    /** Rejected transitions keep accepted state and require snapshot recovery before further deltas. */
     apply(envelope: unknown, path?: string): ProtocolViolation[];
 }
 /**
- * A break follows its requests. Given a provider's stream -- optionally seeded with the snapshot
- * it began from -- every `break-state` moves the way the guide describes: a commit's states only
+ * A break follows its requests. Given a provider's stream -- seeded with its initial snapshot,
+ * either supplied separately or carried by a snapshot event -- every `break-state` moves the way the guide describes: a commit's states only
  * after a grant, never backwards, and a break placed on the agent arriving in effect with `imposed`.
  */
 export declare function assertBreakFollowsItsRequests(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, validateHostRecording, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateBreakTransition, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, validateHostRecording, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 /**
  * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
@@ -305,6 +305,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // What every connection owes on connect, the first and a reloaded second alike.
         const connectObligations = (on) => {
             // A refusal is visible on both sides: what the host would not take, the adapter is told, with the rules.
+            if (adapter.manifest.timeCheck === true)
+                requireMethod(on, "checkTime", "the manifest declares timeCheck");
             requireMethod(on, "refused", "every connection is told what the host refused");
             // Dial is declared by presence: the capability object carries a destination policy rather
             // than an `enabled` flag, so its presence is the declaration.
@@ -479,7 +481,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         const snapshot = await connection.snapshot();
         await snapshotRead(live, snapshot, "snapshot");
         stream.seed(snapshot);
-        breaks.seed(snapshot);
+        violations.push(...breaks.seed(snapshot));
         seeded = true;
         // A snapshot supersedes what it restates and nothing else. Of the events held during the read,
         // a state-replacing kind is dropped, since the snapshot carries that state and must account for
@@ -872,11 +874,11 @@ export function assertTaskCapabilityWithdrawal(tasks, manifest, command) {
     if (withdrawn.length === 0) {
         throw new Error("Task capability withdrawal must end with at least one capability the offer declared withdrawn; a locked control is present without permission, not withdrawn");
     }
-    const before = validateTaskCommand(command, first, "command");
+    const before = validateTaskCommand(command, first, "command", context);
     if (before.length > 0) {
         throw new Error(`Task capability withdrawal: the command must be issuable against the task as offered, or its later refusal proves nothing (${before.map(v => v.rule).join(", ")})`);
     }
-    const after = validateTaskCommand(command, last, "command");
+    const after = validateTaskCommand(command, last, "command", context);
     const forWant = after.filter(v => withdrawn.some(name => v.rule === `command.capability.${name}`));
     if (forWant.length === 0) {
         throw new Error(`Task capability withdrawal: the command must be refused against the republished task for want of ${withdrawn.join(" or ")}; it was ${after.length === 0 ? "accepted" : `refused for ${after.map(v => v.rule).join(", ")}`}`);
@@ -1073,9 +1075,9 @@ export class TaskStream {
                     stages.set(entry.dialId, entry.stage);
             }
         }
-        const partyRingingByHost = isRecord(task) && Array.isArray(task.onCall)
-            && task.onCall.some(entry => isRecord(entry) && entry.role === "party" && entry.stage === "ringing" && typeof entry.dialId === "string");
-        return { partyRingingByHost, channel: String(isRecord(task) ? task.channel : undefined), completionMode: String(isRecord(task) ? task.completionMode : undefined),
+        const partyRingingBeforeWork = isRecord(task) && Array.isArray(task.onCall)
+            && task.onCall.some(entry => isRecord(entry) && entry.role === "party" && entry.stage === "ringing" && (typeof entry.dialId === "string" || (task.phase === "preview" && task.atDeadline === "calls" && entry.dialId === undefined)));
+        return { partyRingingBeforeWork, channel: String(isRecord(task) ? task.channel : undefined), completionMode: String(isRecord(task) ? task.completionMode : undefined),
             wrapAllowance: isRecord(task) && typeof task.wrapAllowance === "number" ? task.wrapAllowance : undefined,
             phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages, record: TaskStream.record(task), allocation: String(isRecord(task) ? task.allocationId : undefined) };
     }
@@ -1268,7 +1270,7 @@ export class TaskStream {
                     refuse("stream.taskMedia.channel", `${at}.type`, "only a voice task has media transitions");
                     break;
                 }
-                if (!AT_WORK.has(known.phase) && !known.partyRingingByHost) {
+                if (!AT_WORK.has(known.phase) && !known.partyRingingBeforeWork) {
                     refuse("stream.taskMediaStarted.beforeWork", `${at}.taskId`, `media cannot arrive on ${id} while it is ${known.phase}: a task is never its audio, and its work has not begun`);
                 }
                 if (known.media === "started") {
@@ -1290,7 +1292,7 @@ export class TaskStream {
                     refuse("stream.taskMedia.channel", `${at}.type`, "only a voice task has media transitions");
                     break;
                 }
-                if (!WORK_BEGUN.has(known.phase)) {
+                if (!WORK_BEGUN.has(known.phase) && !known.partyRingingBeforeWork) {
                     refuse("stream.taskMediaEnded.beforeWork", `${at}.taskId`, `media cannot end on ${id} while it is ${known.phase}: a task is never its audio, and its work has not begun`);
                 }
                 if (known.media !== "started") {
@@ -1441,7 +1443,7 @@ async function driveOneCall(drive) {
             // is a place the stream's rules keep working, not one where they all stop.
             await drive.snapshotRead(second, snapshot, "drive.reload.snapshot");
             found.push(...drive.streams.stream.resync(snapshot, "drive.reload.snapshot"));
-            drive.streams.breaks.seed(snapshot);
+            found.push(...drive.streams.breaks.seed(snapshot));
             const carried = isRecord(snapshot) && Array.isArray(snapshot.tasks)
                 ? snapshot.tasks.find(task => isRecord(task) && task.id === taskId) : undefined;
             ruleEvaluated("drive.reload.snapshot");
@@ -1560,7 +1562,11 @@ async function driveOneCall(drive) {
     // Every command the drive sends is validated against the task as published, and its answer for its method.
     ruleEvaluated("drive.timeout");
     const send = async (command, dialId) => {
-        const own = validateTaskCommand(command, latestTask(), `drive.command.${String(command.type)}`);
+        const own = validateTaskCommand(command, latestTask(), `drive.command.${String(command.type)}`, {
+            levels: effectiveLevels(drive.manifest.orgLevels).map(level => level.id),
+            dialOutcomesDeclared: drive.manifest.dialOutcomes !== undefined,
+            autoAcceptTasks: drive.context.autoAcceptTasks,
+        });
         found.push(...own);
         if (own.length > 0)
             return undefined;
@@ -1651,12 +1657,13 @@ async function driveOneCall(drive) {
     // 3b. The microphone is the host's. With the audio open, the drive mutes it for a moment and
     // reports the leg the provider's record would otherwise miss -- begun, then ended -- and
     // expects each report recorded. If the provider restates the task's record afterwards, the leg is in it.
+    const canonicalTimes = new Map();
     const reportedLegs = [];
     /** The duration the provider's record states for the leg at `at`, as the task stands now. */
     const closedAs = (at) => {
         const history = latestTask().handlingHistory;
         const leg = isRecord(history) && Array.isArray(history.steps)
-            ? history.steps.find(entry => isRecord(entry) && entry.step === "muted" && entry.at === at) : undefined;
+            ? history.steps.find(entry => isRecord(entry) && entry.step === "muted" && entry.at === canonicalTimes.get(at)) : undefined;
         return typeof leg?.seconds === "number" ? leg.seconds : undefined;
     };
     const canRecordMute = session !== undefined && typeof session.setMuted === "function" && typeof drive.connection.recordStep === "function";
@@ -1676,7 +1683,15 @@ async function driveOneCall(drive) {
             refuse("drive.recordStep.rejected", "drive.recordStep", `recordStep rejected rather than answered: ${String(error)}`);
             return;
         }
-        found.push(...validateResult(answer, "recordStep", "drive.recordStep.result"));
+        const resultErrors = validateResult(answer, "recordStep", "drive.recordStep.result");
+        found.push(...resultErrors);
+        if (!resultErrors.length && isRecord(answer) && answer.status === "recorded" && typeof answer.at === "string" && typeof body.at === "string") {
+            const prior = canonicalTimes.get(body.at);
+            if (prior !== undefined && prior !== answer.at)
+                refuse("drive.recordStep.identity", "drive.recordStep.result.at", "one reported leg must retain its provider-assigned history instant");
+            else
+                canonicalTimes.set(body.at, answer.at);
+        }
         if (isRecord(answer) && answer.status === "failed") {
             refuse("drive.recordStep.failed", "drive.recordStep", `the provider refused to record the host's muted leg: ${String(isRecord(answer.failure) ? answer.failure.code : answer.failure)}`);
         }
@@ -1701,12 +1716,12 @@ async function driveOneCall(drive) {
         await new Promise(resolve => setTimeout(resolve, 1000));
         setMuted(false);
         await report({ at, seconds: Math.round((Date.now() - began) / 1000), ended: true });
-        reportedLegs.push({ at, task: latestTask() });
+        reportedLegs.push({ at: canonicalTimes.get(at), task: latestTask() });
         // 3c. A host reload destroys the adapter object and keeps the login's store. Built again from
         // the same login, a second adapter carries the task and the leg -- from its platform, or from
         // the store -- or it composed the record in memory and the record died with it.
-        if (drive.rebuild !== undefined) {
-            await recordSurvivesReload(at);
+        if (drive.rebuild !== undefined && canonicalTimes.has(at)) {
+            await recordSurvivesReload(canonicalTimes.get(at));
             // A reload that stood no client ends the run: there is nothing left to drive.
             if (!drive.handOver.isLive())
                 return found;
@@ -1757,7 +1772,7 @@ async function driveOneCall(drive) {
                 // record as it stands now is what every later restatement is held to.
                 const before = closedAs(openLeg.at);
                 await report({ at: openLeg.at, seconds: Math.max(1, Math.round((Date.now() - openLeg.began) / 1000)), ended: true });
-                reportedLegs.push({ at: openLeg.at, task: openLeg.task, closedAs: before });
+                reportedLegs.push({ at: canonicalTimes.get(openLeg.at), task: openLeg.task, closedAs: before });
             }
             if (completing !== undefined && offers("hold")) {
                 await holdRefusedOutsideHandling();
@@ -1822,6 +1837,8 @@ async function driveOneCall(drive) {
         return latestTask();
     };
     for (const reported of reportedLegs) {
+        if (reported.at === undefined)
+            continue; // A refused/malformed report provides no accepted history identity.
         const published = lastPublished();
         if (published === reported.task)
             continue;
@@ -1852,62 +1869,56 @@ async function driveOneCall(drive) {
 // starting-after-task | in-effect; work ending goes starting-after-task -> in-effect; a denial,
 // a cancel, an end or a release goes back to not-requested; a placed break arrives in-effect
 // with `imposed`. Nothing else is a move the guide describes.
-const COMMITTED = new Set(["starting-after-task", "in-effect"]);
-const BACKWARDS = {
-    "in-effect": ["awaiting-decision", "granted", "starting-after-task"],
-    "starting-after-task": ["awaiting-decision", "granted"],
-    granted: ["awaiting-decision"],
-};
 /** What a stream has said about the agent's break, and the moves it may not make. */
 export class BreakStream {
-    approval;
-    /** Takes the break state a snapshot carries as the point the stream continues from. */
+    state;
+    recovery = true;
+    /** True until a validated authoritative snapshot establishes a usable baseline. */
+    get needsRecovery() { return this.recovery; }
+    /** Caller establishes snapshot freshness/login scope separately; malformed state never replaces the baseline. */
     seed(snapshot) {
         const state = isRecord(snapshot) ? snapshot.break : undefined;
-        this.approval = isRecord(state) && typeof state.approval === "string" ? state.approval : undefined;
+        const found = validateBreakTransition(state, state, "snapshot.break");
+        if (found.length) {
+            this.recovery = true;
+            return found;
+        }
+        this.state = state;
+        this.recovery = false;
+        return [];
     }
-    /** Applies one envelope and returns the moves it may not make given where the break stood. */
+    /** Rejected transitions keep accepted state and require snapshot recovery before further deltas. */
     apply(envelope, path = "event") {
-        const found = [];
         const event = isRecord(envelope) ? envelope.event : undefined;
         if (!isRecord(event))
-            return found;
-        if (event.type === "snapshot") {
-            this.seed(event.snapshot);
-            return found;
-        }
-        if (event.type !== "break-state" || !isRecord(event.break) || typeof event.break.approval !== "string")
-            return found;
-        const from = this.approval;
-        const to = event.break.approval;
-        const at = `${path}.event.break.approval`;
-        if (from !== undefined) {
-            // A commit's states need a grant behind them. A placed break is the one arrival in a
-            // committed state that nobody asked for -- in effect at once, or starting-after-task while
-            // the member finishes a call -- and it says so with `imposed`.
-            if (COMMITTED.has(to) && (from === "not-requested" || from === "awaiting-decision") && event.break.imposed === undefined) {
-                found.push({ rule: "stream.breakState.commitBeforeGrant", path: at,
-                    message: `${to} follows a commit, and a commit follows granted; the break stood at ${from}` });
-            }
-            if ((BACKWARDS[from] ?? []).includes(to)) {
-                found.push({ rule: "stream.breakState.backwards", path: at,
-                    message: `a break does not go from ${from} back to ${to}; a new request passes through not-requested` });
-            }
+            return [];
+        if (event.type === "transport-status" && event.status !== "active") {
+            this.recovery = true;
+            return [];
         }
-        this.approval = to;
+        if (event.type === "snapshot")
+            return this.seed(event.snapshot);
+        if (event.type !== "break-state")
+            return [];
+        if (this.recovery)
+            return [{ rule: "stream.breakState.baseline", path: `${path}.event.break`,
+                    message: "a validated authoritative snapshot is required before accepting break updates" }];
+        const found = validateBreakTransition(this.state, event.break, `${path}.event.break`);
+        if (found.length)
+            this.recovery = true;
+        else
+            this.state = event.break;
         return found;
     }
 }
 /**
- * A break follows its requests. Given a provider's stream -- optionally seeded with the snapshot
- * it began from -- every `break-state` moves the way the guide describes: a commit's states only
+ * A break follows its requests. Given a provider's stream -- seeded with its initial snapshot,
+ * either supplied separately or carried by a snapshot event -- every `break-state` moves the way the guide describes: a commit's states only
  * after a grant, never backwards, and a break placed on the agent arriving in effect with `imposed`.
  */
 export function assertBreakFollowsItsRequests(envelopes, snapshot) {
     const stream = new BreakStream();
-    if (snapshot !== undefined)
-        stream.seed(snapshot);
-    const found = [];
+    const found = snapshot === undefined ? [] : stream.seed(snapshot);
     envelopes.forEach((envelope, index) => found.push(...stream.apply(envelope, `envelopes[${index}]`)));
     assertNoViolations(found, "A break follows its requests");
 }

package/dist/validation.d.ts

@@ -22,6 +22,13 @@ export declare function validateScheduledActivity(activity: unknown, path?: stri
  * on voice, absent elsewhere.
  */
 export declare function validatePhone(value: unknown, manifest: unknown, path?: string): ProtocolViolation[];
+/** Undefined explicitly means unavailable; a returned estimate is not a clock guarantee. */
+export declare function validateProviderTimeEstimate(value: unknown, scope: unknown, path?: string): ProtocolViolation[];
+/** Validate host-local periodic clock-check configuration. Omission disables checking. */
+export declare function validateProviderTimeCheckPolicy(value: unknown, path?: string): ProtocolViolation[];
+export declare function validateProviderTimeCheckRequest(value: unknown, path?: string): ProtocolViolation[];
+/** Checks response shape/correlation, not source-clock accuracy, round-trip delay or freshness. */
+export declare function validateProviderTimeCheckResult(value: unknown, request: unknown, loginId: string, path?: string): ProtocolViolation[];
 export declare function validateManifest(manifest: unknown, path?: string): ProtocolViolation[];
 export interface TaskValidationContext {
     /** The provider's channel, from its manifest. A task must agree with it. */
@@ -40,6 +47,30 @@ export interface TaskValidationContext {
     locked?: readonly string[];
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
+/** Checks break status against the full currently retained task set, after a transaction. */
+export declare function validateBreakStatus(state: unknown, tasks: unknown, path?: string): ProtocolViolation[];
+/**
+ * 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 declare function validateTeamBreakCommand(request: unknown, context: unknown, path?: string): ProtocolViolation[];
+/** The four agent break methods; this is a validation API, not a wire command. */
+export type BreakMethod = "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak";
+/**
+ * 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 declare function validateBreakCommand(method: BreakMethod, request: unknown, state: unknown, context: unknown, path?: string): ProtocolViolation[];
+/**
+ * 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 declare function validateBreakTransition(before: unknown, after: unknown, path?: string): ProtocolViolation[];
 /**
  * Who is reading what the adapter published, and what their login declares. The validators check
  * structure without it; given it, they also hold what the adapter publishes to the login.
@@ -93,6 +124,8 @@ export declare function validateHostGuarantees(guarantees: unknown, path?: strin
  */
 export declare function validateHandlingReport(report: unknown, path?: string, manifest?: unknown): ProtocolViolation[];
 export declare function validateHostReport(report: unknown, path?: string): ProtocolViolation[];
+/** Validate the exact handling/allocation target before provider command dispatch. */
+export declare function validateTaskCommandRequest(request: unknown, task: unknown, path?: string, taskContext?: Omit<TaskValidationContext, "channel">): ProtocolViolation[];
 /**
  * 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
@@ -100,7 +133,7 @@ export declare function validateHostReport(report: unknown, path?: string): Prot
  * 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 declare function validateTaskCommand(command: unknown, task?: unknown, path?: string): ProtocolViolation[];
+export declare function validateTaskCommand(command: unknown, task?: unknown, path?: string, taskContext?: Omit<TaskValidationContext, "channel">): ProtocolViolation[];
 /** The connection methods whose results `validateResult` knows. */
 export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamLeadAssist" | "executeTeamMonitor" | "openMedia" | "setPreference" | "recordStep" | "executeTeamPolicy";
 /**
@@ -151,6 +184,8 @@ export declare function validateRecordingRequest(request: unknown, task: unknown
     host?: unknown;
     hostReport?: unknown;
     softphone?: boolean;
+    /** The same provider/task context used to validate the published task. */
+    taskContext?: Omit<TaskValidationContext, "channel">;
 }, path?: string): ProtocolViolation[];
 /** Check recording-specific result semantics against the owner's confirming observations. */
 export declare function validateRecordingOutcome(command: unknown, before: unknown, after: unknown, result: unknown, path?: string): ProtocolViolation[];