@xema/omni-protocol 0.1.54 → 0.1.56

package/dist/index.d.ts

@@ -1394,7 +1394,7 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
     occurredAt: IsoTimestamp;
     event: ProviderEvent<C>;
 }
-export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.task-not-found", "omni.destination-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed"];
+export declare const OMNI_FAILURE_CODES: readonly ["omni.not-authenticated", "omni.capability-not-enabled", "omni.task-not-found", "omni.destination-not-permitted", "omni.phone-not-permitted", "omni.rate-limited", "omni.unavailable", "omni.break-already-committed"];
 export type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 export interface Connection<C extends Channel = Channel> {
     snapshot(): Snapshot<C> | Promise<Snapshot<C>>;

package/dist/index.js

@@ -102,6 +102,7 @@ export const OMNI_FAILURE_CODES = [
     "omni.capability-not-enabled",
     "omni.task-not-found",
     "omni.destination-not-permitted",
+    "omni.phone-not-permitted",
     "omni.rate-limited",
     "omni.unavailable",
     "omni.break-already-committed",

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type Task, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Host, type HostGuarantees, type HostReport, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
 /**
@@ -84,6 +84,20 @@ export declare function assertCommandRefusedAfterWithdrawal(result: {
         code: string;
     };
 }): void;
+/**
+ * A task's capabilities are current, not fixed. A provider whose platform withdraws a permission
+ * mid-task republishes the task with the set as it now stands, and a command under the withdrawn
+ * capability is refused from then on. `tasks` is what the provider published for one task, first
+ * to last -- the offer, then each republish -- every one validated against the manifest, all the
+ * same id, with at least one capability offered by the first absent from the last. A locked
+ * control is present without permission, not withdrawn: it is still drawn, so it does not count.
+ * `command` is the command a host issues under a withdrawn capability: it must be clean against
+ * the first task and refused against the last for want of that capability and for nothing else.
+ * That pairing is what proves the refusal comes from the withdrawal rather than from a command
+ * that was never issuable. Pair it with `assertCommandRefusedAfterWithdrawal` on the provider's
+ * answer to the same command.
+ */
+export declare function assertTaskCapabilityWithdrawal(tasks: readonly Task[], manifest: Manifest, command: Record<string, unknown>): void;
 /**
  * Throws unless the run reached every subject named: the paired assertion beside a clean result,
  * so a fixture that never produced a roster cannot pass a test that meant to check one.

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, effectiveLevels, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, validateManifest, validateResult, validateSnapshot, validateTimeZone, validatePhone, validateTaskCommand, isTimeZone, sameTimeZone, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateHostGuarantees, validateHostReport, 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
@@ -575,6 +575,54 @@ export function assertCommandRefusedAfterWithdrawal(result) {
         throw new Error(`A command after its capability was withdrawn fails with omni.capability-not-enabled, not ${result.failure?.code}`);
     }
 }
+/**
+ * A task's capabilities are current, not fixed. A provider whose platform withdraws a permission
+ * mid-task republishes the task with the set as it now stands, and a command under the withdrawn
+ * capability is refused from then on. `tasks` is what the provider published for one task, first
+ * to last -- the offer, then each republish -- every one validated against the manifest, all the
+ * same id, with at least one capability offered by the first absent from the last. A locked
+ * control is present without permission, not withdrawn: it is still drawn, so it does not count.
+ * `command` is the command a host issues under a withdrawn capability: it must be clean against
+ * the first task and refused against the last for want of that capability and for nothing else.
+ * That pairing is what proves the refusal comes from the withdrawal rather than from a command
+ * that was never issuable. Pair it with `assertCommandRefusedAfterWithdrawal` on the provider's
+ * answer to the same command.
+ */
+export function assertTaskCapabilityWithdrawal(tasks, manifest, command) {
+    const first = tasks[0];
+    const last = tasks.at(-1);
+    if (tasks.length < 2 || first === undefined || last === undefined) {
+        throw new Error("Task capability withdrawal needs the task as offered and at least one republish of it");
+    }
+    const context = {
+        channel: manifest.channel,
+        levels: effectiveLevels(manifest.orgLevels).map(level => level.id),
+        dialOutcomesDeclared: manifest.dialOutcomes !== undefined,
+    };
+    tasks.forEach((task, index) => {
+        assertNoViolations(validateTask(task, context, `tasks[${index}]`), `Task capability withdrawal: tasks[${index}] must be a task the wire could carry`);
+        if (task.id !== first.id) {
+            throw new Error(`Task capability withdrawal must keep the task: tasks[${index}] is ${task.id}, and the offer was ${first.id}`);
+        }
+    });
+    const withdrawn = Object.keys(first.capabilities).filter(name => last.capabilities[name] === undefined);
+    if (withdrawn.length === 0) {
+        throw new Error("Task capability withdrawal must end with at least one capability the offer declared withdrawn; a locked control is present without permission, not withdrawn");
+    }
+    const before = validateTaskCommand(command, first, "command");
+    if (before.length > 0) {
+        throw new Error(`Task capability withdrawal: the command must be issuable against the task as offered, or its later refusal proves nothing (${before.map(v => v.rule).join(", ")})`);
+    }
+    const after = validateTaskCommand(command, last, "command");
+    const forWant = after.filter(v => withdrawn.some(name => v.rule === `command.capability.${name}`));
+    if (forWant.length === 0) {
+        throw new Error(`Task capability withdrawal: the command must be refused against the republished task for want of ${withdrawn.join(" or ")}; it was ${after.length === 0 ? "accepted" : `refused for ${after.map(v => v.rule).join(", ")}`}`);
+    }
+    const other = after.filter(v => !forWant.includes(v));
+    if (other.length > 0) {
+        throw new Error(`Task capability withdrawal: the republished task refuses the command for more than the withdrawal (${other.map(v => v.rule).join(", ")}); change one thing at a time`);
+    }
+}
 /**
  * Throws unless the run reached every subject named: the paired assertion beside a clean result,
  * so a fixture that never produced a roster cannot pass a test that meant to check one.

package/dist/validation.d.ts

@@ -91,4 +91,11 @@ export interface LoginValidationContext {
     /** The level ids in force, from the manifest. The defaults when absent. */
     levels?: readonly string[];
 }
+export declare function validateAuthenticationFailure(failure: unknown, path?: string): ProtocolViolation[];
+/**
+ * What `start()` or `complete()` answered: a challenge or a rejection from `start`, a login or a
+ * rejection from `complete`. A rejection carries a failure the host can show, and a login is held
+ * to the same rules as any `authenticated` state.
+ */
+export declare function validateAuthenticationResult(result: unknown, method: "start" | "complete", path?: string, context?: LoginValidationContext): ProtocolViolation[];
 export declare function validateAuthenticationState(state: unknown, path?: string, context?: LoginValidationContext): ProtocolViolation[];

package/dist/validation.js

@@ -2053,6 +2053,61 @@ function validateMonitorControl(value, path, into) {
     });
     into.require(value.includes("monitor"), "authentication.capability.team.monitorControl.monitor", path, "whisper and barge begin from a monitor: a lead who may listen in any mode may monitor");
 }
+/**
+ * A failure an authentication reports: on a `rejected` start or completion, or on an `expired`
+ * state. A provider names its own codes freely; an `omni.` code is the contract's and has to be one
+ * it lists. `omni.phone-not-permitted` is never retryable: the agent's station is administrator
+ * configuration, and trying again does not reconfigure it.
+ */
+function validateAuthenticationFailureInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("authentication.failure.shape", path, "a failure must be an object");
+        return;
+    }
+    if (into.filled(value.code, "authentication.failure.code", `${path}.code`, "a failure needs a code") && value.code.startsWith("omni.")) {
+        into.require(OMNI_FAILURE_CODES.includes(value.code), "failure.code.unknown", `${path}.code`, `${String(value.code)} is not a failure code this contract defines`);
+    }
+    into.filled(value.message, "authentication.failure.message", `${path}.message`, "a failure needs a message");
+    into.require(typeof value.retryable === "boolean", "authentication.failure.retryable", `${path}.retryable`, "a failure must say whether it is retryable");
+    if (value.code === "omni.phone-not-permitted") {
+        into.require(value.retryable === false, "authentication.failure.phone.retryable", `${path}.retryable`, "a phone the platform does not permit for this agent is configuration: trying again does not change it, so the refusal is not retryable");
+    }
+    if (value.retryAfterMs !== undefined) {
+        into.require(typeof value.retryAfterMs === "number" && value.retryAfterMs >= 0, "authentication.failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+    }
+    if (value.field !== undefined)
+        into.filled(value.field, "authentication.failure.field", `${path}.field`, "field names a declared credentials field when present");
+}
+export function validateAuthenticationFailure(failure, path = "failure") {
+    const into = new Collector();
+    validateAuthenticationFailureInto(failure, path, into);
+    return into.violations;
+}
+/**
+ * What `start()` or `complete()` answered: a challenge or a rejection from `start`, a login or a
+ * rejection from `complete`. A rejection carries a failure the host can show, and a login is held
+ * to the same rules as any `authenticated` state.
+ */
+export function validateAuthenticationResult(result, method, path = "result", context = {}) {
+    const into = new Collector();
+    if (!isPlainObject(result)) {
+        into.add("authentication.result.shape", path, `${method} must answer an object`);
+        return into.violations;
+    }
+    if (result.status === "rejected") {
+        validateAuthenticationFailureInto(result.failure, `${path}.failure`, into);
+    }
+    else if (method === "start" && result.status === "interaction-required") {
+        into.require(isPlainObject(result.challenge), "authentication.result.challenge", `${path}.challenge`, "interaction-required carries the challenge to put to the person");
+    }
+    else if (method === "complete" && result.status === "authenticated") {
+        into.violations.push(...validateAuthenticationState(result, path, context));
+    }
+    else {
+        into.add("authentication.result.status", `${path}.status`, `${method} answers ${method === "start" ? "interaction-required" : "authenticated"} or rejected, not ${String(result.status)}`);
+    }
+    return into.violations;
+}
 export function validateAuthenticationState(state, path = "authentication", context = {}) {
     const into = new Collector();
     if (!isPlainObject(state)) {
@@ -2072,14 +2127,7 @@ export function validateAuthenticationState(state, path = "authentication", cont
         if (state.identity !== undefined)
             validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
         if (state.failure !== undefined) {
-            if (!isPlainObject(state.failure)) {
-                into.add("authentication.failure.shape", `${path}.failure`, "a failure must be an object when present");
-            }
-            else {
-                into.filled(state.failure.code, "authentication.failure.code", `${path}.failure.code`, "a failure needs a code");
-                into.filled(state.failure.message, "authentication.failure.message", `${path}.failure.message`, "a failure needs a message");
-                into.require(typeof state.failure.retryable === "boolean", "authentication.failure.retryable", `${path}.failure.retryable`, "a failure must say whether it is retryable");
-            }
+            validateAuthenticationFailureInto(state.failure, `${path}.failure`, into);
         }
     }
     else {

package/guide.md

@@ -1120,6 +1120,7 @@ const OMNI_FAILURE_CODES = [
   "omni.capability-not-enabled",
   "omni.task-not-found",
   "omni.destination-not-permitted",
+  "omni.phone-not-permitted",
   "omni.rate-limited",
   "omni.unavailable",
   "omni.break-already-committed",
@@ -2663,6 +2664,44 @@ browser that used it.
 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.
 
+**A capability is a property of the task, and of nothing the task names.** A provider derives it
+from no other source -- not the queue the task came from, not the login, not its own configuration
+-- because each of those answers a question about this task from somewhere that does not know
+about this task, and a client with two sources and a rule for choosing between them is the shape
+that produces two consumers disagreeing about one fact. The task is the one source, and the
+provider puts on the task what the platform permits for it.
+
+**A permission that changes while the task is open is republished on the task at the moment it
+changes.** An agent on a billing dispute may refund up to their own limit and no further. The
+customer wants more, the agent asks for a lead, and the moment the lead joins the call the task is
+republished with the Refund control the agent could not have a minute ago; when the lead leaves, it
+is republished without it. Nothing about the agent changed -- who is on the call did -- and the
+task said so both times, at the moment it became true. A call moves queues the same way: a caller
+identified as a priority customer is transferred to the priority queue, and the task arrives under
+that queue's terms -- a longer wrap allowance, a discount control the general queue never offered --
+restated on the task at the hand-over, not inferred from the queue it left. A capability stated
+once at offer or answer and never corrected is a fact with a shelf life and no expiry, and a host
+draws a control the provider will now refuse -- or withholds one the agent now has. So the provider republishes
+the task, with its capabilities as they now stand, and a host treats the last statement as current
+rather than re-deriving anything. This is the same shape as a room left full after the call ends
+-- a field describing the present, carried past the moment it stopped being true -- carried past
+this time not by a spread but by nobody sending the correction. A provider whose platform can
+change a permission mid-task and does not republish is in breach, however conformant its offer was.
+A capability set can shrink as well as grow, and a host that has only ever seen it grow meets a
+control that was there a moment ago and is gone; a command that arrives after its capability was
+withdrawn is refused with a reason, never acted on. The asymmetry decides which direction a
+provider gets right first: a control gained late is a nicety, a control withdrawn and not
+republished is a button that fails when pressed. `assertTaskCapabilityWithdrawal` is the test for that
+direction: the task as offered and as republished, and one command that was issuable under the
+first and is refused under the last for want of the capability withdrawn -- and nothing else.
+
+**An empty capability set is a statement, not a shrug.** `capabilities: {}` says the platform
+permits nothing on this task. A provider that has not yet learned what the platform permits -- a
+queue's configuration that has not reached it -- knows nothing of the kind, and must not publish
+the task as if it did: it holds the task until it knows, or reports the gap as a `diagnostic`,
+because "no queue governs this call" is a fact and "the configuration has not arrived" is a fault,
+and a host cannot tell them apart from a value that carries neither.
+
 ```ts
 const taskCapabilities = {
   channel: "voice",
@@ -3799,6 +3838,21 @@ that is a telephone. The harness requires no `openMedia` of such an adapter and
 this wire never asks the agent for it: a host declares `phone` and nothing more. What a platform
 asks on surfaces of its own is its own decision.
 
+**A declared phone the platform does not permit for this agent is a login that cannot be
+established.** The manifest says what the platform can do; the agent's record, kept by an
+administrator, says what this agent is configured for, and the two can disagree with the host's
+declaration -- a softphone declared for an agent whose record says desk phone. Honouring that
+declaration on a switch that allows one registration per endpoint would evict the handset: the
+agent's phone stops ringing and their calls land in a tab, and nobody is told. So the provider
+refuses the login at authentication, with `omni.phone-not-permitted` and a message the host shows
+-- "this agent is configured for a desk phone" -- and refusing is correct, not an override of the
+host. It is a refusal, never a negotiation afterwards and never a quiet substitution, and it is
+never retryable: trying again does not reconfigure the agent, and a host validating the answer
+(`validateAuthenticationResult`) refuses a phone refusal marked otherwise
+(`authentication.failure.phone.retryable`). And **a
+provider never makes a declared phone true by changing the platform's configuration**: the record
+is the administrator's, and a login is not a request to reconfigure an agent.
+
 ### Opening the audio
 
 `openMedia` hands Omni the remote audio for one task. Every adapter whose manifest lists
@@ -3963,6 +4017,7 @@ react rather than only display the message:
 | `omni.not-authenticated` | The provider session is no longer usable. The adapter has published `expired` at or before this answer — the state is what Omni surfaces reauthentication from; the code says why this action failed, and is never the only signal. |
 | `omni.capability-not-enabled` | The action targets a capability this task, manifest, or login did not declare — including a lead command from a login whose `capabilities` no longer carry it. |
 | `omni.task-not-found` | The provider-local task id is unknown, typically after the task already ended. |
+| `omni.phone-not-permitted` | The host declared a `phone` the platform does not permit for this agent -- a softphone for an agent configured for a desk phone, or the reverse. The login is refused at authentication, and the provider never reconfigures the agent to make the declaration true. See **How the agent hears the call**. |
 | `omni.destination-not-permitted` | The dialled number, or the `destinationId` named, is not one the provider offers this agent. |
 | `omni.rate-limited` | The action was throttled. Pair with `retryAfterMs`. |
 | `omni.unavailable` | The provider is temporarily unable to serve the action, including any command sent while `transport-status` is not `active`. |
@@ -4270,6 +4325,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `validateHostGuarantees(guarantees)` | What a host promises: only the guarantees this contract names, each declared by presence and never `false`. The harness validates the guarantees of whatever host a test hands the adapter. |
 | `validateHandlingReport(report, path?, manifest?)` | What the host reports of a leg it performed, for an adapter to check before forwarding: a task, a step, when it began, a positive `seconds` where stated, and an explicit `ended` that carries the final duration. Given the manifest, a running report is refused unless it declares `runningStepReports`. |
 | `validateHostReport(report)` | The host's own report as published to an adapter: `online`, and where there is audio, an input that is `available` with the microphone and `flowing`, or `unavailable` with a reason and the failure that says why, and an output that is `available` or `unavailable` with its failure. The harness validates whatever host a test hands the adapter; `stillHost(report)` builds one that never changes. |
+| `validateAuthenticationResult(result, method)` | What `start()` or `complete()` answered: a challenge or a rejection, a login or a rejection. A rejection's failure is held to its rules -- an `omni.` code the contract lists, and `omni.phone-not-permitted` never retryable, since the agent's station is configuration. `validateAuthenticationFailure(failure)` is the same check on a failure alone. |
 | `validateTaskCommand(command, task?)` | What a command needs to be issuable, against the task it names: its own shape -- a dial's `dialId`, a transfer's item, a remove naming exactly one person -- and, with the task, the capability the table above gates it on (`command.capability.<name>`, `.locked`), the phase it belongs to (`command.phase.*`), and the state that has to stand: a consulted entry, a lead requested, somebody else still on the call (`command.conference.remove.alone`). A host validates before sending and an adapter before acting. |
 | `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. Omni applies it to every state a session publishes — the republished as much as the first. |
@@ -4358,6 +4414,10 @@ assertReached(driven, ["task.onCall", "task.media", "event.task-ended"]);
 ```
 `assertReached(result, subjects)` is the paired assertion: it throws naming every subject the run
 never met, so a test that meant to check a roster cannot pass on a fixture that never produced one.
+It reads like a guarantee and is a claim the adopter keeps making: it catches an adapter that
+stopped reaching a subject, not a list that stopped asking, so a list can rot to nothing and stay
+green. Keep it honest with a control beside it -- one subject the run genuinely cannot reach,
+asserted to throw -- so the assertion is shown to be looking rather than agreeing.
 
 Three properties of the harness matter to adapter authors:
 
@@ -4379,6 +4439,7 @@ cannot be established from TypeScript structure alone.
 | Helper | Contract checked |
 | --- | --- |
 | `assertCapabilityWithdrawal(states, snapshot, manifest)` | A capability withdrawn by a later `authenticated` state is gone from the next snapshot: no roster for a login that no longer leads, no requests for one that may no longer join. Every state is validated on the way, `refreshing` must carry the login over, and the sequence passes only through usable states. |
+| `assertTaskCapabilityWithdrawal(tasks, manifest, command)` | A capability withdrawn by a republish of the task is gone from the task: every task in the sequence is validated, all carry the offer's id, at least one capability the offer declared is absent at the end (a locked control is present, not withdrawn), and `command` is clean against the first task and refused against the last for want of a withdrawn capability and nothing else. Pair it with `assertCommandRefusedAfterWithdrawal` on the provider's answer. |
 | `assertCommandRefusedAfterWithdrawal(result)` | A command that arrives after its capability was withdrawn fails with `omni.capability-not-enabled`, named by the provider. The same assertion serves a command the provider never supported under a capability it declares. |
 | `assertReached(result, subjects)` | The exercise met every subject named; throws listing those it did not. Pair it with a clean `exerciseAdapter` result. |
 | `assertAuthenticationRestoreAndExpiry(states)` | A restored authenticated session can refresh and ends in expiry. Every state is validated. |

package/package.json

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