@xema/omni-protocol 0.1.69 → 0.1.71

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 {

package/dist/testing.js

@@ -168,8 +168,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         set: async (key, value) => { storedSecrets.set(key, value); },
         delete: async (key) => { storedSecrets.delete(key); },
     };
-    const authentication = await adapter.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
+    let authentication = await adapter.createAuthenticationSession({ ...context, secrets: authenticationSecrets });
     let connection;
+    /** Whether the run holds a client at all: false between a reload's first client going down and its second standing, and after a reload that failed. */
+    let clientLive = true;
     let unsubscribe;
     let unsubscribeAuthentication;
     let unsubscribeHost;
@@ -318,10 +320,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             requireMethod(live, "recordStep", "the login is on a softphone, whose microphone the host mutes");
         const eventPayloads = new Map();
         let capacityStated;
-        const reloading = { now: false };
         // The drive waits on events: each waiter is offered every envelope as it lands.
         const waiters = new Set();
-        unsubscribe = connection.subscribe(envelope => {
+        const onEnvelope = (envelope) => {
             observeEvent(envelope, seen);
             const broken = validateEventEnvelope(envelope, adapter.manifest, "event", reader());
             violations.push(...broken);
@@ -334,7 +335,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             // client pushes it to the old one too, and an adapter that calls a re-offer of answered work a
             // defect is right to. That diagnostic is the drive's own artefact, and is not counted while the
             // second adapter is up; every other moment it is.
-            if (isRecord(envelope?.event) && envelope.event.type === "diagnostic" && !reloading.now) {
+            if (isRecord(envelope?.event) && envelope.event.type === "diagnostic") {
                 violations.push({ rule: "diagnostic.raised", path: "event.diagnostic",
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
@@ -374,7 +375,45 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             events.push(envelope);
             for (const waiter of waiters)
                 waiter(envelope);
-        });
+        };
+        unsubscribe = connection.subscribe(onEnvelope);
+        // A host reload is the first client dying and a second coming up in its place. The drive hands
+        // the run over: the first connection is unsubscribed, disconnected and its session closed before
+        // the second connects, and the run continues on the second -- so there is no first client for a
+        // platform to push the open task back to, and nothing to exempt.
+        const handOver = {
+            isLive: () => clientLive,
+            down: async () => {
+                let clean = true;
+                try {
+                    unsubscribe?.();
+                }
+                catch {
+                    clean = false;
+                }
+                unsubscribe = undefined;
+                try {
+                    await connection?.disconnect();
+                }
+                catch {
+                    clean = false;
+                }
+                try {
+                    await authentication.close();
+                }
+                catch {
+                    clean = false;
+                }
+                clientLive = false;
+                return clean;
+            },
+            up: (session, second) => {
+                authentication = session;
+                connection = second;
+                unsubscribe = second.subscribe(onEnvelope);
+                clientLive = true;
+            },
+        };
         const snapshot = await connection.snapshot();
         observeSnapshot(snapshot, seen);
         {
@@ -449,9 +488,30 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             violations.push(...await driveOneCall({
                 connection: live, manifest: adapter.manifest, channel: adapter.manifest.channel, softphone, snapshot, events, waiters, stream, localAudio,
                 timeoutMs: options.driveTimeoutMs ?? 5000,
-                context: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held, reloading,
+                context: connected, secrets: authenticationSecrets, reader, rebuild: options.rebuild, held: watched.held, handOver,
+                streams: { stream, breaks },
             }));
         }
+        // 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 clientLive ? [2, 1, 0] : []) {
+            capacityStated = count;
+            const restated = await connection.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;
@@ -473,17 +533,20 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         catch {
             clean = false;
         }
-        try {
-            await connection?.disconnect();
-        }
-        catch {
-            clean = false;
-        }
-        try {
-            await authentication.close();
-        }
-        catch {
-            clean = false;
+        // A run whose reload took the first client down and stood no second holds nothing to close.
+        if (clientLive) {
+            try {
+                await connection?.disconnect();
+            }
+            catch {
+                clean = false;
+            }
+            try {
+                await authentication.close();
+            }
+            catch {
+                clean = false;
+            }
         }
         disconnectWasClean = clean;
     }
@@ -1169,7 +1232,7 @@ async function driveOneCall(drive) {
         drive.waiters.add(waiter);
     });
     const recordSurvivesReload = async (at) => {
-        ruleEvaluated("drive.reload.rejected", "drive.reload.manifest", "drive.reload.login", "drive.reload.snapshot", "drive.reload.allocation", "drive.reload.history");
+        ruleEvaluated("drive.reload.rejected", "drive.reload.manifest", "drive.reload.login", "drive.reload.snapshot", "drive.reload.allocation", "drive.reload.history", "drive.reload.handover");
         let again;
         try {
             again = drive.rebuild();
@@ -1178,16 +1241,17 @@ async function driveOneCall(drive) {
             refuse("drive.reload.rejected", "drive.reload", `building the adapter again threw: ${String(error)}`);
             return;
         }
-        let session;
-        let second;
+        // The same provider, built again: a different manifest is a different adapter, and proves nothing about this one.
+        if (again.manifest.id !== drive.manifest.id) {
+            refuse("drive.reload.manifest", "drive.reload.manifest", `rebuild returned an adapter for ${String(again.manifest.id)}; the reload is of ${String(drive.manifest.id)}`);
+            return;
+        }
+        // The first client dies first, as it does on a reload: from here the run has no connection until the second stands.
+        if (!await drive.handOver.down()) {
+            refuse("drive.reload.handover", "drive.reload", "taking the first client down threw: an unsubscribe, disconnect() or close() failed");
+        }
         try {
-            // The same provider, built again: a different manifest is a different adapter, and proves nothing about this one.
-            if (again.manifest.id !== drive.manifest.id) {
-                refuse("drive.reload.manifest", "drive.reload.manifest", `rebuild returned an adapter for ${String(again.manifest.id)}; the reload is of ${String(drive.manifest.id)}`);
-                return;
-            }
-            drive.reloading.now = true;
-            session = await again.createAuthenticationSession({ ...drive.context, secrets: drive.secrets });
+            const session = await again.createAuthenticationSession({ ...drive.context, secrets: drive.secrets });
             // The reload is a restore before it is anything else: the second session stands authenticated
             // as the same person, from the secrets alone, or nothing it reads afterwards is this login's.
             const restored = await session.state();
@@ -1195,12 +1259,22 @@ async function driveOneCall(drive) {
             const same = isRecord(restored) && restored.status === "authenticated" && isRecord(restored.identity) && restored.identity.id === drive.reader().self;
             if (!same) {
                 refuse("drive.reload.login", "drive.reload.login", `a second adapter built from the same login and secrets did not restore it: the session says ${String(isRecord(restored) ? restored.status : restored)}${isRecord(restored) && isRecord(restored.identity) ? ` as ${String(restored.identity.id)}` : ""}, and the login is ${String(drive.reader().self)}`);
+                // A reload that cannot restore the login is a sign-in screen, not a connection: the run ends here.
+                try {
+                    await session.close();
+                }
+                catch { /* the session that would not restore is closed as far as it can be */ }
                 return;
             }
-            second = await again.connect(drive.context);
+            const second = await again.connect(drive.context);
+            // From here the second client is the run's connection: what it publishes is validated as before.
+            drive.handOver.up(session, second);
+            drive.connection = second;
             const snapshot = await second.snapshot();
-            // The second adapter's snapshot is held to everything a first one is.
+            // The second adapter's snapshot is held to everything a first one is, and the streams take it as the state now.
             found.push(...validateSnapshot(snapshot, again.manifest, "drive.reload.snapshot", drive.reader()));
+            drive.streams.stream.seed(snapshot);
+            drive.streams.breaks.seed(snapshot);
             const carried = isRecord(snapshot) && Array.isArray(snapshot.tasks)
                 ? snapshot.tasks.find(task => isRecord(task) && task.id === taskId) : undefined;
             if (carried === undefined) {
@@ -1228,25 +1302,12 @@ async function driveOneCall(drive) {
             else if (leg.mutedBy !== "host") {
                 refuse("drive.reload.history", "drive.reload.history", `the reloaded record's muted leg at ${at} says mutedBy ${String(leg.mutedBy)}; the host reported host`);
             }
+            // The drive goes on with the task as the reloaded client holds it.
+            task = carried;
         }
         catch (error) {
             refuse("drive.reload.rejected", "drive.reload", `the second adapter rejected rather than answered: ${String(error)}`);
         }
-        finally {
-            try {
-                await second?.disconnect();
-            }
-            catch (error) {
-                refuse("drive.reload.rejected", "drive.reload", `the second adapter's disconnect threw: ${String(error)}`);
-            }
-            try {
-                await session?.close();
-            }
-            catch (error) {
-                refuse("drive.reload.rejected", "drive.reload", `the second adapter's session threw on close: ${String(error)}`);
-            }
-            drive.reloading.now = false;
-        }
     };
     // A task's keys are gone with the task. A task-scoped key carries the task id, so the watched
     // store says which keys were the task's; one still held after task-ended is a key about to be
@@ -1438,8 +1499,12 @@ async function driveOneCall(drive) {
         // 3c. A host reload destroys the adapter object and keeps the login's store. Built again from
         // the same login, a second adapter carries the task and the leg -- from its platform, or from
         // the store -- or it composed the record in memory and the record died with it.
-        if (drive.rebuild !== undefined)
+        if (drive.rebuild !== undefined) {
             await recordSurvivesReload(at);
+            // A reload that stood no client ends the run: there is nothing left to drive.
+            if (!drive.handOver.isLive())
+                return found;
+        }
     }
     // 4. Hold and resume, where offered.
     if (latestTask().phase === "in-progress" && offers("hold")) {

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 =
@@ -3370,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
@@ -3380,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
@@ -3974,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
 
@@ -4587,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. |
@@ -4625,7 +4641,9 @@ A refusal has an aftermath on the desk and a report to the provider, and both ar
   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.
+  nothing. The desk shows nothing for it: the view kept moving for every other event, so "last
+  update refused" would be false of it, and a chip that said nothing would be right about the
+  transport. Counted, and the provider told, is all a host can truthfully do for one event.
 - **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
@@ -4694,15 +4712,19 @@ the drive mutes it for one second and reports the leg through `recordStep`, begu
 expecting each report `recorded` (`drive.recordStep.failed`, `.rejected`); and where the provider
 restates the task's record afterwards, the leg is in it or the hole is named
 (`drive.recordStep.history`). Given `rebuild`, a way to build the adapter again as a host reload
-does, the drive then connects a second adapter for the same login with the same context and the
-same `store`, and expects its snapshot to carry the task with that leg and the host's word: a
-platform that holds the record hands it back, and an adapter that composed the record in memory
-has nothing and is named (`drive.reload.snapshot`, `drive.reload.history`, `.rejected`). The second
-adapter is held to what the first was: the same provider (`drive.reload.manifest`), a snapshot that
-stands as any snapshot must, and a record that lost none of the entries the first had published --
-a record once read is not unread across a reload either. A reconnect on the same adapter object
-would prove nothing, since an in-process adapter's memory survives it; only a second object
-separates kept-in-the-store from never-lost. The second adapter opens its session from the same
+does, the drive reloads the host as a reload happens: the first client is unsubscribed,
+disconnected and its session closed (`drive.reload.handover`), and only then is a second adapter
+built and connected for the same login with the same context and the same `store`; its snapshot
+must carry the task with that leg and the host's word, and the run goes on with the second as its
+connection to the end. A platform that holds the record hands it back, and an adapter that composed
+the record in memory has nothing and is named (`drive.reload.snapshot`, `drive.reload.history`,
+`.rejected`). The second adapter is held to what the first was: the same provider
+(`drive.reload.manifest`), a snapshot that stands as any snapshot must, and a record that lost none
+of the entries the first had published -- a record once read is not unread across a reload either.
+A reconnect on the same adapter object would prove nothing, since an in-process adapter's memory
+survives it; only a second object separates kept-in-the-store from never-lost. And because the
+first client is gone before the second connects, there is no client for the platform to push the
+open task back to, and nothing about the reload is exempt from any rule. The second adapter opens its session from the same
 `secrets`, so the reload is a restore before it is anything else: an adapter that holds a session
 has already put what would rebuild it into the secrets store, from the moment it was handed one,
 not only when a flow completes -- the session is the adapter's, the store is the host's, and a

package/package.json

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