@xema/omni-protocol 0.1.66 → 0.1.67

package/dist/index.d.ts

@@ -442,8 +442,8 @@ export type ConnectContext = {
     protocolVersion: number;
     /** The session that authenticated this connection. */
     loginId: string;
-    /** Omni-side policy: whether the agent's tasks are accepted without asking them. */
-    autoAcceptTasks?: boolean;
+    /** Omni-side policy: whether the agent's tasks are accepted without asking them. Stated, never assumed: a host says which. */
+    autoAcceptTasks: boolean;
     /**
      * The zone the agent's day is reckoned in, the same value passed as
      * `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the
@@ -713,13 +713,24 @@ export declare const ON_CALL_ROLES: readonly ["party", "agent", "consulted", "co
  * either way, and the `stage` it has reached: `ringing` until the dial is answered, `joined` after,
  * stated so a snapshot says who is present without anyone having seen the outcome. Nobody ringing is
  * held. `label` names a destination -- a person, a queue -- not a phrase. At most one `party` and
- * one `consulted`: the consult commands name neither because there is exactly one.
+ * one `consulted`: the consult commands name neither because there is exactly one. The `party`
+ * carries a `stage` only while being dialled again on the same task -- a connect-back the host
+ * placed, carrying its `dialId`, or a callback the platform places itself, carrying none --
+ * `ringing` from the moment the dial is placed and `joined` on its answered outcome, so a host can
+ * show a call being placed rather than assert one that is still ringing. A party with no stage is
+ * on the call.
  */
 export type OnCall = {
     since: IsoTimestamp;
     held?: true;
 } & ({
     role: "party";
+    dialId?: never;
+    stage?: never;
+} | {
+    role: "party";
+    stage: OnCallStage;
+    dialId?: DialId;
 } | {
     role: "agent";
     userId: UserId;

package/dist/testing.d.ts

@@ -29,6 +29,12 @@ export interface AdapterContractResult {
     notExercised: readonly ContractSubject[];
     /** Every violation observed. Non-empty only when `collectOnly` suppressed the throw. */
     violations: readonly ProtocolViolation[];
+    /**
+     * Every rule the run evaluated, pass or fail: the validators' as each was applied, the stream's
+     * and the drive's as each case was considered. A rule absent here was never looked at, which a
+     * clean `violations` says nothing about; a test that needs a rule to have run asserts it here.
+     */
+    rulesEvaluated: ReadonlySet<string>;
 }
 export interface ExerciseAdapterOptions {
     /** Return violations in the result instead of throwing. Defaults to `false`. */
@@ -127,13 +133,18 @@ export declare function assertReconnectWithMissedAssignments<C extends Channel>(
  * both.
  */
 export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
-/** What a stream has said about the tasks it carries, and the rules across events. */
 export declare class TaskStream {
     private readonly tasks;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
     private noteDials;
+    /** How many tasks the stream currently holds open. */
+    openCount(): number;
+    /** Whether an offered task is a dial arriving -- the host's own call, a connect-back -- which counts against no capacity: an entry on its call carrying a dial. */
+    static carriesDial(task: unknown): boolean;
+    /** Whether the update shows the party being dialled again -- a connect-back, a platform's callback -- the one thing that brings a completing task back. */
+    private static partyDialled;
     /** The entries of a task's record, each by step and instant, or undefined where the task carries no record. */
     private static record;
     /** What a restated record lost of the one read before it: nothing, or the entries by step and instant. */

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateHostMute, validateLoginStore, validateHandlingReport, validateManifest, validateResult, validateSnapshot, validateTask, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateDescribedUsers, observeRules, ruleEvaluated, validateHostMute, 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
@@ -154,6 +154,8 @@ function observeEvent(envelope, seen) {
  * asynchronous one — which would let a non-conforming async adapter pass.
  */
 export async function exerciseAdapter(adapter, context, options = {}) {
+    const rulesEvaluated = new Set();
+    const stopObserving = observeRules(rule => { rulesEvaluated.add(rule); });
     const violations = [...validateManifest(adapter.manifest)];
     const events = [];
     const seen = new Set();
@@ -198,7 +200,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             self: current().identity.id,
             capabilities: current().capabilities,
             loginId: context.loginId,
-            autoAcceptTasks: context.autoAcceptTasks ?? true,
+            autoAcceptTasks: context.autoAcceptTasks,
         });
         // The optional methods are optional only until something declares a need for them. Each
         // check pairs a method with the declaration that requires it, as the guide's Live-connection
@@ -301,7 +303,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // record of that leg is the provider's to take; on a desk phone the host holds no microphone.
         if (softphone)
             requireMethod(live, "recordStep", "the login is on a softphone, whose microphone the host mutes");
-        const eventIds = new Set();
+        const eventPayloads = new Map();
+        let capacityStated;
         // The drive waits on events: each waiter is offered every envelope as it lands.
         const waiters = new Set();
         unsubscribe = connection.subscribe(envelope => {
@@ -316,14 +319,36 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
-            // Cross-event rules apply once the stream has a beginning: the connect snapshot.
-            if (seeded)
-                violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
+            // Work is pulled, never pushed: an offer before the host stated capacity is an allocation
+            // against nothing, and an offer beyond the count is one too many -- unless the task is the
+            // host's own dial arriving, which counts against nothing.
+            if (isRecord(envelope?.event) && envelope.event.type === "task-offered") {
+                if (capacityStated === undefined) {
+                    violations.push({ rule: "stream.taskOffered.beforeCapacity", path: "event.task",
+                        message: "a task was offered before the host stated any capacity: work is pulled, and nothing is allocated against a capacity nobody stated" });
+                }
+                else if (seeded && stream.openCount() >= capacityStated && !TaskStream.carriesDial(envelope.event.task)) {
+                    violations.push({ rule: "stream.taskOffered.overCapacity", path: "event.task",
+                        message: `a task was offered with ${stream.openCount()} already open against a stated capacity of ${capacityStated}` });
+                }
+            }
+            // A re-delivered envelope is harmless and applied once; the same id carrying a different
+            // payload is a reused id, which no dedupe can make harmless, and is named.
             if (typeof envelope?.id === "string") {
-                if (eventIds.has(envelope.id))
+                const payload = JSON.stringify(envelope.event);
+                const earlier = eventPayloads.get(envelope.id);
+                if (earlier !== undefined) {
+                    if (earlier !== payload) {
+                        violations.push({ rule: "event.id.reused", path: "event.id",
+                            message: `envelope ${envelope.id} was delivered again with a different event: an id names one event for the life of the login` });
+                    }
                     return;
-                eventIds.add(envelope.id);
+                }
+                eventPayloads.set(envelope.id, payload);
             }
+            // Cross-event rules apply once the stream has a beginning: the connect snapshot.
+            if (seeded)
+                violations.push(...stream.apply(envelope), ...breaks.apply(envelope));
             events.push(envelope);
             for (const waiter of waiters)
                 waiter(envelope);
@@ -336,8 +361,26 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         breaks.seed(snapshot);
         seeded = true;
         requireCapabilityMethods(live, current().capabilities);
-        if (publishesUserIds(snapshot))
+        if (publishesUserIds(snapshot)) {
             requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
+            // Required by presence is not enough: the names the snapshot published are looked up, and what
+            // comes back is held to the shape -- an empty answer to a roster of colleagues is named.
+            const named = userIdsIn(snapshot);
+            if (typeof live.describeUsers === "function" && named.length > 0) {
+                let described;
+                try {
+                    described = await live.describeUsers(named);
+                    violations.push(...validateDescribedUsers(described, named, "connection.describeUsers"));
+                    if (Array.isArray(described) && described.length === 0) {
+                        violations.push({ rule: "connection.describeUsers.empty", path: "connection.describeUsers",
+                            message: `asked about ${named.join(", ")}, whom the snapshot itself named, the provider described nobody` });
+                    }
+                }
+                catch (error) {
+                    violations.push({ rule: "connection.describeUsers.rejected", path: "connection.describeUsers", message: `describeUsers rejected rather than answered: ${String(error)}` });
+                }
+            }
+        }
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection
         // that will not accept one is a connection nothing can be given to.
         // The guide's obligation on a voice adapter: consult the host before declaring the agent
@@ -349,7 +392,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 message: "a voice adapter consults the host's report before declaring the agent ready, and this one never asked",
             });
         }
-        const capacity = await connection.setCapacity({ count: 1 });
+        capacityStated = 1;
+        const capacity = await connection.setCapacity({ count: capacityStated });
         const malformed = validateResult(capacity, "setCapacity", "connection.setCapacity");
         violations.push(...malformed);
         // The provider republishes the agent's day: once connected, the identity carries the zone the
@@ -425,6 +469,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     }
     if (!options.collectOnly)
         assertNoViolations(violations);
+    stopObserving();
     return {
         events: events,
         authenticationState: authenticationState,
@@ -432,6 +477,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         notExercised: CONTRACT_SUBJECTS.filter(subject => !seen.has(subject)),
         disconnectWasClean,
         violations,
+        rulesEvaluated,
     };
 }
 /**
@@ -448,6 +494,42 @@ function publishesUserIds(snapshot) {
         return false;
     return snapshot.tasks.some(taskNamesUsers);
 }
+/** Every UserId a snapshot publishes: on the record, the room, a lead request, an imposed break, the roster. */
+function userIdsIn(snapshot) {
+    const ids = new Set();
+    const add = (value) => { if (typeof value === "string" && value.length > 0)
+        ids.add(value); };
+    add(snapshot?.break?.imposed?.by);
+    const team = snapshot?.team;
+    if (isRecord(team)) {
+        for (const member of Array.isArray(team.members) ? team.members : [])
+            if (isRecord(member))
+                add(member.id);
+        for (const request of Array.isArray(team.requests) ? team.requests : [])
+            if (isRecord(request))
+                add(request.memberId);
+    }
+    for (const task of Array.isArray(snapshot?.tasks) ? snapshot.tasks : []) {
+        const t = task;
+        if (isRecord(t.handlingHistory) && Array.isArray(t.handlingHistory.steps))
+            for (const step of t.handlingHistory.steps)
+                if (isRecord(step))
+                    add(step.by);
+        if (Array.isArray(t.onCall))
+            for (const entry of t.onCall)
+                if (isRecord(entry))
+                    add(entry.userId);
+        if (isRecord(t.leadAssist))
+            add(t.leadAssist.leadId);
+        if (isRecord(t.assisting))
+            add(t.assisting.memberId);
+        if (isRecord(t.monitoring)) {
+            add(t.monitoring.memberId);
+            add(t.monitoring.agentId);
+        }
+    }
+    return [...ids];
+}
 const teamNamesUsers = (team) => isRecord(team) && (some(team.members) || some(team.requests));
 const taskNamesUsers = (task) => isRecord(task) && ((isRecord(task.handlingHistory) && Array.isArray(task.handlingHistory.steps) && task.handlingHistory.steps.some(step => isRecord(step) && step.by !== undefined)) ||
     (isRecord(task.leadAssist) && task.leadAssist.leadId !== undefined) ||
@@ -720,7 +802,19 @@ export function assertDeniedAndRetriedBreak(approvals) {
 // completing or ending, never a phase the audio decided.
 // ---------------------------------------------------------------------------
 const WORK_BEGUN = new Set(["in-progress", "paused", "completing"]);
+/** Where audio can arrive: a task at work. A completing task's call is over; a connect-back returns it to in-progress before any media. */
+const AT_WORK = new Set(["in-progress", "paused"]);
 /** What a stream has said about the tasks it carries, and the rules across events. */
+const TASK_PHASES_ORDERED = ["pending", "confirmed", "preview", "in-progress", "paused", "completing"];
+/** Where a task may be next, by the guide's transition table, closed over the phases between two publications. */
+const REACHABLE_PHASES = {
+    pending: new Set(["pending", "confirmed", "preview", "in-progress", "paused", "completing"]),
+    confirmed: new Set(["confirmed", "preview", "in-progress", "paused", "completing"]),
+    preview: new Set(["preview", "in-progress", "paused", "completing"]),
+    "in-progress": new Set(["in-progress", "paused", "completing"]),
+    paused: new Set(["paused", "in-progress", "completing"]),
+    completing: new Set(["completing"]),
+};
 export class TaskStream {
     tasks = new Map();
     // Every dial the stream can place an outcome against: one the host said it placed, or one a
@@ -744,6 +838,19 @@ export class TaskStream {
                 this.dialled(entry.dialId);
         }
     }
+    /** How many tasks the stream currently holds open. */
+    openCount() { return this.tasks.size; }
+    /** Whether an offered task is a dial arriving -- the host's own call, a connect-back -- which counts against no capacity: an entry on its call carrying a dial. */
+    static carriesDial(task) {
+        if (!isRecord(task) || !Array.isArray(task.onCall))
+            return false;
+        return task.onCall.some(entry => isRecord(entry) && typeof entry.dialId === "string");
+    }
+    /** Whether the update shows the party being dialled again -- a connect-back, a platform's callback -- the one thing that brings a completing task back. */
+    static partyDialled(task) {
+        return isRecord(task) && Array.isArray(task.onCall)
+            && task.onCall.some(entry => isRecord(entry) && entry.role === "party" && typeof entry.stage === "string");
+    }
     /** The entries of a task's record, each by step and instant, or undefined where the task carries no record. */
     static record(task) {
         if (!isRecord(task) || !isRecord(task.handlingHistory) || !Array.isArray(task.handlingHistory.steps))
@@ -794,6 +901,7 @@ export class TaskStream {
         const known = id === undefined ? undefined : this.tasks.get(id);
         switch (event.type) {
             case "snapshot":
+                ruleEvaluated("stream.snapshot.capabilitySource", "stream.snapshot.handlingHistory");
                 // A snapshot replaces what is known, and still may not say a task lost terms it had read.
                 if (isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks)) {
                     event.snapshot.tasks.forEach((task, index) => {
@@ -813,6 +921,7 @@ export class TaskStream {
                 this.seed(event.snapshot);
                 break;
             case "task-offered":
+                ruleEvaluated("stream.taskOffered.duplicate");
                 if (id === undefined)
                     break;
                 if (known !== undefined)
@@ -823,6 +932,7 @@ export class TaskStream {
             case "task-updated":
                 if (id === undefined)
                     break;
+                ruleEvaluated("stream.taskUpdated.unknown", "stream.taskUpdated.capabilitySource", "stream.taskUpdated.phase", "stream.taskUpdated.handlingHistory", "stream.taskMediaEnded.follow", "stream.taskUpdated.media", "stream.taskUpdated.stage");
                 if (known === undefined) {
                     refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
                     break;
@@ -833,6 +943,22 @@ export class TaskStream {
                 if ((known.source === "queue" || known.source === "ungoverned") && isRecord(event.task) && event.task.capabilitySource === "undetermined") {
                     refuse("stream.taskUpdated.capabilitySource", `${at}.task.capabilitySource`, `${id} was published under ${known.source} terms and now says undetermined: terms once read stay read, and a re-read that fails is a diagnostic, not a republish`);
                 }
+                // A task does not go backwards. The stream sees publications, not transitions, and a task may
+                // pass through a phase between two, so what is refused is a phase unreachable from the last
+                // one read by the guide's table: back to pending, back to confirmed once work began, out of
+                // completing except through a connect-back -- which the update itself shows, the party
+                // carrying the host's dial.
+                {
+                    const from = known.phase;
+                    const to = isRecord(event.task) ? String(event.task.phase) : "";
+                    const reachable = REACHABLE_PHASES[from];
+                    if (reachable !== undefined && TASK_PHASES_ORDERED.includes(to) && !reachable.has(to)) {
+                        const connectingBack = from === "completing" && TaskStream.partyDialled(event.task) && (to === "in-progress" || to === "paused");
+                        if (!connectingBack) {
+                            refuse("stream.taskUpdated.phase", `${at}.task.phase`, `${id} was ${from} and the update says ${to}: a task does not go backwards, and ${from === "completing" ? "only the party being dialled again, a connect-back or a callback, with its stage on the call, brings a completing task back" : `${to} is not reachable from ${from}`}`);
+                        }
+                    }
+                }
                 // A record once read is not unread: an update restates it whole, or with more, never with less.
                 {
                     const lost = TaskStream.lost(known.record, TaskStream.record(event.task));
@@ -867,13 +993,14 @@ export class TaskStream {
                 this.noteDials(event.task);
                 break;
             case "task-media-started":
+                ruleEvaluated("stream.taskMediaStarted.unknown", "stream.taskMediaStarted.beforeWork", "stream.taskMediaStarted.duplicate");
                 if (id === undefined)
                     break;
                 if (known === undefined) {
                     refuse("stream.taskMediaStarted.unknown", `${at}.taskId`, `${id} was never offered or carried on a snapshot`);
                     break;
                 }
-                if (!WORK_BEGUN.has(known.phase)) {
+                if (!AT_WORK.has(known.phase)) {
                     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") {
@@ -882,6 +1009,7 @@ export class TaskStream {
                 known.media = "started";
                 break;
             case "task-media-ended":
+                ruleEvaluated("stream.taskMediaEnded.unknown", "stream.taskMediaEnded.beforeWork", "stream.taskMediaEnded.silent");
                 if (id === undefined)
                     break;
                 if (known === undefined) {
@@ -977,6 +1105,15 @@ async function driveOneCall(drive) {
                 return;
             }
             session = await again.createAuthenticationSession({ ...drive.context, secrets: drive.secrets });
+            // The reload is a restore before it is anything else: the second session stands authenticated
+            // as the same person, from the secrets alone, or nothing it reads afterwards is this login's.
+            const restored = await session.state();
+            found.push(...validateAuthenticationState(restored, "drive.reload.login"));
+            const same = isRecord(restored) && restored.status === "authenticated" && isRecord(restored.identity) && restored.identity.id === drive.reader().self;
+            if (!same) {
+                refuse("drive.reload.login", "drive.reload.login", `a second adapter built from the same login and secrets did not restore it: the session says ${String(isRecord(restored) ? restored.status : restored)}${isRecord(restored) && isRecord(restored.identity) ? ` as ${String(restored.identity.id)}` : ""}, and the login is ${String(drive.reader().self)}`);
+                return;
+            }
             second = await again.connect(drive.context);
             const snapshot = await second.snapshot();
             // The second adapter's snapshot is held to everything a first one is.

package/dist/validation.d.ts

@@ -6,6 +6,14 @@ export declare class ProtocolConformanceError extends Error {
 }
 /** Throws `ProtocolConformanceError` when any violation is present. */
 export declare function assertNoViolations(violations: readonly ProtocolViolation[], summary?: string): void;
+/**
+ * Hears every rule a validator evaluates, pass or fail, until the returned function is called. A
+ * green run can then say which rules it looked at rather than only which subjects it reached: a
+ * rule never evaluated is a visible gap, not a pass. The harness registers one for each exercise.
+ */
+export declare function observeRules(listener: (rule: string) => void): () => void;
+/** Says a rule was evaluated, for code that decides outside a collector: the stream, the drive. */
+export declare function ruleEvaluated(...rules: readonly string[]): void;
 /** Every field is optional, so this checks what is present rather than what is missing. */
 export declare function validateContact(contact: unknown, path?: string): ProtocolViolation[];
 export declare function validateScheduledActivity(activity: unknown, path?: string): ProtocolViolation[];
@@ -20,7 +28,7 @@ export interface TaskValidationContext {
     channel: string;
     /** The level ids in force, from the manifest. The defaults when absent. */
     levels?: readonly string[];
-    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
+    /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
     /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
     dialOutcomesDeclared?: boolean;
@@ -45,7 +53,7 @@ export interface ReaderContext {
     levels?: readonly string[];
     /** The login's `loginId`. A snapshot or event naming another belongs to a login that is gone. */
     loginId?: string;
-    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether a pending task states its `acceptance`. */
+    /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
 }
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
@@ -94,6 +102,12 @@ export declare function isTimeZone(value: unknown): value is string;
 export declare function sameTimeZone(a: unknown, b: unknown): boolean;
 /** The zone a host sends at connect: required, and an IANA name. */
 export declare function validateTimeZone(value: unknown, path?: string): ProtocolViolation[];
+/**
+ * What `describeUsers(ids)` answered: an array of users, each one asked for, each a valid identity.
+ * The provider may answer fewer than asked, which is what "unknown to it" looks like; it never
+ * answers somebody nobody asked about.
+ */
+export declare function validateDescribedUsers(users: unknown, asked: readonly string[], path?: string): ProtocolViolation[];
 /** What a login is validated against beyond its own shape. */
 export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */

package/dist/validation.js

@@ -131,14 +131,32 @@ const isDurationSeconds = (value) => typeof value === "number" && Number.isInteg
 /** Opaque, non-empty, provider-issued. Never parsed and never compared across providers. */
 const isUserId = isFilled;
 const isTaskId = isFilled;
+const ruleListeners = new Set();
+/**
+ * Hears every rule a validator evaluates, pass or fail, until the returned function is called. A
+ * green run can then say which rules it looked at rather than only which subjects it reached: a
+ * rule never evaluated is a visible gap, not a pass. The harness registers one for each exercise.
+ */
+export function observeRules(listener) {
+    ruleListeners.add(listener);
+    return () => { ruleListeners.delete(listener); };
+}
+/** Says a rule was evaluated, for code that decides outside a collector: the stream, the drive. */
+export function ruleEvaluated(...rules) {
+    for (const rule of rules)
+        for (const listener of ruleListeners)
+            listener(rule);
+}
 class Collector {
     violations = [];
     add(rule, path, message) {
+        ruleEvaluated(rule);
         this.violations.push({ rule, path, message });
     }
     require(condition, rule, path, message) {
+        ruleEvaluated(rule);
         if (!condition)
-            this.add(rule, path, message);
+            this.violations.push({ rule, path, message });
         return Boolean(condition);
     }
     filled(value, rule, path, message) {
@@ -198,7 +216,7 @@ export function validateScheduledActivity(activity, path = "scheduledActivity")
     validateScheduledActivityInto(activity, path, into);
     return into.violations;
 }
-function validateScheduledActivityInto(activity, path, into) {
+function validateScheduledActivityInto(activity, path, into, levels) {
     if (!isPlainObject(activity)) {
         into.add("activity.shape", path, "a scheduled activity must be an object");
         return;
@@ -213,7 +231,7 @@ function validateScheduledActivityInto(activity, path, into) {
         }
     }
     if (activity.party !== undefined)
-        validateContactInto(activity.party, `${path}.party`, into);
+        validateContactInto(activity.party, `${path}.party`, into, levels);
     validateAttributes(activity.attributes, `${path}.attributes`, into);
 }
 // ---------------------------------------------------------------------------
@@ -672,7 +690,7 @@ function validateBrowsers(value, path, into) {
         }
     });
 }
-function validateTaskAttributes(value, path, into) {
+function validateTaskAttributes(value, path, into, levels) {
     if (value === undefined)
         return;
     if (!Array.isArray(value)) {
@@ -699,7 +717,7 @@ function validateTaskAttributes(value, path, into) {
                 into.require(typeof attribute.value === "string", "task.attribute.text", `${at}.value`, "a text attribute needs a string value");
                 break;
             case "contact":
-                validateContactInto(attribute.contact, `${at}.contact`, into);
+                validateContactInto(attribute.party, `${at}.party`, into, levels);
                 break;
             case "timestamp":
                 into.timestamp(attribute.at, "task.attribute.timestamp", `${at}.at`);
@@ -791,13 +809,18 @@ 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. */
-function validateTaskMedia(value, channel, path, into) {
+function validateTaskMedia(value, channel, phase, 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);
+    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.
+        into.require(!WORK_NOT_BEGUN.includes(phase), "task.media.beforeWork", path, `a ${String(phase)} task has no media: audio arrives once its work has begun`);
+    }
 }
+const WORK_NOT_BEGUN = ["pending", "confirmed", "preview"];
 /**
  * Who is on the call, as the provider states it. Voice only. Each entry is a role with what that
  * role needs and nothing another role would: a party or an agent dialled nowhere, so neither
@@ -845,9 +868,23 @@ function validateOnCall(value, channel, path, into) {
             if (entry.label !== undefined)
                 into.filled(entry.label, "task.onCall.label", `${at}.label`, "a label must not be empty when present");
         }
+        else if (role === "party" && (entry.dialId !== undefined || entry.stage !== undefined)) {
+            // The party is dialled again on the same task -- a connect-back the host placed, a callback the
+            // platform placed -- and then carries the stage the dial has reached; a dial with no stage is
+            // half a claim, and the host's dialId is present where a host placed it, as on any dialled entry.
+            into.require(entry.stage !== undefined, "task.onCall.party.dial", at, "a party being dialled again carries the stage the dial has reached; the host's dialId beside it where a host placed the dial");
+            if (entry.dialId !== undefined)
+                into.filled(entry.dialId, "task.onCall.dialId", `${at}.dialId`, "dialId must not be empty when present");
+            if (entry.stage !== undefined && into.oneOf(entry.stage, ON_CALL_STAGES, "task.onCall.stage", `${at}.stage`)) {
+                into.require(!(entry.stage === "ringing" && entry.held === true), "task.onCall.held.ringing", `${at}.held`, "nobody ringing is held; held belongs to somebody who has joined");
+            }
+            for (const field of ["destinationId", "label"]) {
+                into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a party is not a directory item; ${field} belongs on consulted or conferenced`);
+            }
+        }
         else {
             for (const field of ["destinationId", "dialId", "label", "stage"]) {
-                into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, `a ${role} was dialled from nowhere; ${field} belongs on consulted or conferenced`);
+                into.require(entry[field] === undefined, `task.onCall.${field}.unexpected`, `${at}.${field}`, role === "party" ? `a party carries ${field} on a connect-back alone, with its dial and stage together` : `a ${role} was dialled from nowhere; ${field} belongs on consulted or conferenced`);
             }
         }
     });
@@ -975,7 +1012,7 @@ function validateTaskInto(task, context, path, into) {
     if (task.party !== undefined)
         validateContactInto(task.party, `${path}.party`, into, context.levels);
     validateBrowsers(task.browsers, `${path}.browsers`, into);
-    validateTaskAttributes(task.attributes, `${path}.attributes`, into);
+    validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
     validateOnCall(task.onCall, context.channel, `${path}.onCall`, into);
     // The room is who is on the call now, and a task outlives its call by the whole of wrap-up: a
@@ -984,7 +1021,7 @@ function validateTaskInto(task, context, path, into) {
     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`);
     }
-    validateTaskMedia(task.media, context.channel, `${path}.media`, into);
+    validateTaskMedia(task.media, context.channel, task.phase, `${path}.media`, into);
     validateLeadAssist(task.leadAssist, context.channel, `${path}.leadAssist`, into);
     validateAssisting(task.assisting, context.channel, `${path}.assisting`, into);
     validateMonitoring(task.monitoring, context.channel, `${path}.monitoring`, into);
@@ -1320,7 +1357,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     if (snapshot.contacts !== undefined) {
         into.require(idle.contacts === true, "snapshot.contacts.capability", `${path}.contacts`, "contacts require the contacts idle capability");
         if (Array.isArray(snapshot.contacts)) {
-            snapshot.contacts.forEach((contact, index) => validateContactInto(contact, `${path}.contacts[${index}]`, into));
+            snapshot.contacts.forEach((contact, index) => validateContactInto(contact, `${path}.contacts[${index}]`, into, levels));
         }
         else {
             into.add("snapshot.contacts.shape", `${path}.contacts`, "contacts must be an array when present");
@@ -1331,7 +1368,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         if (Array.isArray(snapshot.scheduledActivities)) {
             const seen = new Set();
             snapshot.scheduledActivities.forEach((activity, index) => {
-                validateScheduledActivityInto(activity, `${path}.scheduledActivities[${index}]`, into);
+                validateScheduledActivityInto(activity, `${path}.scheduledActivities[${index}]`, into, levels);
                 if (isPlainObject(activity) && isFilled(activity.id)) {
                     if (seen.has(activity.id)) {
                         into.add("activity.id.unique", `${path}.scheduledActivities[${index}].id`, `duplicate activity id: ${activity.id}`);
@@ -1535,7 +1572,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
             }
             else {
-                event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into));
+                event.contacts.forEach((contact, index) => validateContactInto(contact, `${at}.contacts[${index}]`, into, levels));
             }
             break;
         case "calendar-updated":
@@ -1546,7 +1583,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             else {
                 const ids = new Set();
                 event.scheduledActivities.forEach((activity, index) => {
-                    validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into);
+                    validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into, levels);
                     if (isPlainObject(activity) && isFilled(activity.id)) {
                         if (ids.has(activity.id))
                             into.add("activity.id.unique", `${at}.scheduledActivities[${index}].id`, `duplicate activity id: ${activity.id}`);
@@ -1826,6 +1863,22 @@ export function validateTaskCommand(command, task, path = "command") {
         : [...new Set([...TASK_COMMAND_NAMES.voice, ...TASK_COMMAND_NAMES.chat, ...TASK_COMMAND_NAMES.email])];
     if (type === "custom") {
         into.filled(command.name, "command.custom.name", `${path}.name`, "a custom command names the control it presses");
+        if (task === undefined)
+            return into.violations;
+        // Held to the task: the control it presses is one the task published, and what the control asked for travels with it.
+        const custom = isPlainObject(task) && isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
+        const control = Array.isArray(custom) ? custom.filter(isPlainObject).find(entry => entry.id === command.name) : undefined;
+        if (control === undefined) {
+            into.add("command.capability.custom", path, `custom ${String(command.name)} presses a control the task never published`);
+            return into.violations;
+        }
+        if (isPlainObject(control.prompt) && Array.isArray(control.prompt.fields)) {
+            for (const field of control.prompt.fields.filter(isPlainObject)) {
+                if (typeof field.name === "string") {
+                    into.require(typeof command[field.name] === "string" && command[field.name].length > 0, "command.custom.prompt", `${path}.${field.name}`, `the control asked for ${field.name} and the command does not carry it`);
+                }
+            }
+        }
         return into.violations;
     }
     if (!into.require(typeof type === "string" && names.includes(type), "command.type", `${path}.type`, channel === undefined ? `unsupported command: ${String(type)}` : `a ${channel} task has no ${String(type)} command`)) {
@@ -1911,12 +1964,17 @@ export function validateTaskCommand(command, task, path = "command") {
     // 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");
+    // A destination is one the directory offered: the id Omni sends is the id the provider published.
+    const listed = (name) => {
+        const declared = capabilities[name];
+        const directory = isPlainObject(declared) && Array.isArray(declared.destinations) ? declared.destinations.filter(isPlainObject) : [];
+        into.require(directory.some(item => item.id === command.destinationId), "command.destination.unknown", `${path}.destinationId`, `${String(command.destinationId)} is not a destination the task's ${name} directory offered`);
+    };
     const onCall = Array.isArray(task.onCall) ? task.onCall.filter(isPlainObject) : [];
     switch (type) {
         case "answer":
         case "accept":
         case "decline":
-        case "reject":
             inPhase("command.phase.pending", "pending");
             if (type === "decline")
                 offered("decline");
@@ -1944,10 +2002,14 @@ export function validateTaskCommand(command, task, path = "command") {
             break;
         case "transfer":
             handling();
-            if (command.action === "cold")
-                offered("coldTransfer");
-            else if (command.action === "warm")
-                offered("warmTransfer");
+            if (command.action === "cold") {
+                if (offered("coldTransfer"))
+                    listed("coldTransfer");
+            }
+            else if (command.action === "warm") {
+                if (offered("warmTransfer"))
+                    listed("warmTransfer");
+            }
             else if (command.action === "complete" || command.action === "cancel") {
                 into.require(onCall.some(entry => entry.role === "consulted"), "command.transfer.consulted", path, `${String(command.action)} needs a consulted entry on onCall: without one there is nothing to complete or cancel`);
             }
@@ -1964,9 +2026,12 @@ export function validateTaskCommand(command, task, path = "command") {
                 into.require(task.assisting !== undefined, "command.leadAssist.assisting", path, `${String(command.action)} is the lead's own act on a call they joined: the task carries assisting`);
             }
             break;
-        case "conference":
+        case "conference": {
             handling();
-            if (offered("conference") && command.action === "remove") {
+            const conferencing = offered("conference");
+            if (conferencing && command.action === "add")
+                listed("conference");
+            if (conferencing && command.action === "remove") {
                 const others = onCall.filter(entry => entry.role !== "agent");
                 if (command.party === true) {
                     into.require(others.some(entry => entry.role !== "party"), "command.conference.remove.alone", path, "removing the party would leave the agent alone: that is end-call");
@@ -1977,9 +2042,32 @@ export function validateTaskCommand(command, task, path = "command") {
                 }
             }
             break;
-        case "complete":
+        }
+        case "complete": {
             into.require(task.completionMode === "agent-command", "command.complete.mode", path, "complete belongs to agent-command; a provider-automatic task completes itself");
+            // What travels with complete is what the dispositions capability published: a code from its
+            // list where it has one, a code at all where it requires one, notes as it said, nothing where it published nothing.
+            const dispositions = capabilities.dispositions;
+            if (dispositions === undefined) {
+                into.require(command.disposition === undefined, "command.complete.disposition.unexpected", `${path}.disposition`, "the task declares no dispositions; complete travels with no code");
+                into.require(command.notes === undefined, "command.complete.notes.unexpected", `${path}.notes`, "the task declares no dispositions; complete travels with no notes");
+            }
+            else if (isPlainObject(dispositions)) {
+                if (Array.isArray(dispositions.codes) && command.disposition !== undefined) {
+                    into.require(dispositions.codes.some(code => isPlainObject(code) && code.id === command.disposition), "command.complete.disposition.unknown", `${path}.disposition`, `${String(command.disposition)} is not a code the task published`);
+                }
+                if (dispositions.required === true) {
+                    into.require(command.disposition !== undefined, "command.complete.disposition.required", `${path}.disposition`, "the task requires a disposition and complete carries none");
+                }
+                if (dispositions.notes === "none") {
+                    into.require(command.notes === undefined, "command.complete.notes.unexpected", `${path}.notes`, "the task takes no notes");
+                }
+                else if (dispositions.notes === "required") {
+                    into.require(typeof command.notes === "string" && command.notes.length > 0, "command.complete.notes.required", `${path}.notes`, "the task requires notes and complete carries none");
+                }
+            }
             break;
+        }
         default:
             break;
     }
@@ -2076,6 +2164,26 @@ export function validateTimeZone(value, path = "context.timeZone") {
     into.require(isTimeZone(value), "context.timeZone", path, "a host states the agent's time zone at connect as an IANA name, such as Asia/Kolkata; an offset cannot survive a daylight-saving boundary");
     return into.violations;
 }
+/**
+ * What `describeUsers(ids)` answered: an array of users, each one asked for, each a valid identity.
+ * The provider may answer fewer than asked, which is what "unknown to it" looks like; it never
+ * answers somebody nobody asked about.
+ */
+export function validateDescribedUsers(users, asked, path = "describeUsers") {
+    const into = new Collector();
+    if (!Array.isArray(users)) {
+        into.add("describeUsers.shape", path, "describeUsers answers an array of users, empty when it knows none of them");
+        return into.violations;
+    }
+    users.forEach((user, index) => {
+        const at = `${path}[${index}]`;
+        validateUser(user, "describeUsers.user", at, into);
+        if (isPlainObject(user) && typeof user.id === "string") {
+            into.require(asked.includes(user.id), "describeUsers.unasked", `${at}.id`, `${user.id} was not among the ids asked for`);
+        }
+    });
+    return into.violations;
+}
 function validateUser(value, rule, path, into) {
     if (!isPlainObject(value)) {
         into.add(rule, path, "an identity must be an object");

package/guide.md

@@ -314,7 +314,7 @@ type LoginStore = {
 type ConnectContext = {
   protocolVersion: number;
   loginId: string;
-  autoAcceptTasks?: boolean;
+  autoAcceptTasks: boolean;
   timeZone: TimeZone;
   store: LoginStore;
   phone?: Phone;
@@ -621,7 +621,8 @@ type OnCallRole = "party" | "agent" | "consulted" | "conferenced";
 type OnCallStage = "ringing" | "joined";
 
 type OnCall = { since: IsoTimestamp; held?: true } & (
-  | { role: "party" }
+  | { role: "party"; dialId?: never; stage?: never }
+  | { role: "party"; stage: OnCallStage; dialId?: DialId }
   | { role: "agent"; userId: UserId }
   | { role: "consulted" | "conferenced"; destinationId: string; stage: OnCallStage; dialId?: DialId; label?: string }
 );
@@ -1943,7 +1944,7 @@ Creates one live provider connection for the signed-in agent.
 | --- | --- |
 | `protocolVersion` | Version negotiated before authentication. Fixed for this login. |
 | `loginId` | Omni-generated identity for this login. It is the same value passed as `AuthenticationContext.loginId`, so an adapter can correlate this connection with the session that authenticated it. Stable across transport reconnects and changed only by a new login. |
-| `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login. Treated as `true` when omitted. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
+| `autoAcceptTasks` | Agent provisioning policy relayed to the provider at login, stated by the host on every connection and never assumed from its absence. When `true`, a pending task states its `acceptance`; when `false`, every task requires agent acceptance. Fixed for this connection, like everything else here: the provider states or omits `acceptance` by the value it was sent, and Omni validates by that same value, not by a policy that has since moved — a change reaches the provider through a fresh `connect()`. |
 | `timeZone` | The same value passed as `AuthenticationContext.timeZone`. The provider stores it on the agent and carries it on the identity. See **The agent's day**. |
 | `phone` | The same value passed as `AuthenticationContext.phone`: how this login hears its calls. The type ties `host.mute` to it: a `softphone` login's host states what its Mute does, and a desk-phone or conversation login's host cannot, so the omission is a compile error rather than a live seat's discovery. See **The station is the host's**. |
 | `store` | The login's operational store, kept by the host for the life of the login, across a reload of the host, and cleared at sign-out: where an adapter that composes a record keeps what its platform cannot hold for it, such as the handling legs a host reported. Three functions, by key. Never for anything sensitive, which is `AuthenticationContext.secrets`, a store a host may clear aggressively. **A task's keys carry the task id and go with the task**: a key written about a task names the task's id in the key, and is deleted before the task's end is published, because a platform retires a task id minutes after closing it and a requeue takes seconds, so a key that outlives its task is inherited by the next offer of the same id -- a record with legs the host never reported against it. A login-scoped key carries no task id and outlives any task. The harness requires the store of every connection (`store.shape`, `store.get`, `.set`, `.delete`), watches the one it hands over, and names a task's key still held after `task-ended` (`drive.store.retained`) or written about the task after its end -- a persist hung off a timer that saw the task as it was (`drive.store.late`). The ordinary late write is the host's, not the adapter's: a host reports a leg without waiting for the answer, so an unmute can follow `complete` by a tick, and the adapter answers a report about a task that has ended `failed` with `omni.task-not-found` and writes nothing -- the host ends its own open legs at the task's end, so such a report is the host's error to see, and a host reads every `recordStep` answer and awaits the one for the leg it closes at a task's end, the only moment a refusal is expected, since a report nobody waits for is an error nobody can see; an adapter that names no task in its keys gets no cleanup check, which is a gap rather than a pass, never an exemption: the obligation is that nothing of a closed task survives its ending, and an adapter that keeps every open task in one login-scoped value owes exactly that inside the value, where the harness cannot look. One key per task, named for it, is the shape the harness can hold, and the shape to reach for. The store lists nothing, so an adapter that needs to find its tasks keeps a login-scoped index of ids beside them; at the task's end it deletes the body first and reindexes after, since a crash between the two then leaves an index naming a task with no body, which a reader skips, where the other order leaves a body for a task that has ended, which is the hazard itself. A reader of the index tolerates an id with no body as an ending that was underway, not as corruption. |
@@ -2144,12 +2145,11 @@ provider's requirement, stated on a wire where Omni was willing to accept for th
 no-auto-accept policy puts no word on the wire at all — the field is absent, and the **Accept**
 press is Omni's doing, not the provider's.
 
-**An absent value means `true`**, as `readyOnLogin` does, because an agent who has signed in and
-gone ready is telling the deployment they are working. Requiring a press before every contact is
-the exception a provisioning file asks for, not the state it falls into when a flag is missing.
-
-Nothing is given away by that default. `acceptance` is the provider's own control and outranks
-it: `consent` puts the decision back in the agent's hands for any task where it
+**The value is stated, never assumed.** `autoAcceptTasks` is required of every connection: a
+host says which policy the deployment provisioned, and a validator that is not told checks
+neither rule rather than guess the permissive one (`task.acceptance.required` and
+`.unexpected` fire only against a stated value). `acceptance` is the provider's own control and
+outranks the policy: `consent` puts the decision back in the agent's hands for any task where it
 belongs, whatever the host was configured with.
 
 An automatically accepted task still arrives through `task-offered`.
@@ -2230,7 +2230,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. |
 | `party` | The person or entity on the other end of this task, as a `Contact`: often a name and one address; a withheld caller ID may leave nothing to send at all. Optional. The party is who the task is *with*; `contacts` is the directory. |
 | `phase` | Current canonical task phase: `pending`, `confirmed`, `preview`, `in-progress`, `paused`, or `completing`. `preview` is voice only. |
-| `media` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-media-started`**. |
+| `media` | Voice only. The task's real-time audio as the provider holds it: `started` while audio is attached, `ended` once it ended, omitted while none is. The provider's word — see **`task-media-started`**. Media names a task whose work has begun: on a `pending`, `confirmed` or `preview` task it is refused (`task.media.beforeWork`), on a snapshot as on the event, since a host opens the microphone on it. |
 | `acceptance` | How this offer is accepted — `no-preference`, `consent`, or `automatic` — stated on the pending task so a reconnect snapshot says it too. Required while `pending` when `autoAcceptTasks` was `true`, forbidden when it was `false`, and absent past `pending`. See **Acceptance modes**. |
 | `previewEndsAt` | Voice only, in `preview`: when the system stops waiting for the agent to press Call. Absent, the agent has as long as they need. Always with `atDeadline`. See **Preview: the agent presses Call**. |
 | `atDeadline` | Voice only, in `preview`, with `previewEndsAt`: what the system does at the deadline -- `calls` places the call itself, `expires` takes the record back and the task ends `expired`. |
@@ -2239,7 +2239,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `wrapAllowance` | 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. |
 | `attributes` | Optional ordered, typed `TaskAttribute` entries with keys unique within the task. Each contact or timestamp is a separate array item; new attribute shapes require new union members. |
 | `handlingHistory` | The call record: `steps` — the ordered handling history of this open task, one entry per occurrence, oldest first — and what they add up to before this agent, `handleSeconds`, `holdSeconds`, `queueSeconds`, `transfers`, each present when the provider knows it. Live task data restated with the task, not a permanent archive. See **How a task has been handled**. |
-| `onCall` | Voice only. Who is on the call, or being brought onto it, as the provider states it, replaced whole with the task: `party` is the customer, `agent` a person by user id, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destinationId` dialled, the `dialId` where a host placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
+| `onCall` | Voice only. Who is on the call, or being brought onto it, as the provider states it, replaced whole with the task: `party` is the customer -- carrying a `stage` while being dialled again on the same task, a connect-back with the host's `dialId` or a platform's callback without, ringing from the moment the dial is placed and joined on its answered outcome --, `agent` a person by user id, `consulted` and `conferenced` somebody a dial is bringing in, listed from the moment the dial is placed -- with the `destinationId` dialled, the `dialId` where a host placed it, the `stage` reached (`ringing` until answered, `joined` after), and `held: true` on anyone joined and parked. A `consulted` entry is what makes `transfer` `complete` and `cancel` issuable. `label` names a destination -- a person, a queue -- not a phrase; the host supplies the verb. Present when the provider knows the room, absent when it does not. See **Every dial has an outcome**. |
 | `leadAssist` | Voice only. Present from the agent's request for a lead until the lead leaves or the request ends: `requested` while nobody has joined, `joined` with the lead's `leadId` once somebody has. See **Lead assist**. |
 | `assisting` | Voice only, on the lead's own task for a call they joined: which member asked, with their note. Its presence is what makes `lead-assist` `take-over` and `leave` issuable. See **Lead assist**. |
 | `monitoring` | Voice only, on the lead's own task while they listen to a member's call: whose call, which call, and the `mode` they are heard in, restated on every change. Never on the member's task, and never together with `assisting`. See **Monitoring a call**. |
@@ -2422,6 +2422,16 @@ whose outcome says so and a call whose media ended: the task returns to `complet
 same event and the clock starts again from there. At no point is an agent dialling against a
 deadline.
 
+**The room shows the party being dialled again.** From the moment the connect-back is placed the
+`party` entry carries `stage: "ringing"` and the host's `dialId`, exactly as a consulted or
+conferenced entry does from its dial, and `joined` on the answered `dial-outcome` and never before
+it (`stream.taskUpdated.stage`); a host shows a call being placed, not a party it asserts is on a
+call that is still ringing. A callback the platform places itself on the same task -- the first
+call over, the platform dialling the party again without a command -- shows the same thing with no
+host `dialId`, as any platform-placed dial does. A party with no stage is on the call, and a dial
+with no stage is half a claim (`task.onCall.party.dial`). The stage is also what lets the stream
+tell a task coming back from one going backwards (`stream.taskUpdated.phase`).
+
 **The control exists only while there is a window to use it in.** Under `agent-command` the task
 stays `completing` until the agent completes it, so the window is open for as long as they need.
 Under `provider-automatic` the window is the allowance -- and with `wrapAllowance: 0` there
@@ -2500,7 +2510,10 @@ entries, one per join. Order is enforced: an entry earlier than the one before i
 total the provider adds: *time to offer*, from the call's arrival to the agent's screen lighting
 up, is the `offered` entry's `at` minus the last `queued` entry's, and the ring is outside it.
 `queueSeconds` keeps the industry's meaning -- the whole wait until somebody answered -- and is not
-that interval.
+that interval. **The second is the record's grain.** A duration is a positive whole number of
+seconds, and nought is refused because it claims no time; a leg that happened is stated at the
+grain: rounded to the nearest second, and a leg that rounds to nought is stated as `1`, the error
+being under the contract's resolution, where dropping the entry would say the leg never happened.
 
 **A record once read is not unread.** Every restatement of a task's record -- on `task-updated`,
 on a resync snapshot -- carries every entry the host has already read, by step and instant, and
@@ -2795,7 +2808,17 @@ Terms once read stay read: a re-read that fails mid-task is not a new fact about
 last statement stands and the failure is a `diagnostic`, and a task that was published under
 `queue` or `ungoverned` never returns to `undetermined`, on an update (`stream.taskUpdated.capabilitySource`)
 or on a resync snapshot (`stream.snapshot.capabilitySource`); a record once read never loses an
-entry the same two ways (`stream.taskUpdated.handlingHistory`, `stream.snapshot.handlingHistory`).
+entry the same two ways (`stream.taskUpdated.handlingHistory`, `stream.snapshot.handlingHistory`);
+and a task does not go backwards (`stream.taskUpdated.phase`): the stream sees publications, not
+transitions, and a task may pass through a phase between two, so `pending` to `in-progress` stands
+with `confirmed` between them, and what is refused is a phase unreachable from the last one read by
+the transition table -- back to `pending`, back to `confirmed` or `preview` once work began, out of
+`completing` except by the party being dialled again, a connect-back or a platform's callback,
+which the update itself shows: the party on the call carrying a `stage`. A completing task
+republished as `in-progress` from a stale copy carries no such stage, and that is the ending the
+agent never saw. Audio arrives only on a task at work: `task-media-started` on a `completing` task
+is refused as it is on a pending one (`stream.taskMediaStarted.beforeWork`), since a connect-back
+returns the task to `in-progress` before any media.
 
 What the agent is told differs by source, and only one source tells them anything. Under `queue`
 and `ungoverned` the agent sees controls and nothing about where they came from: both are facts,
@@ -2850,8 +2873,10 @@ See **Which commands need a capability**.
 
 ### Publishing codes and destinations
 
-Four capabilities accept an object instead of `true` when the provider wants Omni to render real
-choices. `true` remains valid and means "offer the control with nothing published".
+Four capabilities accept an object when the provider wants Omni to render real choices. For
+`dispositions` alone, `true` remains valid and means "offer the control with nothing published";
+the three directory controls -- `coldTransfer`, `warmTransfer`, `conference` -- carry their
+directory or are refused, since once nothing is typed the directory is the control.
 
 #### `dispositions`
 
@@ -3698,7 +3723,7 @@ choice that is no command at all:
 
 | The lead | The agent's task | The lead's task |
 | --- | --- | --- |
-| `{ type: "lead-assist", action: "take-over" }` | `task-ended` with `{ type: "transferred", destination: leadId }`, straight from `in-progress`: **no `completing` window**, the agent is idle at once | Continues alone, and ends as any call does |
+| `{ type: "lead-assist", action: "take-over" }` | `task-ended` with `{ type: "transferred", destinationId: leadId }`, straight from `in-progress`: **no `completing` window**, the agent is idle at once | Continues alone, and ends as any call does |
 | `{ type: "lead-assist", action: "leave" }` | Continues; `leadAssist` is cleared | `task-ended` with `{ type: "left" }` -- the call goes on without them |
 | Stays until the customer hangs up | `task-media-ended`, `completing`, its own disposition | The same, independently: **both have the disposal window** |
 
@@ -4134,12 +4159,14 @@ declared:
 | `conference` with `action: "remove"` | The `conference` capability, and somebody else on the call: a remove that would leave the agent alone is `end-call`, and a provider answers it `failed`. |
 | `decline` | The `decline` capability on any channel, **and** Omni provisioning permitting it. One word for refusing an offer, whatever the channel. |
 | `call` | The `preview` phase. A record put in front of an agent is there to be called, so the phase is the gate and there is no capability. It is a dial, with a `dialId` and a `dial-outcome`. |
-| `complete` | `completionMode: "agent-command"`. The `dispositions` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. |
+| `complete` | `completionMode: "agent-command"`. The `dispositions` capability decides whether a code travels with the command, never whether the command exists — a task Omni cannot complete never ends. What travels is what the capability published: a code from its list where it has one (`command.complete.disposition.unknown`), a code at all where it requires one (`.disposition.required`), notes as it said (`.notes.required`, `.notes.unexpected`), and neither where the task declares no dispositions (`.disposition.unexpected`). |
 | `connect-back` | The `connectBack` capability **and** the `completing` phase. It exists to reach the party again after the call, so it has no meaning while the call is up. |
 | `transfer` with `action: "warm"` | The `warmTransfer` capability. `action: "cold"` is gated by `coldTransfer`; the two are declared and offered separately. |
 | `transfer` with `action: "complete"` or `"cancel"` | A consultation in progress -- a `consulted` entry on `Task.onCall`. Without one there is nothing to complete or cancel, and a provider that receives either answers `failed`. |
 | `lead-assist` with `action: "request"` or `"cancel"` | The `leadAssist` capability. `cancel` needs a request standing -- `Task.leadAssist` with status `requested`. |
 | `lead-assist` with `action: "take-over"` or `"leave"` | The lead's own task, on a call they joined -- `Task.assisting` present. An agent's task never has it, and a provider that receives either without it answers `failed`. |
+| `transfer` with a destination, `conference` with `action: "add"` | Its capability, and a `destinationId` the directory offered: the id Omni sends is the id the provider published (`command.destination.unknown`). |
+| `custom` | A control the task published under `capabilities.custom`, by its `id` (`command.capability.custom`), carrying every field the control's `prompt` asked for (`command.custom.prompt`). |
 | Everything else | Its own named capability. |
 
 **A control on the contact belongs to the handling phases**, `in-progress` and `paused`:
@@ -4150,7 +4177,7 @@ call with nobody on it, a conversation closed -- and a wrap-up that still shows
 for nothing. The capability stays declared, because it is a property of the task and the task is
 still open; the phase says there is nothing to use it on. Omni shows none of these controls outside
 the two phases, and `validateTaskCommand` refuses each of them there (`command.phase.handling`).
-The commands with a phase of their own -- `answer`, `accept`, `decline` and `reject` in `pending`,
+The commands with a phase of their own -- `answer`, `accept` and `decline` in `pending`,
 `call` in `preview`, `connect-back` in `completing`, `complete` in any -- are not among them.
 
 `validateTaskCommand(command, task)` holds a command to this table at runtime, both ways: the
@@ -4594,7 +4621,18 @@ complete it with a disposition where the agent completes -- and holds every step
 host holds a provider to. Each command is validated against the task as published
 (`drive.command.*`), each answer for its method, a refusal of a control the task offered is a
 violation (`drive.command.failed`), and an event the provider owes and never sends is one too
-(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). With the audio open on a softphone,
+(`drive.timeout`, after `driveTimeoutMs`, 5000 by default). Around the drive the exercise holds
+the run to what a host holds a provider to between commands: an offer before the host stated
+capacity, or beyond the count with nothing dialled on it, is named
+(`stream.taskOffered.beforeCapacity`, `.overCapacity`); every user the snapshot names is looked up
+through `describeUsers` and the answer held to the shape, nobody unasked, nobody described as
+nothing (`describeUsers.user.*`, `describeUsers.unasked`, `connection.describeUsers.empty`); and
+the second adapter a `rebuild` gives comes up signed in as the same login from the secrets alone
+before it reads anything (`drive.reload.login`). The result also says which rules the
+run evaluated, pass or fail, in `rulesEvaluated`: the validators' as each was applied, the stream's
+as each case was considered, so a test that needs a rule to have run asserts it there rather than
+inferring it from an empty `violations`, and a rule absent from it was never looked at, which is a
+gap and not a pass. With the audio open on a softphone,
 the drive mutes it for one second and reports the leg through `recordStep`, begun and then ended,
 expecting each report `recorded` (`drive.recordStep.failed`, `.rejected`); and where the provider
 restates the task's record afterwards, the leg is in it or the hole is named

package/package.json

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