@xema/omni-protocol 0.1.14 → 0.1.16

package/README.md

@@ -30,7 +30,8 @@ An adapter is loaded from a separate package and may be compiled against a diffe
 version, so its output is untrusted input. Every validator takes `unknown` and returns every
 violation it found rather than throwing on the first, so a caller reports all of them at once.
 Validating a snapshot before it replaces provider state is what stops a malformed task reaching
-the agent's workspace.
+the agent's workspace; validating a result with `validateResult(result, method)` before acting on
+it is what stops a status the host does not know being shown as an outcome.
 
 ```ts
 const violations = validateSnapshot(snapshot, manifest);

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateSnapshot, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateResult, validateSnapshot, } 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
@@ -59,8 +59,11 @@ function observeTask(value, seen) {
     const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
     if (isRecord(capabilities.dispositions))
         seen.add("task.dispositions");
-    if (isRecord(capabilities.blindTransfer) && some(capabilities.blindTransfer.destinations))
-        seen.add("task.destinations");
+    for (const directory of ["blindTransfer", "consultTransfer", "conference"]) {
+        const declared = capabilities[directory];
+        if (isRecord(declared) && some(declared.destinations))
+            seen.add("task.destinations");
+    }
     if (some(capabilities.custom))
         seen.add("task.custom");
 }
@@ -173,7 +176,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 throw new Error("unreachable: the exercise has an authenticated login");
             return login;
         };
-        const reader = () => ({ self: current().identity.id, capabilities: current().capabilities });
+        const reader = () => ({
+            self: current().identity.id,
+            capabilities: current().capabilities,
+            sessionId: context.sessionId,
+            autoAcceptTasks: context.autoAcceptTasks ?? true,
+        });
         // 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
         // table does; a missing one is a control the agent would be shown and could never use.
@@ -229,6 +237,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         unsubscribe = connection.subscribe(envelope => {
             observeEvent(envelope, seen);
             violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
+            if (eventNamesUsers(envelope))
+                requireMethod(live, "describeUsers", "an event publishes a UserId");
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -245,7 +255,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // 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.
         const capacity = await connection.setCapacity({ count: 1 });
-        if (capacity.status === "failed") {
+        const malformed = validateResult(capacity, "setCapacity", "connection.setCapacity");
+        violations.push(...malformed);
+        // A refusal is read only from a result that has the shape of one.
+        if (malformed.length === 0 && capacity.status === "failed") {
             violations.push({
                 rule: "connection.setCapacity.failed",
                 path: "connection.setCapacity",
@@ -307,11 +320,29 @@ export async function exerciseAdapter(adapter, context, options = {}) {
 function publishesUserIds(snapshot) {
     if (snapshot?.break?.imposed?.by !== undefined)
         return true;
-    if (Array.isArray(snapshot?.team?.members) && snapshot.team.members.length > 0)
+    if (teamNamesUsers(snapshot?.team))
         return true;
     if (!Array.isArray(snapshot?.tasks))
         return false;
-    return snapshot.tasks.some(task => Array.isArray(task?.handlingHistory) && task.handlingHistory.some(step => step?.by !== undefined));
+    return snapshot.tasks.some(taskNamesUsers);
+}
+const teamNamesUsers = (team) => isRecord(team) && (some(team.members) || some(team.requests));
+const taskNamesUsers = (task) => isRecord(task) && ((Array.isArray(task.handlingHistory) && task.handlingHistory.some(step => isRecord(step) && step.by !== undefined)) ||
+    (isRecord(task.lead) && task.lead.leadId !== undefined) ||
+    isRecord(task.assisting));
+/** Whether an event publishes a `UserId`, on a roster, a task, or the snapshot a reconnect carries. */
+function eventNamesUsers(envelope) {
+    const event = isRecord(envelope) ? envelope.event : undefined;
+    if (!isRecord(event))
+        return false;
+    switch (event.type) {
+        case "snapshot": return publishesUserIds(event.snapshot);
+        case "break-state": return isRecord(event.break) && isRecord(event.break.imposed) && event.break.imposed.by !== undefined;
+        case "task-offered":
+        case "task-updated": return taskNamesUsers(event.task);
+        case "team-updated": return teamNamesUsers(event.team);
+        default: return false;
+    }
 }
 /**
  * `refreshing` carries the identity and capabilities of the login it refreshes. A change to

package/dist/validation.d.ts

@@ -30,8 +30,21 @@ export interface ReaderContext {
      * snapshot carries a roster, nobody else's does, and `requests` need `team.consultControl`.
      */
     capabilities?: SessionCapabilities;
+    /** The login's `sessionId`. A snapshot or event naming another belongs to a login that is gone. */
+    sessionId?: string;
+    /** `ConnectContext.autoAcceptTasks` as sent, absent meaning `true`: whether `task-offered` carries an `acceptanceMode`. */
+    autoAcceptTasks?: boolean;
 }
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateEventEnvelope(envelope: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
+/** The connection methods whose results `validateResult` knows. */
+export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia";
+/**
+ * Validates what a connection method answered. A result is untrusted for the same reason a
+ * snapshot is: it comes from an adapter that may be compiled against another version, and Omni
+ * shows the agent what it says. A status the method does not answer, a failure status without a
+ * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
+ */
+export declare function validateResult(result: unknown, method: ResultMethod, path?: string): ProtocolViolation[];
 export declare function validateAuthenticationState(state: unknown, path?: string): ProtocolViolation[];

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, } from "./index.js";
+import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -70,6 +70,12 @@ const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
 const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true });
+const MEMBER_BREAKS = membersOf({
+    "awaiting-decision": true, granted: true, "starting-after-task": true,
+});
+const OFFERABLE_PHASES = membersOf({
+    pending: true, confirmed: true, preparing: true,
+});
 const TEAM_CAPABILITIES = membersOf({ breakControl: true, consultControl: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const EXPIRABLE_PHASES = membersOf({
@@ -283,7 +289,9 @@ export function validateManifest(manifest, path = "manifest") {
     }
     else {
         methods.forEach((method, index) => {
-            into.oneOf(method, AUTHENTICATION_METHODS, "manifest.authenticationMethod", `${path}.authenticationMethods[${index}]`);
+            if (into.oneOf(method, AUTHENTICATION_METHODS, "manifest.authenticationMethod", `${path}.authenticationMethods[${index}]`) && methods.indexOf(method) !== index) {
+                into.add("manifest.authenticationMethod.unique", `${path}.authenticationMethods[${index}]`, `duplicate authentication method: ${String(method)}`);
+            }
         });
     }
     if (channelValid)
@@ -331,19 +339,28 @@ function validateDestinationDirectory(value, path, into) {
         return;
     }
     into.require(typeof value.allowManualEntry === "boolean", "task.destinations.allowManualEntry", `${path}.allowManualEntry`, "a directory must say whether manual entry is allowed");
+    // A directory with nothing in it and no typing is a control with nothing to offer.
+    if (value.allowManualEntry === false && !(Array.isArray(value.destinations) && value.destinations.length > 0)) {
+        into.add("task.destinations.offer", path, "a directory with no destinations must allow manual entry, or the control has nothing to offer");
+    }
     if (value.destinations === undefined)
         return;
     if (!Array.isArray(value.destinations)) {
         into.add("task.destinations.list", `${path}.destinations`, "destinations must be an array when present");
         return;
     }
+    const seen = new Set();
     value.destinations.forEach((destination, index) => {
         const at = `${path}.destinations[${index}]`;
         if (!isPlainObject(destination)) {
             into.add("task.destination.shape", at, "each destination must be an object");
             return;
         }
-        into.filled(destination.id, "task.destination.id", `${at}.id`, "a destination needs an id");
+        if (into.filled(destination.id, "task.destination.id", `${at}.id`, "a destination needs an id")) {
+            if (seen.has(destination.id))
+                into.add("task.destination.unique", `${at}.id`, `duplicate destination id: ${destination.id}`);
+            seen.add(destination.id);
+        }
         into.filled(destination.label, "task.destination.label", `${at}.label`, "a destination needs a label");
         into.filled(destination.address, "task.destination.address", `${at}.address`, "a destination needs an address");
         into.oneOf(destination.kind, DESTINATION_KINDS, "task.destination.kind", `${at}.kind`);
@@ -359,6 +376,10 @@ function validateDispositions(value, path, into) {
     if (value.required !== undefined) {
         into.require(typeof value.required === "boolean", "task.dispositions.required", `${path}.required`, "required must be a boolean when present");
     }
+    // A code must be collected before completion, so there must be one to collect.
+    if (value.required === true && !(Array.isArray(value.codes) && value.codes.length > 0)) {
+        into.add("task.dispositions.required.codes", `${path}.codes`, "a required disposition policy must publish at least one code");
+    }
     if (value.notes !== undefined)
         into.oneOf(value.notes, NOTES_POLICIES, "task.dispositions.notes", `${path}.notes`);
     if (value.codes === undefined)
@@ -414,6 +435,7 @@ function validateBrowsers(value, path, into) {
         return;
     }
     const seen = new Set();
+    const names = new Set();
     value.forEach((browser, index) => {
         const at = `${path}[${index}]`;
         if (!isPlainObject(browser)) {
@@ -425,7 +447,13 @@ function validateBrowsers(value, path, into) {
                 into.add("task.browser.unique", `${at}.id`, `duplicate browser id: ${browser.id}`);
             seen.add(browser.id);
         }
-        into.filled(browser.name, "task.browser.name", `${at}.name`, "a browser needs a name");
+        // The name is an input to a `TAB_NAME` isolation scheme: two tabs with one name would
+        // silently share a session.
+        if (into.filled(browser.name, "task.browser.name", `${at}.name`, "a browser needs a name")) {
+            if (names.has(browser.name))
+                into.add("task.browser.name.unique", `${at}.name`, `duplicate browser name: ${browser.name}`);
+            names.add(browser.name);
+        }
         into.filled(browser.purpose, "task.browser.purpose", `${at}.purpose`, "a browser needs a purpose");
         if (into.filled(browser.url, "task.browser.url", `${at}.url`, "a browser needs a url")) {
             let scheme;
@@ -463,13 +491,18 @@ function validateTaskAttributes(value, path, into) {
         into.add("task.attributes.shape", path, "attributes must be an array when present");
         return;
     }
+    const keys = new Set();
     value.forEach((attribute, index) => {
         const at = `${path}[${index}]`;
         if (!isPlainObject(attribute)) {
             into.add("task.attribute.shape", at, "each task attribute must be an object");
             return;
         }
-        into.filled(attribute.key, "task.attribute.key", `${at}.key`, "a task attribute needs a key");
+        if (into.filled(attribute.key, "task.attribute.key", `${at}.key`, "a task attribute needs a key")) {
+            if (keys.has(attribute.key))
+                into.add("task.attribute.unique", `${at}.key`, `duplicate attribute key: ${attribute.key}`);
+            keys.add(attribute.key);
+        }
         if (attribute.label !== undefined) {
             into.filled(attribute.label, "task.attribute.label", `${at}.label`, "a label must not be empty when present");
         }
@@ -509,6 +542,8 @@ function validateHandlingHistory(value, path, into) {
         }
         if (entry.by !== undefined) {
             into.require(isUserId(entry.by), "task.handlingHistory.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
+            // On `queued` nobody takes part, so there is nothing to name.
+            into.require(entry.step !== "queued", "task.handlingHistory.by.unexpected", `${at}.by`, "a queued step names nobody");
         }
     });
 }
@@ -611,6 +646,15 @@ function validateTaskInto(task, context, path, into) {
         return;
     }
     const allowed = isChannel(context.channel) ? TASK_CAPABILITIES[context.channel] : TASK_CAPABILITIES.voice;
+    // A task that supplies browser definitions declares the capability that shows them, and one
+    // that declares it supplies at least one: the capability puts a panel in the workspace, and a
+    // panel with nothing in it is a control with nothing to offer.
+    if (Array.isArray(task.browsers) && task.browsers.length > 0 && capabilities.browsers !== true) {
+        into.add("task.browsers.capability", `${path}.browsers`, "a task that supplies browsers declares capabilities.browsers");
+    }
+    if (capabilities.browsers === true && Array.isArray(task.browsers) && task.browsers.length === 0) {
+        into.add("task.browsers.required", `${path}.browsers`, "a task that declares capabilities.browsers supplies at least one; with none, omit the capability");
+    }
     for (const [name, declared] of Object.entries(capabilities)) {
         if (declared === undefined)
             continue;
@@ -669,6 +713,10 @@ function validateBreakState(value, path, into) {
             into.filled(value[field], `break.${field}`, `${path}.${field}`, `${field} must not be empty when present`);
         }
     }
+    // The refusal is the reason the control is withdrawn; beside `accepting: true` it explains nothing.
+    if (value.refusedReason !== undefined) {
+        into.require(value.accepting !== true, "break.refusedReason.accepting", `${path}.refusedReason`, "refusedReason is shown when accepting is false; omit it while the agent may ask");
+    }
     if (value.retryAfterMs !== undefined) {
         into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "break.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
     }
@@ -678,14 +726,21 @@ function validateBreakState(value, path, into) {
         // break that is not happening.
         into.require(value.approval !== "not-requested", "break.activeReasonId.approval", `${path}.activeReasonId`, "activeReasonId must be omitted when no break is requested or in effect");
     }
-    if (value.imposed !== undefined)
+    if (value.imposed !== undefined) {
         validateImposedBreak(value.imposed, `${path}.imposed`, into);
+        // An imposed break is a break somebody placed; beside `not-requested` there is no break.
+        into.require(value.approval !== "not-requested", "break.imposed.approval", `${path}.imposed`, "an imposed break is a break in progress; not-requested says there is none");
+    }
     if (value.reasons === undefined)
         return;
     if (!Array.isArray(value.reasons)) {
         into.add("break.reasons.shape", `${path}.reasons`, "break reasons must be an array when present");
         return;
     }
+    // A provider that defines no codes omits the field: an empty list is a second spelling of that.
+    if (value.reasons.length === 0) {
+        into.add("break.reasons.empty", `${path}.reasons`, "a provider that defines no reasons omits the field rather than publishing an empty list");
+    }
     const seen = new Set();
     value.reasons.forEach((reason, index) => {
         const at = `${path}.reasons[${index}]`;
@@ -705,6 +760,10 @@ function validateBreakState(value, path, into) {
             into.require(reason.alwaysAvailable === true, "break.reason.alwaysAvailable", `${at}.alwaysAvailable`, "alwaysAvailable is declared by presence: send true or omit it");
         }
     });
+    // The active reason is one of the published ones, or it is a reason Omni cannot name.
+    if (typeof value.activeReasonId === "string" && value.activeReasonId.length > 0) {
+        into.require(seen.has(value.activeReasonId), "break.activeReasonId.known", `${path}.activeReasonId`, `activeReasonId names a reason the provider did not publish: ${value.activeReasonId}`);
+    }
 }
 export function validateTeamRoster(roster, path = "team", context = {}) {
     const into = new Collector();
@@ -780,8 +839,13 @@ function validateTeamRosterInto(roster, path, context, into) {
         into.oneOf(member.availability, TEAM_AVAILABILITIES, "team.member.availability", `${at}.availability`);
         if (member.since !== undefined)
             into.timestamp(member.since, "team.member.since", `${at}.since`);
-        if (member.break !== undefined)
-            into.oneOf(member.break, BREAK_APPROVALS, "team.member.break", `${at}.break`);
+        if (member.break !== undefined) {
+            // Only an outstanding request appears here: `not-requested` is absence, `in-effect` is
+            // `availability: "on-break"`, and a denial never survives to be reported.
+            if (into.oneOf(member.break, MEMBER_BREAKS, "team.member.break", `${at}.break`)) {
+                into.require(member.availability !== "signed-out" && member.availability !== "on-break", "team.member.break.availability", `${at}.break`, "a member on a break or signed out has no request outstanding");
+            }
+        }
     });
 }
 export function validateSnapshot(snapshot, manifest, path = "snapshot", context = {}) {
@@ -792,15 +856,25 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     into.oneOf(snapshot.status, CONNECTION_STATUSES, "snapshot.status", `${path}.status`);
-    into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to");
+    if (into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to")
+        && context.sessionId !== undefined) {
+        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);
     if (!Array.isArray(snapshot.tasks)) {
         into.add("snapshot.tasks.shape", `${path}.tasks`, "a snapshot must carry a tasks array");
     }
     else {
         const seen = new Set();
+        let assisting;
         snapshot.tasks.forEach((task, index) => {
             validateTaskInto(task, { channel }, `${path}.tasks[${index}]`, into);
+            // A lead assists one call at a time.
+            if (isPlainObject(task) && task.assisting !== undefined) {
+                if (assisting !== undefined)
+                    into.add("snapshot.assisting.single", `${path}.tasks[${index}].assisting`, "a lead assists one call at a time");
+                assisting = index;
+            }
             if (isPlainObject(task) && isTaskId(task.id)) {
                 if (seen.has(task.id))
                     into.add("task.id.unique", `${path}.tasks[${index}].id`, `duplicate task id: ${task.id}`);
@@ -895,9 +969,7 @@ function validateTaskOutcome(value, path, into) {
                 into.add("event.taskEnded.outcome.failed", `${path}.failure`, "a failed outcome must carry a failure");
             }
             else {
-                into.filled(value.failure.code, "failure.code", `${path}.failure.code`, "a failure needs a code");
-                into.filled(value.failure.message, "failure.message", `${path}.failure.message`, "a failure needs a message");
-                into.require(typeof value.failure.retryable === "boolean", "failure.retryable", `${path}.failure.retryable`, "a failure must say whether it is retryable");
+                validateFailureInto(value.failure, `${path}.failure`, into);
             }
             break;
         default:
@@ -921,7 +993,13 @@ function validateProviderSummary(value, path, into) {
         into.add("event.summary.metrics.shape", `${path}.metrics`, "metrics must be an array when present");
         return;
     }
+    const ids = new Set();
     value.metrics.forEach((metric, index) => {
+        if (isPlainObject(metric) && isFilled(metric.id)) {
+            if (ids.has(metric.id))
+                into.add("event.summary.metric.unique", `${path}.metrics[${index}].id`, `duplicate metric id: ${metric.id}`);
+            ids.add(metric.id);
+        }
         const at = `${path}.metrics[${index}]`;
         if (!isPlainObject(metric)) {
             into.add("event.summary.metric.shape", at, "each metric must be an object");
@@ -940,7 +1018,11 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
     }
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     into.filled(envelope.id, "event.id", `${path}.id`, "an event needs an id");
-    into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to");
+    if (into.filled(envelope.sessionId, "event.sessionId", `${path}.sessionId`, "an event needs the session id it belongs to")
+        && context.sessionId !== undefined) {
+        into.require(envelope.sessionId === context.sessionId, "event.sessionId.mismatch", `${path}.sessionId`, `an event for session ${String(envelope.sessionId)} on a login whose session is ${context.sessionId}`);
+    }
+    const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
     into.timestamp(envelope.occurredAt, "event.occurredAt", `${path}.occurredAt`);
     const event = envelope.event;
     if (!isPlainObject(event)) {
@@ -964,9 +1046,20 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             break;
         case "task-offered":
             validateTaskInto(event.task, { channel }, `${at}.task`, into);
+            // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
+            if (isPlainObject(event.task) && typeof event.task.phase === "string") {
+                into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
+            }
             if (event.acceptanceMode !== undefined) {
                 into.oneOf(event.acceptanceMode, ACCEPTANCE_MODES, "event.taskOffered.acceptanceMode", `${at}.acceptanceMode`);
             }
+            // The mode travels exactly when Omni said tasks may be auto-accepted.
+            if (context.autoAcceptTasks === true) {
+                into.require(event.acceptanceMode !== undefined, "event.taskOffered.acceptanceMode.required", `${at}.acceptanceMode`, "autoAcceptTasks is on, so task-offered carries an acceptanceMode");
+            }
+            else if (context.autoAcceptTasks === false) {
+                into.require(event.acceptanceMode === undefined, "event.taskOffered.acceptanceMode.unexpected", `${at}.acceptanceMode`, "autoAcceptTasks is off, so every task requires agent acceptance and task-offered carries no acceptanceMode");
+            }
             for (const field of ["allocationExpiresAt", "preparationEndsAt"]) {
                 if (event[field] !== undefined)
                     into.timestamp(event[field], `event.taskOffered.${field}`, `${at}.${field}`);
@@ -998,6 +1091,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateTeamRosterInto(event.team, `${at}.team`, context, into);
             break;
         case "contacts-updated":
+            into.require(idle.contacts === true, "event.contacts.capability", `${at}.contacts`, "contacts-updated requires the contacts idle capability");
             if (!Array.isArray(event.contacts)) {
                 into.add("event.contacts.shape", `${at}.contacts`, "contacts must be an array");
             }
@@ -1006,11 +1100,20 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             }
             break;
         case "calendar-updated":
+            into.require(idle.calendar === true, "event.calendar.capability", `${at}.scheduledActivities`, "calendar-updated requires the calendar idle capability");
             if (!Array.isArray(event.scheduledActivities)) {
                 into.add("event.calendar.shape", `${at}.scheduledActivities`, "scheduledActivities must be an array");
             }
             else {
-                event.scheduledActivities.forEach((activity, index) => validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into));
+                const ids = new Set();
+                event.scheduledActivities.forEach((activity, index) => {
+                    validateScheduledActivityInto(activity, `${at}.scheduledActivities[${index}]`, into);
+                    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}`);
+                        ids.add(activity.id);
+                    }
+                });
             }
             break;
         default:
@@ -1019,6 +1122,75 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
     return into.violations;
 }
 // ---------------------------------------------------------------------------
+// Results. A result crosses the same boundary a snapshot does, from an adapter that may be
+// compiled against another version, and Omni shows the agent what it says.
+// ---------------------------------------------------------------------------
+/** A `ProtocolFailure`, wherever one appears: on a result, or on a task's failed outcome. */
+function validateFailureInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("failure.shape", path, "a failure must be an object");
+        return;
+    }
+    if (into.filled(value.code, "failure.code", `${path}.code`, "a failure needs a code")) {
+        // A provider names its own codes freely; the `omni.` namespace is the contract's, and a code
+        // in it that the contract lacks is one Omni would show without knowing what it means.
+        if (value.code.startsWith("omni.")) {
+            into.require(OMNI_FAILURE_CODES.includes(value.code), "failure.code.unknown", `${path}.code`, `not a contract failure code: ${value.code}`);
+        }
+    }
+    into.filled(value.message, "failure.message", `${path}.message`, "a failure needs a message");
+    into.require(typeof value.retryable === "boolean", "failure.retryable", `${path}.retryable`, "a failure must say whether it is retryable");
+    if (value.retryAfterMs !== undefined) {
+        into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+    }
+}
+// Pinned to the result unions: each method's one success status, and the status that carries a
+// failure. A method added to `Connection` without a row here is a compile error at the call site.
+const RESULT_STATUSES = {
+    execute: { success: "applied", failure: "failed" },
+    dial: { success: "dialled", failure: "failed" },
+    setCapacity: { success: "accepted", failure: "failed" },
+    requestBreak: { success: "requested", failure: "failed" },
+    commitBreak: { success: "committed", failure: "failed" },
+    cancelBreak: { success: "cancelled", failure: "failed" },
+    endBreak: { success: "ended", failure: "failed" },
+    executeTeamBreak: { success: "applied", failure: "failed" },
+    executeTeamConsult: { success: "applied", failure: "failed" },
+    openMedia: { success: "opened", failure: "unavailable" },
+};
+/**
+ * Validates what a connection method answered. A result is untrusted for the same reason a
+ * snapshot is: it comes from an adapter that may be compiled against another version, and Omni
+ * shows the agent what it says. A status the method does not answer, a failure status without a
+ * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
+ */
+export function validateResult(result, method, path = "result") {
+    const into = new Collector();
+    const statuses = RESULT_STATUSES[method];
+    if (!isPlainObject(result)) {
+        into.add("result.shape", path, `${method} must answer an object`);
+        return into.violations;
+    }
+    if (result.status === statuses.success) {
+        into.require(result.failure === undefined, "result.failure.unexpected", `${path}.failure`, `${statuses.success} carries no failure`);
+        if (method === "openMedia") {
+            into.require(isPlainObject(result.session), "result.session", `${path}.session`, "opened carries the media session");
+        }
+    }
+    else if (result.status === statuses.failure) {
+        if (result.failure === undefined) {
+            into.add("result.failure.required", `${path}.failure`, `${statuses.failure} carries the failure that says why`);
+        }
+        else {
+            validateFailureInto(result.failure, `${path}.failure`, into);
+        }
+    }
+    else {
+        into.add("result.status", `${path}.status`, `${method} answers ${statuses.success} or ${statuses.failure}, not ${String(result.status)}`);
+    }
+    return into.violations;
+}
+// ---------------------------------------------------------------------------
 // Authentication.
 // ---------------------------------------------------------------------------
 function validateUser(value, rule, path, into) {
@@ -1088,6 +1260,9 @@ export function validateAuthenticationState(state, path = "authentication") {
     else {
         into.require(state.identity === undefined, "authentication.identity.unexpected", `${path}.identity`, `${state.status} must not carry an identity`);
     }
+    if (state.failure !== undefined) {
+        into.require(state.status === "expired", "authentication.failure.unexpected", `${path}.failure`, "only an expired state may carry a failure");
+    }
     if (state.expiresAt !== undefined) {
         into.require(state.status === "authenticated", "authentication.expiresAt.unexpected", `${path}.expiresAt`, "only an authenticated state may carry an expiry");
         into.timestamp(state.expiresAt, "authentication.expiresAt", `${path}.expiresAt`);

package/guide.md

@@ -1731,7 +1731,7 @@ time. Runtime conformance checks also require the task channel to match its prov
 | `channel` | Channel handling this task. It must equal the source provider's manifest channel. |
 | `taskType` | Required provider-defined source or category of work, such as a voice `Queue Name`, `Mailbox Folder`, `Chat Source`, `Support`, `Billing`, or `Returns`. |
 | `capabilities` | Controls and workspace features available for this specific task. |
-| `browsers` | Named browser definitions for the task workspace; empty when the task does not declare the `browsers` capability. |
+| `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`. |
 | `reference` | Optional agent-facing reference such as a case, call, conversation, ticket, or message number. It is distinct from the protocol `id`. |
@@ -2042,14 +2042,13 @@ browser that used it.
 
 ### Task capabilities
 
-Task capabilities belong to each `Task`. If `hold` is false or omitted on one task, Omni
+Task capabilities belong to each `Task`. If `hold` is omitted on one task, Omni
 must not show or issue hold for that task even if another task from the same provider supports it.
 
 ```ts
 const taskCapabilities = {
   channel: "voice",
   capabilities: {
-    browsers: true,
     hold: true,
     dispositions: true,
   },
@@ -2225,7 +2224,8 @@ Starts one outbound call from the idle dialpad. It is present only when the voic
 declares `dial`.
 
 - `destination` is the original number selected or entered by the agent.
-- `source` is `contact` or `manual` and must comply with `destinationPolicy`.
+- The provider holds `destination` to its declared `destinationPolicy`: under `contacts-only`, a
+  number that is not one of its contacts answers `failed` with `omni.destination-not-permitted`.
 - `dialled` confirms that outbound call creation completed.
 - `failed` contains a `ProtocolFailure` and confirms no call was placed.
 
@@ -2246,7 +2246,7 @@ nothing while none are being accepted — so they are not published separately.
 | `refusedReason` | Display-ready reason shown when `accepting` is false — a standing gate that applies to everyone. |
 | `decisionReason` | The words whoever decided attached, from `decide.reason`. About one request and one decision, not a standing gate. |
 | `retryAfterMs` | How long until the agent may retry, when the provider can say. |
-| `reasons` | Not-ready codes this provider offers. Omitted when it defines none. |
+| `reasons` | Not-ready codes this provider offers. Omitted when it defines none; an empty list is refused, being a second spelling of the same fact. |
 | `activeReasonId` | The `BreakReason.id` the current break is on. Omitted when there is no break, or when the provider cannot say. |
 | `imposed` | Set when the break was placed on the agent rather than requested. |
 
@@ -2934,6 +2934,11 @@ Applies a `TaskCommandRequest` to one provider-local task.
   deciding a member's break that another lead has already decided is `applied` when the decisions
   agree and `failed`, saying so in `message`, when they differ. `commitBreak()` on a break already
   in effect is `committed` for the same reason.
+- **A result is untrusted for the same reason a snapshot is.** It comes from an adapter that may be
+  compiled against another version, and Omni shows the agent what it says. Omni validates it at
+  the boundary with `validateResult(result, "execute")` — a status the method does not answer, a
+  `failed` without its failure, a success carrying one, or an `omni.` code this contract lacks is
+  refused, and the command is treated as unsettled.
 - **A settled result is a fact; an unsettled promise is not.** Transport uncertainty may reject the
   promise with no result at all, and that means *unknown*, not *failed*, and a snapshot follows —
   see **An unsettled result is unknown**. `failed` must never be returned for something the
@@ -3176,6 +3181,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `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. |
+| `validateResult(result, method)` | What a connection method answered: the status it gives, a failure where the status says so and nowhere else, the failure's shape, and that an `omni.` code is one this contract names. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. |
 
 Each returns `ProtocolViolation[]` rather than throwing, so a caller can report every problem at

package/package.json

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