@zieglar/pi-chat-exchange 0.0.0-stage → 0.2.0

package/dist/host/mcp-binding-config.js

@@ -0,0 +1,209 @@
+/**
+ * HANDOFF-853274 — trusted MCP endpoint binding configuration.
+ *
+ * The MCP server's Endpoint identity comes ONLY from this operator-controlled
+ * launch configuration (passed by absolute path on the command line). MCP tool
+ * arguments never select a sender, endpoint, participant, session, or
+ * capability. This module is a pure validator: it reads no file, no
+ * environment, and never echoes configuration values in its errors (only a
+ * structural field path).
+ */
+import { isAbsolute, normalize } from "node:path";
+import { LEASE_MAX_TTL_SECONDS, LEASE_MIN_TTL_SECONDS } from "../storage/ownership.js";
+export const MCP_BINDING_CONFIG_VERSION = 1;
+export const MCP_DEFAULT_LEASE_TTL_SECONDS = 120;
+export const MCP_DEFAULT_RENEW_INTERVAL_SECONDS = 30;
+/** Upper bound on the configuration file the composition root will read. */
+export const MCP_BINDING_CONFIG_MAX_BYTES = 65_536;
+/** Sanitized configuration refusal: a fixed code plus a structural field path;
+ * never a configuration value. */
+export class McpBindingConfigError extends Error {
+    code = "CE_MCP_CONFIG_INVALID";
+    field;
+    constructor(field) {
+        super(`CE_MCP_CONFIG_INVALID at ${field}`);
+        this.name = "McpBindingConfigError";
+        this.field = field;
+    }
+}
+const LABEL_MAX = { adapter: 64, endpointId: 256, identity: 256 };
+const STORE_FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Capability plaintext never belongs in operator configuration. */
+const CREDENTIAL_SHAPED = /cap_[0-9a-f]{16,}/i;
+function plain(value, field, keys, required) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new McpBindingConfigError(field);
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new McpBindingConfigError(field);
+    const own = Reflect.ownKeys(value);
+    const out = {};
+    for (const key of own) {
+        if (typeof key !== "string" || !keys.includes(key))
+            throw new McpBindingConfigError(field);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !("value" in descriptor) || descriptor.enumerable !== true) {
+            throw new McpBindingConfigError(`${field}.${key}`);
+        }
+        out[key] = descriptor.value;
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(out, key))
+            throw new McpBindingConfigError(`${field}.${key}`);
+    }
+    return out;
+}
+function label(value, field, max) {
+    if (typeof value !== "string" || value.length === 0 || value.length > max || value.includes("\u0000")) {
+        throw new McpBindingConfigError(field);
+    }
+    if (CREDENTIAL_SHAPED.test(value))
+        throw new McpBindingConfigError(field);
+    return value;
+}
+function endpointRef(value, field) {
+    const fields = plain(value, field, ["adapter", "endpointId"], ["adapter", "endpointId"]);
+    return Object.freeze({
+        adapter: label(fields.adapter, `${field}.adapter`, LABEL_MAX.adapter),
+        endpointId: label(fields.endpointId, `${field}.endpointId`, LABEL_MAX.endpointId),
+    });
+}
+function storeLocation(value) {
+    const fields = plain(value, "store", ["directory", "file"], ["directory"]);
+    const directory = fields.directory;
+    if (typeof directory !== "string" ||
+        directory.length === 0 ||
+        directory.length > 4096 ||
+        directory.includes("\u0000") ||
+        !isAbsolute(directory) ||
+        normalize(directory) !== directory ||
+        directory === "/" ||
+        directory.endsWith("/")) {
+        throw new McpBindingConfigError("store.directory");
+    }
+    const file = fields.file === undefined ? "ce-store.sqlite" : fields.file;
+    if (typeof file !== "string" || !STORE_FILE_PATTERN.test(file) || file.includes("..")) {
+        throw new McpBindingConfigError("store.file");
+    }
+    return Object.freeze({ directory, file });
+}
+function integer(value, field, min, max) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+        throw new McpBindingConfigError(field);
+    }
+    return value;
+}
+function leasePolicy(value) {
+    if (value === undefined) {
+        return Object.freeze({ ttlSeconds: MCP_DEFAULT_LEASE_TTL_SECONDS, renewIntervalSeconds: MCP_DEFAULT_RENEW_INTERVAL_SECONDS });
+    }
+    const fields = plain(value, "lease", ["ttlSeconds", "renewIntervalSeconds"], []);
+    const ttlSeconds = fields.ttlSeconds === undefined
+        ? MCP_DEFAULT_LEASE_TTL_SECONDS
+        : integer(fields.ttlSeconds, "lease.ttlSeconds", LEASE_MIN_TTL_SECONDS, LEASE_MAX_TTL_SECONDS);
+    // Renewal must happen at least twice per term so one missed tick cannot
+    // let a live process lose its lease.
+    const renewIntervalSeconds = fields.renewIntervalSeconds === undefined
+        ? Math.min(MCP_DEFAULT_RENEW_INTERVAL_SECONDS, Math.floor(ttlSeconds / 2))
+        : integer(fields.renewIntervalSeconds, "lease.renewIntervalSeconds", 1, Math.floor(ttlSeconds / 2));
+    return Object.freeze({ ttlSeconds, renewIntervalSeconds });
+}
+function payloadReadPolicy(value) {
+    if (value === undefined)
+        return Object.freeze({ enabled: false });
+    const fields = plain(value, "payloadRead", ["enabled"], ["enabled"]);
+    if (typeof fields.enabled !== "boolean")
+        throw new McpBindingConfigError("payloadRead.enabled");
+    return Object.freeze({ enabled: fields.enabled });
+}
+/** HANDOFF-CE-E2B-01: the ACK opt-in is validated exactly like `payloadRead`.
+ * Absent means disabled; only a real boolean is accepted, and an unknown or
+ * accessor-backed field refuses with a structural path, never a value. */
+function ackPolicy(value) {
+    if (value === undefined)
+        return Object.freeze({ enabled: false });
+    const fields = plain(value, "ack", ["enabled"], ["enabled"]);
+    if (typeof fields.enabled !== "boolean")
+        throw new McpBindingConfigError("ack.enabled");
+    return Object.freeze({ enabled: fields.enabled });
+}
+/** HANDOFF-CE-DIAG-06: the development execution guard opt-in is validated
+ * exactly like `ack`. Absent means disabled; only a real boolean is accepted,
+ * and an unknown or accessor-backed field refuses with a structural path. */
+function debugExecutionGuardPolicy(value) {
+    if (value === undefined)
+        return Object.freeze({ enabled: false });
+    const fields = plain(value, "debugExecutionGuard", ["enabled"], ["enabled"]);
+    if (typeof fields.enabled !== "boolean")
+        throw new McpBindingConfigError("debugExecutionGuard.enabled");
+    return Object.freeze({ enabled: fields.enabled });
+}
+const MANAGED_TUNNEL_ID = /^tunnel_[A-Za-z0-9]{8,}$/;
+const MANAGED_ORGANIZATION_ID = /^org-[A-Za-z0-9]{1,128}$/;
+/** Managed provenance is validated with the same label discipline as every
+ * other field: strict identity shapes, no credential-shaped strings. */
+function managedMetadata(value) {
+    if (value === undefined)
+        return undefined;
+    const fields = plain(value, "managed", ["tunnelId", "organizationId", "adapter"], ["tunnelId", "adapter"]);
+    const tunnelId = label(fields.tunnelId, "managed.tunnelId", LABEL_MAX.identity);
+    if (!MANAGED_TUNNEL_ID.test(tunnelId))
+        throw new McpBindingConfigError("managed.tunnelId");
+    const adapter = label(fields.adapter, "managed.adapter", LABEL_MAX.adapter);
+    const organizationId = fields.organizationId === undefined
+        ? undefined
+        : label(fields.organizationId, "managed.organizationId", LABEL_MAX.identity);
+    if (organizationId !== undefined && !MANAGED_ORGANIZATION_ID.test(organizationId)) {
+        throw new McpBindingConfigError("managed.organizationId");
+    }
+    return Object.freeze({ tunnelId, ...(organizationId === undefined ? {} : { organizationId }), adapter });
+}
+/** Validate an already-parsed JSON value. Unknown fields, wrong types, unsafe
+ * paths, out-of-range lease settings, duplicate or self-referencing
+ * recipients, and credential-shaped strings are all refused. */
+export function parseMcpBindingConfig(raw) {
+    const fields = plain(raw, "config", ["version", "store", "exchange", "endpoint", "recipients", "lease", "payloadRead", "ack", "debugExecutionGuard", "managed", "admissionPolicy"], ["version", "store", "exchange", "endpoint", "recipients"]);
+    if (fields.version !== MCP_BINDING_CONFIG_VERSION)
+        throw new McpBindingConfigError("config.version");
+    const store = storeLocation(fields.store);
+    const exchangeFields = plain(fields.exchange, "exchange", ["namespace", "idempotencyKey"], ["namespace", "idempotencyKey"]);
+    const exchange = Object.freeze({
+        namespace: label(exchangeFields.namespace, "exchange.namespace", LABEL_MAX.identity),
+        idempotencyKey: label(exchangeFields.idempotencyKey, "exchange.idempotencyKey", LABEL_MAX.identity),
+    });
+    const managed = fields.managed === undefined ? undefined : managedMetadata(fields.managed);
+    let admissionPolicy;
+    if (fields.admissionPolicy !== undefined) {
+        const ref = plain(fields.admissionPolicy, "admissionPolicy", ["kind", "profilePath"], ["kind", "profilePath"]);
+        const path = label(ref.profilePath, "admissionPolicy.profilePath", 4096);
+        if (ref.kind !== "ce-multi-session-v1" || !isAbsolute(path) || normalize(path) !== path || /[\u0000-\u001f\u007f]/.test(path))
+            throw new McpBindingConfigError("admissionPolicy");
+        admissionPolicy = Object.freeze({ kind: "ce-multi-session-v1", profilePath: path });
+    }
+    const endpoint = endpointRef(fields.endpoint, "endpoint");
+    if (!Array.isArray(fields.recipients))
+        throw new McpBindingConfigError("recipients");
+    const recipients = [];
+    const seen = new Set();
+    fields.recipients.forEach((entry, index) => {
+        const ref = endpointRef(entry, `recipients[${index}]`);
+        if (ref.adapter === endpoint.adapter || ref.endpointId === endpoint.endpointId || seen.has(ref.endpointId)) {
+            throw new McpBindingConfigError(`recipients[${index}]`);
+        }
+        seen.add(ref.endpointId);
+        recipients.push(ref);
+    });
+    return Object.freeze({
+        store,
+        exchange,
+        endpoint,
+        recipients: Object.freeze(recipients),
+        lease: leasePolicy(fields.lease),
+        payloadRead: payloadReadPolicy(fields.payloadRead),
+        ack: ackPolicy(fields.ack),
+        debugExecutionGuard: debugExecutionGuardPolicy(fields.debugExecutionGuard),
+        ...(managed === undefined ? {} : { managed }),
+        ...(admissionPolicy === undefined ? {} : { admissionPolicy }),
+    });
+}
+//# sourceMappingURL=mcp-binding-config.js.map

package/dist/host/ownership-recovery.js

@@ -0,0 +1,257 @@
+/**
+ * Explicit operator-only stale ownership recovery.
+ *
+ * This is the production caller for CE-TAKEOVER-RECOVERY-CALLER-001. It is not
+ * reachable from MCP tools or model arguments. The caller must identify the
+ * exact durable owner it inspected; only an expired owner may be superseded.
+ * Recovery reuses the existing Session/capability/takeover/release/detach
+ * primitives and never edits ownership rows directly.
+ */
+import { bindSession, detachSession, generateSessionId, LEASE_DEFAULT_TTL_SECONDS, LEASE_MAX_TTL_SECONDS, LEASE_MIN_TTL_SECONDS, readCurrentOwnership, readFencingHighWater, readLeaseStatus, readSessionLifecycle, releaseOwnership, SESSION_ID_PATTERN, takeoverOwnership, } from "../storage/ownership.js";
+import { issueCapability, readParticipantByEndpoint } from "../storage/participant.js";
+const ERROR_DETAIL = {
+    CE_RECOVERY_INVALID_REQUEST: "recovery request rejected",
+    CE_RECOVERY_TARGET_MISMATCH: "configured endpoint does not match a durable Participant",
+    CE_RECOVERY_OWNER_ABSENT: "target endpoint has no ownership row",
+    CE_RECOVERY_OWNER_MISMATCH: "current ownership does not match the operator-confirmed evidence",
+    CE_RECOVERY_OWNER_ACTIVE: "current ownership lease is active; recovery refused",
+    CE_RECOVERY_CLOCK_REGRESSION: "operation clock precedes the persisted lease term",
+    CE_RECOVERY_RACE_LOST: "durable ownership changed during recovery; no retry performed",
+    CE_RECOVERY_BUSY: "durable store is contended; recovery rolled back",
+    CE_RECOVERY_OUTCOME_UNKNOWN: "recovery outcome is unknown; inspect durable state and do not retry",
+    CE_RECOVERY_FAILED: "recovery failed closed",
+};
+export class CeRecoveryError extends Error {
+    code;
+    retryable = false;
+    constructor(code) {
+        super(ERROR_DETAIL[code]);
+        this.code = code;
+        this.name = "CeRecoveryError";
+    }
+}
+function invalid() {
+    throw new CeRecoveryError("CE_RECOVERY_INVALID_REQUEST");
+}
+function plain(value, keys, required) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        invalid();
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        invalid();
+    const result = {};
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !keys.includes(key))
+            invalid();
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !("value" in descriptor) || descriptor.enumerable !== true)
+            invalid();
+        result[key] = descriptor.value;
+    }
+    if (required.some((key) => !Object.hasOwn(result, key)))
+        invalid();
+    return result;
+}
+function label(value, maximum) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum || value.includes("\u0000"))
+        invalid();
+    return value;
+}
+function instant(value, nullable = false) {
+    if (nullable && value === null)
+        return null;
+    if (typeof value !== "string")
+        invalid();
+    const milliseconds = Date.parse(value);
+    if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== value)
+        invalid();
+    return value;
+}
+function normalizeRequest(input) {
+    const fields = plain(input, ["adapter", "endpointId", "expectedOwner", "leaseTtlSeconds"], ["adapter", "endpointId", "expectedOwner"]);
+    const owner = plain(fields.expectedOwner, ["sessionId", "fencingToken", "leaseStartedAt", "expiresAt"], ["sessionId", "fencingToken", "leaseStartedAt", "expiresAt"]);
+    if (typeof owner.sessionId !== "string" || !SESSION_ID_PATTERN.test(owner.sessionId))
+        invalid();
+    if (typeof owner.fencingToken !== "number" || !Number.isSafeInteger(owner.fencingToken) || owner.fencingToken < 1)
+        invalid();
+    const ttl = fields.leaseTtlSeconds === undefined ? LEASE_DEFAULT_TTL_SECONDS : fields.leaseTtlSeconds;
+    if (typeof ttl !== "number" ||
+        !Number.isSafeInteger(ttl) ||
+        ttl < LEASE_MIN_TTL_SECONDS ||
+        ttl > LEASE_MAX_TTL_SECONDS)
+        invalid();
+    return Object.freeze({
+        adapter: label(fields.adapter, 64),
+        endpointId: label(fields.endpointId, 256),
+        expectedOwner: Object.freeze({
+            sessionId: owner.sessionId,
+            fencingToken: owner.fencingToken,
+            leaseStartedAt: instant(owner.leaseStartedAt, true),
+            expiresAt: instant(owner.expiresAt),
+        }),
+        leaseTtlSeconds: ttl,
+    });
+}
+function exactOwner(actual, expected) {
+    return actual.sessionId === expected.sessionId &&
+        actual.fencingToken === expected.fencingToken &&
+        actual.leaseStartedAt === expected.leaseStartedAt &&
+        actual.expiresAt === expected.expiresAt;
+}
+function property(error, name) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    return Object.getOwnPropertyDescriptor(error, name)?.value;
+}
+/** Classification valid ONLY before the takeover commits: every outcome here is
+ * either a refusal or a proven rollback. */
+function mapPreWriteError(error) {
+    if (error instanceof CeRecoveryError)
+        return error;
+    if (property(error, "outcome") === "INDETERMINATE")
+        return new CeRecoveryError("CE_RECOVERY_OUTCOME_UNKNOWN");
+    const code = property(error, "code");
+    if (code === "OWNERSHIP_HELD" || code === "OWNERSHIP_TAKEOVER_INELIGIBLE" || code === "OWNERSHIP_TAKEOVER_REQUIRED") {
+        return new CeRecoveryError("CE_RECOVERY_RACE_LOST");
+    }
+    if (property(error, "retryable") === true && property(error, "outcome") === "ROLLED_BACK") {
+        return new CeRecoveryError("CE_RECOVERY_BUSY");
+    }
+    return new CeRecoveryError("CE_RECOVERY_FAILED");
+}
+function cleanupKnownOrphan(store, participantId, sessionId, resumeCapability, seams) {
+    try {
+        detachSession(store, { participantId, sessionId, capability: resumeCapability }, seams);
+    }
+    catch {
+        // Best effort only: the primary refusal stays authoritative, exactly as the
+        // shared host seam does for a refused start's orphan Session.
+    }
+}
+/**
+ * Recover one exact expired owner and leave the Participant UNOWNED so its normal
+ * host can acquire a fresh, strictly greater fencing token. The structured
+ * receipt is operator evidence only; it contains identifiers and term evidence,
+ * never capability plaintext or the host secret.
+ */
+export function recoverExpiredOwnership(store, input, seams = {}) {
+    const request = normalizeRequest(input);
+    // Preflight reads stay inside the typed surface: a contended or corrupt store
+    // must not escape as a raw storage error with a misleading CLI diagnosis.
+    let participant;
+    let previous;
+    let status;
+    try {
+        participant = readParticipantByEndpoint(store, request.adapter, request.endpointId);
+        if (participant === undefined)
+            throw new CeRecoveryError("CE_RECOVERY_TARGET_MISMATCH");
+        previous = readCurrentOwnership(store, participant.participantId);
+        status = previous === undefined
+            ? undefined
+            : readLeaseStatus(store, { participantId: participant.participantId }, seams);
+    }
+    catch (error) {
+        throw mapPreWriteError(error);
+    }
+    if (previous === undefined)
+        throw new CeRecoveryError("CE_RECOVERY_OWNER_ABSENT");
+    if (!exactOwner(previous, request.expectedOwner))
+        throw new CeRecoveryError("CE_RECOVERY_OWNER_MISMATCH");
+    if (status === "ACTIVE")
+        throw new CeRecoveryError("CE_RECOVERY_OWNER_ACTIVE");
+    if (status === "CLOCK_REGRESSION")
+        throw new CeRecoveryError("CE_RECOVERY_CLOCK_REGRESSION");
+    if (status !== "EXPIRED")
+        throw new CeRecoveryError("CE_RECOVERY_OWNER_ABSENT");
+    const recoverySessionId = (seams.sessionId ?? generateSessionId)();
+    if (!SESSION_ID_PATTERN.test(recoverySessionId))
+        invalid();
+    let resumeCapability;
+    try {
+        const attachCapability = issueCapability(store, { participantId: participant.participantId, scope: "attach" }, seams).capability;
+        bindSession(store, { participantId: participant.participantId, sessionId: recoverySessionId, capability: attachCapability }, seams);
+        resumeCapability = issueCapability(store, { participantId: participant.participantId, scope: "resume", sessionId: recoverySessionId }, seams).capability;
+        const takeoverCapability = issueCapability(store, { participantId: participant.participantId, scope: "takeover", sessionId: recoverySessionId }, seams).capability;
+        let takeover;
+        try {
+            takeover = takeoverOwnership(store, {
+                participantId: participant.participantId,
+                sessionId: recoverySessionId,
+                capability: takeoverCapability,
+                leaseTtlSeconds: request.leaseTtlSeconds,
+            }, seams);
+        }
+        catch (error) {
+            const mapped = mapPreWriteError(error);
+            if (mapped.code !== "CE_RECOVERY_OUTCOME_UNKNOWN") {
+                cleanupKnownOrphan(store, participant.participantId, recoverySessionId, resumeCapability, seams);
+            }
+            throw mapped;
+        }
+        // The takeover has committed. From here no failure is a proven rollback, so
+        // every later problem is an unknown outcome requiring operator inspection:
+        // reporting "rolled back" or "failed closed" would be untrue.
+        let released;
+        let detached;
+        let highWater;
+        try {
+            seams.afterTakeover?.();
+            released = releaseOwnership(store, {
+                participantId: participant.participantId,
+                sessionId: recoverySessionId,
+                fencingToken: takeover.fencingToken,
+                capability: resumeCapability,
+            }, seams);
+            detached = detachSession(store, { participantId: participant.participantId, sessionId: recoverySessionId, capability: resumeCapability }, seams);
+            const finalOwner = readCurrentOwnership(store, participant.participantId);
+            const lifecycle = readSessionLifecycle(store, { participantId: participant.participantId, sessionId: recoverySessionId });
+            highWater = readFencingHighWater(store, participant.participantId);
+            if (finalOwner !== undefined ||
+                lifecycle.state !== "DETACHED" ||
+                lifecycle.detachedAt === undefined ||
+                highWater !== takeover.fencingToken) {
+                throw new CeRecoveryError("CE_RECOVERY_OUTCOME_UNKNOWN");
+            }
+        }
+        catch {
+            throw new CeRecoveryError("CE_RECOVERY_OUTCOME_UNKNOWN");
+        }
+        return Object.freeze({
+            version: 1,
+            disposition: "RECOVERED",
+            endpoint: Object.freeze({ adapter: request.adapter, endpointId: request.endpointId }),
+            participantId: participant.participantId,
+            supersededOwner: request.expectedOwner,
+            recoverySessionId,
+            takeover: Object.freeze({
+                fencingToken: takeover.fencingToken,
+                leaseStartedAt: takeover.leaseStartedAt,
+                expiresAt: takeover.expiresAt,
+            }),
+            releasedAt: released.releasedAt,
+            detachedAt: detached.detachedAt,
+            final: Object.freeze({
+                ownership: "UNOWNED",
+                fencingHighWater: highWater,
+                recoverySession: "DETACHED",
+            }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CeRecoveryError)
+            throw error;
+        if (resumeCapability !== undefined) {
+            try {
+                const current = readCurrentOwnership(store, participant.participantId);
+                if (current === undefined || current.sessionId !== recoverySessionId) {
+                    cleanupKnownOrphan(store, participant.participantId, recoverySessionId, resumeCapability, seams);
+                }
+            }
+            catch {
+                // Best effort only: the original failure stays authoritative.
+            }
+        }
+        throw mapPreWriteError(error);
+    }
+}
+//# sourceMappingURL=ownership-recovery.js.map

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Public library surface of pi-chat-exchange: the frozen protocol contracts
+ * and the pure core rules (plus the in-memory idempotency reference).
+ * Control surfaces and endpoint integrations are internal seams, not re-exported;
+ * `src/bin` composes the MCP smoke entrypoint.
+ */
+export * from "./protocol/index.js";
+export * from "./core/rules.js";
+export * from "./core/reference.js";
+export * from "./core/authorization.js";
+//# sourceMappingURL=index.js.map

package/dist/protocol/capabilities.js

@@ -0,0 +1,46 @@
+/**
+ * Action/capability contracts (PH-0003). Endpoint peers have no protocol role.
+ * These plain contexts are TRUSTED HOST INPUT, not self-issued credentials.
+ * The future host authenticates identity and loads grants transactionally.
+ * Interface implementation and support advertisement confer no authority.
+ */
+import { Type } from "@sinclair/typebox";
+import { EndpointRefSchema } from "./entities.js";
+import { EXCHANGE_ID_PATTERN, MESSAGE_ID_PATTERN, ATTEMPT_ID_PATTERN } from "./identity.js";
+const ExchangeIdSchema = Type.String({ pattern: EXCHANGE_ID_PATTERN.source });
+const MessageIdSchema = Type.String({ pattern: MESSAGE_ID_PATTERN.source });
+const AttemptIdSchema = Type.String({ pattern: ATTEMPT_ID_PATTERN.source });
+export const CONTROL_OPERATIONS = ["exchange_send", "exchange_get", "exchange_list", "exchange_cancel", "exchange_result"];
+export const OPTIONAL_CONTROL_CAPABILITIES = ["exchange_close", "exchange_archive"];
+export const ENDPOINT_OPERATIONS = ["message_claim", "dispatch_mark_started", "delivery_report", "activity_report", "settlement_report", "result_publish", "lease_release", "ambiguity_resolve", "cancel_confirm"];
+const strict = { additionalProperties: false };
+const principal = Type.String({ minLength: 1, maxLength: 256 });
+const collectionScope = Type.Object({ kind: Type.Literal("collection") }, strict);
+const exchangeScope = Type.Object({ kind: Type.Literal("exchange"), exchangeId: ExchangeIdSchema }, strict);
+const ownerScope = Type.Object({ kind: Type.Literal("owner"), exchangeId: ExchangeIdSchema, ownerId: principal }, strict);
+const messageScope = Type.Object({ kind: Type.Literal("message"), exchangeId: ExchangeIdSchema, messageId: MessageIdSchema }, strict);
+const destinationScope = Type.Object({ kind: Type.Literal("destination"), exchangeId: ExchangeIdSchema, messageId: MessageIdSchema, endpoint: EndpointRefSchema }, strict);
+const attemptScope = Type.Object({ kind: Type.Literal("attempt"), exchangeId: ExchangeIdSchema, messageId: MessageIdSchema, attemptId: AttemptIdSchema, endpoint: EndpointRefSchema }, strict);
+const actions = (names) => Type.Union(names.map((name) => Type.Literal(name)));
+export const ActionGrantSchema = Type.Union([
+    Type.Object({ action: actions(["exchange_send", "exchange_get", "exchange_result"]), principalId: principal, scope: exchangeScope }, strict),
+    Type.Object({ action: Type.Literal("exchange_list"), principalId: principal, scope: collectionScope }, strict),
+    Type.Object({ action: actions(OPTIONAL_CONTROL_CAPABILITIES), principalId: principal, scope: ownerScope }, strict),
+    Type.Object({ action: Type.Literal("exchange_cancel"), principalId: principal, scope: messageScope }, strict),
+    Type.Object({ action: Type.Literal("message_claim"), principalId: principal, scope: destinationScope }, strict),
+    Type.Object({ action: actions(ENDPOINT_OPERATIONS.filter((action) => action !== "message_claim")), principalId: principal, scope: attemptScope }, strict),
+]);
+export const AuthorizationContextSchema = Type.Object({ principalId: principal, grants: Type.Array(ActionGrantSchema) }, strict);
+export function isControlOperation(name) {
+    return CONTROL_OPERATIONS.includes(name);
+}
+export function isEndpointOperation(name) {
+    return ENDPOINT_OPERATIONS.includes(name);
+}
+/** Catalog separation is a development check, not host authorization. */
+export function assertOperationSeparation() {
+    if ([...CONTROL_OPERATIONS, ...OPTIONAL_CONTROL_CAPABILITIES].some(isEndpointOperation)) {
+        throw new Error("control and endpoint action catalogs overlap");
+    }
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/protocol/endpoint-capabilities.js

@@ -0,0 +1,15 @@
+/** Support advertisements are not evidence or authorization. No runtime binding. */
+import { Type } from "@sinclair/typebox";
+export const CapabilitySupportSchema = Type.Union([Type.Literal("supported"), Type.Literal("unsupported"), Type.Literal("unknown")]);
+export const EndpointCapabilitiesSchema = Type.Object({
+    delivery: CapabilitySupportSchema,
+    observation: Type.Optional(CapabilitySupportSchema),
+    cancellation: Type.Optional(CapabilitySupportSchema),
+    followup: Type.Optional(CapabilitySupportSchema),
+    resultProduction: Type.Optional(CapabilitySupportSchema),
+}, { additionalProperties: false });
+/** Missing support remains UNKNOWN. Nothing here creates a receipt or runtime fact. */
+export function endpointCapabilitySupport(capabilities, capability) {
+    return capabilities[capability] ?? "unknown";
+}
+//# sourceMappingURL=endpoint-capabilities.js.map