@xema/omni-protocol 0.1.74 → 0.1.75

package/dist/testing.d.ts

@@ -57,6 +57,13 @@ export interface ExerciseAdapterOptions {
      * memory has nothing, and is named. Without it the store is required and never read.
      */
     rebuild?: () => Adapter<Channel>;
+    /**
+     * The values the queue locks on this login's tasks -- a party's number or email -- as the run's
+     * author knows them. A task whose party stands locked may carry none of them anywhere else
+     * (`task.locked.leak`). Required once any task locks a party field: a run that cannot ask the
+     * question is not a pass, and says so by throwing rather than passing.
+     */
+    lockedValues?: readonly string[];
 }
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,

package/dist/testing.js

@@ -163,6 +163,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     const breaks = new BreakStream();
     let seeded = false;
     const duringRead = [];
+    let lockedPartySeen = false;
     const storedSecrets = new Map();
     const authenticationSecrets = {
         get: async (key) => storedSecrets.get(key),
@@ -204,6 +205,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             capabilities: current().capabilities,
             loginId: context.loginId,
             autoAcceptTasks: context.autoAcceptTasks,
+            locked: options.lockedValues,
         });
         // The optional methods are optional only until something declares a need for them. Each
         // check pairs a method with the declaration that requires it, as the guide's Live-connection
@@ -341,6 +343,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                     message: `the provider reported a diagnostic: expected ${String(envelope.event.expected)}; observed ${String(envelope.event.observed)}` });
             }
             violations.push(...undeterminedTasks(eventTasks(envelope), "event"));
+            lockedPartySeen ||= eventTasks(envelope).some(locksParty);
             if (eventNamesUsers(envelope))
                 requireMethod(live, "describeUsers", "an event publishes a UserId");
             // Work is pulled, never pushed: an offer before the host stated capacity is an allocation
@@ -427,6 +430,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
                 tellRefused({ artefact: "snapshot", violations: broken });
         }
         violations.push(...undeterminedTasks(Array.isArray(snapshot?.tasks) ? snapshot.tasks : [], "snapshot.tasks"));
+        lockedPartySeen ||= (Array.isArray(snapshot?.tasks) ? snapshot.tasks : []).some(locksParty);
         stream.seed(snapshot);
         breaks.seed(snapshot);
         seeded = true;
@@ -587,6 +591,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             message: "an unsubscribe, disconnect(), or close() threw during shutdown",
         });
     }
+    // A task locked a party field and the run was not told the value: task.locked.leak was never
+    // asked, and a result that cannot say is not returned as one that passed.
+    if (lockedPartySeen && options.lockedValues === undefined) {
+        stopObserving();
+        throw new TypeError("a task locks its party's number or email and the run states no lockedValues: task.locked.leak cannot be evaluated; pass the values the queue locked in options.lockedValues");
+    }
     if (!options.collectOnly)
         assertNoViolations(violations);
     stopObserving();
@@ -727,6 +737,13 @@ export function assertAuthenticationRestoreAndExpiry(states) {
     }
 }
 /** The tasks an envelope carries: the one a task event names, or a snapshot event's list. */
+/** Whether a task's party stands locked on its number or email, which is what obliges a run to state the locked values. */
+function locksParty(task) {
+    if (!isRecord(task) || !isRecord(task.party))
+        return false;
+    const locked = (value) => isRecord(value) && value.lockedBy !== undefined;
+    return locked(task.party.number) || locked(task.party.email);
+}
 function eventTasks(envelope) {
     if (!isRecord(envelope) || !isRecord(envelope.event))
         return [];

package/dist/validation.d.ts

@@ -32,6 +32,12 @@ export interface TaskValidationContext {
     autoAcceptTasks?: boolean;
     /** Whether the manifest declares `dialOutcomes`. A task that may dial needs it to; absent, the question is not asked. */
     dialOutcomesDeclared?: boolean;
+    /**
+     * The values the queue locked on this login's tasks -- a party's number or email -- as whoever
+     * runs the validator knows them. Where a task's party stands locked, no other field of it may
+     * carry one of these. Unknown to a host, which never sees the value, and then unchecked.
+     */
+    locked?: readonly string[];
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
 /**
@@ -53,6 +59,12 @@ export interface ReaderContext {
     levels?: readonly string[];
     /** The login's `loginId`. A snapshot or event naming another belongs to a login that is gone. */
     loginId?: string;
+    /**
+     * The values the queue locked on this login's tasks, as whoever runs the validator knows them:
+     * a conformance run states them, a host never has them. Where a task's party stands locked, no
+     * other field of it may carry one (`task.locked.leak`). Absent, unchecked.
+     */
+    locked?: readonly string[];
     /** `ConnectContext.autoAcceptTasks` as sent: whether a pending task states its `acceptance`. Unknown to a caller without the context, and then unchecked. */
     autoAcceptTasks?: boolean;
 }

package/dist/validation.js

@@ -598,6 +598,53 @@ const PERSON_SETTABLE = /^(hold|skill:.+)$/;
 const isLocked = (value) => isPlainObject(value) && value.lockedBy !== undefined;
 /** The level ids in force: the manifest's, or the defaults when the caller holds no manifest. */
 const levelIds = (levels) => levels ?? DEFAULT_LEVEL_IDS;
+/**
+ * What the queue locks is locked on the whole task. Given the locked values, every other field an
+ * agent reads -- the title, the reference, an attribute, a custom control's label, a browser URL the
+ * desk shows -- is held to carrying none of them. A number is compared by its digits, so no
+ * formatting hides it; anything else by its text, case aside.
+ */
+function validateNothingLeaksInto(task, locked, path, into) {
+    ruleEvaluated("task.locked.leak");
+    const carries = (text, value) => {
+        if (typeof text !== "string")
+            return false;
+        const digits = value.replace(/[\s+().-]/g, "");
+        if (/^\d+$/.test(digits))
+            return text.replace(/\D/g, "").includes(digits);
+        return text.toLowerCase().includes(value.trim().toLowerCase());
+    };
+    const hold = (text, at) => {
+        for (const value of locked) {
+            if (carries(text, value))
+                into.add("task.locked.leak", at, "carries a value the queue locked: what the queue locks is locked on the whole task, and appears nowhere the agent reads");
+        }
+    };
+    hold(task.title, `${path}.title`);
+    hold(task.reference, `${path}.reference`);
+    if (Array.isArray(task.attributes)) {
+        task.attributes.forEach((attribute, index) => {
+            if (!isPlainObject(attribute))
+                return;
+            hold(attribute.label, `${path}.attributes[${index}].label`);
+            hold(attribute.value, `${path}.attributes[${index}].value`);
+            if (isPlainObject(attribute.party)) {
+                hold(attribute.party.number, `${path}.attributes[${index}].party.number`);
+                hold(attribute.party.email, `${path}.attributes[${index}].party.email`);
+            }
+        });
+    }
+    const custom = isPlainObject(task.capabilities) ? task.capabilities.custom : undefined;
+    if (Array.isArray(custom))
+        custom.forEach((control, index) => { if (isPlainObject(control))
+            hold(control.label, `${path}.capabilities.custom[${index}].label`); });
+    if (Array.isArray(task.browsers)) {
+        task.browsers.forEach((browser, index) => {
+            if (isPlainObject(browser) && browser.urlVisibility !== "hidden")
+                hold(browser.url, `${path}.browsers[${index}].url`);
+        });
+    }
+}
 /** `lockedBy`: a declared level other than `person`, who never locks their own value. */
 function validateLockedByInto(value, rule, path, levels, into) {
     if (!into.filled(value, rule, path, "lockedBy names the level that locked it"))
@@ -1015,6 +1062,9 @@ function validateTaskInto(task, context, path, into) {
     }
     if (task.party !== undefined)
         validateContactInto(task.party, `${path}.party`, into, context.levels);
+    if (context.locked !== undefined && isPlainObject(task.party) && (isLocked(task.party.number) || isLocked(task.party.email))) {
+        validateNothingLeaksInto(task, context.locked, path, into);
+    }
     validateBrowsers(task.browsers, `${path}.browsers`, into);
     validateTaskAttributes(task.attributes, `${path}.attributes`, into, context.levels);
     validateHandlingHistory(task.handlingHistory, `${path}.handlingHistory`, into, { phase: task.phase, media: task.media });
@@ -1308,7 +1358,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
         let assisting;
         let monitoring;
         snapshot.tasks.forEach((task, index) => {
-            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${path}.tasks[${index}]`, into);
+            validateTaskInto(task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${path}.tasks[${index}]`, into);
             // A lead assists one call at a time, and listens to one at a time.
             if (isPlainObject(task) && task.assisting !== undefined) {
                 if (assisting !== undefined)
@@ -1520,7 +1570,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
             validateBreakState(event.break, `${at}.break`, into);
             break;
         case "task-offered":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             // An offer introduces work that is not yet under way; work in progress arrives only on a snapshot.
             if (isPlainObject(event.task) && typeof event.task.phase === "string") {
                 into.require(OFFERABLE_PHASES.includes(event.task.phase), "event.taskOffered.phase", `${at}.task.phase`, `task-offered introduces a task as ${OFFERABLE_PHASES.join(", ")}, never as ${event.task.phase}`);
@@ -1529,7 +1579,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event", contex
                 into.timestamp(event.allocationExpiresAt, "event.taskOffered.allocationExpiresAt", `${at}.allocationExpiresAt`);
             break;
         case "task-updated":
-            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest) }, `${at}.task`, into);
+            validateTaskInto(event.task, { channel, levels, autoAcceptTasks: context.autoAcceptTasks, dialOutcomesDeclared: manifestDials(manifest), locked: context.locked }, `${at}.task`, into);
             break;
         case "task-media-started":
             into.require(isTaskId(event.taskId), "event.taskMediaStarted.taskId", `${at}.taskId`, "a task id is required");

package/guide.md

@@ -831,7 +831,14 @@ lock, so nothing that can be locked — a directory, a number — may carry that
 contact's number and email are the same, since each identifies a person: where the queue says
 the agent may not see it, the provider sends `{ lockedBy }` in its place — the last digits or
 nothing — and a CRM link carries a token, never the value with a flag the desk is asked to honour.
-A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
+**What the queue locks is locked on the whole task.** A number the agent may not see appears
+nowhere else they read — not in the title, the reference, an attribute, a custom control's label,
+or a browser URL the desk shows; a browser whose URL must carry it says `urlVisibility: "hidden"`.
+The adapter is the one that knows the value, so it is the one held to it: given the values the
+queue locked, the validator refuses any other field carrying one, digits compared as digits so no
+formatting hides them (`task.locked.leak`), and a conformance run whose tasks lock a party's number
+or email states those values in `lockedValues`, since a run that cannot ask the question is not a
+pass. A host never has the value and never asks. A name is not locked. What the queue provides rather than permits — browsers, dispositions, custom
 controls — is content, and is never locked.
 
 **A lead sets the team's policy from their roster.** A login that declares
@@ -4624,7 +4631,7 @@ same exported checks are used by Omni and adapter tests so their interpretations
 | Function | Validates |
 | --- | --- |
 | `validateManifest(manifest)` | Identity, protocol-version interoperability, authentication methods, and idle-capability shapes. |
-| `validateTask(task, { channel })` | Identity, channel agreement, phase, wrap allowance, capability shapes, custom controls, and browsers. |
+| `validateTask(task, { channel, locked? })` | Identity, channel agreement, phase, wrap allowance, capability shapes, custom controls, and browsers. Given `locked`, the values the queue locked, a task whose party stands locked carries none of them anywhere else (`task.locked.leak`). |
 | `validateSnapshot(snapshot, manifest)` | Status, break state, break reasons, team roster, the stated `taskCount` reconciled against the tasks carried, 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. |

package/package.json

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