@xema/omni-protocol 0.1.55 → 0.1.57

package/dist/index.d.ts

@@ -744,6 +744,13 @@ export interface Locked {
  * is the discriminant: a value that carries it is the lock, so no `T` may carry that key.
  */
 export type Lockable<T> = T | Locked;
+/**
+ * Who chose a task's capabilities. `undetermined` is a fault the provider states on the task rather
+ * than hides: the platform's terms could not be read, and the set published is what the provider
+ * will honour, not what the platform permits.
+ */
+export type CapabilitySource = "queue" | "ungoverned" | "undetermined";
+export declare const CAPABILITY_SOURCES: readonly ["queue", "ungoverned", "undetermined"];
 export type Task<C extends Channel = Channel> = {
     id: TaskId;
     title: string;
@@ -751,6 +758,13 @@ export type Task<C extends Channel = Channel> = {
     /** The provider's own name for a category of work. Finer-grained than a channel. */
     taskType: string;
     capabilities: TaskCapabilities<C>;
+    /**
+     * Where the capabilities came from before the provider put them on the task, so a host can tell
+     * a fact from a fault: `queue` when somebody chose these terms, `ungoverned` when nothing handed
+     * the work over, `undetermined` when a queue was named and its terms could not be read -- the
+     * provider then publishes what it will honour and says so here, where the controls are drawn.
+     */
+    capabilitySource: CapabilitySource;
     browsers: TaskBrowser[];
     /** The person or entity on the other end of this task. Who the task is with; `contacts` on the snapshot is the directory. */
     party?: Contact;

package/dist/index.js

@@ -68,6 +68,7 @@ export const DEFAULT_LEVELS = [
 export function effectiveLevels(declared) {
     return [...(declared ?? DEFAULT_LEVELS)];
 }
+export const CAPABILITY_SOURCES = ["queue", "ungoverned", "undetermined"];
 // ---------------------------------------------------------------------------
 // Task commands.
 // ---------------------------------------------------------------------------

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
@@ -301,6 +301,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 violations.push({ rule: "diagnostic.raised", path: "event.diagnostic",
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
+            violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
             if (eventDeclaresMute(envelope))
@@ -320,6 +321,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         const snapshot = await connection.snapshot();
         observeSnapshot(snapshot, seen);
         violations.push(...validateSnapshot(snapshot, adapter.manifest, "snapshot", reader()));
+        violations.push(...undeterminedTasks(Array.isArray(snapshot?.tasks) ? snapshot.tasks : [], "snapshot.tasks"));
         stream.seed(snapshot);
         breaks.seed(snapshot);
         seeded = true;
@@ -526,6 +528,28 @@ export function assertAuthenticationRestoreAndExpiry(states) {
         throw new Error("Refreshing state must occur before expiry");
     }
 }
+/** The tasks an envelope carries: the one a task event names, or a snapshot event's list. */
+function eventTasks(envelope) {
+    if (!isRecord(envelope) || !isRecord(envelope.event))
+        return [];
+    const event = envelope.event;
+    if (event.type === "task-offered" || event.type === "task-updated")
+        return [event.task];
+    if (event.type === "snapshot" && isRecord(event.snapshot) && Array.isArray(event.snapshot.tasks))
+        return event.snapshot.tasks;
+    return [];
+}
+/**
+ * A task published under `undetermined` terms is a fact to a host and a failure to a conformance
+ * run, as a diagnostic is: the platform under test could not say what it permits, and a green
+ * result must not paper over it.
+ */
+function undeterminedTasks(tasks, path) {
+    return tasks.flatMap((task, index) => isRecord(task) && task.capabilitySource === "undetermined"
+        ? [{ rule: "capabilitySource.undetermined", path: `${path}[${index}].capabilitySource`,
+                message: `task ${String(task.id)} was published under terms the provider could not determine` }]
+        : []);
+}
 /**
  * Capabilities are current, not fixed. A provider that withdraws one republishes `authenticated`
  * with the new set, and the next snapshot agrees with it. `states` is what the authentication
@@ -575,6 +599,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.
@@ -687,7 +759,7 @@ export class TaskStream {
                     stages.set(entry.dialId, entry.stage);
             }
         }
-        return { phase: String(isRecord(task) ? task.phase : undefined), media, stages };
+        return { phase: String(isRecord(task) ? task.phase : undefined), media, source: String(isRecord(task) ? task.capabilitySource : undefined), stages };
     }
     /** Replaces what is known with a snapshot's tasks, as a snapshot replaces Omni's state. */
     seed(snapshot) {
@@ -729,6 +801,12 @@ export class TaskStream {
                     refuse("stream.taskUpdated.unknown", `${at}.task.id`, `${id} was never offered or carried on a snapshot`);
                     break;
                 }
+                // Terms once read stay read. A re-read that fails is not a new fact about the task, so the
+                // last statement stands and the failure is a diagnostic; undetermined is a place a task
+                // starts from, never one it returns to.
+                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`);
+                }
                 if (known.media === "ended") {
                     const phase = isRecord(event.task) ? String(event.task.phase) : "";
                     if (phase !== "completing") {

package/dist/validation.js

@@ -41,6 +41,7 @@ const TASK_PHASES = membersOf({
     pending: true, confirmed: true, preview: true, "in-progress": true, paused: true, completing: true,
 });
 const COMPLETION_MODES = membersOf({ "agent-command": true, "provider-automatic": true });
+const CAPABILITY_SOURCES = membersOf({ queue: true, ungoverned: true, undetermined: true });
 const ACCEPTANCE_MODES = membersOf({
     "no-preference": true, "consent": true, "automatic": true,
 });
@@ -970,6 +971,9 @@ function validateTaskInto(task, context, path, into) {
     if (task.assisting !== undefined && task.monitoring !== undefined) {
         into.add("task.monitoring.assisting", `${path}.monitoring`, "a task is a joined call or a monitored one, never both");
     }
+    // Where the terms came from is stated with them: a host cannot tell "the platform permits
+    // nothing" from "the terms could not be read" from the set alone, and the provider knows which.
+    into.oneOf(task.capabilitySource, CAPABILITY_SOURCES, "task.capabilitySource", `${path}.capabilitySource`);
     const capabilities = task.capabilities;
     if (!isPlainObject(capabilities)) {
         into.add("task.capabilities.shape", `${path}.capabilities`, "a task needs a capabilities object");

package/guide.md

@@ -644,12 +644,15 @@ type Lockable<T> = T | Locked;
 
 type TaskMediaState = "started" | "ended";
 
+type CapabilitySource = "queue" | "ungoverned" | "undetermined";
+
 type Task<C extends Channel = Channel> = {
   id: TaskId;
   title: string;
   channel: C;
   taskType: string;
   capabilities: TaskCapabilities<C>;
+  capabilitySource: CapabilitySource;
   browsers: TaskBrowser[];
   party?: Contact;
   phase: TaskPhase;
@@ -2194,6 +2197,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. |
+| `capabilitySource` | Required. Who chose the capabilities: `queue` when somebody configured these terms, `ungoverned` when nothing handed the work over -- an agent's own outbound -- and `undetermined` when a queue was named and its terms could not be read, in which case `capabilities` is what the provider will honour, not what the platform permits. A host shows `undetermined` where the agent works. See **Task capabilities**. |
 | `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. |
@@ -2664,6 +2668,80 @@ 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 -- and says, in `capabilitySource`, who
+chose those terms. `queue` says somebody configured them. `ungoverned` says nothing handed the work
+over: an agent's own outbound call has no queue behind it, and the provider states what it permits
+for such a call. Neither changes where a host reads the capabilities from, which is the task; the
+source is one more published fact about them, and the one that lets a host tell a fact from a fault
+(see below).
+
+**Completing the task is not a capability, and no capability set withholds it.** `complete` is
+governed by `completionMode` alone: under `agent-command` it is always available, whatever the set
+says, and the `dispositions` capability decides only whether a code travels with it. Likewise
+Answer on a pending task and Call on a preview are the phase's controls, not the set's. The
+capability set governs what the agent may do *with* the task; disposing of it is never on the
+list.
+
+**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: {}` under `queue` or
+`ungoverned` says the platform permits nothing capability-gated on this task, and a host draws
+nothing beyond what the phase and `completionMode` require. 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, neither as `{}` nor as every control it has.
+It publishes the task under `capabilitySource: "undetermined"`, with the capabilities it will
+honour until it knows, and a host shows that where the agent works, beside the controls it draws
+from them: "no queue governs this call" is a fact, "the configuration has not arrived" is a fault,
+and the set alone cannot tell them apart, so the provider says which. What a provider honours
+under undetermined terms is its own call -- a floor that would rather an agent briefly hold a
+control the platform might not have granted than lose hold or hang-up mid-call over a slow
+configuration read publishes those -- and the protocol chooses no default set for it. The fault is
+also reported as a `diagnostic` naming the task, one per occurrence, so an operator counts it. When
+the terms arrive, the task is republished under `queue` with the set as it now stands: the same
+republish as any other permission that changed while the task was open. The move goes one way.
+Terms once read stay read: a re-read that fails mid-task is not a new fact about the task, so the
+last statement stands and the failure is a `diagnostic`, and a task that was published under
+`queue` or `ungoverned` never returns to `undetermined` (`stream.taskUpdated.capabilitySource`).
+
+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,
+and an agent working a call has no use for the name of the rule behind its buttons. Under
+`undetermined` the agent is told, beside the controls, that these are what the provider will honour
+until the queue's terms arrive, and that the controls may change when they do -- a statement about
+the buttons in front of them now, not about the provider, because that is what changes when the
+republish lands. The two words are close in English and far apart on the desk: `ungoverned` is
+silence, `undetermined` is a notice. `exerciseAdapter` treats a
+task published under `undetermined` as a violation (`capabilitySource.undetermined`), as it treats
+a diagnostic: a conformance run against a platform that cannot say what it permits fails loudly
+rather than passing with a note.
+
 ```ts
 const taskCapabilities = {
   channel: "voice",
@@ -4209,7 +4287,9 @@ agent works and keeps a count an operator can read, because a healthy workspace
 console is the silence problem one layer up. One event per occurrence; the host counts, the
 provider does not batch. `exerciseAdapter` treats a diagnostic delivered during a run as a
 violation (`diagnostic.raised`): a conformance run against a platform that is breaking its rules
-fails loudly rather than passing with a note.
+fails loudly rather than passing with a note. A task published under `capabilitySource:
+"undetermined"` is the same kind of fact, stated on the task instead, and fails a run the same way
+(`capabilitySource.undetermined`); see **Task capabilities**.
 
 | Field | Contract |
 | --- | --- |
@@ -4401,6 +4481,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.55",
+  "version": "0.1.57",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",