@xema/omni-protocol 0.1.11 → 0.1.12

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/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 { 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,
     };
@@ -296,6 +422,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

@@ -3148,7 +3148,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 +3204,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
@@ -3225,6 +3234,7 @@ cannot be established from TypeScript structure alone.
 | --- | --- |
 | `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. |
+| `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.12",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",