@xema/omni-protocol 0.1.23 → 0.1.25

package/dist/index.d.ts

@@ -326,6 +326,12 @@ export interface ConnectContext {
     log?: (entry: unknown) => void;
 }
 export type ConnectionStatus = "connecting" | "active" | "error";
+/**
+ * What revives a connection that reported `error`: `reconnect` -- the login is good, dispose this
+ * connection and call `connect()` again -- or `reauthenticate` -- run the authentication flow
+ * first. The adapter knows which; the host acts on its word.
+ */
+export type ConnectionRecovery = "reconnect" | "reauthenticate";
 /** Every field is optional: a provider sends what it knows and omits what it does not. */
 export interface Contact {
     name?: string;
@@ -590,10 +596,12 @@ export type Task<C extends Channel = Channel> = {
     consultation?: TaskConsultation;
     lead?: TaskLead;
     assisting?: TaskAssisting;
+    media?: TaskMediaState;
 } : {
     consultation?: never;
     lead?: never;
     assisting?: never;
+    media?: never;
 });
 /** What the provider wants of Omni's acceptance policy for one offer. */
 export type AcceptanceMode = "no-preference" | "require-agent-acceptance" | "require-automatic-acceptance";
@@ -924,6 +932,12 @@ export type TeamCommandResult = {
 export interface TeamBreakCommandRequest {
     command: TeamBreakCommand;
 }
+/**
+ * The task's real-time audio as the provider holds it: `ready` while audio should be attached,
+ * `ended` once primary handling's audio ended, and the field omitted while none should be. The
+ * provider's word -- a desk attaches and renders audio from it, never from its own senses.
+ */
+export type TaskMediaState = "ready" | "ended";
 export interface VoiceMediaSession {
     remoteAudio: MediaStream;
     setMuted(muted: boolean): void;
@@ -992,6 +1006,8 @@ export interface Snapshot<C extends Channel = Channel> {
     break: BreakState;
     /** Every task currently owned by this agent for this provider. */
     tasks: Task<C>[];
+    /** The provider's own count of those tasks, stated rather than inferred: it must equal `tasks.length`, so a blank or unanswered state can never pass as a confirmed empty. */
+    taskCount: number;
     contacts?: Contact[];
     scheduledActivities?: ScheduledActivity[];
     team?: TeamRoster;
@@ -1024,7 +1040,12 @@ export type ProviderEvent<C extends Channel = Channel> = {
     snapshot: Snapshot<C>;
 } | {
     type: "provider-status";
-    status: ConnectionStatus;
+    status: "connecting" | "active";
+    message?: string;
+} | {
+    type: "provider-status";
+    status: "error";
+    recovery: ConnectionRecovery;
     message?: string;
 } | {
     type: "break-state";
@@ -1038,6 +1059,9 @@ export type ProviderEvent<C extends Channel = Channel> = {
 } | {
     type: "task-updated";
     task: Task<C>;
+} | {
+    type: "task-media-ready";
+    taskId: TaskId;
 } | {
     type: "task-media-ended";
     taskId: TaskId;

package/dist/testing.d.ts

@@ -7,7 +7,7 @@ export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation }
  * rules -- each optional part of a task, each optional part of the break state and roster, each
  * declared contribution, and each event type.
  */
-declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.media", "task.dispositions", "task.destinations", "task.custom", "task.locked", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities", "team.policies"];
 export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
@@ -98,6 +98,7 @@ export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApp
 /** What a stream has said about the tasks it carries, and the rules across events. */
 export declare class TaskStream {
     private readonly tasks;
+    private static stated;
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot: unknown): void;
     /** Applies one envelope and returns what it may not say given what came before. */
@@ -119,8 +120,9 @@ export declare class BreakStream {
 export declare function assertBreakFollowsItsRequests(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /**
  * The media follows the task and never decides it. Given a provider's stream -- optionally seeded
- * with the snapshot it began from -- every task is introduced once, `task-media-ended` names a
- * task whose work has begun, and what follows it is `completing` or `task-ended`.
+ * with the snapshot it began from -- every task is introduced once, `task-media-ready` and
+ * `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what
+ * follows the media ending is `completing` or `task-ended`.
  */
 export declare function assertMediaFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
 /** A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`. */

package/dist/testing.js

@@ -15,6 +15,7 @@ const STATE_SUBJECTS = [
     "task.consultation",
     "task.lead",
     "task.assisting",
+    "task.media",
     "task.dispositions",
     "task.destinations",
     "task.custom",
@@ -31,7 +32,7 @@ const STATE_SUBJECTS = [
 // `ProviderEvent` without a row here, or a row it lacks, is a compile error.
 const EVENT_TYPES = {
     snapshot: true, "provider-status": true, "break-state": true, "task-offered": true, "task-updated": true,
-    "task-media-ended": true, "task-ended": true, announcement: true, "provider-summary": true,
+    "task-media-ready": true, "task-media-ended": true, "task-ended": true, announcement: true, "provider-summary": true,
     "team-updated": true, "contacts-updated": true, "calendar-updated": true,
 };
 const CONTRACT_SUBJECTS = [
@@ -58,6 +59,8 @@ function observeTask(value, seen) {
         seen.add("task.lead");
     if (value.assisting !== undefined)
         seen.add("task.assisting");
+    if (value.media !== undefined)
+        seen.add("task.media");
     const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
     if (isRecord(capabilities.dispositions))
         seen.add("task.dispositions");
@@ -578,13 +581,18 @@ export function assertDeniedAndRetriedBreak(approvals) {
 // ---------------------------------------------------------------------------
 // The task stream. Each event is validated on its own; what one event may say about a task
 // depends on what was said before, and only something that watched the whole stream can hold a
-// provider to it. A task is never its audio: media ends only on work that has begun, and what
-// follows the media ending is the work completing or ending, never a phase the audio decided.
+// provider to it. A task is never its audio: media arrives on the provider's word, ends only
+// where it arrived and on work that has begun, and what follows the media ending is the work
+// completing or ending, never a phase the audio decided.
 // ---------------------------------------------------------------------------
 const WORK_BEGUN = new Set(["in-progress", "paused", "completing"]);
 /** What a stream has said about the tasks it carries, and the rules across events. */
 export class TaskStream {
     tasks = new Map();
+    static stated(task) {
+        const media = isRecord(task) && (task.media === "ready" || task.media === "ended") ? task.media : "none";
+        return { phase: String(isRecord(task) ? task.phase : undefined), media };
+    }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
         this.tasks.clear();
@@ -592,7 +600,7 @@ export class TaskStream {
             return;
         for (const task of snapshot.tasks) {
             if (isRecord(task) && typeof task.id === "string")
-                this.tasks.set(task.id, { phase: String(task.phase), mediaEnded: false });
+                this.tasks.set(task.id, TaskStream.stated(task));
         }
     }
     /** Applies one envelope and returns what it may not say given what came before. */
@@ -614,7 +622,7 @@ export class TaskStream {
                     break;
                 if (known !== undefined)
                     refuse("stream.taskOffered.duplicate", `${at}.task.id`, `${id} is already on the stream; an offer introduces a task once`);
-                this.tasks.set(id, { phase: String(isRecord(event.task) ? event.task.phase : undefined), mediaEnded: false });
+                this.tasks.set(id, TaskStream.stated(event.task));
                 break;
             case "task-updated":
                 if (id === undefined)
@@ -623,14 +631,37 @@ export class TaskStream {
                     refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
                     break;
                 }
-                if (known.mediaEnded) {
+                if (known.media === "ended") {
                     const phase = isRecord(event.task) ? String(event.task.phase) : "";
                     if (phase !== "completing") {
                         refuse("stream.taskMediaEnded.follow", `${at}.task.phase`, `after its media ended, ${id} completes or ends; ${phase} is a phase the audio does not decide`);
                     }
-                    known.mediaEnded = phase === "completing" ? false : known.mediaEnded;
                 }
-                known.phase = isRecord(event.task) ? String(event.task.phase) : known.phase;
+                // A task replaces the task, and an update re-states media without moving it: the
+                // transitions belong to task-media-ready and task-media-ended. Releasing ended is the
+                // one move an update may make, since wrapped audio has nothing left to end.
+                {
+                    const next = TaskStream.stated(event.task);
+                    if (known.media !== next.media && !(known.media === "ended" && next.media === "none")) {
+                        refuse("stream.taskUpdated.media", `${at}.task.media`, `a task-updated re-states media, it does not move it: ${id} held ${known.media} and the update says ${next.media}; audio arrives on task-media-ready and ends on task-media-ended`);
+                    }
+                    this.tasks.set(id, next);
+                }
+                break;
+            case "task-media-ready":
+                if (id === undefined)
+                    break;
+                if (known === undefined) {
+                    refuse("stream.taskMediaReady.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
+                    break;
+                }
+                if (!WORK_BEGUN.has(known.phase)) {
+                    refuse("stream.taskMediaReady.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 === "ready") {
+                    refuse("stream.taskMediaReady.duplicate", `${at}.taskId`, `media is already ready on ${id}; ready and ended alternate`);
+                }
+                known.media = "ready";
                 break;
             case "task-media-ended":
                 if (id === undefined)
@@ -642,7 +673,10 @@ export class TaskStream {
                 if (!WORK_BEGUN.has(known.phase)) {
                     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`);
                 }
-                known.mediaEnded = true;
+                if (known.media !== "ready") {
+                    refuse("stream.taskMediaEnded.silent", `${at}.taskId`, `media cannot end on ${id} where none arrived: audio attaches on task-media-ready, or on a task carried with media ready`);
+                }
+                known.media = "ended";
                 break;
             case "task-ended":
                 if (id === undefined)
@@ -722,8 +756,9 @@ export function assertBreakFollowsItsRequests(envelopes, snapshot) {
 }
 /**
  * The media follows the task and never decides it. Given a provider's stream -- optionally seeded
- * with the snapshot it began from -- every task is introduced once, `task-media-ended` names a
- * task whose work has begun, and what follows it is `completing` or `task-ended`.
+ * with the snapshot it began from -- every task is introduced once, `task-media-ready` and
+ * `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what
+ * follows the media ending is `completing` or `task-ended`.
  */
 export function assertMediaFollowsTheTask(envelopes, snapshot) {
     const stream = new TaskStream();

package/dist/validation.js

@@ -36,6 +36,7 @@ export function assertNoViolations(violations, summary) {
  */
 const membersOf = (members) => Object.keys(members);
 const CHANNELS = membersOf({ voice: true, chat: true, email: true });
+const CONNECTION_RECOVERIES = membersOf({ reconnect: true, reauthenticate: true });
 const TASK_PHASES = membersOf({
     pending: true, confirmed: true, preparing: true, "in-progress": true, paused: true, completing: true,
 });
@@ -648,6 +649,15 @@ function validateHandlingHistory(value, path, into) {
     });
 }
 /** Present only while consulting, and only on voice: elsewhere there is nobody to consult. */
+const TASK_MEDIA_STATES = membersOf({ ready: true, ended: true });
+/** Real-time media is a voice affair, and its state is one of two words. */
+function validateTaskMedia(value, channel, path, into) {
+    if (value === undefined)
+        return;
+    if (!into.require(channel === "voice", "task.media.channel", path, `a ${channel} task carries no real-time media state`))
+        return;
+    into.oneOf(value, TASK_MEDIA_STATES, "task.media", path);
+}
 function validateConsultation(value, channel, path, into) {
     if (value === undefined)
         return;
@@ -738,6 +748,7 @@ function validateTaskInto(task, context, path, into) {
     validateTaskAttributes(task.attributes, `${path}.attributes`, into);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into);
     validateConsultation(task.consultation, context.channel, `${path}.consultation`, into);
+    validateTaskMedia(task.media, context.channel, `${path}.media`, into);
     validateLead(task.lead, context.channel, `${path}.lead`, into);
     validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);
     const capabilities = task.capabilities;
@@ -982,6 +993,12 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         into.require(snapshot.sessionId === context.sessionId, "snapshot.sessionId.mismatch", `${path}.sessionId`, `a snapshot for session ${String(snapshot.sessionId)} on a login whose session is ${context.sessionId}`);
     }
     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")
+        && Array.isArray(snapshot.tasks)) {
+        into.require(snapshot.taskCount === snapshot.tasks.length, "snapshot.taskCount.mismatch", `${path}.taskCount`, `taskCount says ${snapshot.taskCount} and tasks carries ${snapshot.tasks.length}: a count that does not reconcile is an answer nobody gave`);
+    }
     if (!Array.isArray(snapshot.tasks)) {
         into.add("snapshot.tasks.shape", `${path}.tasks`, "a snapshot must carry a tasks array");
     }
@@ -1159,6 +1176,15 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             break;
         case "provider-status":
             into.oneOf(event.status, CONNECTION_STATUSES, "event.providerStatus.status", `${at}.status`);
+            // An error says how to revive it; any other status has nothing to revive.
+            if (event.status === "error") {
+                if (into.require(event.recovery !== undefined, "event.providerStatus.recovery.required", `${at}.recovery`, "an error names its recovery: reconnect, or reauthenticate")) {
+                    into.oneOf(event.recovery, CONNECTION_RECOVERIES, "event.providerStatus.recovery", `${at}.recovery`);
+                }
+            }
+            else {
+                into.require(event.recovery === undefined, "event.providerStatus.recovery.unexpected", `${at}.recovery`, "recovery goes with an error; nothing needs reviving here");
+            }
             if (event.message !== undefined) {
                 into.filled(event.message, "event.providerStatus.message", `${at}.message`, "a message must not be empty when present");
             }
@@ -1190,6 +1216,9 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
         case "task-updated":
             validateTaskInto(event.task, { channel, tiers }, `${at}.task`, into);
             break;
+        case "task-media-ready":
+            into.require(isTaskId(event.taskId), "event.taskMediaReady.taskId", `${at}.taskId`, "a task id is required");
+            break;
         case "task-media-ended":
             into.require(isTaskId(event.taskId), "event.taskMediaEnded.taskId", `${at}.taskId`, "a task id is required");
             break;

package/guide.md

@@ -363,6 +363,7 @@ type Snapshot = {
   sessionId: string;
   break: BreakState;
   tasks: Task[];
+  taskCount: number;
   contacts?: Contact[];
   scheduledActivities?: ScheduledActivity[];
   team?: TeamRoster;
@@ -582,6 +583,8 @@ type Locked = {
 
 type Lockable<T> = T | Locked;
 
+type TaskMediaState = "ready" | "ended";
+
 type Task<C extends Channel = Channel> = {
   id: TaskId;
   title: string;
@@ -596,8 +599,8 @@ type Task<C extends Channel = Channel> = {
   handlingHistory?: TaskHandlingStep[];
 } & TaskCompletion & (
   C extends "voice"
-    ? { consultation?: TaskConsultation; lead?: TaskLead; assisting?: TaskAssisting }
-    : { consultation?: never; lead?: never; assisting?: never }
+    ? { consultation?: TaskConsultation; lead?: TaskLead; assisting?: TaskAssisting; media?: TaskMediaState }
+    : { consultation?: never; lead?: never; assisting?: never; media?: never }
 );
 
 type AcceptanceMode =
@@ -919,9 +922,12 @@ type ProviderSummary = {
   metrics?: SummaryMetric[];
 };
 
+type ConnectionRecovery = "reconnect" | "reauthenticate";
+
 type ProviderEvent =
   | { type: "snapshot"; reason: "reconnected" | "provider-requested"; snapshot: Snapshot }
-  | { type: "provider-status"; status: ConnectionStatus; message?: string }
+  | { type: "provider-status"; status: "connecting" | "active"; message?: string }
+  | { type: "provider-status"; status: "error"; recovery: ConnectionRecovery; message?: string }
   | { type: "break-state"; break: BreakState }
   | {
       type: "task-offered";
@@ -931,6 +937,7 @@ type ProviderEvent =
       preparationEndsAt?: IsoTimestamp;
     }
   | { type: "task-updated"; task: Task }
+  | { type: "task-media-ready"; taskId: TaskId }
   | { type: "task-media-ended"; taskId: TaskId }
   | { type: "task-ended"; taskId: TaskId; outcome: TaskOutcome }
   | { type: "announcement"; text: string; html?: string; announcedAt: IsoTimestamp; expiresAt?: IsoTimestamp }
@@ -1217,6 +1224,17 @@ which field says so varies. See **Which commands need a capability**.
 
 Snapshots establish and replace provider state when an agent signs in, reconnects, or resynchronises.
 
+**A snapshot is the provider's answer, and an adapter that got no answer publishes nothing.** A
+state read that answers unknown — a session not yet associated, a backend mid-failover — is not an
+empty state: the adapter keeps what it holds, stays `connecting`, and publishes a snapshot only
+once the provider has actually answered for this login, exactly as `connect()` may not resolve
+before it can provide a meaningful one. And emptiness is stated, never inferred: every snapshot
+carries `taskCount`, the provider's own count reconciled against `tasks.length`, so a snapshot
+with no work says `taskCount: 0` in so many words and a blank or half-built state — which lacks
+the count — can never pass as a confirmed empty. Absence of knowledge is never evidence of
+absence, and every place "empty" is allowed to carry both meanings will eventually clear
+somebody's live call.
+
 Events report completed transactions after that baseline. Nothing is missed while the connection
 holds; when it drops, the reconnect snapshot re-establishes the baseline before any further event
 is applied.
@@ -1793,6 +1811,9 @@ Creates one live provider connection for the signed-in agent.
 - May reject for authentication, configuration, or startup failure.
 - Must not create a second agent session merely because the underlying transport reconnects.
 - The returned connection owns reconnect until Omni calls `disconnect()` or aborts `context.signal`.
+- May be called again on the same login after that: once per `Connection`, not once per login.
+  Omni disposes a connection whose `error` named `recovery: "reconnect"` with `disconnect()` and
+  calls `connect()` afresh — see **`provider-status`**.
 
 ### `ConnectContext`
 
@@ -1828,6 +1849,7 @@ a capability it agrees with the login: a lead's snapshot carries `team`, nobody
 | `sessionId` | Identity of this login session. It must match the connection context. |
 | `break` | Complete break state, including approval, accepting state, reasons, retry details, and any imposed break. |
 | `tasks` | Complete set of tasks currently offered to or owned by this agent. |
+| `taskCount` | The provider's own count of those tasks, stated rather than inferred, and it must equal `tasks.length`. A snapshot with no work says `taskCount: 0` in so many words — a blank or unanswered state lacks the count and cannot pass as a confirmed empty. |
 | `contacts` | Required complete contact contribution when the manifest declares `contacts`; `[]` clears it. Omitted only when it does not. |
 | `scheduledActivities` | Required complete calendar contribution when the manifest declares `calendar`; `[]` clears it. Omitted only when it does not. |
 | `team` | Required `TeamRoster` when the login declares `capabilities.team`, `[]` when nobody is in it. Forbidden otherwise — the login is the permission. |
@@ -2048,6 +2070,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `browsers` | Named browser definitions for the task workspace: at least one when the task declares the `browsers` capability, empty when it does not. |
 | `contact` | Optional `Contact` for the person or entity on this task. Often a name and one address; a withheld caller ID may leave nothing to send at all. |
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preparing`, `in-progress`, `paused`, or `completing`. |
+| `media` | Voice only. The task's real-time audio as the provider holds it: `ready` while audio should be attached, `ended` once it ended, omitted while none should be. The provider's word — see **`task-media-ready`**. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
 | `completionMode` | `agent-command` waits for the channel's `complete` command; `provider-automatic` completes without one. |
 | `completionAllowance` | Fixed time allowed to complete the task after primary handling ends. For real-time media, it begins after `task-media-ended`. Required under `provider-automatic`, where the provider acts on it. Optional under `agent-command`: omitted says the provider imposes no deadline, and Omni counts nothing down. |
@@ -2107,7 +2130,8 @@ command.
 routed to the agent and accepted as `acceptanceMode` dictates, and its presence and phase follow
 the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
 consult, a conference leg joining or leaving, a transfer, a callback — the media follows
-separately, attaching through `openMedia` and ending with `task-media-ended`. Omni does not ring,
+separately, arriving on `task-media-ready`, attaching through `openMedia` and ending with
+`task-media-ended`. Omni does not ring,
 bridge, or hold a line. How the phone rings, whether it rings at all, and where legs join and leave
 are the adapter's and the platform's, transient, and decide neither when a task exists nor what
 phase it is in.
@@ -2118,9 +2142,10 @@ allowance starts on it and the callback control appears on it — and Omni follo
 follows any other. What Omni never does is derive a task's state from its own media session: a
 stream that drops, a track that ends, a transport that disconnects, a microphone that fails, an
 endpoint re-registering change nothing about the task until the provider says so. Structurally:
-`task-media-ended` names a task whose work has begun, what follows it is `completing` or
-`task-ended`, and every task is introduced once — `exerciseAdapter` holds the stream to that from
-the connect snapshot on, and `assertMediaFollowsTheTask` holds any sequence.
+`task-media-ready` and `task-media-ended` alternate on a task whose work has begun, media ends
+only where it arrived, what follows the media ending is `completing` or `task-ended`, and every
+task is introduced once — `exerciseAdapter` holds the stream to that from the connect snapshot on,
+and `assertMediaFollowsTheTask` holds any sequence.
 
 #### Completion timing
 
@@ -3233,6 +3258,11 @@ carries as `audio.input.localAudio`, and absent while that input is `unavailable
 bridges audio without a host-side input may ignore it; one that needs it and finds it absent
 answers `unavailable` with a failure Omni shows the agent.
 
+**When to ask is the provider's word, not Omni's guess.** Omni opens media on `task-media-ready`,
+and on a task arriving with `media: "ready"` on a snapshot; it closes on `task-media-ended` and
+when the task ends. Between those words, nothing Omni's own senses report — a stream that drops, a
+track that ends — moves the task or its audio.
+
 **A task-scoped session does not oblige one call per task.** A platform holding a nailed-up
 leg for a whole shift may return the same session for every task and release the underlying
 path only when the connection closes. A platform placing a call per contact returns a new one
@@ -3385,7 +3415,10 @@ silently lose a message, so while the connection is up Omni has seen everything
 Loss has exactly one shape: the connection went away. The adapter reports `connecting` or `error`,
 reconnects, and emits a `snapshot` event carrying complete state. That snapshot is the repair —
 whatever was missed while the connection was down is in it, and Omni replaces its provider view
-rather than reasoning about what it did not receive.
+rather than reasoning about what it did not receive. A repair is an answer like any other: a
+platform that has not yet answered for this login after a reconnect — a state read served empty by
+a backend that does not know the session yet — yields no snapshot, and the adapter stays
+`connecting` holding what it holds. See **Snapshots establish state; events report transactions**.
 
 A snapshot must account for **everything the adapter has emitted before it resolves**, not merely
 everything emitted when it was requested. Omni discards events buffered during the read on that
@@ -3424,7 +3457,24 @@ safe for the agent to see.
 | --- | --- |
 | `connecting` | No usable transport right now, and the adapter expects to recover on its own. Nobody needs to act. Startup and every reconnect pass through this value. |
 | `active` | The transport is up and the provider is serving this session. It is the only value under which work arrives. |
-| `error` | The adapter cannot serve the session and is not simply mid-reconnect. Say why in `message`. It is not terminal — an adapter that recovers reports `connecting` and then `active`. |
+| `error` | The adapter cannot serve the session and is not simply mid-reconnect. Say why in `message`, and say what revives it in `recovery` — required here, forbidden on any other status. It is not terminal: an adapter that recovers on its own still reports `connecting` and then `active`, and one that cannot is revived as `recovery` says. |
+
+**An error names its recovery, and the host acts on that word.** The adapter knows why its session
+died; the host knows how to run a login. `recovery` joins the two:
+
+- **`reconnect`** — the login is good and this connection is not: a backend restart, a session the
+  platform no longer recognises. Omni calls `disconnect()` on the dead connection and then
+  `connect()` again on the same login — same `sessionId` — and the fresh connect snapshot
+  re-establishes state exactly as a reconnect snapshot does. `connect()` is once per
+  `Connection`, not once per login.
+- **`reauthenticate`** — the session under the login died: a token rejected, a remote logout. Omni
+  runs the authentication flow first; the authentication session decides whether stored material
+  refreshes it silently or the agent must act, exactly as at sign-in.
+
+**Patience is the host's.** An adapter in `connecting` retries for as long as it takes and never
+has to decide when to stop. Omni owns giving up: after however long it chooses to wait, it may
+call `disconnect()` and either `connect()` afresh or surface the failure — so neither side waits
+for the other to blink.
 
 **Status is about the transport, nothing else.** It does not say whether the agent is available,
 whether they are on a break, or how much work they can take: capacity travels on `setCapacity`,
@@ -3474,10 +3524,27 @@ snapshots until it ends.
 Replaces the current representation of one provider-local task. It is a full task value, not a
 partial patch.
 
+### `task-media-ready`
+
+The provider's word that the task's audio should now attach. Omni calls `openMedia` on it — and on
+a task carried with `media: "ready"`, which is how a reconnect snapshot reattaches audio an
+earlier event brought — and renders the call as live from that word, never from its own senses. It
+names a task whose work has begun, and it alternates with `task-media-ended`: media that was never
+made ready cannot end, so a live call whose provider says nothing about its audio is a provider in
+breach, not a state a desk fills in from its own devices.
+
+The event is the transition and the task's `media` field is the state. A `task-updated` re-states
+the media its task already holds — republishing `ready` on a hold is a statement, not a second
+arrival — but it does not move it: an update that itself flips the field is refused
+(`stream.taskUpdated.media`), and the pairing at the moment audio arrives is the phase change
+without the field, then the event. Releasing `ended` is the one move an update may make, since
+wrapped audio has nothing left to end.
+
 ### `task-media-ended`
 
 Signals that a task's real-time media ended. For voice and similar channels, this starts the fixed
-completion timer. It does not remove the task.
+completion timer. It does not remove the task, and it ends only audio that `task-media-ready` — or
+a task carried with `media: "ready"` — attached.
 
 ### `task-ended`
 
@@ -3566,7 +3633,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | --- | --- |
 | `validateManifest(manifest)` | Identity, protocol-version interoperability, authentication methods, and idle-capability shapes. |
 | `validateTask(task, { channel })` | Identity, channel agreement, phase, completion allowance, capability shapes, custom controls, and browsers. |
-| `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, and every task, contact, and activity, including idle-capability gating both ways: a contribution the manifest never declared is refused, and one it declares is required, `[]` included. |
+| `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, the stated `taskCount` reconciled against the tasks carried, and every task, contact, and activity, including idle-capability gating both ways: a contribution the manifest never declared is refused, and one it declares is required, `[]` included. |
 | `validateEventEnvelope(envelope, manifest)` | Envelope identity, timestamp, and the payload for each event type. |
 | `validateContact(contact)` | Contact field shapes and attribute keys. Every field is optional, so this checks what is present rather than what is missing. |
 | `validateScheduledActivity(activity)` | Required activity fields and start/end ordering. |
@@ -3660,7 +3727,7 @@ cannot be established from TypeScript structure alone.
 | `stillHost(report?)` | A host that reports one thing and never changes, for a test context: `{ online: true }` by default, a report with audio for a voice adapter. |
 | `TaskStream`, `BreakStream` | The cross-event models the harness applies after the connect snapshot, exported for a host that wants the same rules at its boundary: `seed(snapshot)`, then `apply(envelope)` returns the violations. |
 | `assertBreakFollowsItsRequests(envelopes, snapshot?)` | A break follows its requests: a commit's states only after a grant, never backwards, and a placed break arriving in effect with `imposed`. The harness applies the same rules after the connect snapshot. |
-| `assertMediaFollowsTheTask(envelopes, snapshot?)` | The media follows the task and never decides it: every task is introduced once, `task-media-ended` names a task whose work has begun, and what follows it is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no media satisfies it by never testing it — pair it with the assertion that the media end is present. |
+| `assertMediaFollowsTheTask(envelopes, snapshot?)` | The media follows the task and never decides it: every task is introduced once, `task-media-ready` and `task-media-ended` alternate on work that has begun, media ends only where it arrived, and what follows the media ending is `completing` or `task-ended`. The harness applies the same rules to every event after the connect snapshot (`stream.*`). A sequence with no media satisfies it by never testing it — pair it with the assertion that the media end is present. |
 | `assertBreakParticipants(candidates, participants)` | A break attempt asks every usable provider holding capacity, `refreshing` included, and nothing of a provider whose login is `expired`. |
 | `assertBreakBeginsAfterTask(steps)` | A break asked for on a task is committed as `starting-after-task` while work remains and reaches `in-effect` only once nothing is outstanding — never beside a task, never later than the step that has none. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |

package/package.json

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