@xema/omni-protocol 0.1.10 → 0.1.12

package/README.md

@@ -40,22 +40,28 @@ 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.
+Some rules need more than the object in hand. A roster never carries the agent it is published to,
+a lead's snapshot always carries one and nobody else's ever does — and a validator cannot know who
+is reading, or what their login declares, from the snapshot alone. `validateTeamRoster`,
+`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.
 
 ```ts
-validateSnapshot(snapshot, manifest, "snapshot", { self: authentication.identity.id });
+const { identity, capabilities } = authenticated;
+validateSnapshot(snapshot, manifest, "snapshot", { self: identity.id, capabilities });
 ```
 
 ## Conformance
 
 `exerciseAdapter` validates the manifest, opens an authenticated session, connects, checks
-required capability methods, subscribes, validates the snapshot and every delivered event, states
-a capacity, then unsubscribes and disconnects.
+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
+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 });
@@ -63,8 +69,8 @@ expect(result.violations).toEqual([]);
 expect(result.disconnectWasClean).toBe(true);
 ```
 
-Run the contract scenarios beside it — authentication restore and expiry, reconnect with missed
-assignments, break denial and retry, wrap timeout, browser isolation.
+Run the contract scenarios beside it — authentication restore and expiry, capability withdrawal,
+reconnect with missed assignments, break denial and retry, wrap timeout, browser isolation.
 
 > **Assert both directions.** Every helper rejects a violating input as well as accepting a
 > conforming one. A suite that only asserts "this conforming case does not throw" passes unchanged

package/dist/index.d.ts

@@ -135,9 +135,28 @@ export interface AuthenticationFailure {
     /** Names a declared credentials field when the failure belongs to one. */
     field?: string;
 }
+/** What a lead may do with their team. Declared by presence. */
+export interface TeamCapabilities {
+    /** This lead decides their team's breaks. Requires `executeTeamBreak`. */
+    breakControl?: true;
+    /** This lead may join a member's call on request. Requires `executeTeamConsult`. */
+    consultControl?: true;
+}
 /**
- * Only `authenticated` and `refreshing` know who the agent is, and only `authenticated` has
- * something to expire. A state carrying more than it knows is a state Omni would render as fact.
+ * What this login may do, beyond any one task. It travels with the identity because it is part
+ * of who the agent is on this provider: the provider knows the roles and says so at sign-in.
+ * Current as of the latest `authenticated` state, never fixed for the login.
+ */
+export interface SessionCapabilities {
+    /** This login may request a break. Requires the four break methods. */
+    breaks?: true;
+    /** This login leads a team: a `TeamRoster` is published to it on every snapshot, `[]` included. */
+    team?: TeamCapabilities;
+}
+/**
+ * Only `authenticated` and `refreshing` know who the agent is and what they may do, and only
+ * `authenticated` has something to expire. A state carrying more than it knows is a state Omni
+ * would render as fact.
  */
 export type AuthenticationState = {
     status: "signed-out";
@@ -146,10 +165,12 @@ export type AuthenticationState = {
 } | {
     status: "authenticated";
     identity: User;
+    capabilities: SessionCapabilities;
     expiresAt?: IsoTimestamp;
 } | {
     status: "refreshing";
     identity: User;
+    capabilities: SessionCapabilities;
 } | {
     status: "expired";
     identity?: User;
@@ -199,6 +220,7 @@ export type CompleteAuthenticationRequest = {
 export type CompleteAuthenticationResult = {
     status: "authenticated";
     identity: User;
+    capabilities: SessionCapabilities;
     expiresAt?: IsoTimestamp;
 } | {
     status: "rejected";
@@ -705,10 +727,6 @@ export interface TeamMember {
     since?: IsoTimestamp;
     break?: BreakApproval;
 }
-/**
- * Published only to an agent entitled to one. Its presence is the permission -- nothing else
- * makes somebody a lead, and there is no separate flag to fall out of step with the data.
- */
 /** A member asking this lead to join their call. */
 export interface LeadRequest {
     id: string;
@@ -717,12 +735,13 @@ export interface LeadRequest {
     note?: string;
     since: IsoTimestamp;
 }
+/**
+ * The login is the permission: published to a login that declares `capabilities.team`, on every
+ * snapshot, and to nobody else. What the lead may do with it is on the login too, not here.
+ */
 export interface TeamRoster {
     members: TeamMember[];
-    breakControl?: true;
-    /** Present when this lead may join a member's call on request. */
-    consultControl?: true;
-    /** Omitted when the lead may not be asked; `[]` when nobody is asking. */
+    /** Omitted when the login lacks `team.consultControl`; `[]` when nobody is asking. */
     requests?: LeadRequest[];
 }
 export type TeamConsultCommand = {
@@ -777,15 +796,10 @@ export type OpenMediaResult = {
     status: "unavailable";
     failure: ProtocolFailure;
 };
-export interface SessionCapabilities {
-    breaks?: true;
-    teamBreakControl?: true;
-}
 /** The provider's complete state at one moment. It replaces what Omni holds; never a patch. */
 export interface Snapshot<C extends Channel = Channel> {
     status: ConnectionStatus;
     sessionId: string;
-    sessionCapabilities: SessionCapabilities;
     break: BreakState;
     /** Every task currently owned by this agent for this provider. */
     tasks: Task<C>[];
@@ -888,7 +902,7 @@ export interface Connection<C extends Channel = Channel> {
     /** Required when the manifest declares `idleCapabilities.dial`. */
     dial?(request: DialRequest): Promise<DialResult>;
     /**
-     * The four break methods stand or fall together. Declaring `sessionCapabilities.breaks` and
+     * The four break methods stand or fall together. Declaring `capabilities.breaks` at login and
      * implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can
      * never start, and the two-phase coordination has no way to report it.
      */
@@ -896,9 +910,9 @@ export interface Connection<C extends Channel = Channel> {
     commitBreak?(): Promise<BreakCommitResult>;
     cancelBreak?(): Promise<BreakCancelResult>;
     endBreak?(): Promise<BreakEndResult>;
-    /** Required when the adapter publishes a `TeamRoster` carrying `breakControl`. */
+    /** Required when the login declares `capabilities.team.breakControl`. */
     executeTeamBreak?(request: TeamBreakCommandRequest): Promise<TeamCommandResult>;
-    /** Required when the adapter publishes a `TeamRoster` carrying `consultControl`. */
+    /** Required when the login declares `capabilities.team.consultControl`. */
     executeTeamConsult?(request: TeamConsultCommandRequest): Promise<TeamCommandResult>;
     /** Required of every voice adapter: all voice audio lands in Omni. */
     openMedia?(request: OpenMediaRequest): Promise<OpenMediaResult>;

package/dist/testing.d.ts

@@ -1,11 +1,32 @@
-import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Snapshot, type TaskCompletion, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext } 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. */
     authenticationState: AuthenticationState;
-    /** True only when `disconnect()` and `close()` both settled without throwing. */
+    /**
+     * The latest login the session published during the run. Equal to `authenticationState` unless
+     * the adapter republished `authenticated` -- capabilities are current, not fixed.
+     */
+    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[];
 }
@@ -16,8 +37,9 @@ export interface ExerciseAdapterOptions {
 /**
  * Adapter conformance exercise: validates the manifest, opens an authenticated session,
  * connects, checks that every method the declarations require is implemented, subscribes,
- * validates the snapshot and every delivered event, states a capacity, then unsubscribes and
- * disconnects.
+ * validates the snapshot, every delivered event, and every authentication state the session
+ * publishes during the run -- against the latest login, since capabilities are current, not
+ * fixed -- states a capacity, then unsubscribes and disconnects.
  *
  * Violations are collected rather than thrown from inside the adapter's own
  * dispatch path. Throwing from a subscribe listener unwinds through the provider
@@ -25,8 +47,38 @@ export interface ExerciseAdapterOptions {
  * 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>;
-/** Validates restored authentication followed by a refresh failure or expiry. */
+/**
+ * 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.
+ */
 export declare function assertAuthenticationRestoreAndExpiry(states: readonly AuthenticationState[]): void;
+/**
+ * Capabilities are current, not fixed. A provider that withdraws one republishes `authenticated`
+ * with the new set, and the next snapshot agrees with it. `states` is what the authentication
+ * session published, first to last: beginning and ending `authenticated` for the same identity,
+ * passing only through usable states (`expired` or `signed-out` ends the login instead), with at
+ * least one capability gone by the end. `snapshot` is the first snapshot published after the last
+ * state, validated against that login -- so a roster still published to a login that no longer
+ * leads, or requests to one that may no longer join, is the failure.
+ */
+export declare function assertCapabilityWithdrawal(states: readonly AuthenticationState[], snapshot: Snapshot, manifest: Manifest): void;
+/**
+ * A command that arrives after its capability was withdrawn is answered `failed` with
+ * `omni.capability-not-enabled`: the provider names it, so Omni never has to infer from a
+ * capability change it may not have rendered yet that "no longer a lead" is the message.
+ * Takes any command result -- a team command, a break method -- after such a withdrawal.
+ */
+export declare function assertCommandRefusedAfterWithdrawal(result: {
+    status: string;
+    failure?: {
+        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,11 +1,134 @@
 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,
- * validates the snapshot and every delivered event, states a capacity, then unsubscribes and
- * disconnects.
+ * validates the snapshot, every delivered event, and every authentication state the session
+ * publishes during the run -- against the latest login, since capabilities are current, not
+ * fixed -- states a capacity, then unsubscribes and disconnects.
  *
  * Violations are collected rather than thrown from inside the adapter's own
  * dispatch path. Throwing from a subscribe listener unwinds through the provider
@@ -15,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,
@@ -26,7 +150,9 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     });
     let connection;
     let unsubscribe;
+    let unsubscribeAuthentication;
     let authenticationState;
+    let login;
     let disconnectWasClean = false;
     try {
         authenticationState = await authentication.state();
@@ -34,33 +160,75 @@ 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 harness knows who is signed in and what their login declares, so it can hold the
+        // adapter to rules the structural validators cannot check alone: a roster never carries the
+        // agent it is published to, a lead's snapshot always carries one, nobody else's ever does.
+        // Capabilities are current, not fixed, so the login is read when something is validated,
+        // never captured at sign-in: a provider that withdraws one republishes `authenticated`, and
+        // everything published after that is held to the new set. A published state that fails
+        // validation is reported and not adopted -- the harness keeps the last login it could trust.
+        login = authenticationState;
+        const current = () => {
+            if (login === undefined)
+                throw new Error("unreachable: the exercise has an authenticated login");
+            return login;
+        };
+        const reader = () => ({ self: current().identity.id, capabilities: current().capabilities });
         // 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
         // table does; a missing one is a control the agent would be shown and could never use.
-        const requireMethod = (name, because) => {
-            if (typeof live[name] !== "function") {
-                violations.push({
-                    rule: `connection.${name}.required`,
-                    path: `connection.${name}`,
-                    message: `${because}, but the connection does not implement ${name}()`,
-                });
+        const reported = new Set();
+        const requireMethod = (on, name, because) => {
+            if (typeof on[name] === "function" || reported.has(name))
+                return;
+            reported.add(name);
+            violations.push({
+                rule: `connection.${name}.required`,
+                path: `connection.${name}`,
+                message: `${because}, but the connection does not implement ${name}()`,
+            });
+        };
+        const requireCapabilityMethods = (on, capabilities) => {
+            if (capabilities.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.
+                for (const method of ["requestBreak", "commitBreak", "cancelBreak", "endBreak"]) {
+                    requireMethod(on, method, "the login declares capabilities.breaks");
+                }
             }
+            if (capabilities.team?.breakControl === true)
+                requireMethod(on, "executeTeamBreak", "the login declares capabilities.team.breakControl");
+            if (capabilities.team?.consultControl === true)
+                requireMethod(on, "executeTeamConsult", "the login declares capabilities.team.consultControl");
         };
+        unsubscribeAuthentication = authentication.subscribe(state => {
+            const own = validateAuthenticationState(state);
+            violations.push(...own);
+            if (own.length > 0)
+                return;
+            if (state.status === "refreshing") {
+                violations.push(...refreshingCarriesOver(current(), state, "authentication"));
+            }
+            else if (state.status === "authenticated") {
+                login = state;
+                // A capability granted later requires its methods just as one declared at sign-in does.
+                if (connection !== undefined)
+                    requireCapabilityMethods(connection, state.capabilities);
+            }
+        });
+        connection = await adapter.connect(context);
+        const live = connection;
         // Dial is declared by presence: the capability object carries a destination policy rather
         // than an `enabled` flag, so its presence is the declaration.
         if (adapter.manifest.idleCapabilities?.dial !== undefined)
-            requireMethod("dial", "the manifest declares dial");
+            requireMethod(live, "dial", "the manifest declares dial");
         // Every voice task's audio lands in Omni, so there is no voice adapter that does not open it.
         if (adapter.manifest.channel === "voice")
-            requireMethod("openMedia", "the manifest channel is voice");
+            requireMethod(live, "openMedia", "the manifest channel is voice");
         const eventIds = new Set();
         unsubscribe = connection.subscribe(envelope => {
-            violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader));
+            observeEvent(envelope, seen);
+            violations.push(...validateEventEnvelope(envelope, adapter.manifest, "event", reader()));
             if (typeof envelope?.id === "string") {
                 if (eventIds.has(envelope.id))
                     return;
@@ -69,20 +237,11 @@ export async function exerciseAdapter(adapter, context, options = {}) {
             events.push(envelope);
         });
         const snapshot = await connection.snapshot();
-        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.
-            for (const method of ["requestBreak", "commitBreak", "cancelBreak", "endBreak"]) {
-                requireMethod(method, "the snapshot declares sessionCapabilities.breaks");
-            }
-        }
-        if (snapshot?.team?.breakControl === true)
-            requireMethod("executeTeamBreak", "the roster carries breakControl");
-        if (snapshot?.team?.consultControl === true)
-            requireMethod("executeTeamConsult", "the roster carries consultControl");
+        observeSnapshot(snapshot, seen);
+        violations.push(...validateSnapshot(snapshot, adapter.manifest, "snapshot", reader()));
+        requireCapabilityMethods(live, current().capabilities);
         if (publishesUserIds(snapshot))
-            requireMethod("describeUsers", "the snapshot publishes a UserId");
+            requireMethod(live, "describeUsers", "the snapshot publishes a UserId");
         // 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 });
@@ -102,6 +261,12 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         catch {
             clean = false;
         }
+        try {
+            unsubscribeAuthentication?.();
+        }
+        catch {
+            clean = false;
+        }
         try {
             await connection?.disconnect();
         }
@@ -120,7 +285,7 @@ export async function exerciseAdapter(adapter, context, options = {}) {
         violations.push({
             rule: "connection.disconnect.clean",
             path: "connection.disconnect",
-            message: "unsubscribe(), disconnect(), or close() threw during shutdown",
+            message: "an unsubscribe, disconnect(), or close() threw during shutdown",
         });
     }
     if (!options.collectOnly)
@@ -128,6 +293,8 @@ export async function exerciseAdapter(adapter, context, options = {}) {
     return {
         events: events,
         authenticationState: authenticationState,
+        login: (login ?? authenticationState),
+        notExercised: CONTRACT_SUBJECTS.filter(subject => !seen.has(subject)),
         disconnectWasClean,
         violations,
     };
@@ -146,8 +313,55 @@ function publishesUserIds(snapshot) {
         return false;
     return snapshot.tasks.some(task => Array.isArray(task?.handlingHistory) && task.handlingHistory.some(step => step?.by !== undefined));
 }
-/** Validates restored authentication followed by a refresh failure or expiry. */
+const sameCapabilities = (a, b) => a.breaks === b.breaks &&
+    (a.team === undefined) === (b.team === undefined) &&
+    a.team?.breakControl === b.team?.breakControl &&
+    a.team?.consultControl === b.team?.consultControl;
+/**
+ * `refreshing` carries the identity and capabilities of the login it refreshes. A change to
+ * either is published as `authenticated`; a different identity is a new login.
+ */
+function refreshingCarriesOver(login, state, path) {
+    const found = [];
+    if (state.identity.id !== login.identity.id) {
+        found.push({
+            rule: "authentication.refreshing.identity",
+            path: `${path}.identity.id`,
+            message: "refreshing carries the identity of the login it refreshes; a different identity is a new login",
+        });
+    }
+    if (!sameCapabilities(state.capabilities, login.capabilities)) {
+        found.push({
+            rule: "authentication.refreshing.capabilities",
+            path: `${path}.capabilities`,
+            message: "refreshing carries the capabilities of the login it refreshes; a change is published as authenticated",
+        });
+    }
+    return found;
+}
+/** Validates each state of a published sequence, and that every `refreshing` carries over the login before it. */
+function assertLoginSequence(states, summary) {
+    const found = [];
+    let login;
+    states.forEach((state, index) => {
+        const path = `states[${index}]`;
+        const own = validateAuthenticationState(state, path);
+        found.push(...own);
+        if (own.length > 0)
+            return;
+        if (state.status === "authenticated")
+            login = state;
+        else if (state.status === "refreshing" && login !== undefined)
+            found.push(...refreshingCarriesOver(login, state, path));
+    });
+    assertNoViolations(found, summary);
+}
+/**
+ * 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.
+ */
 export function assertAuthenticationRestoreAndExpiry(states) {
+    assertLoginSequence(states, "Authentication scenario");
     if (states.length < 2 || states[0]?.status !== "authenticated") {
         throw new Error("Authentication scenario must start with a restored authenticated state");
     }
@@ -160,6 +374,64 @@ export function assertAuthenticationRestoreAndExpiry(states) {
         throw new Error("Refreshing state must occur before expiry");
     }
 }
+/**
+ * Capabilities are current, not fixed. A provider that withdraws one republishes `authenticated`
+ * with the new set, and the next snapshot agrees with it. `states` is what the authentication
+ * session published, first to last: beginning and ending `authenticated` for the same identity,
+ * passing only through usable states (`expired` or `signed-out` ends the login instead), with at
+ * least one capability gone by the end. `snapshot` is the first snapshot published after the last
+ * state, validated against that login -- so a roster still published to a login that no longer
+ * leads, or requests to one that may no longer join, is the failure.
+ */
+export function assertCapabilityWithdrawal(states, snapshot, manifest) {
+    assertLoginSequence(states, "Capability withdrawal");
+    const stray = states.findIndex(state => state.status !== "authenticated" && state.status !== "refreshing");
+    if (stray >= 0) {
+        throw new Error(`Capability withdrawal passes only through usable states; states[${stray}] is ${states[stray]?.status}, which ends the login`);
+    }
+    const first = states[0];
+    const last = states.at(-1);
+    if (first?.status !== "authenticated" || last?.status !== "authenticated") {
+        throw new Error("Capability withdrawal must begin and end with an authenticated login");
+    }
+    if (first.identity.id !== last.identity.id) {
+        throw new Error("Capability withdrawal must keep the identity: a different identity is a new login");
+    }
+    const before = first.capabilities;
+    const after = last.capabilities;
+    const withdrawn = (before.breaks === true && after.breaks !== true) ||
+        (before.team !== undefined && after.team === undefined) ||
+        (before.team?.breakControl === true && after.team?.breakControl !== true) ||
+        (before.team?.consultControl === true && after.team?.consultControl !== true);
+    if (!withdrawn) {
+        throw new Error("Capability withdrawal must end with at least one capability the first login declared withdrawn");
+    }
+    assertNoViolations(validateSnapshot(snapshot, manifest, "snapshot", { self: last.identity.id, capabilities: after }), "Capability withdrawal: the snapshot after the last login must agree with it");
+}
+/**
+ * A command that arrives after its capability was withdrawn is answered `failed` with
+ * `omni.capability-not-enabled`: the provider names it, so Omni never has to infer from a
+ * capability change it may not have rendered yet that "no longer a lead" is the message.
+ * Takes any command result -- a team command, a break method -- after such a withdrawal.
+ */
+export function assertCommandRefusedAfterWithdrawal(result) {
+    if (result.status !== "failed") {
+        throw new Error(`A command after its capability was withdrawn must fail; received ${result.status}`);
+    }
+    if (result.failure?.code !== "omni.capability-not-enabled") {
+        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.d.ts

@@ -1,4 +1,4 @@
-import { type ProtocolViolation, type UserId } from "./index.js";
+import { type ProtocolViolation, type SessionCapabilities, type UserId } from "./index.js";
 export type { ProtocolViolation } from "./index.js";
 export declare class ProtocolConformanceError extends Error {
     readonly violations: readonly ProtocolViolation[];
@@ -16,8 +16,8 @@ export interface TaskValidationContext {
 }
 export declare function validateTask(task: unknown, context: TaskValidationContext, 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.
+ * Who is reading what the adapter published, and what their login declares. The validators check
+ * structure without it; given it, they also hold what the adapter publishes to the login.
  */
 export interface ReaderContext {
     /**
@@ -25,6 +25,11 @@ export interface ReaderContext {
      * a roster that lists them in `members`, or their own ask in `requests`, is a violation.
      */
     self?: UserId;
+    /**
+     * The login's `AuthenticationState.capabilities`. The login is the permission: a lead's
+     * snapshot carries a roster, nobody else's does, and `requests` need `team.consultControl`.
+     */
+    capabilities?: SessionCapabilities;
 }
 export declare function validateTeamRoster(roster: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];
 export declare function validateSnapshot(snapshot: unknown, manifest: unknown, path?: string, context?: ReaderContext): ProtocolViolation[];

package/dist/validation.js

@@ -69,7 +69,8 @@ const DIAL_DESTINATION_POLICIES = membersOf({ "contacts-only": true, "any-number
 const SNAPSHOT_REASONS = membersOf({
     reconnected: true, "provider-requested": true,
 });
-const SESSION_CAPABILITIES = membersOf({ breaks: true, teamBreakControl: true });
+const SESSION_CAPABILITIES = membersOf({ breaks: true, team: true });
+const TEAM_CAPABILITIES = membersOf({ breakControl: true, consultControl: true });
 const COMPLETED_BY = membersOf({ agent: true, provider: true });
 const EXPIRABLE_PHASES = membersOf({
     pending: true, confirmed: true, preparing: true,
@@ -715,15 +716,24 @@ function validateTeamRosterInto(roster, path, context, into) {
         into.add("team.shape", path, "a team roster must be an object");
         return;
     }
-    if (roster.breakControl !== undefined) {
-        into.require(roster.breakControl === true, "team.breakControl", `${path}.breakControl`, "breakControl is declared by presence: send true or omit it");
+    // The login is the permission: a roster reaches a login that declares `capabilities.team` and
+    // nobody else. Only a caller holding the login can check it.
+    if (context.capabilities !== undefined && context.capabilities.team === undefined) {
+        into.add("team.unentitled", path, "a roster published to a login that does not declare capabilities.team: the login is the permission");
     }
-    if (roster.consultControl !== undefined) {
-        into.require(roster.consultControl === true, "team.consultControl", `${path}.consultControl`, "consultControl is declared by presence: send true or omit it");
+    if (roster.requests === undefined) {
+        // `[]` says nobody is asking; omission says the lead may not be asked. A login that may be
+        // asked therefore always carries the list.
+        if (context.capabilities?.team?.consultControl === true) {
+            into.add("team.requests.required", `${path}.requests`, "the login declares team.consultControl, so the roster carries requests: [] when nobody is asking");
+        }
     }
-    if (roster.requests !== undefined) {
+    else {
         // Requests are what a lead acts on, so a lead who may not act has no business receiving them.
-        into.require(roster.consultControl === true, "team.requests.capability", `${path}.requests`, "requests require consultControl: a lead who may not join has nothing to decide");
+        // Whether they may is on the login, so the check needs the login in hand.
+        if (context.capabilities !== undefined) {
+            into.require(context.capabilities.team?.consultControl === true, "team.requests.capability", `${path}.requests`, "requests require team.consultControl on the login: a lead who may not join has nothing to decide");
+        }
         if (!Array.isArray(roster.requests)) {
             into.add("team.requests.shape", `${path}.requests`, "requests must be an array when present");
         }
@@ -783,19 +793,6 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
     const channel = isPlainObject(manifest) && typeof manifest.channel === "string" ? manifest.channel : "voice";
     into.oneOf(snapshot.status, CONNECTION_STATUSES, "snapshot.status", `${path}.status`);
     into.filled(snapshot.sessionId, "snapshot.sessionId", `${path}.sessionId`, "a snapshot needs the session id it belongs to");
-    const sessionCapabilities = snapshot.sessionCapabilities;
-    if (!isPlainObject(sessionCapabilities)) {
-        into.add("snapshot.sessionCapabilities.shape", `${path}.sessionCapabilities`, "a snapshot needs a sessionCapabilities object");
-    }
-    else {
-        for (const [name, declared] of Object.entries(sessionCapabilities)) {
-            if (declared === undefined)
-                continue;
-            if (!into.require(SESSION_CAPABILITIES.includes(name), "snapshot.sessionCapability.unknown", `${path}.sessionCapabilities.${name}`, `unsupported session capability: ${name}`))
-                continue;
-            into.require(declared === true, "snapshot.sessionCapability.value", `${path}.sessionCapabilities.${name}`, `${name} is declared by presence: send true or omit it`);
-        }
-    }
     validateBreakState(snapshot.break, `${path}.break`, into);
     if (!Array.isArray(snapshot.tasks)) {
         into.add("snapshot.tasks.shape", `${path}.tasks`, "a snapshot must carry a tasks array");
@@ -814,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)) {
@@ -841,6 +847,11 @@ export function validateSnapshot(snapshot, manifest, path = "snapshot", context
             into.add("snapshot.calendar.shape", `${path}.scheduledActivities`, "scheduledActivities must be an array when present");
         }
     }
+    // The login is the permission: a lead's snapshot carries a roster, `[]` included. The other
+    // direction -- a roster to a login that does not lead -- is the roster's own rule.
+    if (context.capabilities?.team !== undefined && snapshot.team === undefined) {
+        into.add("team.required", `${path}.team`, "the login declares capabilities.team, so every snapshot carries a roster: [] when nobody is in it");
+    }
     if (snapshot.team !== undefined)
         validateTeamRosterInto(snapshot.team, `${path}.team`, context, into);
     return into.violations;
@@ -1012,6 +1023,33 @@ function validateUser(value, rule, path, into) {
     into.require(isUserId(value.id), `${rule}.id`, `${path}.id`, "an identity needs a provider-issued user id");
     into.filled(value.displayName, `${rule}.displayName`, `${path}.displayName`, "an identity needs a display name");
 }
+function validateSessionCapabilitiesInto(value, path, into) {
+    if (!isPlainObject(value)) {
+        into.add("authentication.capabilities.shape", path, "a usable login declares its capabilities: an object, {} when it has none");
+        return;
+    }
+    for (const [name, declared] of Object.entries(value)) {
+        if (declared === undefined)
+            continue;
+        if (!into.require(SESSION_CAPABILITIES.includes(name), "authentication.capability.unknown", `${path}.${name}`, `unsupported session capability: ${name}`))
+            continue;
+        if (name === "team") {
+            if (!isPlainObject(declared)) {
+                into.add("authentication.capability.team.shape", `${path}.team`, "team names what the lead may do: an object, {} for a lead with no controls");
+                continue;
+            }
+            for (const [control, on] of Object.entries(declared)) {
+                if (on === undefined)
+                    continue;
+                if (!into.require(TEAM_CAPABILITIES.includes(control), "authentication.capability.team.unknown", `${path}.team.${control}`, `unsupported team capability: ${control}`))
+                    continue;
+                into.require(on === true, "authentication.capability.value", `${path}.team.${control}`, `${control} is declared by presence: send true or omit it`);
+            }
+            continue;
+        }
+        into.require(declared === true, "authentication.capability.value", `${path}.${name}`, `${name} is declared by presence: send true or omit it`);
+    }
+}
 export function validateAuthenticationState(state, path = "authentication") {
     const into = new Collector();
     if (!isPlainObject(state)) {
@@ -1025,6 +1063,7 @@ export function validateAuthenticationState(state, path = "authentication") {
     // may carry an identity. Anything else is a state claiming knowledge it does not have.
     if (state.status === "authenticated" || state.status === "refreshing") {
         validateUser(state.identity, "authentication.identity", `${path}.identity`, into);
+        validateSessionCapabilitiesInto(state.capabilities, `${path}.capabilities`, into);
     }
     else if (state.status === "expired") {
         if (state.identity !== undefined)
@@ -1047,5 +1086,8 @@ export function validateAuthenticationState(state, path = "authentication") {
         into.require(state.status === "authenticated", "authentication.expiresAt.unexpected", `${path}.expiresAt`, "only an authenticated state may carry an expiry");
         into.timestamp(state.expiresAt, "authentication.expiresAt", `${path}.expiresAt`);
     }
+    if (state.status !== "authenticated" && state.status !== "refreshing") {
+        into.require(state.capabilities === undefined, "authentication.capabilities.unexpected", `${path}.capabilities`, `${state.status} must not carry capabilities`);
+    }
     return into.violations;
 }

package/guide.md

@@ -21,7 +21,7 @@ are used precisely throughout and mean nothing looser here.
 | **Provider** | One independently connected external system: a voice platform, a chat platform, a mail platform. |
 | **Adapter** | The package implementing this contract for one provider. One adapter is one provider, so the words are often interchangeable; *provider* names the system, *adapter* the code speaking for it. |
 | **Agent** | The person signed in and taking work. Not to be confused with a transfer destination whose `kind` is `agent`, which is a routing target. |
-| **Lead** | An agent the provider also publishes a `TeamRoster` to. Nothing else makes somebody a lead: **its presence is the permission**. |
+| **Lead** | An agent whose login declares `capabilities.team`. The provider publishes a `TeamRoster` to them and to nobody else: **the login is the permission**. |
 | **Provisioning** | Omni-side policy about this agent, configured outside the protocol and never sent to a provider. It gates whether an offer may be rejected, whether the agent goes ready on login, and whether tasks are auto-accepted. Where a capability and provisioning disagree, the stricter wins. |
 | **Task** | One unit of assigned work — a call, a chat, a mail. |
 | **Channel** | The kind of work a provider carries: `voice`, `chat`, or `email`. Fixed per provider by its manifest. |
@@ -220,11 +220,21 @@ type AuthenticationContext = {
   log?: (entry: unknown) => void;
 };
 
+type TeamCapabilities = {
+  breakControl?: true;
+  consultControl?: true;
+};
+
+type SessionCapabilities = {
+  breaks?: true;
+  team?: TeamCapabilities;
+};
+
 type AuthenticationState =
   | { status: "signed-out" }
   | { status: "authenticating" }
-  | { status: "authenticated"; identity: User; expiresAt?: IsoTimestamp }
-  | { status: "refreshing"; identity: User }
+  | { status: "authenticated"; identity: User; capabilities: SessionCapabilities; expiresAt?: IsoTimestamp }
+  | { status: "refreshing"; identity: User; capabilities: SessionCapabilities }
   | { status: "expired"; identity?: User; failure?: AuthenticationFailure };
 
 type AuthenticationFailure = {
@@ -249,15 +259,9 @@ type ConnectionStatus = "connecting" | "active" | "error";
 ### Provider state
 
 ```ts
-type SessionCapabilities = {
-  breaks?: true;
-  teamBreakControl?: true;
-};
-
 type Snapshot = {
   status: ConnectionStatus;
   sessionId: string;
-  sessionCapabilities: SessionCapabilities;
   break: BreakState;
   tasks: Task[];
   contacts?: Contact[];
@@ -608,8 +612,6 @@ type LeadRequest = {
 
 type TeamRoster = {
   members: TeamMember[];
-  breakControl?: true;
-  consultControl?: true;
   requests?: LeadRequest[];
 };
 
@@ -1306,8 +1308,8 @@ It carries no identity: who the agent is on this provider is the outcome of auth
 input to it.
 
 Closing this session releases observers and temporary flow state; it does not sign the agent out.
-Omni keeps the session open while the provider connection is active so refresh and expiry changes
-remain observable.
+Omni keeps the session open while the provider connection is active so refresh, expiry, and
+capability changes remain observable.
 
 ### Authentication state
 
@@ -1318,14 +1320,53 @@ reports later changes.
 | --- | --- |
 | `signed-out` | No usable provider session exists. |
 | `authenticating` | An interactive `browser-sso` or `credentials` flow is active. |
-| `authenticated` | A usable session exists. Includes the provider identity and optional token expiry time. |
-| `refreshing` | The adapter is refreshing its session. Existing provider identity remains available. |
+| `authenticated` | A usable session exists. Includes the provider identity, the login's `capabilities`, and optional token expiry time. |
+| `refreshing` | The adapter is refreshing its session. Existing provider identity and capabilities remain available, unchanged: a change to either is published as `authenticated`. |
 | `expired` | The session cannot currently be used. It may include an identity and typed failure. |
 
 Omni calls `connect()` only after authentication reaches `authenticated`. Token refresh remains
 adapter-owned; the adapter publishes `refreshing`, followed by `authenticated` or `expired`.
-If authentication expires during active work, Omni preserves the task workspace and shows
-reauthentication for that provider.
+`refreshing` asks nothing of the agent and Omni shows nothing for it. If authentication expires
+during active work, Omni preserves the task workspace and shows reauthentication for that
+provider: the transport is still up and the tasks still on it, so this is a login problem with a
+login fix, rendered apart from a provider Omni cannot reach. Commands meanwhile answer
+`omni.not-authenticated`.
+
+**Re-authentication restores the login; it does not replace it.** It runs on the session Omni
+kept, under the same `sessionId` — the old `flowId` died with the expiry, so the adapter issues a
+new challenge — and when the state returns to `authenticated` the connection and everything on it
+carry on: Omni does not call `connect()` again, since a second connection would be a second
+session for one agent. What "signing in again replaces the login" describes is a new
+`AuthenticationSession` under a new `sessionId`, after `signed-out`.
+
+### What the login may do
+
+`capabilities` declares provider actions available to this login rather than to one task: whether
+the agent may ask for a break, and whether they lead a team — and if so, whether they decide its
+breaks and whether they may join a member's call. It is declared by presence, like every capability
+in this contract, and it travels with the identity because it is part of who the agent is on this
+provider: the provider knows the roles, and says so at sign-in rather than leaving Omni to infer
+them from what arrives later.
+
+| Field | Contract |
+| --- | --- |
+| `breaks` | This login may request a break. Requires the four break methods on the connection. |
+| `team` | This login leads a team. The provider publishes a `TeamRoster` to it on every snapshot — `[]` when nobody is in it — and to nobody else. |
+| `team.breakControl` | This lead decides their team's breaks. Requires `executeTeamBreak`. |
+| `team.consultControl` | This lead may join a member's call on request. Requires `executeTeamConsult`. |
+
+A session action is available only when both the capability and Omni provisioning permit it.
+
+**Capabilities are current, not fixed.** They describe the login as of its latest `authenticated`
+state. A provider that reads roles live — a lead demoted mid-shift — republishes `authenticated`
+with the new set through `subscribe()` on the authentication session, which Omni keeps open for
+the life of the connection for exactly this reason, and the next snapshot agrees with it. Omni
+provisions what the capabilities call for at sign-in — a team panel for a lead, empty until the
+roster arrives, and nothing for anybody else — and withdraws it on the next render when the
+capability goes. A command that arrives after its capability was withdrawn is answered `failed`
+with `omni.capability-not-enabled`: the provider names it, so Omni never has to infer from a
+capability change it may not have rendered yet that "you are no longer a lead" is the message
+rather than "that did not work".
 
 ### Starting authentication
 
@@ -1391,14 +1432,16 @@ settles. The adapter must not persist raw credentials. Field-specific failures m
 
 `cancelAuthentication(flowId)` cancels an abandoned Browser SSO window or credentials form and
 releases its temporary state. It does not sign out an already authenticated session. It answers
-`cancelled`, and a repeat is safe and answers `already-cancelled`.
+`accepted`; a repeat, or a flow that already ended, is nothing to act on and answers `accepted`
+too, by the rule that a command asking for a state answers success when that state holds.
 
 ### Completion and failures
 
-`complete()` returns either an authenticated provider identity or a typed failure:
+`complete()` returns either the authenticated state — identity and capabilities — or a typed
+failure:
 
 ```ts
-{ status: "authenticated", identity: { id: "1042", displayName: "Asha Rao" } }
+{ status: "authenticated", identity: { id: "1042", displayName: "Asha Rao" }, capabilities: { breaks: true } }
 ```
 
 The `User` it carries is the **root of this provider's user namespace**. Every other person this
@@ -1416,7 +1459,7 @@ authorization codes, tokens, or provider responses containing secrets.
 
 ### Sign-out
 
-`signOut(requestId)` revokes or invalidates the provider session where supported, deletes stored
+`signOut()` revokes or invalidates the provider session where supported, deletes stored
 session secrets, and moves state to `signed-out`.
 `close()` stops authentication-state observation but does not sign the agent out.
 
@@ -1462,21 +1505,19 @@ because Omni renders that form itself. That is a local convenience and never rea
 
 ### `Snapshot`
 
-`sessionCapabilities` declares provider actions available for the current login rather than for one
-task. Protocol v1 includes agent break requests and team break control. A session action is
-available only when both the corresponding session capability and Omni provisioning permit it.
-The snapshot replaces the set completely, so a resync can grant or withdraw a capability safely.
+What the login may do is declared on its `AuthenticationState` — see **What the login may do** —
+not here. The snapshot carries what the provider holds for the agent now, and where that depends on
+a capability it agrees with the login: a lead's snapshot carries `team`, nobody else's does.
 
 | Field | Contract |
 | --- | --- |
 | `status` | Current `ConnectionStatus` — whether this provider's transport can serve the session. Defined under **`provider-status`**. |
 | `sessionId` | Identity of this login session. It must match the connection context. |
-| `sessionCapabilities` | Complete provider capability set for this login. Effective permission is its intersection with Omni provisioning. |
 | `break` | Complete break state, including approval, accepting state, reasons, retry details, and any imposed break. |
 | `tasks` | Complete set of tasks currently offered to or owned by this agent. |
 | `contacts` | Required complete contact contribution when the manifest declares `contacts`; `[]` clears it. Omitted only when it does not. |
 | `scheduledActivities` | Required complete calendar contribution when the manifest declares `calendar`; `[]` clears it. Omitted only when it does not. |
-| `team` | `TeamRoster` for an agent who leads a team. Omitted for everybody else — its presence is the permission. |
+| `team` | Required `TeamRoster` when the login declares `capabilities.team`, `[]` when nobody is in it. Forbidden otherwise — the login is the permission. |
 
 ## Live connection
 
@@ -1493,15 +1534,15 @@ surface in one place, and what obliges an adapter to implement each one.
 | `execute(request)` | Always. Every channel has commands no capability gates — see **Which commands need a capability**. |
 | `describeUsers(ids)` | The adapter publishes any `UserId`: on `ImposedBreak.by`, a roster, or `handlingHistory[].by`. |
 | `dial(request)` | The manifest declares `idleCapabilities.dial`. |
-| `requestBreak(request)` | `sessionCapabilities.breaks` is declared. |
-| `commitBreak()` | `sessionCapabilities.breaks` is declared. Commit and cancel are not optional halves of it. |
-| `cancelBreak()` | `sessionCapabilities.breaks` is declared. |
-| `endBreak()` | `sessionCapabilities.breaks` is declared. |
-| `executeTeamBreak(command)` | The adapter publishes a `TeamRoster` carrying `breakControl`. |
-| `executeTeamConsult(command)` | The adapter publishes a `TeamRoster` carrying `consultControl`. |
+| `requestBreak(request)` | The login declares `capabilities.breaks`. |
+| `commitBreak()` | The login declares `capabilities.breaks`. Commit and cancel are not optional halves of it. |
+| `cancelBreak()` | The login declares `capabilities.breaks`. |
+| `endBreak()` | The login declares `capabilities.breaks`. |
+| `executeTeamBreak(command)` | The login declares `capabilities.team.breakControl`. |
+| `executeTeamConsult(command)` | The login declares `capabilities.team.consultControl`. |
 | `openMedia(request)` | The manifest channel is `voice`. Every voice task's audio lands in Omni, so there is no voice adapter that does not implement it. |
 
-**The four break methods stand or fall together.** Declaring `sessionCapabilities.breaks` and then
+**The four break methods stand or fall together.** Declaring `capabilities.breaks` at login and then
 implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can never
 start, and the two-phase coordination in **Coordinating a multi-provider break** has no way to
 report that: `granted` is a promise to honour a later commit.
@@ -2429,7 +2470,7 @@ outstanding and offers **Cancel break request**, but does not tell the agent tha
 begun.
 
 Omni offers the aggregate Break control only when every provider currently holding capacity
-declares `sessionCapabilities.breaks`. If one cannot be stopped, offering a global break would
+declares `capabilities.breaks` at login. If one cannot be stopped, offering a global break would
 knowingly permit partial availability.
 
 Omni coordinates one attempt as follows:
@@ -2553,10 +2594,8 @@ A lead who also takes calls sees their team on the idle dashboard. `Snapshot.tea
 
 | Field | Contract |
 | --- | --- |
-| `members` | Every member of this lead's team, whatever their state. `[]` says the lead has a team with nobody in it; omitting the roster says something else entirely — see **Its presence is the permission** below. |
-| `breakControl` | Present when this lead decides their team's breaks, absent when they do not. |
-| `consultControl` | Present when this lead may join a member's call on request, absent when they may not. |
-| `requests` | The members currently asking this lead to join a call, each with the task and the note. Omitted when the lead may not be asked; `[]` when nobody is asking. See **Consulting a lead**. |
+| `members` | Every member of this lead's team, whatever their state. `[]` says the lead has a team with nobody in it; omitting the roster says something else entirely — see **The login is the permission** below. |
+| `requests` | The members currently asking this lead to join a call, each with the task and the note. Required when the login declares `team.consultControl`, `[]` when nobody is asking; omitted when it does not. See **Consulting a lead**. |
 
 | `TeamMember` field | Contract |
 | --- | --- |
@@ -2585,19 +2624,20 @@ everybody — worse than showing nothing, because it looks like data. Send it on
 knows when the state actually began. It times the current `availability`, so it moves every time
 that value does.
 
-**Its presence is the permission.** Publish a roster only to an agent entitled to one. Omni never
-decides who leads a team: no roster means nothing is shown, which is the correct rendering for an
-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 login is the permission.** A roster goes to a login that declares `capabilities.team`, on
+every snapshot, and to nobody else. Omni never decides who leads a team: the provider said so at
+sign-in, and the roster agrees with it — present, `[]` included, for a lead; absent for everybody
+else, which is the correct rendering for an agent who leads nobody. What the lead may do with the
+roster is on the login too, `team.breakControl` and `team.consultControl`, never on the roster.
 
 **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.
+among their own members filters the signed-in identity out before publishing. **Being a lead is a
+role the provider knows, never inferred from who is listed:** it is declared at sign-in, 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
 
@@ -2634,8 +2674,8 @@ team, and a second lead method beside `executeTeamBreak`:
 executeTeamConsult({ command: TeamConsultCommand }): Promise<TeamCommandResult>
 ```
 
-Required when the roster carries `consultControl`, and gated by it exactly as `executeTeamBreak`
-is by `breakControl`. The flow, in order:
+Required when the login declares `capabilities.team.consultControl`, and gated by it exactly as
+`executeTeamBreak` is by `team.breakControl`. The flow, in order:
 
 ```ts
 // 1. The agent asks, with a small note. Their task carries `lead` from here on.
@@ -2718,8 +2758,8 @@ whole and replaced whole, and a provider that cannot say omits it.
 
 **An agent is not waiting on one person.** Authority is held by several, everyone who holds it
 sees the request on their own console, and **any one of them settles it**. Omni offers the
-decision to whoever is reading a roster that carries `breakControl` — which is how the provider
-already says who may decide — and does not try to work out whose turn it is.
+decision to every login that declares `team.breakControl` — which is how the provider already
+says who may decide — and does not try to work out whose turn it is.
 
 A request needing *more than one* approval is not something this contract describes. There is
 no partial state to report and no progress to display: a request is either still owed a
@@ -2896,8 +2936,8 @@ react rather than only display the message:
 
 | Code | Meaning |
 | --- | --- |
-| `omni.not-authenticated` | The provider session is no longer usable. Omni surfaces reauthentication. |
-| `omni.capability-not-enabled` | The action targets a capability this task or manifest did not declare. |
+| `omni.not-authenticated` | The provider session is no longer usable. The adapter has published `expired` at or before this answer — the state is what Omni surfaces reauthentication from; the code says why this action failed, and is never the only signal. |
+| `omni.capability-not-enabled` | The action targets a capability this task, manifest, or login did not declare — including a lead command from a login whose `capabilities` no longer carry it. |
 | `omni.task-not-found` | The provider-local task id is unknown, typically after the task already ended. |
 | `omni.destination-not-permitted` | The dial or transfer destination violates the provider's policy. |
 | `omni.rate-limited` | The action was throttled. Pair with `retryAfterMs`. |
@@ -2967,9 +3007,10 @@ direction — the provider asking Omni to reconcile — and neither replaces the
 
 Carries a complete `Snapshot` after reconnect or when the provider explicitly requests
 reconciliation. `reason` is `reconnected` or `provider-requested`. Omni replaces the provider's
-current status, session capabilities, break state, tasks, contacts, scheduled activities and team
-roster with this snapshot. A roster absent from the snapshot withdraws one previously published,
-exactly as it would withdraw a capability.
+current status, break state, tasks, contacts, scheduled activities and team roster with this
+snapshot. It carries what the login's capabilities call for — a roster for a lead, on every
+snapshot — and nothing they do not; a capability is withdrawn by a republished `authenticated`,
+never by an omission from a snapshot.
 
 ### `provider-status`
 
@@ -3067,7 +3108,8 @@ each connected provider.
 
 Replaces this provider's complete `TeamRoster`. It is emitted only for an agent the provider
 publishes a roster to, and it carries the whole team every time — never a change to it, for the
-reason set out under **Team leads**. Omitting the roster on a later snapshot withdraws it.
+reason set out under **Team leads**. A lead's snapshot always carries the roster; it goes only when
+a republished `authenticated` no longer declares `capabilities.team`.
 
 ### `contacts-updated`
 
@@ -3106,16 +3148,26 @@ 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 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. |
-| `validateAuthenticationState(state)` | The identity each state must carry, and the expiry that only `authenticated` may. |
+| `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
 once. 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`.
 
+Some rules need to know who is reading. `validateTeamRoster`, `validateSnapshot`, and
+`validateEventEnvelope` take an optional final `{ self, capabilities }` — the signed-in agent's
+`AuthenticationState.identity.id` and their login's `capabilities`. Given `self`, a roster that
+carries that agent reports `team.member.self` or `team.request.self`. Given `capabilities`, a lead's
+snapshot without a roster reports `team.required`, a roster published to a login that does not lead
+reports `team.unentitled`, `requests` on a roster whose login lacks `team.consultControl` reports
+`team.requests.capability`, and a roster without them on a login that declares it reports
+`team.requests.required`. Without them those rules are not checked, because they cannot be.
+`exerciseAdapter` always passes both.
+
 `assertNoViolations(violations)` throws `ProtocolConformanceError` — which carries the full
 `violations` array — when the list is non-empty.
 
@@ -3131,9 +3183,10 @@ reaching the workspace.
 Adapter conformance exercise from `@xema/omni-protocol/testing`.
 
 It validates the manifest, opens an authenticated session, connects, checks required capability
-methods, subscribes, validates the snapshot and every delivered event, states a capacity, then
-unsubscribes and disconnects. Provider packages should run it with a deterministic
-test transport and authentication state.
+methods, subscribes, validates the snapshot, every delivered event, and every authentication state
+the session publishes during the run — each against the latest login, since capabilities are
+current, not fixed — states a capacity, then unsubscribes and disconnects. Provider packages should
+run it with a deterministic test transport and authentication state.
 
 By default it throws `ProtocolConformanceError` listing every violation. Pass
 `{ collectOnly: true }` to receive them on the result instead:
@@ -3144,15 +3197,33 @@ expect(result.violations).toEqual([]);
 expect(result.disconnectWasClean).toBe(true);
 ```
 
-Two properties of the harness matter to adapter authors:
+`result.authenticationState` is the state the session was restored with; `result.login` is the
+latest the session published during the run, which differs only when the adapter republished
+`authenticated`. A published state that fails validation is reported and not adopted, and a
+`refreshing` state must carry over the login it refreshes — a different identity is
+`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
   would unwind through the provider's own dispatch for a synchronous emitter, and would be
   swallowed as an unhandled rejection for an asynchronous one — letting a non-conforming async
   adapter pass.
-- **Resources are released even when the adapter fails.** `unsubscribe()`, `disconnect()`, and
+- **Resources are released even when the adapter fails.** Every unsubscribe, `disconnect()`, and
   `close()` run in a `finally` block, and a throw from any of them is reported as
   `disconnectWasClean: false` rather than being hidden.
+- **The login is read, never captured.** Everything is validated against the latest
+  `authenticated` state, so a withdrawal published before a snapshot is held against that snapshot.
 
 ### Contract scenarios
 
@@ -3161,7 +3232,10 @@ cannot be established from TypeScript structure alone.
 
 | Helper | Contract checked |
 | --- | --- |
-| `assertAuthenticationRestoreAndExpiry(states)` | A restored authenticated session can refresh and ends in expiry. |
+| `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. |
 | `assertWrapTimeout(task, mediaEndedAt, deadline, toleranceMs?)` | The wrap deadline equals media end plus the task allowance, within a tolerance that defaults to 1000ms; a task with no allowance has no deadline, and one observed is the violation. |

package/package.json

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