@xema/omni-protocol 0.1.8 → 0.1.10

package/README.md

@@ -40,6 +40,17 @@ assertNoViolations(violations);
 A violation carries a stable `rule` id such as `task.browser.url.scheme`, the `path` it was found
 at such as `snapshot.tasks[0].browsers[1].url`, and a `message`.
 
+One rule needs more than the object in hand. A roster never carries the agent it is published to
+— a lead does not report to themself — and a validator cannot know who that is from the roster
+alone. `validateTeamRoster`, `validateSnapshot`, and `validateEventEnvelope` each take an optional
+final `{ self }`, the signed-in agent's `AuthenticationState.identity.id`; given it, they report
+`team.member.self` and `team.request.self`. Without it that rule is not checked. `exerciseAdapter`
+always passes it.
+
+```ts
+validateSnapshot(snapshot, manifest, "snapshot", { self: authentication.identity.id });
+```
+
 ## Conformance
 
 `exerciseAdapter` validates the manifest, opens an authenticated session, connects, checks

package/dist/testing.js

@@ -34,6 +34,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         if (authenticationState.status !== "authenticated") {
             throw new Error(`Adapter contract exercise requires authenticated test state, received ${authenticationState.status}`);
         }
+        // The harness knows who is signed in, so it can hold the adapter to a rule the structural
+        // validators cannot check alone: a roster never carries the agent it is published to.
+        const reader = { self: authenticationState.identity.id };
         connection = await adapter.connect(context);
         const live = connection;
         // The optional methods are optional only until something declares a need for them. Each
@@ -57,7 +60,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             requireMethod("openMedia", "the manifest channel is voice");
         const eventIds = new Set();
         unsubscribe = connection.subscribe(envelope => {
-            violations.push(...validateEventEnvelope(envelope, adapter.manifest));
+            violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -66,7 +69,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             events.push(envelope);
         });
         const snapshot = await connection.snapshot();
-        violations.push(...validateSnapshot(snapshot, adapter.manifest));
+        violations.push(...validateSnapshot(snapshot, adapter.manifest, "snapshot", reader));
         if (snapshot?.sessionCapabilities?.breaks === true) {
             // The four stand or fall together: `granted` is a promise to honour a later commit, and
             // an adapter with requestBreak but no commitBreak leaves an agent a break that never starts.

package/dist/validation.d.ts

@@ -1,4 +1,4 @@
-import { type ProtocolViolation } from "./index.js";
+import { type ProtocolViolation, type UserId } from "./index.js";
 export type { ProtocolViolation } from "./index.js";
 export declare class ProtocolConformanceError extends Error {
     readonly violations: readonly ProtocolViolation[];
@@ -15,7 +15,18 @@ export interface TaskValidationContext {
     channel: string;
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, path?: string): ProtocolViolation[];
-export declare function validateTeamRoster(roster: unknown, path?: string): ProtocolViolation[];
-export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string): ProtocolViolation[];
-export declare function validateEventEnvelope(envelope: unknown, manifest: unknown, path?: string): ProtocolViolation[];
+/**
+ * Who is reading what the adapter published. The validators check structure without it; given
+ * `self`, they also check that a roster never carries the agent it is published to.
+ */
+export interface ReaderContext {
+    /**
+     * The signed-in agent, `AuthenticationState.identity.id`. A lead does not report to themself:
+     * a roster that lists them in `members`, or their own ask in `requests`, is a violation.
+     */
+    self?: UserId;
+}
+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[];
 export declare function validateAuthenticationState(state: unknown, path?: string): ProtocolViolation[];

package/dist/validation.js

@@ -705,12 +705,12 @@ function validateBreakState(value, path, into) {
         }
     });
 }
-export function validateTeamRoster(roster, path = "team") {
+export function validateTeamRoster(roster, path = "team", context = {}) {
     const into = new Collector();
-    validateTeamRosterInto(roster, path, into);
+    validateTeamRosterInto(roster, path, context, into);
     return into.violations;
 }
-function validateTeamRosterInto(roster, path, into) {
+function validateTeamRosterInto(roster, path, context, into) {
     if (!isPlainObject(roster)) {
         into.add("team.shape", path, "a team roster must be an object");
         return;
@@ -740,7 +740,9 @@ function validateTeamRosterInto(roster, path, into) {
                         into.add("team.request.unique", `${at}.id`, `duplicate request id: ${request.id}`);
                     seenRequests.add(request.id);
                 }
-                into.require(isUserId(request.memberId), "team.request.memberId", `${at}.memberId`, "a request names the member asking");
+                if (into.require(isUserId(request.memberId), "team.request.memberId", `${at}.memberId`, "a request names the member asking")) {
+                    into.require(request.memberId !== context.self, "team.request.self", `${at}.memberId`, "the roster carries the reader's own ask: an agent's request for a lead goes to whoever leads them");
+                }
                 into.require(isTaskId(request.taskId), "team.request.taskId", `${at}.taskId`, "a request names the task the lead would join");
                 if (request.note !== undefined)
                     into.filled(request.note, "team.request.note", `${at}.note`, "a note must not be empty when present");
@@ -763,6 +765,7 @@ function validateTeamRosterInto(roster, path, into) {
             if (seen.has(member.id))
                 into.add("team.member.unique", `${at}.id`, `duplicate roster member: ${member.id}`);
             seen.add(member.id);
+            into.require(member.id !== context.self, "team.member.self", `${at}.id`, "the roster carries the agent it is published to: a lead does not report to themself");
         }
         into.oneOf(member.availability, TEAM_AVAILABILITIES, "team.member.availability", `${at}.availability`);
         if (member.since !== undefined)
@@ -771,7 +774,7 @@ function validateTeamRosterInto(roster, path, into) {
             into.oneOf(member.break, BREAK_APPROVALS, "team.member.break", `${at}.break`);
     });
 }
-export function validateSnapshot(snapshot, manifest, path = "snapshot") {
+export function validateSnapshot(snapshot, manifest, path = "snapshot", context = {}) {
     const into = new Collector();
     if (!isPlainObject(snapshot)) {
         into.add("snapshot.shape", path, "a snapshot must be an object");
@@ -839,7 +842,7 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot") {
         }
     }
     if (snapshot.team !== undefined)
-        validateTeamRosterInto(snapshot.team, `${path}.team`, into);
+        validateTeamRosterInto(snapshot.team, `${path}.team`, context, into);
     return into.violations;
 }
 // ---------------------------------------------------------------------------
@@ -912,7 +915,7 @@ function validateProviderSummary(value, path, into) {
         into.require(typeof metric.value === "string", "event.summary.metric.value", `${at}.value`, "a metric value must be a string; the provider decides how it reads");
     });
 }
-export function validateEventEnvelope(envelope, manifest, path = "event") {
+export function validateEventEnvelope(envelope, manifest, path = "event", context = {}) {
     const into = new Collector();
     if (!isPlainObject(envelope)) {
         into.add("event.shape", path, "an event envelope must be an object");
@@ -931,7 +934,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event") {
     switch (event.type) {
         case "snapshot":
             into.oneOf(event.reason, SNAPSHOT_REASONS, "event.snapshot.reason", `${at}.reason`);
-            into.violations.push(...validateSnapshot(event.snapshot, manifest, `${at}.snapshot`));
+            into.violations.push(...validateSnapshot(event.snapshot, manifest, `${at}.snapshot`, context));
             break;
         case "provider-status":
             into.oneOf(event.status, CONNECTION_STATUSES, "event.providerStatus.status", `${at}.status`);
@@ -975,7 +978,7 @@ export function validateEventEnvelope(envelope, manifest, path = "event") {
             validateProviderSummary(event.summary, `${at}.summary`, into);
             break;
         case "team-updated":
-            validateTeamRosterInto(event.team, `${at}.team`, into);
+            validateTeamRosterInto(event.team, `${at}.team`, context, into);
             break;
         case "contacts-updated":
             if (!Array.isArray(event.contacts)) {

package/guide.md

@@ -926,6 +926,11 @@ snapshot is the answer; Omni waits for it rather than calling `snapshot()` itsel
 transport is up, a result says the provider accepted the command, and the event that follows —
 `task-updated`, `break-state` — says what it did.
 
+**Classify on the rejection, never on a connection status published separately from it.** The
+status is a report about the wire and races the rejection; the rejection is the event. A rejection
+is the provider's answer only when it carries the provider's answer — a failure the provider
+named. Every other rejection is transport loss, whatever the last `provider-status` said.
+
 A command therefore carries no key. The provider names its own records — a task, a lead request, a
 member — and Omni refers to them by those names; **Omni never asks a provider to remember a name
 Omni made up.**
@@ -2585,6 +2590,15 @@ decides who leads a team: no roster means nothing is shown, which is the correct
 agent who leads nobody. The same rule governs `TeamRoster.breakControl` — present when this lead
 decides their team's breaks, absent when they do not.
 
+**The roster never carries the agent it is published to — not in `members`, and not in
+`requests`.** A lead does not report to themself: their own break request and their own ask for a
+lead go up to whoever leads them and appear on *that* person's roster, while the requester sees
+only their own `BreakState` and their task's `lead` move. An adapter whose platform lists the lead
+among their own members filters the signed-in identity out before publishing. **Entitlement is a
+role the provider knows, never inferred from who is listed:** a lead with nobody in their team
+publishes `[]`, an agent with no such role publishes nothing, and no member count can tell those
+two apart.
+
 ### Lead commands
 
 One method, `executeTeamBreak`, taking a discriminated command exactly as `execute` takes a

package/package.json

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