@xema/omni-protocol 0.1.14 → 0.1.15

package/README.md

@@ -30,7 +30,8 @@ An adapter is loaded from a separate package and may be compiled against a diffe
 version, so its output is untrusted input. Every validator takes `unknown` and returns every
 violation it found rather than throwing on the first, so a caller reports all of them at once.
 Validating a snapshot before it replaces provider state is what stops a malformed task reaching
-the agent's workspace.
+the agent's workspace; validating a result with `validateResult(result, method)` before acting on
+it is what stops a status the host does not know being shown as an outcome.
 
 ```ts
 const violations = validateSnapshot(snapshot, manifest);

package/dist/testing.js

@@ -1,5 +1,5 @@
 import { browserSessionKey, sameCapabilities, } from "./index.js";
-import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateSnapshot, } from "./validation.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateResult, 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
@@ -245,7 +245,10 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         // Capacity is stated, not requested: nothing may be allocated until it is, so a connection
         // that will not accept one is a connection nothing can be given to.
         const capacity = await connection.setCapacity({ count: 1 });
-        if (capacity.status === "failed") {
+        const malformed = validateResult(capacity, "setCapacity", "connection.setCapacity");
+        violations.push(...malformed);
+        // A refusal is read only from a result that has the shape of one.
+        if (malformed.length === 0 && capacity.status === "failed") {
             violations.push({
                 rule: "connection.setCapacity.failed",
                 path: "connection.setCapacity",

package/dist/validation.d.ts

@@ -34,4 +34,13 @@ export interface ReaderContext {
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateEventEnvelope(envelope: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
+/** The connection methods whose results `validateResult` knows. */
+export type ResultMethod = "execute" | "dial" | "setCapacity" | "requestBreak" | "commitBreak" | "cancelBreak" | "endBreak" | "executeTeamBreak" | "executeTeamConsult" | "openMedia";
+/**
+ * Validates what a connection method answered. A result is untrusted for the same reason a
+ * snapshot is: it comes from an adapter that may be compiled against another version, and Omni
+ * shows the agent what it says. A status the method does not answer, a failure status without a
+ * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
+ */
+export declare function validateResult(result: unknown, method: ResultMethod, path?: string): ProtocolViolation[];
 export declare function validateAuthenticationState(state: unknown, path?: string): ProtocolViolation[];

package/dist/validation.js

@@ -9,7 +9,7 @@
 // Each list is pinned to its type both ways -- a member the type lacks, or a member the list
 // lacks, fails to compile -- so what the validators accept cannot drift from what the
 // declarations say.
-import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, } from "./index.js";
+import { ALLOWED_BROWSER_URL_SCHEMES, BREAK_KINDS, BROWSER_ISOLATION_SCHEMES, IDLE_CAPABILITIES, OMNI_FAILURE_CODES, OMNI_SUPPORTED_PROTOCOL_VERSIONS, negotiateProtocolVersion, } from "./index.js";
 export class ProtocolConformanceError extends Error {
     violations;
     constructor(violations, summary = "Adapter violates the Omni protocol") {
@@ -895,9 +895,7 @@ function validateTaskOutcome(value, path, into) {
                 into.add("event.taskEnded.outcome.failed", `${path}.failure`, "a failed outcome must carry a failure");
             }
             else {
-                into.filled(value.failure.code, "failure.code", `${path}.failure.code`, "a failure needs a code");
-                into.filled(value.failure.message, "failure.message", `${path}.failure.message`, "a failure needs a message");
-                into.require(typeof value.failure.retryable === "boolean", "failure.retryable", `${path}.failure.retryable`, "a failure must say whether it is retryable");
+                validateFailureInto(value.failure, `${path}.failure`, into);
             }
             break;
         default:
@@ -1019,6 +1017,75 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
     return into.violations;
 }
 // ---------------------------------------------------------------------------
+// Results. A result crosses the same boundary a snapshot does, from an adapter that may be
+// compiled against another version, and Omni shows the agent what it says.
+// ---------------------------------------------------------------------------
+/** A `ProtocolFailure`, wherever one appears: on a result, or on a task's failed outcome. */
+function validateFailureInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("failure.shape", path, "a failure must be an object");
+        return;
+    }
+    if (into.filled(value.code, "failure.code", `${path}.code`, "a failure needs a code")) {
+        // A provider names its own codes freely; the `omni.` namespace is the contract's, and a code
+        // in it that the contract lacks is one Omni would show without knowing what it means.
+        if (value.code.startsWith("omni.")) {
+            into.require(OMNI_FAILURE_CODES.includes(value.code), "failure.code.unknown", `${path}.code`, `not a contract failure code: ${value.code}`);
+        }
+    }
+    into.filled(value.message, "failure.message", `${path}.message`, "a failure needs a message");
+    into.require(typeof value.retryable === "boolean", "failure.retryable", `${path}.retryable`, "a failure must say whether it is retryable");
+    if (value.retryAfterMs !== undefined) {
+        into.require(typeof value.retryAfterMs === "number" && Number.isFinite(value.retryAfterMs) && value.retryAfterMs >= 0, "failure.retryAfterMs", `${path}.retryAfterMs`, "retryAfterMs must be a non-negative number when present");
+    }
+}
+// Pinned to the result unions: each method's one success status, and the status that carries a
+// failure. A method added to `Connection` without a row here is a compile error at the call site.
+const RESULT_STATUSES = {
+    execute: { success: "applied", failure: "failed" },
+    dial: { success: "dialled", failure: "failed" },
+    setCapacity: { success: "accepted", failure: "failed" },
+    requestBreak: { success: "requested", failure: "failed" },
+    commitBreak: { success: "committed", failure: "failed" },
+    cancelBreak: { success: "cancelled", failure: "failed" },
+    endBreak: { success: "ended", failure: "failed" },
+    executeTeamBreak: { success: "applied", failure: "failed" },
+    executeTeamConsult: { success: "applied", failure: "failed" },
+    openMedia: { success: "opened", failure: "unavailable" },
+};
+/**
+ * Validates what a connection method answered. A result is untrusted for the same reason a
+ * snapshot is: it comes from an adapter that may be compiled against another version, and Omni
+ * shows the agent what it says. A status the method does not answer, a failure status without a
+ * failure, a success carrying one, or an `omni.` code the contract lacks are each refused.
+ */
+export function validateResult(result, method, path = "result") {
+    const into = new Collector();
+    const statuses = RESULT_STATUSES[method];
+    if (!isPlainObject(result)) {
+        into.add("result.shape", path, `${method} must answer an object`);
+        return into.violations;
+    }
+    if (result.status === statuses.success) {
+        into.require(result.failure === undefined, "result.failure.unexpected", `${path}.failure`, `${statuses.success} carries no failure`);
+        if (method === "openMedia") {
+            into.require(isPlainObject(result.session), "result.session", `${path}.session`, "opened carries the media session");
+        }
+    }
+    else if (result.status === statuses.failure) {
+        if (result.failure === undefined) {
+            into.add("result.failure.required", `${path}.failure`, `${statuses.failure} carries the failure that says why`);
+        }
+        else {
+            validateFailureInto(result.failure, `${path}.failure`, into);
+        }
+    }
+    else {
+        into.add("result.status", `${path}.status`, `${method} answers ${statuses.success} or ${statuses.failure}, not ${String(result.status)}`);
+    }
+    return into.violations;
+}
+// ---------------------------------------------------------------------------
 // Authentication.
 // ---------------------------------------------------------------------------
 function validateUser(value, rule, path, into) {

package/guide.md

@@ -2225,7 +2225,8 @@ Starts one outbound call from the idle dialpad. It is present only when the voic
 declares `dial`.
 
 - `destination` is the original number selected or entered by the agent.
-- `source` is `contact` or `manual` and must comply with `destinationPolicy`.
+- The provider holds `destination` to its declared `destinationPolicy`: under `contacts-only`, a
+  number that is not one of its contacts answers `failed` with `omni.destination-not-permitted`.
 - `dialled` confirms that outbound call creation completed.
 - `failed` contains a `ProtocolFailure` and confirms no call was placed.
 
@@ -2934,6 +2935,11 @@ Applies a `TaskCommandRequest` to one provider-local task.
   deciding a member's break that another lead has already decided is `applied` when the decisions
   agree and `failed`, saying so in `message`, when they differ. `commitBreak()` on a break already
   in effect is `committed` for the same reason.
+- **A result is untrusted for the same reason a snapshot is.** It comes from an adapter that may be
+  compiled against another version, and Omni shows the agent what it says. Omni validates it at
+  the boundary with `validateResult(result, "execute")` — a status the method does not answer, a
+  `failed` without its failure, a success carrying one, or an `omni.` code this contract lacks is
+  refused, and the command is treated as unsettled.
 - **A settled result is a fact; an unsettled promise is not.** Transport uncertainty may reject the
   promise with no result at all, and that means *unknown*, not *failed*, and a snapshot follows —
   see **An unsettled result is unknown**. `failed` must never be returned for something the
@@ -3176,6 +3182,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | `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. |
+| `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. |
 | `validateAuthenticationState(state)` | The identity each state must carry, the capabilities a usable login declares, and the expiry that only `authenticated` may. |
 
 Each returns `ProtocolViolation[]` rather than throwing, so a caller can report every problem at

package/package.json

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