@xema/omni-protocol 0.1.0

package/dist/index.js

@@ -0,0 +1,185 @@
+// The Omni protocol.
+//
+// Where this file and guide.md disagree, the guide is right and this is a defect.
+/** The protocol version implemented by this package. */
+export const OMNI_PROTOCOL_VERSION = 1;
+/** Every version this package can interoperate with. */
+export const OMNI_SUPPORTED_PROTOCOL_VERSIONS = [OMNI_PROTOCOL_VERSION];
+/**
+ * Highest version supported by both the adapter and the host, or `undefined` when they cannot
+ * interoperate. Omni must refuse to connect on `undefined` rather than attempting partial
+ * compatibility.
+ */
+export function negotiateProtocolVersion(adapterVersions, hostVersions = OMNI_SUPPORTED_PROTOCOL_VERSIONS) {
+    const host = new Set(hostVersions);
+    const shared = adapterVersions.filter(version => host.has(version));
+    return shared.length === 0 ? undefined : Math.max(...shared);
+}
+/** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
+export const IDLE_CAPABILITIES = ["dial", "personalBrowser", "calendar", "contacts"];
+/** What Omni calls each idle capability. */
+export const IDLE_CAPABILITY_UI = {
+    dial: "Dialpad",
+    personalBrowser: "Browser",
+    calendar: "Calendar",
+    contacts: "Contacts",
+};
+// ---------------------------------------------------------------------------
+// Task workspace.
+// ---------------------------------------------------------------------------
+/**
+ * How a reusing browser's session is keyed.
+ *
+ * Named constants rather than a bare union because the values are structured strings: easy to
+ * mistype and unreadable as an argument.
+ */
+export const BROWSER_ISOLATION_SCHEMES = {
+    PROVIDER_NAME__TASK_ID__TAB_NAME: "ProviderName.TaskId.TabName",
+    TAB_NAME: "TabName",
+    PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME: "ProviderName.TaskTypeName.TabName",
+    PROVIDER_NAME__TAB_NAME: "ProviderName.TabName",
+    PROVIDER_NAME__TASK_TYPE_NAME: "ProviderName.TaskTypeName",
+    TASK_TYPE_NAME__TAB_NAME: "TaskTypeName.TabName",
+};
+export const ALLOWED_BROWSER_URL_SCHEMES = ["http:", "https:"];
+export function isAllowedBrowserUrl(url) {
+    try {
+        return ALLOWED_BROWSER_URL_SCHEMES.includes(new URL(url).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Task commands.
+// ---------------------------------------------------------------------------
+export const TASK_COMMAND_NAMES = {
+    voice: ["answer", "decline", "start-call", "mute", "hold", "resume", "disconnect",
+        "transfer", "conference", "recording", "complete"],
+    chat: ["accept", "reject", "pause", "resume", "complete"],
+    email: ["accept", "reject", "complete"],
+};
+export const BREAK_KINDS = [
+    "short-break", "meal", "rest", "training", "coaching",
+    "meeting", "administrative", "technical", "personal", "other",
+];
+export const OMNI_FAILURE_CODES = [
+    "omni.not-authenticated",
+    "omni.capability-not-enabled",
+    "omni.task-not-found",
+    "omni.destination-not-permitted",
+    "omni.rate-limited",
+    "omni.unavailable",
+    "omni.break-already-committed",
+];
+/**
+ * Preserves the adapter's inferred concrete type while checking it implements `Adapter`.
+ * No connection, no runtime side effects.
+ */
+export function defineAdapter(adapter) {
+    return adapter;
+}
+// ---------------------------------------------------------------------------
+// Presentation defaults.
+// ---------------------------------------------------------------------------
+export const DEFAULT_TASK_PHASE_LABELS = {
+    voice: {
+        pending: "Offered", confirmed: "Accepted", preparing: "Preview",
+        "in-progress": "On Call", paused: "On Hold", completing: "After Call Work",
+    },
+    chat: {
+        pending: "Incoming Chat", confirmed: "Accepted", preparing: "Preparing",
+        "in-progress": "In Chat", paused: "Paused", completing: "Wrap-up",
+    },
+    email: {
+        pending: "Assigned", confirmed: "Accepted", preparing: "Reviewing",
+        "in-progress": "Working", paused: "Paused", completing: "Completing",
+    },
+};
+export const DEFAULT_TASK_TYPE_PRESENTATION = {
+    voice: { singular: "Call", plural: "Calls", referenceLabel: "Call ID" },
+    chat: { singular: "Chat", plural: "Chats", referenceLabel: "Chat ID" },
+    email: { singular: "Email", plural: "Emails", referenceLabel: "Email ID" },
+};
+// ---------------------------------------------------------------------------
+// Utilities.
+// ---------------------------------------------------------------------------
+/**
+ * A collision-safe global task key.
+ *
+ * Task ids are unique only within one provider, so two providers will eventually issue the same
+ * string. Encoding before joining is what stops a provider id containing a separator from
+ * forging another provider's key.
+ */
+export const taskKey = (providerId, taskId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(taskId)}`;
+/**
+ * The same treatment for a `UserId`, and needed for the same reason.
+ *
+ * There is no Omni-wide user identity: one person on several providers has several identities
+ * and nothing here pairs them. A bare `UserId` is only ever compared against another from the
+ * same provider; anything wider goes through this.
+ */
+export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
+/** Every handling step somebody takes part in. `queued` is the one nobody does. */
+export const HANDLING_STEPS_WITH_A_PERSON = [
+    "offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered",
+];
+/** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
+export function handlingStepExpectsAPerson(step) {
+    return HANDLING_STEPS_WITH_A_PERSON.includes(step);
+}
+/**
+ * The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
+ *
+ * Fails closed. A browser with `reuse: false` has no key; nor does a reusing one whose scheme is
+ * missing or unknown -- the type forbids that, but an adapter compiled against another version can
+ * still send it, and the safe reading is "do not share", never "share with everyone named the
+ * same". Every part is encoded, separator included, before joining, so a tab called `a.b`
+ * cannot collide with a provider called `a` and a tab called `b`.
+ */
+export function browserSessionKey(input) {
+    const { providerId, taskId, taskType, browser } = input;
+    if (browser.reuse !== true)
+        return undefined;
+    // `encodeURIComponent` leaves `.` untouched, and `.` is the separator: a raw join would let
+    // provider `Acme.Voice` with type `Support` forge the key of `Acme` with `Voice.Support`.
+    const part = (value) => encodeURIComponent(value).replaceAll(".", "%2E");
+    switch (browser.isolationScheme) {
+        case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_ID__TAB_NAME:
+            return `${part(providerId)}.${part(taskId)}.${part(browser.name)}`;
+        case BROWSER_ISOLATION_SCHEMES.TAB_NAME:
+            return part(browser.name);
+        case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME__TAB_NAME:
+            return `${part(providerId)}.${part(taskType)}.${part(browser.name)}`;
+        case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TAB_NAME:
+            return `${part(providerId)}.${part(browser.name)}`;
+        case BROWSER_ISOLATION_SCHEMES.PROVIDER_NAME__TASK_TYPE_NAME:
+            return `${part(providerId)}.${part(taskType)}`;
+        case BROWSER_ISOLATION_SCHEMES.TASK_TYPE_NAME__TAB_NAME:
+            return `${part(taskType)}.${part(browser.name)}`;
+        default:
+            return undefined;
+    }
+}
+/**
+ * The comparison key for a contact number. Never for display: keep the original value for that.
+ *
+ * Applies NFKC, strips whitespace, brackets, slashes, periods and every Unicode dash, and rewrites
+ * a leading `00` to `+`, so `+1 (415) 555-0100`, `+1.415.555.0100` and `0014155550100` all merge.
+ * Cross-provider merging is reliable only for E.164 input: a national-format number carries no
+ * country context, nothing in this protocol supplies one, and so it does not merge with its
+ * `+`-prefixed twin.
+ */
+export function normalizeContactNumber(number) {
+    const compact = number
+        .normalize("NFKC")
+        .trim()
+        .replace(/[\s\p{Pd}().\/\\[\]]/gu, "")
+        .replace(/^00/, "+");
+    const digits = compact.replace(/\D/g, "");
+    return compact.startsWith("+") ? `+${digits}` : digits;
+}
+/** The comparison key for a contact email. Never for display. */
+export function normalizeContactEmail(email) {
+    return email.normalize("NFKC").trim().toLocaleLowerCase("en-US");
+}

package/dist/testing.d.ts

@@ -0,0 +1,62 @@
+import { type Adapter, type AuthenticationState, type ProviderEventEnvelope, type Connection, type Snapshot, type Task, type BreakApproval, type BrowserSessionKeyInput, type Channel, type ConnectContext, type DialRequest, type TaskCommandRequest } from "./index.js";
+import { type ProtocolViolation } from "./validation.js";
+export { ProtocolConformanceError, assertNoViolations, type ProtocolViolation } from "./validation.js";
+export interface AdapterContractResult {
+    events: ProviderEventEnvelope[];
+    authenticationState: AuthenticationState;
+    /** True only when `disconnect()` and `close()` both settled without throwing. */
+    disconnectWasClean: boolean;
+    /** Every violation observed. Non-empty only when `collectOnly` suppressed the throw. */
+    violations: readonly ProtocolViolation[];
+}
+export interface ExerciseAdapterOptions {
+    /** Return violations in the result instead of throwing. Defaults to `false`. */
+    collectOnly?: boolean;
+}
+/**
+ * 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.
+ *
+ * Violations are collected rather than thrown from inside the adapter's own
+ * dispatch path. Throwing from a subscribe listener unwinds through the provider
+ * for a synchronous emitter, and is swallowed as an unhandled rejection for an
+ * asynchronous one — which would let a non-conforming async adapter pass.
+ */
+export declare function exerciseAdapter<C extends Channel>(adapter: Adapter<C>, context: ConnectContext, options?: ExerciseAdapterOptions): Promise<AdapterContractResult>;
+/** Verifies the at-most-once contract by issuing the same command twice. */
+export declare function assertCommandIdempotency(connection: Pick<Connection, "execute">, request: TaskCommandRequest): Promise<void>;
+/** Validates restored authentication followed by a refresh failure or expiry. */
+export declare function assertAuthenticationRestoreAndExpiry(states: readonly AuthenticationState[]): 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. */
+export declare function assertReconnectWithMissedAssignments<C extends Channel>(before: Snapshot<C>, reconnect: ProviderEventEnvelope<C>, missedTaskIds: readonly string[]): void;
+/**
+ * Validates a refused break followed by a later request that is granted.
+ *
+ * There is no `denied` approval: a refusal returns the agent to `not-requested`, because a
+ * pending request nobody is coming to decide is worse than none. So the scenario is a request
+ * that goes back to not-requested, and a later one that is granted.
+ */
+export declare function assertDeniedAndRetriedBreak(approvals: readonly BreakApproval[]): void;
+/** Verifies that retrying one dial command cannot place a second call. */
+export declare function assertDialIdempotency(connection: Pick<Connection, "dial">, request: DialRequest): Promise<void>;
+/**
+ * Validates the deadline derived from media end and the task's fixed wrap allowance.
+ * `toleranceMs` absorbs scheduler jitter in a real implementation; pass 0 to demand
+ * an exact match.
+ */
+export declare function assertWrapTimeout(task: Pick<Task, "completionAllowance">, mediaEndedAt: string, observedDeadline: string, toleranceMs?: number): void;
+/** One browser in one task of one provider. `providerId` is `Manifest.id`, never `displayName`. */
+export type BrowserIsolationScenario = BrowserSessionKeyInput;
+/** Validates whether two task-browser definitions should share one browser session. */
+export declare function assertBrowserIsolationAndReuse(left: BrowserIsolationScenario, right: BrowserIsolationScenario, expectedReuse: boolean): void;
+/**
+ * Asserts that no two distinct scenarios in `scenarios` derive the same session key.
+ * Feed it adversarial names — a provider called `A.B` against a task type called
+ * `B`, casing variants, separators — because a collision silently shares cookies,
+ * storage, and permissions between two backends.
+ */
+export declare function assertNoBrowserSessionKeyCollisions(scenarios: readonly BrowserIsolationScenario[]): void;

package/dist/testing.js

@@ -0,0 +1,294 @@
+import { browserSessionKey, } from "./index.js";
+import { assertNoViolations, validateAuthenticationState, validateEventEnvelope, validateManifest, validateSnapshot, } from "./validation.js";
+export { ProtocolConformanceError, assertNoViolations } from "./validation.js";
+/**
+ * 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.
+ *
+ * Violations are collected rather than thrown from inside the adapter's own
+ * dispatch path. Throwing from a subscribe listener unwinds through the provider
+ * for a synchronous emitter, and is swallowed as an unhandled rejection for an
+ * asynchronous one — which would let a non-conforming async adapter pass.
+ */
+export async function exerciseAdapter(adapter, context, options = {}) {
+    const violations = [...validateManifest(adapter.manifest)];
+    const events = [];
+    const storedSecrets = new Map();
+    const authentication = await adapter.createAuthenticationSession({
+        ...context,
+        secrets: {
+            get: async (key) => storedSecrets.get(key),
+            set: async (key, value) => { storedSecrets.set(key, value); },
+            delete: async (key) => { storedSecrets.delete(key); },
+        },
+    });
+    let connection;
+    let unsubscribe;
+    let authenticationState;
+    let disconnectWasClean = false;
+    try {
+        authenticationState = await authentication.state();
+        violations.push(...validateAuthenticationState(authenticationState));
+        if (authenticationState.status !== "authenticated") {
+            throw new Error(`Adapter contract exercise requires authenticated test state, received ${authenticationState.status}`);
+        }
+        connection = await adapter.connect(context);
+        const live = connection;
+        // 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}()`,
+                });
+            }
+        };
+        // 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");
+        // 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");
+        const eventIds = new Set();
+        unsubscribe = connection.subscribe(envelope => {
+            violations.push(...validateEventEnvelope(envelope, adapter.manifest));
+            if (typeof envelope?.id === "string") {
+                if (eventIds.has(envelope.id))
+                    return;
+                eventIds.add(envelope.id);
+            }
+            events.push(envelope);
+        });
+        const snapshot = await connection.snapshot();
+        violations.push(...validateSnapshot(snapshot, adapter.manifest));
+        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 (publishesUserIds(snapshot))
+            requireMethod("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 });
+        if (capacity.status === "failed") {
+            violations.push({
+                rule: "connection.setCapacity.failed",
+                path: "connection.setCapacity",
+                message: `the provider would not accept a capacity: ${capacity.failure.code}`,
+            });
+        }
+    }
+    finally {
+        let clean = true;
+        try {
+            unsubscribe?.();
+        }
+        catch {
+            clean = false;
+        }
+        try {
+            await connection?.disconnect();
+        }
+        catch {
+            clean = false;
+        }
+        try {
+            await authentication.close();
+        }
+        catch {
+            clean = false;
+        }
+        disconnectWasClean = clean;
+    }
+    if (!disconnectWasClean) {
+        violations.push({
+            rule: "connection.disconnect.clean",
+            path: "connection.disconnect",
+            message: "unsubscribe(), disconnect(), or close() threw during shutdown",
+        });
+    }
+    if (!options.collectOnly)
+        assertNoViolations(violations);
+    return {
+        events: events,
+        authenticationState: authenticationState,
+        disconnectWasClean,
+        violations,
+    };
+}
+/**
+ * Whether a snapshot carries any `UserId`, which is what obliges an adapter to describe users.
+ * The snapshot is untrusted input that has already been reported on, so nothing here assumes
+ * its shape.
+ */
+function publishesUserIds(snapshot) {
+    if (snapshot?.break?.imposed?.by !== undefined)
+        return true;
+    if (Array.isArray(snapshot?.team?.members) && snapshot.team.members.length > 0)
+        return true;
+    if (!Array.isArray(snapshot?.tasks))
+        return false;
+    return snapshot.tasks.some(task => Array.isArray(task?.handlingHistory) && task.handlingHistory.some(step => step?.by !== undefined));
+}
+/** Verifies the at-most-once contract by issuing the same command twice. */
+export async function assertCommandIdempotency(connection, request) {
+    const first = await connection.execute(request);
+    if (first.commandId !== request.commandId)
+        throw new Error("Command result id mismatch");
+    if (first.status === "failed") {
+        throw new Error(`Command failed: ${first.failure.code}`);
+    }
+    const retry = await connection.execute(request);
+    if (retry.commandId !== request.commandId)
+        throw new Error("Retried command result id mismatch");
+    if (retry.status !== "already-applied") {
+        throw new Error(`Retried command must return already-applied, received ${retry.status}`);
+    }
+}
+/** Validates restored authentication followed by a refresh failure or expiry. */
+export function assertAuthenticationRestoreAndExpiry(states) {
+    if (states.length < 2 || states[0]?.status !== "authenticated") {
+        throw new Error("Authentication scenario must start with a restored authenticated state");
+    }
+    const expiredIndex = states.findIndex(state => state.status === "expired");
+    if (expiredIndex < 1 || states.at(-1)?.status !== "expired") {
+        throw new Error("Authentication scenario must end in an expired state");
+    }
+    const refreshingIndex = states.findIndex(state => state.status === "refreshing");
+    if (refreshingIndex >= 0 && refreshingIndex > expiredIndex) {
+        throw new Error("Refreshing state must occur before expiry");
+    }
+}
+/** Validates duplicate delivery and returns the event sequence Omni applies once per ID. */
+export function assertDuplicateEventDelivery(envelopes) {
+    const byId = new Map();
+    let duplicateFound = false;
+    for (const envelope of envelopes) {
+        const existing = byId.get(envelope.id);
+        if (!existing) {
+            byId.set(envelope.id, envelope);
+            continue;
+        }
+        duplicateFound = true;
+        if (JSON.stringify(existing) !== JSON.stringify(envelope)) {
+            throw new Error(`Duplicate event ID '${envelope.id}' changed its payload`);
+        }
+    }
+    if (!duplicateFound)
+        throw new Error("Duplicate delivery scenario requires a repeated event ID");
+    return [...byId.values()];
+}
+/** Validates an authoritative reconnect snapshot containing assignments missed while offline. */
+export function assertReconnectWithMissedAssignments(before, reconnect, missedTaskIds) {
+    if (reconnect.event.type !== "snapshot" || reconnect.event.reason !== "reconnected") {
+        throw new Error("Reconnect scenario requires a reconnected snapshot event");
+    }
+    const beforeIds = new Set(before.tasks.map(task => task.id));
+    const refreshedIds = new Set(reconnect.event.snapshot.tasks.map(task => task.id));
+    for (const taskId of missedTaskIds) {
+        if (beforeIds.has(taskId))
+            throw new Error(`Task '${taskId}' was not missed before reconnect`);
+        if (!refreshedIds.has(taskId))
+            throw new Error(`Reconnect snapshot is missing task '${taskId}'`);
+    }
+}
+/**
+ * Validates a refused break followed by a later request that is granted.
+ *
+ * There is no `denied` approval: a refusal returns the agent to `not-requested`, because a
+ * pending request nobody is coming to decide is worse than none. So the scenario is a request
+ * that goes back to not-requested, and a later one that is granted.
+ */
+export function assertDeniedAndRetriedBreak(approvals) {
+    const asked = approvals.indexOf("awaiting-decision");
+    if (asked < 0)
+        throw new Error("Break retry scenario requires an initial request");
+    const refused = approvals.indexOf("not-requested", asked + 1);
+    if (refused < 0)
+        throw new Error("A refused break must return to not-requested, leaving nothing pending");
+    const granted = approvals.findIndex((approval, index) => index > refused && (approval === "granted" || approval === "in-effect"));
+    if (granted < 0)
+        throw new Error("Break retry scenario must grant a later request");
+    const last = approvals.at(-1);
+    if (last !== "granted" && last !== "in-effect") {
+        throw new Error(`Break retry scenario must end granted or in effect, ended ${String(last)}`);
+    }
+}
+/** Verifies that retrying one dial command cannot place a second call. */
+export async function assertDialIdempotency(connection, request) {
+    if (!connection.dial)
+        throw new Error("Dial capability requires Connection.dial()");
+    const first = await connection.dial(request);
+    if (first.commandId !== request.commandId)
+        throw new Error("Dial result id mismatch");
+    if (first.status === "failed")
+        throw new Error(`Dial failed: ${first.failure.code}`);
+    const retry = await connection.dial(request);
+    if (retry.commandId !== request.commandId)
+        throw new Error("Retried dial result id mismatch");
+    // Each method answers in its own words: a retried dial says already-dialled, not
+    // already-applied, because what it did was dial.
+    if (retry.status !== "already-dialled") {
+        throw new Error(`Retried dial must return already-dialled, received ${retry.status}`);
+    }
+}
+/**
+ * Validates the deadline derived from media end and the task's fixed wrap allowance.
+ * `toleranceMs` absorbs scheduler jitter in a real implementation; pass 0 to demand
+ * an exact match.
+ */
+export function assertWrapTimeout(task, mediaEndedAt, observedDeadline, toleranceMs = 1_000) {
+    const ended = Date.parse(mediaEndedAt);
+    const deadline = Date.parse(observedDeadline);
+    if (Number.isNaN(ended) || Number.isNaN(deadline))
+        throw new Error("Wrap scenario requires valid ISO-8601 times");
+    const expected = ended + task.completionAllowance * 1_000;
+    if (Math.abs(deadline - expected) > toleranceMs) {
+        throw new Error(`Wrap deadline mismatch: expected ${new Date(expected).toISOString()} within ${toleranceMs}ms, received ${observedDeadline}`);
+    }
+}
+/** The session key one scenario derives, or `undefined` where the browser shares nothing. */
+const sessionKeyFor = (scenario) => browserSessionKey(scenario);
+/** Validates whether two task-browser definitions should share one browser session. */
+export function assertBrowserIsolationAndReuse(left, right, expectedReuse) {
+    const leftKey = sessionKeyFor(left);
+    const rightKey = sessionKeyFor(right);
+    // A browser that does not reuse has no session key at all, so two of them never share one.
+    // Treating "no key" as a match would report reuse nobody asked for.
+    const actualReuse = leftKey !== undefined && leftKey === rightKey;
+    if (actualReuse !== expectedReuse) {
+        throw new Error(`Browser reuse mismatch: expected ${expectedReuse}, received ${actualReuse} (${String(leftKey)} vs ${String(rightKey)})`);
+    }
+}
+/**
+ * Asserts that no two distinct scenarios in `scenarios` derive the same session key.
+ * Feed it adversarial names — a provider called `A.B` against a task type called
+ * `B`, casing variants, separators — because a collision silently shares cookies,
+ * storage, and permissions between two backends.
+ */
+export function assertNoBrowserSessionKeyCollisions(scenarios) {
+    const byKey = new Map();
+    for (const scenario of scenarios) {
+        const key = sessionKeyFor(scenario);
+        if (key === undefined)
+            continue;
+        const existing = byKey.get(key);
+        if (existing) {
+            throw new Error(`Browser session key collision on '${key}': ` +
+                `${JSON.stringify({ provider: existing.providerId, taskType: existing.taskType, tab: existing.browser.name })} and ` +
+                `${JSON.stringify({ provider: scenario.providerId, taskType: scenario.taskType, tab: scenario.browser.name })}`);
+        }
+        byKey.set(key, scenario);
+    }
+}

package/dist/validation.d.ts

@@ -0,0 +1,21 @@
+import { type ProtocolViolation } from "./index.js";
+export type { ProtocolViolation } from "./index.js";
+export declare class ProtocolConformanceError extends Error {
+    readonly violations: readonly ProtocolViolation[];
+    constructor(violations: readonly ProtocolViolation[], summary?: string);
+}
+/** Throws `ProtocolConformanceError` when any violation is present. */
+export declare function assertNoViolations(violations: readonly ProtocolViolation[], summary?: string): void;
+/** Every field is optional, so this checks what is present rather than what is missing. */
+export declare function validateContact(contact: unknown, path?: string): ProtocolViolation[];
+export declare function validateScheduledActivity(activity: unknown, path?: string): ProtocolViolation[];
+export declare function validateManifest(manifest: unknown, path?: string): ProtocolViolation[];
+export interface TaskValidationContext {
+    /** The provider's channel, from its manifest. A task must agree with it. */
+    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[];
+export declare function validateAuthenticationState(state: unknown, path?: string): ProtocolViolation[];