@xema/omni-protocol 0.1.68 → 0.1.70

package/dist/index.d.ts

@@ -1397,11 +1397,15 @@ export interface Snapshot<C extends Channel = Channel> {
 /**
  * How many tasks this provider may have allocated to the agent at once.
  *
- * An absolute ceiling, never less than 1, standing until Omni restates it. The provider counts
- * its own outstanding tasks against it and needs no new signal when one ends. What the agent
- * holds at other providers is not this provider's concern -- Omni set `count` knowing it.
+ * An absolute ceiling standing until Omni restates it. The provider counts its own outstanding
+ * tasks against it and needs no new signal when one ends. The agent is one person on several
+ * providers, and the host divides their capacity among them: `0` is host-stopped -- the agent's
+ * capacity is elsewhere for now, this provider allocates nothing and shows the member as
+ * `on-task` -- and is not a break, which is the agent not working at all. The host restates a
+ * count of one or more when this provider has the agent's capacity again.
  */
 export interface AgentCapacity {
+    /** A whole number, zero or more; zero is host-stopped. */
     count: number;
 }
 export interface SummaryMetric {
@@ -1507,10 +1511,24 @@ export interface ProviderEventEnvelope<C extends Channel = Channel> {
 }
 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];
+/**
+ * What the host refused, told to the adapter that published it: a snapshot the host would not
+ * replace its state with, or an event it dropped, and every rule it broke. A refusal the provider
+ * never hears of is a desk frozen at its last good state for a shift with nothing wrong on the
+ * provider's side; this is how both sides see it.
+ */
+export interface Refusal {
+    artefact: "snapshot" | "event";
+    /** The envelope refused, where the artefact is an event. */
+    envelopeId?: string;
+    violations: ProtocolViolation[];
+}
 export interface Connection<C extends Channel = Channel> {
     snapshot(): Snapshot<C> | Promise<Snapshot<C>>;
     /** Delivery order must match the order the provider observes changes. Never replay. */
     subscribe(listener: (envelope: ProviderEventEnvelope<C>) => void): Unsubscribe;
+    /** Told what the host refused, snapshot or event, with every rule broken. Always; a refusal is visible on both sides. */
+    refused(report: Refusal): void;
     /** Nothing may be allocated until a capacity is stated, so every connection receives it. */
     setCapacity(capacity: AgentCapacity): Promise<CapacityResult>;
     execute(request: TaskCommandRequest<C>): Promise<TaskCommandResult>;

package/dist/testing.js

@@ -292,6 +292,19 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         const connected = { ...context, host, store: watched.store };
         connection = await adapter.connect(connected);
         const live = connection;
+        // A refusal is visible on both sides: what the host would not take, the adapter is told, with the rules.
+        requireMethod(live, "refused", "every connection is told what the host refused");
+        const tellRefused = (report) => {
+            if (typeof live.refused !== "function")
+                return;
+            ruleEvaluated("connection.refused.rejected");
+            try {
+                live.refused(report);
+            }
+            catch (error) {
+                violations.push({ rule: "connection.refused.rejected", path: "connection.refused", message: `told of a refusal, the adapter threw: ${String(error)}` });
+            }
+        };
         // Dial is declared by presence: the capability object carries a destination policy rather
         // than an `enabled` flag, so its presence is the declaration.
         if (adapter.manifest.idleCapabilities?.dial !== undefined)
@@ -310,7 +323,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         const waiters = new Set();
         unsubscribe = connection.subscribe(envelope => {
             observeEvent(envelope, seen);
-            violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
+            const broken = validateEventEnvelope(envelope, adapter.manifest, "event", reader());
+            violations.push(...broken);
+            if (broken.length > 0)
+                tellRefused({ artefact: "event", envelopeId: typeof envelope?.id === "string" ? envelope.id : undefined, violations: broken });
             // A diagnostic is informational to a host and a failure to a conformance run: the platform
             // under test broke a rule the adapter relies on, and a green result must not paper over it.
             // A reload in life has no first connection: the page is gone. The drive keeps its first
@@ -361,7 +377,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         });
         const snapshot = await connection.snapshot();
         observeSnapshot(snapshot, seen);
-        violations.push(...validateSnapshot(snapshot, adapter.manifest, "snapshot", reader()));
+        {
+            const broken = validateSnapshot(snapshot, adapter.manifest, "snapshot", reader());
+            violations.push(...broken);
+            if (broken.length > 0)
+                tellRefused({ artefact: "snapshot", violations: broken });
+        }
         violations.push(...undeterminedTasks(Array.isArray(snapshot?.tasks) ? snapshot.tasks : [], "snapshot.tasks"));
         stream.seed(snapshot);
         breaks.seed(snapshot);
@@ -431,6 +452,26 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 context: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held, reloading,
             }));
         }
+        // Capacity supersedes rather than accumulates, so a decrease is as ordinary as an increase: the
+        // host raises it, lowers it, and takes it away, and the provider takes each as the ceiling it is.
+        // A provider whose ceiling can only rise passes a zero it special-cases and still cannot go from
+        // five to three, so the exercise moves the axis both ways. Zero is host-stopped: the agent's
+        // capacity is elsewhere, and the provider allocates nothing and refuses nothing for it. Any offer
+        // after a lower count is caught against it (stream.taskOffered.overCapacity).
+        ruleEvaluated("connection.setCapacity.lowered", "connection.setCapacity.zero");
+        for (const count of [2, 1, 0]) {
+            capacityStated = count;
+            const restated = await live.setCapacity({ count });
+            const shape = validateResult(restated, "setCapacity", "connection.setCapacity");
+            violations.push(...shape);
+            if (shape.length === 0 && restated.status === "failed") {
+                violations.push({ rule: count === 0 ? "connection.setCapacity.zero" : "connection.setCapacity.lowered", path: "connection.setCapacity",
+                    message: count === 0
+                        ? `the provider would not take a capacity of zero: ${restated.failure.code}; zero is host-stopped, the agent's capacity being elsewhere, and a provider allocates nothing and refuses nothing for it`
+                        : `the provider would not take a capacity of ${count} after a higher one: ${restated.failure.code}; capacity supersedes, and a decrease is as ordinary as an increase` });
+                break;
+            }
+        }
     }
     finally {
         let clean = true;

package/dist/validation.d.ts

@@ -64,6 +64,8 @@ export declare function validateEventEnvelope(envelope: unknown, manifest: unkno
  * phone the microphone is the phone's, and off voice there is none. Neither the value nor its
  * absence is inferred from what kind of application the host is.
  */
+/** What the host states as capacity: a whole number, zero or more, zero being host-stopped. */
+export declare function validateCapacity(capacity: unknown, path?: string): ProtocolViolation[];
 /** The login's store, which the host provides on every connection: three functions, and nothing else is a store. */
 export declare function validateLoginStore(store: unknown, path?: string): ProtocolViolation[];
 export declare function validateHostMute(mute: unknown, softphone: boolean, path?: string): ProtocolViolation[];

package/dist/validation.js

@@ -1700,6 +1700,16 @@ const HOST_MUTES = membersOf({ stream: true, station: true });
  * phone the microphone is the phone's, and off voice there is none. Neither the value nor its
  * absence is inferred from what kind of application the host is.
  */
+/** What the host states as capacity: a whole number, zero or more, zero being host-stopped. */
+export function validateCapacity(capacity, path = "capacity") {
+    const into = new Collector();
+    if (!isPlainObject(capacity)) {
+        into.add("capacity.shape", path, "a capacity is an object carrying count");
+        return into.violations;
+    }
+    into.require(typeof capacity.count === "number" && Number.isInteger(capacity.count) && capacity.count >= 0, "capacity.count", `${path}.count`, "count is a whole number, zero or more: how many tasks this provider may allocate at once, zero while the agent's capacity is elsewhere");
+    return into.violations;
+}
 /** The login's store, which the host provides on every connection: three functions, and nothing else is a store. */
 export function validateLoginStore(store, path = "store") {
     const into = new Collector();

package/guide.md

@@ -425,7 +425,7 @@ type Snapshot = {
 };
 
 type AgentCapacity = {
-  count: number; // absolute ceiling, at least 1
+  count: number; // absolute ceiling, zero or more; zero is host-stopped
 };
 
 type CapacityResult =
@@ -1066,9 +1066,16 @@ adapter compiled against the browser lib.
 ### Adapter and connection
 
 ```ts
+type Refusal = {
+  artefact: "snapshot" | "event";
+  envelopeId?: string;
+  violations: ProtocolViolation[];
+};
+
 type Connection<C extends Channel = Channel> = {
   snapshot(): Snapshot<C> | Promise<Snapshot<C>>;
   subscribe(listener: (envelope: ProviderEventEnvelope<C>) => void): Unsubscribe;
+  refused(report: Refusal): void;
   setCapacity(capacity: AgentCapacity): Promise<CapacityResult>;
   execute(request: TaskCommandRequest<C>): Promise<TaskCommandResult>;
   disconnect(): Promise<void>;
@@ -2028,6 +2035,7 @@ surface in one place, and what obliges an adapter to implement each one.
 | `snapshot()` | Always. |
 | `subscribe(listener)` | Always. |
 | `disconnect()` | Always. |
+| `refused(report)` | Always. The host tells the adapter what it would not take -- a snapshot it did not replace its state with, an event it dropped -- with every rule broken, so a refusal is visible on both sides. See **What the host does with what it refuses**. |
 | `setCapacity(capacity)` | Always. Nothing may be allocated until a capacity is stated, so there is no connection that does not receive it. |
 | `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability**. |
 | `describeUsers(ids)` | The adapter publishes any `UserId`: on `ImposedBreak.by`, a roster, or `handlingHistory[].by`. Each `User` carries its `timeZone` where the provider knows it. |
@@ -2358,9 +2366,10 @@ Reaching the instant is not itself a transition: the provider reports what it di
 
 **Drop both fields when the phase moves.** A provider that builds the `in-progress` task by
 spreading the `preview` one carries `previewEndsAt` and `atDeadline` with it, and the host refuses
-the update (`task.preview.deadline.unexpected`) while the provider's own state looks right: the
-desk hears nothing and the provider sees nothing wrong. The task past preview has no deadline to
-wait for, so it carries neither field.
+the update (`task.preview.deadline.unexpected`): the desk keeps the task as it last stood, and the
+provider is told through `refused` exactly which rule, so the state that looked right on its side
+is named on its side. The task past preview has no deadline to wait for, so it carries neither
+field.
 
 **A task is never its audio.** A voice task is the allocation: the call is offered when it is
 routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
@@ -3361,9 +3370,10 @@ hold applied. A `held` result would repeat the discriminant that travelled with
 
 States how many tasks this provider may have allocated to the agent **at once**.
 
-`count` is an absolute ceiling, not an increment and never less than 1. An agent's capacity is a
-property of the agent, not of the moment: it is stated when the agent is set up and restated only
-when it genuinely changes, which is a provisioning change rather than a task starting or ending.
+`count` is an absolute ceiling, not an increment, a whole number of zero or more
+(`capacity.count`). An agent's capacity is a property of the agent, not of the moment: it is
+stated when the agent is set up and restated only when it genuinely changes, which is a
+provisioning change rather than a task starting or ending -- with one exception below.
 
 **The provider counts its own outstanding tasks against it.** Allocate while you hold fewer than
 `count` tasks for this agent, and stop when you hold that many; when one of yours ends you have
@@ -3371,9 +3381,21 @@ room again and need no new signal to know it. Omni does not re-state capacity as
 go, and a provider that waits for it will stall.
 
 Your own tasks are the only ones you count. What the agent holds at other providers is not your
-concern — Omni set `count` knowing it.
-
-Capacity supersedes rather than accumulates: the latest value is the ceiling.
+concern — Omni set `count` knowing it, and this is how: the agent is one person on several
+providers, and the host divides their capacity among them rather than telling each the whole. A
+provider that has none of it for now is told **`count: 0`, host-stopped**: allocate nothing, show
+the member as `on-task` on the roster, since the agent is working, and take the next count as any
+other when the host has capacity for this provider again. Zero is not a refusal to state, and a
+provider that answers it `failed` is named (`connection.setCapacity.zero`); it is the one restatement
+that follows work rather than provisioning.
+
+Capacity supersedes rather than accumulates: the latest value is the ceiling, and a decrease is as
+ordinary as an increase. A provider whose ceiling can only rise -- one that keeps the highest count
+it was ever told, or returns early on a small one -- cannot be told to take less work, and a host
+taking capacity away is answered `applied` while the work keeps coming. The harness moves the axis
+both ways after the drive, two then one then nought, and names a provider that will not come down
+(`connection.setCapacity.lowered`, `connection.setCapacity.zero`); an offer after a lower count is
+caught against it (`stream.taskOffered.overCapacity`).
 
 **Capacity gates what the provider allocates, not what the agent starts.** A call placed from the
 idle dialpad arrives through `task-offered` like any other task, and a full agent does not forbid
@@ -3965,10 +3987,12 @@ anything to become available.
 | Omni commits a break | `commitBreak`. The break stops allocation, not the ceiling. |
 | Agent returns from break | `endBreak` |
 
-**Stopping is a break, not a capacity of zero.** Capacity says how much this agent can carry at
-once; a break says they are not working. Collapsing the two would leave a provider unable to tell
-an agent at their limit from an agent who has gone to lunch, and only one of those needs a reason,
-a decision and a return.
+**A break is not a capacity of zero, and neither is the reverse.** Capacity says how much of this
+agent this provider may carry; a break says they are not working at all. A provider told
+`count: 0` shows an agent whose capacity is elsewhere, `on-task`; a provider told a break shows
+`on-break`. Collapsing the two would leave a provider unable to tell an agent working on another
+provider from an agent who has gone to lunch, and only one of those needs a reason, a decision and
+a return.
 
 ### How the agent hears the call
 
@@ -4578,6 +4602,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `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. |
 | `validateHostMute(mute, softphone)` | What the host's Mute does, stated on a softphone login and nowhere else: `stream` or `station` (`host.mute`), required where the host holds a microphone (`host.mute.required`) and refused where it does not (`host.mute.unexpected`). The harness holds `ConnectContext.host.mute` to it. |
 | `validateLoginStore(store)` | The login's store the host hands every connection: an object with `get`, `set` and `delete` (`store.shape`, `store.get`, `.set`, `.delete`). The harness holds `ConnectContext.store` to it. |
+| `validateCapacity(capacity)` | What the host states as capacity: a whole number of zero or more (`capacity.count`), zero being host-stopped. The harness states one on connect and two, one and zero after the drive, and names a provider that will not come down (`connection.setCapacity.lowered`) or take zero (`connection.setCapacity.zero`). |
 | `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.*`, `command.phase.handling` for every control on the call or the conversation), 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. |
@@ -4605,6 +4630,25 @@ and may be compiled against a different protocol version, so its output is untru
 Validating a snapshot before it replaces provider state is what stops a malformed task from
 reaching the workspace.
 
+### What the host does with what it refuses
+
+A refusal has an aftermath on the desk and a report to the provider, and both are stated.
+
+- **A refused snapshot replaces nothing.** The host keeps the last state it took from this
+  provider whole, and shows the provider as faulted -- the transport as it stands, and the words
+  "last update refused" with the rule -- so the agent knows the view is standing still rather than
+  believing it current. It does not adopt the good half of a snapshot: a task the agent is on would
+  vanish from the desk while the call is up.
+- **A refused event is dropped and counted.** The state the host holds does not move for it. The
+  provider is told, and may republish a corrected state or raise a `diagnostic`; the host retries
+  nothing.
+- **The provider is told, every time.** `refused(report)` carries the artefact, the envelope id for
+  an event, and every violation with its rule and path. An adapter logs it at error and treats it as
+  its own defect until shown otherwise: what the host refused never reached the agent, and a
+  provider that hears nothing runs a whole shift beside a frozen desk with nothing wrong on its
+  side. The harness tells an adapter under test exactly as a host does
+  (`connection.refused.required`, `connection.refused.rejected`).
+
 ## Conformance helpers
 
 ### `exerciseAdapter(adapter, context, options?)`

package/package.json

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