@xema/omni-protocol 0.1.11 → 0.1.13

package/README.md

@@ -58,7 +58,10 @@ validateSnapshot(snapshot, manifest, "snapshot", { self: identity.id, capabiliti
 `exerciseAdapter` validates the manifest, opens an authenticated session, connects, checks
 required capability methods, subscribes, validates the snapshot, every delivered event, and every
 authentication state published during the run — against the latest login — states a capacity,
-then unsubscribes and disconnects.
+then unsubscribes and disconnects. `result.notExercised` names what the run never reached — each
+optional part of a task, of the break state and roster, each contribution, each event type — so a
+clean result is read for what it covers and not for the whole contract; `assertReached(result,
+subjects)` is the paired assertion.
 
 ```ts
 const result = await exerciseAdapter(adapter, context, { collectOnly: true });

package/dist/index.d.ts

@@ -137,7 +137,11 @@ export interface AuthenticationFailure {
 }
 /** What a lead may do with their team. Declared by presence. */
 export interface TeamCapabilities {
-    /** This lead decides their team's breaks. Requires `executeTeamBreak`. */
+    /**
+     * This lead may act on their team's breaks through `executeTeamBreak` -- place, release, decide,
+     * set policy -- as far as the provider supports; a command it lacks answers
+     * `omni.capability-not-enabled`. Requires `executeTeamBreak`.
+     */
     breakControl?: true;
     /** This lead may join a member's call on request. Requires `executeTeamConsult`. */
     consultControl?: true;
@@ -998,6 +1002,13 @@ export interface BrowserSessionKeyInput {
     taskType: string;
     browser: TaskBrowser;
 }
+/**
+ * Whether two logins declare the same capabilities, field by field. The comparison an adapter
+ * makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
+ * guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
+ * not the thing being compared. Key order does not matter, and `team: {}` is not `team` absent.
+ */
+export declare function sameCapabilities(a: SessionCapabilities, b: SessionCapabilities): boolean;
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
  *

package/dist/index.js

@@ -128,6 +128,18 @@ export const HANDLING_STEPS_WITH_A_PERSON = [
 export function handlingStepExpectsAPerson(step) {
     return HANDLING_STEPS_WITH_A_PERSON.includes(step);
 }
+/**
+ * Whether two logins declare the same capabilities, field by field. The comparison an adapter
+ * makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
+ * guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
+ * not the thing being compared. Key order does not matter, and `team: {}` is not `team` absent.
+ */
+export function sameCapabilities(a, b) {
+    return a.breaks === b.breaks &&
+        (a.team === undefined) === (b.team === undefined) &&
+        a.team?.breakControl === b.team?.breakControl &&
+        a.team?.consultControl === b.team?.consultControl;
+}
 /**
  * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
  *

package/dist/testing.d.ts

@@ -1,6 +1,14 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Manifest } from "./index.js";
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type Manifest, type ProviderEvent } from "./index.js";
 import { type ProtocolViolation } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
+/**
+ * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
+ * a fixture without it exercises none of its rules and passes clean. One subject per family of
+ * rules -- each optional part of a task, each optional part of the break state and roster, each
+ * declared contribution, and each event type.
+ */
+declare const STATE_SUBJECTS: readonly ["tasks", "task.browsers", "task.attributes", "task.handlingHistory", "task.consultation", "task.lead", "task.assisting", "task.dispositions", "task.destinations", "task.custom", "break.reasons", "break.imposed", "team.members", "team.requests", "contacts", "scheduledActivities"];
+export type ContractSubject = (typeof STATE_SUBJECTS)[number] | `event.${ProviderEvent["type"]}`;
 export interface AdapterContractResult {
     events: ProviderEventEnvelope[];
     /** The state the session was restored with at sign-in. */
@@ -12,6 +20,13 @@ export interface AdapterContractResult {
     login: AuthenticationState;
     /** True only when every unsubscribe, `disconnect()`, and `close()` settled without throwing. */
     disconnectWasClean: boolean;
+    /**
+     * What the run never reached, and so what a clean `violations` says nothing about. Nothing here
+     * is a violation -- an adapter with no team has nothing to exercise -- but a fixture with no
+     * tasks exercises no task rule, and an adapter's own test asserts that the subjects it meant to
+     * reach are absent from this list.
+     */
+    notExercised: readonly ContractSubject[];
     /** Every violation observed. Non-empty only when `collectOnly` suppressed the throw. */
     violations: readonly ProtocolViolation[];
 }
@@ -59,6 +74,11 @@ export declare function assertCommandRefusedAfterWithdrawal(result: {
         code: string;
     };
 }): 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.
+ */
+export declare function assertReached(result: AdapterContractResult, subjects: readonly ContractSubject[]): void;
 /** Validates duplicate delivery and returns the event sequence Omni applies once per ID. */
 export declare function assertDuplicateEventDelivery<C extends Channel>(envelopes: readonly ProviderEventEnvelope<C>[]): ProviderEventEnvelope<C>[];
 /** Validates an authoritative reconnect snapshot containing assignments missed while offline. */

package/dist/testing.js

@@ -1,6 +1,128 @@
-import { browserSessionKey, } from "./index.js";
+import { browserSessionKey, sameCapabilities, } from "./index.js";
 import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateSnapshot, } from "./validation.js";
 export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
+/**
+ * A part of the contract a run may never reach: state nothing obliges an adapter to publish, so
+ * a fixture without it exercises none of its rules and passes clean. One subject per family of
+ * rules -- each optional part of a task, each optional part of the break state and roster, each
+ * declared contribution, and each event type.
+ */
+const STATE_SUBJECTS = [
+    "tasks",
+    "task.browsers",
+    "task.attributes",
+    "task.handlingHistory",
+    "task.consultation",
+    "task.lead",
+    "task.assisting",
+    "task.dispositions",
+    "task.destinations",
+    "task.custom",
+    "break.reasons",
+    "break.imposed",
+    "team.members",
+    "team.requests",
+    "contacts",
+    "scheduledActivities",
+];
+// Pinned to the event union the way validation pins its closed sets: a type added to
+// `ProviderEvent` without a row here, or a row it lacks, is a compile error.
+const EVENT_TYPES = {
+    snapshot: true, "provider-status": true, "break-state": true, "task-offered": true, "task-updated": true,
+    "task-media-ended": true, "task-ended": true, announcement: true, "provider-summary": true,
+    "team-updated": true, "contacts-updated": true, "calendar-updated": true,
+};
+const CONTRACT_SUBJECTS = [
+    ...STATE_SUBJECTS,
+    ...Object.keys(EVENT_TYPES).map(type => `event.${type}`),
+];
+// What the run observed. The input is untrusted and has already been reported on, so nothing
+// here assumes its shape; a subject is reached only by something the element rules would see.
+const isRecord = (value) => typeof value === "object" && value !== null;
+const some = (value) => Array.isArray(value) && value.length > 0;
+function observeTask(value, seen) {
+    if (!isRecord(value))
+        return;
+    seen.add("tasks");
+    if (some(value.browsers))
+        seen.add("task.browsers");
+    if (some(value.attributes))
+        seen.add("task.attributes");
+    if (some(value.handlingHistory))
+        seen.add("task.handlingHistory");
+    if (value.consultation !== undefined)
+        seen.add("task.consultation");
+    if (value.lead !== undefined)
+        seen.add("task.lead");
+    if (value.assisting !== undefined)
+        seen.add("task.assisting");
+    const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
+    if (isRecord(capabilities.dispositions))
+        seen.add("task.dispositions");
+    if (isRecord(capabilities.blindTransfer) && some(capabilities.blindTransfer.destinations))
+        seen.add("task.destinations");
+    if (some(capabilities.custom))
+        seen.add("task.custom");
+}
+function observeBreak(value, seen) {
+    if (!isRecord(value))
+        return;
+    if (some(value.reasons))
+        seen.add("break.reasons");
+    if (value.imposed !== undefined)
+        seen.add("break.imposed");
+}
+function observeTeam(value, seen) {
+    if (!isRecord(value))
+        return;
+    if (some(value.members))
+        seen.add("team.members");
+    if (some(value.requests))
+        seen.add("team.requests");
+}
+function observeSnapshot(value, seen) {
+    if (!isRecord(value))
+        return;
+    if (Array.isArray(value.tasks))
+        value.tasks.forEach(task => observeTask(task, seen));
+    observeBreak(value.break, seen);
+    observeTeam(value.team, seen);
+    if (some(value.contacts))
+        seen.add("contacts");
+    if (some(value.scheduledActivities))
+        seen.add("scheduledActivities");
+}
+function observeEvent(envelope, seen) {
+    const event = isRecord(envelope) ? envelope.event : undefined;
+    if (!isRecord(event))
+        return;
+    if (typeof event.type === "string" && event.type in EVENT_TYPES)
+        seen.add(`event.${event.type}`);
+    switch (event.type) {
+        case "snapshot":
+            observeSnapshot(event.snapshot, seen);
+            break;
+        case "break-state":
+            observeBreak(event.break, seen);
+            break;
+        case "task-offered":
+        case "task-updated":
+            observeTask(event.task, seen);
+            break;
+        case "team-updated":
+            observeTeam(event.team, seen);
+            break;
+        case "contacts-updated":
+            if (some(event.contacts))
+                seen.add("contacts");
+            break;
+        case "calendar-updated":
+            if (some(event.scheduledActivities))
+                seen.add("scheduledActivities");
+            break;
+        default: break;
+    }
+}
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,
  * connects, checks that every method the declarations require is implemented, subscribes,
@@ -16,6 +138,7 @@ export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
 export async function exerciseAdapter(adapter, context, options = {}) {
     const violations = [...validateManifest(adapter.manifest)];
     const events = [];
+    const seen = new Set();
     const storedSecrets = new Map();
     const authentication = await adapter.createAuthenticationSession({
         ...context,
@@ -104,6 +227,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             requireMethod(live, "openMedia", "the manifest channel is voice");
         const eventIds = new Set();
         unsubscribe = connection.subscribe(envelope => {
+            observeEvent(envelope, seen);
             violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
@@ -113,6 +237,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             events.push(envelope);
         });
         const snapshot = await connection.snapshot();
+        observeSnapshot(snapshot, seen);
         violations.push(...validateSnapshot(snapshot, adapter.manifest, "snapshot", reader()));
         requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot))
@@ -169,6 +294,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         events: events,
         authenticationState: authenticationState,
         login: (login ?? authenticationState),
+        notExercised: CONTRACT_SUBJECTS.filter(subject => !seen.has(subject)),
         disconnectWasClean,
         violations,
     };
@@ -187,10 +313,6 @@ function publishesUserIds(snapshot) {
         return false;
     return snapshot.tasks.some(task => Array.isArray(task?.handlingHistory) && task.handlingHistory.some(step => step?.by !== undefined));
 }
-const sameCapabilities = (a, b) => a.breaks === b.breaks &&
-    (a.team === undefined) === (b.team === undefined) &&
-    a.team?.breakControl === b.team?.breakControl &&
-    a.team?.consultControl === b.team?.consultControl;
 /**
  * `refreshing` carries the identity and capabilities of the login it refreshes. A change to
  * either is published as `authenticated`; a different identity is a new login.
@@ -296,6 +418,16 @@ export function assertCommandRefusedAfterWithdrawal(result) {
         throw new Error(`A command after its capability was withdrawn fails with omni.capability-not-enabled, not ${result.failure?.code}`);
     }
 }
+/**
+ * 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.
+ */
+export function assertReached(result, subjects) {
+    const missed = subjects.filter(subject => result.notExercised.includes(subject));
+    if (missed.length > 0) {
+        throw new Error(`The exercise never reached ${missed.join(", ")}: its clean result says nothing about them`);
+    }
+}
 /** Validates duplicate delivery and returns the event sequence Omni applies once per ID. */
 export function assertDuplicateEventDelivery(envelopes) {
     const byId = new Map();

package/dist/validation.js

@@ -811,6 +811,15 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     // Presence is the permission, and it cuts both ways: data a provider never declared a
     // capability for is data Omni would show against a control the agent does not have.
     const idle = isPlainObject(manifest) && isPlainObject(manifest.idleCapabilities) ? manifest.idleCapabilities : {};
+    // And it cuts the other way too: a declared contribution is required, `[]` included. A snapshot
+    // that omits one the manifest declares has not cleared it, it has said nothing, and Omni would
+    // go on showing whatever it held.
+    if (snapshot.contacts === undefined && idle.contacts === true) {
+        into.add("snapshot.contacts.required", `${path}.contacts`, "the manifest declares contacts, so every snapshot carries the contribution: [] when there are none");
+    }
+    if (snapshot.scheduledActivities === undefined && idle.calendar === true) {
+        into.add("snapshot.calendar.required", `${path}.scheduledActivities`, "the manifest declares calendar, so every snapshot carries the contribution: [] when there are none");
+    }
     if (snapshot.contacts !== undefined) {
         into.require(idle.contacts === true, "snapshot.contacts.capability", `${path}.contacts`, "contacts require the contacts idle capability");
         if (Array.isArray(snapshot.contacts)) {

package/guide.md

@@ -1352,7 +1352,7 @@ them from what arrives later.
 | --- | --- |
 | `breaks` | This login may request a break. Requires the four break methods on the connection. |
 | `team` | This login leads a team. The provider publishes a `TeamRoster` to it on every snapshot — `[]` when nobody is in it — and to nobody else. |
-| `team.breakControl` | This lead decides their team's breaks. Requires `executeTeamBreak`. |
+| `team.breakControl` | This lead may act on their team's breaks through `executeTeamBreak` — place, release, decide, set policy — as far as the provider supports; a command it lacks answers `omni.capability-not-enabled`. Omni asks for a decision only against a member whose `break` is `awaiting-decision`, so a provider that grants on request is never asked to decide. Requires `executeTeamBreak`. |
 | `team.consultControl` | This lead may join a member's call on request. Requires `executeTeamConsult`. |
 
 A session action is available only when both the capability and Omni provisioning permit it.
@@ -1366,7 +1366,10 @@ roster arrives, and nothing for anybody else — and withdraws it on the next re
 capability goes. A command that arrives after its capability was withdrawn is answered `failed`
 with `omni.capability-not-enabled`: the provider names it, so Omni never has to infer from a
 capability change it may not have rendered yet that "you are no longer a lead" is the message
-rather than "that did not work".
+rather than "that did not work". One trap for adapter authors: the natural guard on a republish
+compares the identity, and a demotion does not touch it — compare the capabilities, field by
+field, which is what `sameCapabilities()` does. The thing that changed is not the thing you are
+comparing, and `assertCapabilityWithdrawal` is the test that catches a guard which never fires.
 
 ### Starting authentication
 
@@ -3138,6 +3141,12 @@ Use it for every `UserId` — `handlingHistory[].by`, roster members, `memberId`
 lead command, `ImposedBreak.by`. A bare one is only ever compared against another from the **same** provider; anything
 wider goes through this key.
 
+### `sameCapabilities(a, b)`
+
+Whether two logins declare the same capabilities, field by field — key order aside, and with
+`team: {}` distinct from `team` absent. It is the comparison an adapter makes before republishing
+`authenticated`, and the one `exerciseAdapter` holds `refreshing` to.
+
 ## Runtime validation
 
 Structural rules in this document are executable through the runtime validators Omni applies to
@@ -3148,7 +3157,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | --- | --- |
 | `validateManifest(manifest)` | Identity, protocol-version interoperability, authentication methods, and idle-capability shapes. |
 | `validateTask(task, { channel })` | Identity, channel agreement, phase, completion allowance, capability shapes, custom controls, and browsers. |
-| `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, and every task, contact, and activity, including idle-capability gating. |
+| `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, and every task, contact, and activity, including idle-capability gating both ways: a contribution the manifest never declared is refused, and one it declares is required, `[]` included. |
 | `validateEventEnvelope(envelope, manifest)` | Envelope identity, timestamp, and the payload for each event type. |
 | `validateContact(contact)` | Contact field shapes and attribute keys. Every field is optional, so this checks what is present rather than what is missing. |
 | `validateScheduledActivity(activity)` | Required activity fields and start/end ordering. |
@@ -3204,6 +3213,15 @@ latest the session published during the run, which differs only when the adapter
 `authentication.refreshing.identity`, a changed capability set `authentication.refreshing.capabilities`.
 A capability granted by a later login requires its methods just as one declared at sign-in does.
 
+`result.notExercised` lists what the run never reached — one subject per family of rules: each
+optional part of a task (`task.browsers`, `task.handlingHistory`, `task.lead`, …), the break's
+`reasons` and `imposed`, the roster's `members` and `requests`, each declared contribution, and
+each event type (`event.task-ended`, …) — and so what a clean `violations` says nothing about.
+Nothing there is a violation: an adapter with no team has nothing to exercise. But a fixture with
+no tasks exercises no task rule, and a pass over it reads as coverage it is not.
+`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.
+
 Three properties of the harness matter to adapter authors:
 
 - **Violations are collected, never thrown from inside the subscribe listener.** Throwing there
@@ -3224,7 +3242,8 @@ 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. |
-| `assertCommandRefusedAfterWithdrawal(result)` | A command that arrives after its capability was withdrawn fails with `omni.capability-not-enabled`, named by the provider. |
+| `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. |
 | `assertReconnectWithMissedAssignments(before, reconnect, ids)` | A reconnect snapshot restores assignments received while offline. |
 | `assertDeniedAndRetriedBreak(states)` | A denial transitions directly to `not-requested`; a later request can still be granted. |

package/package.json

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