@xema/omni-protocol 0.1.111 → 0.1.113

package/README.md

@@ -15,7 +15,7 @@ system.
 | `guide/` | One file per role and channel: `agent.md`, `lead.md`, `queue.md`, `breaks.md`, `phone.md`, `voice.md`, `chat.md`, `email.md`. Each points back into `guide.md` for what it relies on. |
 | `src/index.ts` | The TypeScript declarations. |
 | `src/validation.ts` | Runtime validators Omni applies to adapter output. |
-| `src/testing.ts` | Conformance helpers an adapter runs against its own test state. |
+| `src/testing.ts` | Testing an adapter an adapter runs against its own test state. |
 | `tests/` | One test file per source module, plus the guards over the guide and the repository's own text. |
 
 ## Entry points
@@ -23,7 +23,7 @@ system.
 ```ts
 import { defineAdapter } from "@xema/omni-protocol";
 import { validateSnapshot, assertNoViolations } from "@xema/omni-protocol/validation";
-import { exerciseAdapter } from "@xema/omni-protocol/testing";
+import { testAdapter } from "@xema/omni-protocol/testing";
 ```
 
 ## Validation is not only for tests
@@ -49,7 +49,7 @@ is reading, or what their login declares, from the snapshot alone. `validateTeam
 `validateSnapshot`, and `validateEventEnvelope` each take an optional final `{ self, capabilities }`
 from the `authenticated` state; given them, they report `team.member.self`, `team.request.self`,
 `team.required`, `team.unentitled`, `team.requests.capability`, and `team.requests.required`.
-Without them those rules are not checked. `exerciseAdapter` always passes both.
+Without them those rules are not checked. `testAdapter` always passes both.
 
 ```ts
 const { identity, capabilities } = authenticated;
@@ -58,17 +58,17 @@ validateSnapshot(snapshot, manifest, "snapshot", { self: identity.id, capabiliti
 
 ## Conformance
 
-`exerciseAdapter` validates the manifest, opens an authenticated session, connects, checks
+`testAdapter` 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. `result.notExercised` names what the run never reached — each
+then unsubscribes and disconnects. `result.notTested` names what the run never reached — each
 optional part of a task, of the break state and team member list, 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 context = { protocolVersion: OMNI_PROTOCOL_VERSION, loginId: "session-1", host: stillHost(report) };
-const result = await exerciseAdapter(adapter, context, { collectOnly: true });
+const result = await testAdapter(adapter, context, { collectOnly: true });
 expect(result.violations).toEqual([]);
 expect(result.disconnectWasClean).toBe(true);
 ```

package/dist/index.d.ts

@@ -1662,6 +1662,12 @@ export type HistoryReport = {
     ended?: never;
     seconds?: DurationSeconds;
 });
+/**
+ * `at` is the provider's instant for the leg, on its own clock, assigned when the provider writes
+ * the leg into its record and never an echo of the host's: the host keeps the answer as the leg's
+ * identity from then on, and names it on the closing report. A provider that echoes the host's
+ * instant has assigned nothing, and the test names it (`test.recordStep.identity`).
+ */
 export type HistoryReportResult = {
     status: "recorded";
     at: IsoTimestamp;

package/dist/testing.d.ts

@@ -26,32 +26,32 @@ export interface AdapterContractResult {
      * 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[];
+    notTested: readonly ContractSubject[];
     /** Every violation observed. Non-empty only when `collectOnly` suppressed the throw. */
     violations: readonly ProtocolViolation[];
     /**
      * Every rule the run evaluated, pass or fail: the validators' as each was applied, the stream's
-     * and the drive's as each case was considered. A rule absent here was never looked at, which a
+     * and the test's as each case was considered. A rule absent here was never looked at, which a
      * clean `violations` says nothing about; a test that needs a rule to have run asserts it here.
      */
-    rulesEvaluated: ReadonlySet<string>;
+    rulesTested: ReadonlySet<string>;
 }
-export interface ExerciseAdapterOptions {
+export interface TestAdapterOptions {
     /** Return violations in the result instead of throwing. Defaults to `false`. */
     collectOnly?: boolean;
     /**
-     * Drive one ordinary lifecycle on the first task the provider offers -- accept it, open its
+     * Test one ordinary lifecycle on the first task the provider offers -- accept it, open its
      * audio on a softphone, hold and resume where offered, end the call where offered, complete it
      * where the agent completes -- so the rules about a live call are reached rather than listed
-     * under `notExercised`. Off by default, since it issues commands against whatever platform the
+     * under `notTested`. Off by default, since it issues commands against whatever platform the
      * adapter is connected to: turn it on against a test backend.
      */
-    drive?: boolean;
-    /** How long the drive waits for each thing the provider owes it. Defaults to 5000. */
-    driveTimeoutMs?: number;
+    withCall?: boolean;
+    /** How long the test waits for each thing the provider owes it. Defaults to 5000. */
+    timeoutMs?: number;
     /**
      * Builds the adapter again, as a host reload does: a new object with no memory, for the same
-     * login. Given it, the drive -- once the host's muted leg is recorded -- connects a second adapter
+     * login. Given it, the test -- once the host's muted leg is recorded -- connects a second adapter
      * with the same context and the same store and expects its snapshot to carry the task with that
      * leg. A platform that holds the record hands it back; an adapter that composed the record in
      * memory has nothing, and is named. Without it the store is required and never read.
@@ -77,7 +77,7 @@ export interface ExerciseAdapterOptions {
  * for a synchronous emitter, and is swallowed as an unhandled rejection for an
  * asynchronous one — which would let a non-conforming async adapter pass.
  */
-export declare function exerciseAdapter<C extends Channel>(adapter: Adapter<C>, context: ConnectContext, options?: ExerciseAdapterOptions): Promise<AdapterContractResult>;
+export declare function testAdapter<C extends Channel>(adapter: Adapter<C>, context: ConnectContext, options?: TestAdapterOptions): Promise<AdapterContractResult>;
 /**
  * Validates restored authentication followed by a refresh failure or expiry. Every state is
  * validated, and a `refreshing` state must carry over the login it refreshes.
@@ -151,6 +151,14 @@ export declare class TaskStream {
     private readonly endedAssignments;
     /** Every assignment a `task-offered` introduced, as against one a snapshot carried: each is owed its ending. */
     private readonly offered;
+    /** The last seconds-left value the stream read per task and field, with the provider instant it was published at. */
+    private readonly countdowns;
+    /**
+     * A seconds-left value is the provider's arithmetic at the instant of the publication, never a
+     * value copied from an earlier one: between two publications the countdown loses at least the
+     * seconds the provider's own clock says passed, within a second of rounding.
+     */
+    private holdCountdowns;
     private readonly dials;
     /** The host placed a dial: its outcome, whenever it arrives, is one the stream expects. */
     dialled(dialId: string): void;
@@ -229,10 +237,10 @@ export declare function assertBreakFollowsItsRequests(envelopes: readonly Provid
  * follows the audio ending is `completing` or `task-ended`.
  */
 export declare function assertAudioFollowsTheTask(envelopes: readonly ProviderEventEnvelope[], snapshot?: Snapshot): void;
-/** A login store that lives in memory for the test: what most adapter tests hand `exerciseAdapter` as `context.store`. */
+/** A login store that lives in memory for the test: what most adapter tests hand `testAdapter` as `context.store`. */
 export declare function memoryStore(): LoginStore;
 /**
- * A host that reports one thing and never changes: what most adapter tests hand `exerciseAdapter`.
+ * A host that reports one thing and never changes: what most adapter tests hand `testAdapter`.
  * A softphone host states what its Mute does; a desk-phone or conversation host has no microphone and states nothing.
  */
 export declare function stillHost(report: HostReport, guarantees: HostGuarantees, mute: HostMute): Host & {