@motebit/protocol 1.2.0 → 2.0.0

package/README.md

@@ -37,11 +37,13 @@ const relayFee = PLATFORM_FEE_RATE; // 0.05 — the universal 5% relay fee.
 - **Identity** — `MotebitIdentity`, `KeySuccessionRecord`, `DeviceRegistration`
 - **Execution receipts** — `ExecutionReceipt` with nested delegation chains
 - **Credentials** — W3C VC 2.0 types (`ReputationCredentialSubject`, `TrustCredentialSubject`)
-- **Settlement** — `BudgetAllocation`, `SettlementRecord`, `PLATFORM_FEE_RATE`
+- **Settlement** — `BudgetAllocation`, `SettlementRecord`, `PLATFORM_FEE_RATE`; `SettlementMode` closed union (`"relay" | "p2p"`) with `ALL_SETTLEMENT_MODES` for iteration and `isSettlementMode` for narrowing wire-format payloads pulled from discovery / peer-negotiation responses; `SettlementAsset` closed union (`"USDC"` at sub-phase A) with `ALL_SETTLEMENT_ASSETS` for iteration and `isSettlementAsset` for narrowing — the typed vocabulary of stablecoin assets the protocol clears settlement in; `SovereignRail.asset` is structurally tightened to this union so a peer announcing an unknown asset fails closed. **Guest-rail capability marker interfaces** + type guards — `GuestRail` carries `supportsDeposit` / `supportsWithdraw` / `supportsBatch` discriminants; `DepositableGuestRail` / `WithdrawableGuestRail` / `BatchableGuestRail` add the corresponding methods; `isDepositableRail` / `isWithdrawableRail` / `isBatchableRail` narrow at the call site. The marker on `WithdrawableGuestRail` is the structural enforcement of the off-ramp doctrine: rails that don't opt in (e.g., Bridge, treasury-only) cannot drive user-facing withdrawals because `withdraw` does not exist on the base type
 - **Trust algebra** — semiring operations for delegation-chain trust computation
-- **Policy** — `ToolDefinition`, `PolicyDecision`, `RiskLevel`, `SensitivityLevel`
+- **Policy** — `ToolDefinition`, `PolicyDecision`, `RiskLevel`, `SensitivityLevel` (the 5-tier privacy ladder, the most load-bearing closed registry; `ALL_SENSITIVITY_LEVELS` for iteration, `isSensitivityLevel` for narrowing unknown payloads, `rankSensitivity` / `maxSensitivity` / `sensitivityPermits` for the algebra)
+- **Event-log vocabulary** — `EventType` closed enum (59 entries spanning identity / memory / goals / approvals / plans / consolidation / co-browse / agents); `ALL_EVENT_TYPES` for iteration, `isEventType` for narrowing wire-format payloads pulled from sync peers or federation
 - **Storage adapters** — pluggable persistence contracts for any backend
 - **Cryptosuite registry** — `SuiteId` union for crypto-agile wire artifacts
+- **Auto-router registry** — `TaskShape` closed union (`ALL_TASK_SHAPES`, `isTaskShape`) for the model-selection primitive; named constants `QUICK_TASK_SHAPE`, `CHAT_TASK_SHAPE`, `REASONING_TASK_SHAPE`, `CODE_TASK_SHAPE`, `RESEARCH_TASK_SHAPE`, `CREATIVE_TASK_SHAPE`, `MATH_TASK_SHAPE`. Paired with `ProviderCapability` + `RoutingConstraint` + `RoutingDecision` types consumed by `@motebit/policy::dispatchRouting`
 
 Product-level types (state vectors, creature behavior, rendering spec) live in [`@motebit/sdk`](https://www.npmjs.com/package/@motebit/sdk), which re-exports everything here plus the product vocabulary.
 

package/dist/artifact-type.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Content-artifact types — the closed registry of `artifact_type` claim
+ * values for the C2PA-shape content-provenance primitive
+ * (`ContentArtifactManifest` in `@motebit/crypto`).
+ *
+ * Provenance binding (per `docs/doctrine/self-attesting-system.md` and
+ * `docs/doctrine/nist-alignment.md` §8) requires every signed motebit
+ * artifact to carry a producer-declared category so a verifier can
+ * route, audit, or display the artifact without parsing its bytes.
+ * Pre-registry, the category was a free string in the manifest —
+ * a typo at a producer site (`artifact_type: "audit_trail"` instead
+ * of `"audit-trail"`) became a verifier-side classification miss
+ * with no compile-time signal. Locking the registry as a closed
+ * union makes the typo a compile error AND a CI error.
+ *
+ * **Closed registry shape** — same closure pattern as `TokenAudience`,
+ * `SuiteId`, `SettlementRail`, `ToolMode`, `ComputerActionKind`. The
+ * `ContentArtifactType` literal union is the wire law; named
+ * constants are the developer ergonomics. The drift gate
+ * `check-artifact-type-canonical` scans every `artifact_type:
+ * "<literal>"` and `artifactType: "<literal>"` call against
+ * `ALL_CONTENT_ARTIFACT_TYPES`.
+ *
+ * Adding a category is intentional protocol-level work: a new entry
+ * here, a new producer site, the doctrine reference at
+ * `docs/doctrine/nist-alignment.md` §8 updated. Same governance as
+ * cryptosuite agility (`SuiteId` registry) and audience binding
+ * (`TokenAudience` registry).
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+/**
+ * The closed set of content-artifact categories motebit currently
+ * signs. The first twelve cover the state-export endpoints at
+ * `services/relay/src/state-export.ts` (relay-assembled bundles
+ * the relay signs as a witness over its database state per the
+ * recognition note in `docs/doctrine/nist-alignment.md` §8). The
+ * thirteenth — `goal-result` — is the **first non-relay-state-export
+ * consumer**: a motebit-direct, per-fire artifact that the motebit
+ * itself signs as the producer (the agent's own work product, not
+ * a relay-assembled bundle). The expansion is doctrinally aligned —
+ * the registry's stated semantic is "content-artifact category for
+ * C2PA-shape provenance," not "relay state-export bundle." Goals
+ * is the first arc to prove the registry generalizes; future
+ * motebit-direct artifacts (chat-bundle exports, generated documents,
+ * tool-call-result bundles) compose against the same shape.
+ *
+ *   - `state-snapshot` — relay's stored state vector for a motebit
+ *     (`/api/v1/state/:motebitId`)
+ *   - `memory-export` — memory-graph snapshot (nodes + edges) with
+ *     optional sensitivity redaction (`/api/v1/memory/:motebitId`)
+ *   - `goal-list` — motebit's declared goals
+ *     (`/api/v1/goals/:motebitId`)
+ *   - `conversation-list` — conversation index for a motebit
+ *     (`/api/v1/conversations/:motebitId`)
+ *   - `conversation-messages` — message history for a specific
+ *     conversation
+ *     (`/api/v1/conversations/:motebitId/:conversationId/messages`)
+ *   - `device-list` — registered devices for a motebit
+ *     (`/api/v1/devices/:motebitId`)
+ *   - `audit-trail` — `ToolAuditEntry[]` for a motebit's session
+ *     window (`/api/v1/audit/:motebitId`)
+ *   - `plan-list` — plans for a motebit, each carrying its steps
+ *     (`/api/v1/plans/:motebitId`)
+ *   - `plan-detail` — a single plan with its steps
+ *     (`/api/v1/plans/:motebitId/:planId`)
+ *   - `gradient-history` — intelligence-gradient snapshots
+ *     (`/api/v1/gradient/:motebitId`)
+ *   - `sync-pull` — event-log pull beyond a clock cursor
+ *     (`/api/v1/sync/:motebitId/pull`)
+ *   - `execution-ledger` — execution timeline for a goal, including
+ *     inner motebit-signed delegation receipt summaries; the
+ *     canonical layered-signing consumer
+ *     (`/api/v1/execution/:motebitId/:goalId`)
+ *   - `goal-result` — per-fire content motebit produced for a
+ *     scheduled goal. Producer = motebit identity (not relay).
+ *     Doctrine: `docs/doctrine/goal-results.md` §"The three
+ *     categories" — the artifact category's cryptographic
+ *     provenance envelope. Bound to the fire via `invocation`
+ *     (goal_id + execution-receipt id when present).
+ *
+ * Adding an endpoint is intentional protocol-level work: a new
+ * `ContentArtifactType` entry here, a new named constant, a new
+ * `ALL_CONTENT_ARTIFACT_TYPES` member, gate-side `CANONICAL_ARTIFACT_TYPES`
+ * update in `scripts/check-artifact-type-canonical.ts`. Drift gate
+ * `check-state-export-signed` enforces that every new `app.get(...)`
+ * in `services/relay/src/state-export.ts` emits a manifest before
+ * returning — that gate scopes only to relay state-export endpoints,
+ * not to motebit-direct consumers like `goal-result`, which the
+ * runtime signs at fire-time through its own helper.
+ */
+export type ContentArtifactType = "state-snapshot" | "memory-export" | "goal-list" | "conversation-list" | "conversation-messages" | "device-list" | "audit-trail" | "plan-list" | "plan-detail" | "gradient-history" | "sync-pull" | "execution-ledger" | "goal-result";
+/** Relay's stored state-vector snapshot for a motebit. */
+export declare const STATE_SNAPSHOT_ARTIFACT: ContentArtifactType;
+/** Relay-assembled memory-graph snapshot (nodes + edges). */
+export declare const MEMORY_EXPORT_ARTIFACT: ContentArtifactType;
+/** Relay-assembled goal list for a motebit. */
+export declare const GOAL_LIST_ARTIFACT: ContentArtifactType;
+/** Relay-assembled conversation index for a motebit. */
+export declare const CONVERSATION_LIST_ARTIFACT: ContentArtifactType;
+/** Relay-assembled message history for a specific conversation. */
+export declare const CONVERSATION_MESSAGES_ARTIFACT: ContentArtifactType;
+/** Relay-assembled list of devices registered to a motebit. */
+export declare const DEVICE_LIST_ARTIFACT: ContentArtifactType;
+/** Relay-assembled tool-audit-trail export. */
+export declare const AUDIT_TRAIL_ARTIFACT: ContentArtifactType;
+/** Relay-assembled list of plans for a motebit, each with embedded steps. */
+export declare const PLAN_LIST_ARTIFACT: ContentArtifactType;
+/** Relay-assembled single-plan export with its steps. */
+export declare const PLAN_DETAIL_ARTIFACT: ContentArtifactType;
+/** Relay-assembled intelligence-gradient-history export. */
+export declare const GRADIENT_HISTORY_ARTIFACT: ContentArtifactType;
+/** Relay-assembled event-log pull beyond a `version_clock` cursor. */
+export declare const SYNC_PULL_ARTIFACT: ContentArtifactType;
+/**
+ * Relay-assembled execution-timeline export with embedded motebit-signed
+ * delegation receipts. Canonical layered-signing consumer — outer relay
+ * manifest attests bundle assembly, inner motebit signatures pass through
+ * byte-identical. See `spec/execution-ledger-v1.md`.
+ */
+export declare const EXECUTION_LEDGER_ARTIFACT: ContentArtifactType;
+/**
+ * Per-fire artifact bytes for a scheduled goal — the content motebit
+ * produced when the goal cadence fired (or the user invoked
+ * `runNow`). First non-relay-state-export consumer of the registry:
+ * the motebit identity signs as producer, not the relay. Doctrine:
+ * `docs/doctrine/goal-results.md` §"The three categories" — the
+ * artifact category's cryptographic provenance envelope.
+ */
+export declare const GOAL_RESULT_ARTIFACT: ContentArtifactType;
+/**
+ * Canonical iteration order, frozen. Consumers that need to iterate
+ * (drift gates, tooling, docs) use this so TypeScript sees the narrow
+ * union rather than `string[]`.
+ */
+export declare const ALL_CONTENT_ARTIFACT_TYPES: readonly ContentArtifactType[];
+/**
+ * Type guard — narrows `unknown` to `ContentArtifactType`. Drift-gate-driven
+ * literal scanners use this to validate strings; verifiers that want to
+ * dispatch on category call this before the switch so an unchecked cast
+ * is a fail-open path the gate will flag.
+ */
+export declare function isContentArtifactType(value: unknown): value is ContentArtifactType;
+//# sourceMappingURL=artifact-type.d.ts.map

package/dist/artifact-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-type.d.ts","sourceRoot":"","sources":["../src/artifact-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,MAAM,mBAAmB,GAC3B,gBAAgB,GAChB,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,uBAAuB,GACvB,aAAa,GACb,aAAa,GACb,WAAW,GACX,aAAa,GACb,kBAAkB,GAClB,WAAW,GACX,kBAAkB,GAClB,aAAa,CAAC;AAUlB,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,EAAE,mBAAsC,CAAC;AAE7E,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,EAAE,mBAAqC,CAAC;AAE3E,+CAA+C;AAC/C,eAAO,MAAM,kBAAkB,EAAE,mBAAiC,CAAC;AAEnE,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,EAAE,mBAAyC,CAAC;AAEnF,mEAAmE;AACnE,eAAO,MAAM,8BAA8B,EAAE,mBAA6C,CAAC;AAE3F,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,EAAE,mBAAmC,CAAC;AAEvE,+CAA+C;AAC/C,eAAO,MAAM,oBAAoB,EAAE,mBAAmC,CAAC;AAEvE,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,EAAE,mBAAiC,CAAC;AAEnE,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,EAAE,mBAAmC,CAAC;AAEvE,4DAA4D;AAC5D,eAAO,MAAM,yBAAyB,EAAE,mBAAwC,CAAC;AAEjF,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,EAAE,mBAAiC,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,mBAAwC,CAAC;AAEjF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,mBAAmC,CAAC;AAIvE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,mBAAmB,EAcnE,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAIlF"}

package/dist/artifact-type.js

@@ -0,0 +1,107 @@
+/**
+ * Content-artifact types — the closed registry of `artifact_type` claim
+ * values for the C2PA-shape content-provenance primitive
+ * (`ContentArtifactManifest` in `@motebit/crypto`).
+ *
+ * Provenance binding (per `docs/doctrine/self-attesting-system.md` and
+ * `docs/doctrine/nist-alignment.md` §8) requires every signed motebit
+ * artifact to carry a producer-declared category so a verifier can
+ * route, audit, or display the artifact without parsing its bytes.
+ * Pre-registry, the category was a free string in the manifest —
+ * a typo at a producer site (`artifact_type: "audit_trail"` instead
+ * of `"audit-trail"`) became a verifier-side classification miss
+ * with no compile-time signal. Locking the registry as a closed
+ * union makes the typo a compile error AND a CI error.
+ *
+ * **Closed registry shape** — same closure pattern as `TokenAudience`,
+ * `SuiteId`, `SettlementRail`, `ToolMode`, `ComputerActionKind`. The
+ * `ContentArtifactType` literal union is the wire law; named
+ * constants are the developer ergonomics. The drift gate
+ * `check-artifact-type-canonical` scans every `artifact_type:
+ * "<literal>"` and `artifactType: "<literal>"` call against
+ * `ALL_CONTENT_ARTIFACT_TYPES`.
+ *
+ * Adding a category is intentional protocol-level work: a new entry
+ * here, a new producer site, the doctrine reference at
+ * `docs/doctrine/nist-alignment.md` §8 updated. Same governance as
+ * cryptosuite agility (`SuiteId` registry) and audience binding
+ * (`TokenAudience` registry).
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+// === Named constants — same value, narrower type ============================
+//
+// Callers that import these get `ContentArtifactType` typing without the
+// union being inferred from a string-literal at every site. Two ergonomic
+// shapes: pass a constant (`EXECUTION_LEDGER_ARTIFACT`) for documentation +
+// grep affordance, or inline the literal — the union narrowing catches typos
+// in either case.
+/** Relay's stored state-vector snapshot for a motebit. */
+export const STATE_SNAPSHOT_ARTIFACT = "state-snapshot";
+/** Relay-assembled memory-graph snapshot (nodes + edges). */
+export const MEMORY_EXPORT_ARTIFACT = "memory-export";
+/** Relay-assembled goal list for a motebit. */
+export const GOAL_LIST_ARTIFACT = "goal-list";
+/** Relay-assembled conversation index for a motebit. */
+export const CONVERSATION_LIST_ARTIFACT = "conversation-list";
+/** Relay-assembled message history for a specific conversation. */
+export const CONVERSATION_MESSAGES_ARTIFACT = "conversation-messages";
+/** Relay-assembled list of devices registered to a motebit. */
+export const DEVICE_LIST_ARTIFACT = "device-list";
+/** Relay-assembled tool-audit-trail export. */
+export const AUDIT_TRAIL_ARTIFACT = "audit-trail";
+/** Relay-assembled list of plans for a motebit, each with embedded steps. */
+export const PLAN_LIST_ARTIFACT = "plan-list";
+/** Relay-assembled single-plan export with its steps. */
+export const PLAN_DETAIL_ARTIFACT = "plan-detail";
+/** Relay-assembled intelligence-gradient-history export. */
+export const GRADIENT_HISTORY_ARTIFACT = "gradient-history";
+/** Relay-assembled event-log pull beyond a `version_clock` cursor. */
+export const SYNC_PULL_ARTIFACT = "sync-pull";
+/**
+ * Relay-assembled execution-timeline export with embedded motebit-signed
+ * delegation receipts. Canonical layered-signing consumer — outer relay
+ * manifest attests bundle assembly, inner motebit signatures pass through
+ * byte-identical. See `spec/execution-ledger-v1.md`.
+ */
+export const EXECUTION_LEDGER_ARTIFACT = "execution-ledger";
+/**
+ * Per-fire artifact bytes for a scheduled goal — the content motebit
+ * produced when the goal cadence fired (or the user invoked
+ * `runNow`). First non-relay-state-export consumer of the registry:
+ * the motebit identity signs as producer, not the relay. Doctrine:
+ * `docs/doctrine/goal-results.md` §"The three categories" — the
+ * artifact category's cryptographic provenance envelope.
+ */
+export const GOAL_RESULT_ARTIFACT = "goal-result";
+// === Iteration + type guard =================================================
+/**
+ * Canonical iteration order, frozen. Consumers that need to iterate
+ * (drift gates, tooling, docs) use this so TypeScript sees the narrow
+ * union rather than `string[]`.
+ */
+export const ALL_CONTENT_ARTIFACT_TYPES = Object.freeze([
+    "state-snapshot",
+    "memory-export",
+    "goal-list",
+    "conversation-list",
+    "conversation-messages",
+    "device-list",
+    "audit-trail",
+    "plan-list",
+    "plan-detail",
+    "gradient-history",
+    "sync-pull",
+    "execution-ledger",
+    "goal-result",
+]);
+/**
+ * Type guard — narrows `unknown` to `ContentArtifactType`. Drift-gate-driven
+ * literal scanners use this to validate strings; verifiers that want to
+ * dispatch on category call this before the switch so an unchecked cast
+ * is a fail-open path the gate will flag.
+ */
+export function isContentArtifactType(value) {
+    return (typeof value === "string" && ALL_CONTENT_ARTIFACT_TYPES.includes(value));
+}
+//# sourceMappingURL=artifact-type.js.map

package/dist/artifact-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-type.js","sourceRoot":"","sources":["../src/artifact-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA6EH,+EAA+E;AAC/E,EAAE;AACF,yEAAyE;AACzE,0EAA0E;AAC1E,4EAA4E;AAC5E,6EAA6E;AAC7E,kBAAkB;AAElB,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAwB,gBAAgB,CAAC;AAE7E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,sBAAsB,GAAwB,eAAe,CAAC;AAE3E,+CAA+C;AAC/C,MAAM,CAAC,MAAM,kBAAkB,GAAwB,WAAW,CAAC;AAEnE,wDAAwD;AACxD,MAAM,CAAC,MAAM,0BAA0B,GAAwB,mBAAmB,CAAC;AAEnF,mEAAmE;AACnE,MAAM,CAAC,MAAM,8BAA8B,GAAwB,uBAAuB,CAAC;AAE3F,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAwB,aAAa,CAAC;AAEvE,+CAA+C;AAC/C,MAAM,CAAC,MAAM,oBAAoB,GAAwB,aAAa,CAAC;AAEvE,6EAA6E;AAC7E,MAAM,CAAC,MAAM,kBAAkB,GAAwB,WAAW,CAAC;AAEnE,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAwB,aAAa,CAAC;AAEvE,4DAA4D;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GAAwB,kBAAkB,CAAC;AAEjF,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAwB,WAAW,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAwB,kBAAkB,CAAC;AAEjF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAwB,aAAa,CAAC;AAEvE,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAmC,MAAM,CAAC,MAAM,CAAC;IACtF,gBAAgB;IAChB,eAAe;IACf,WAAW;IACX,mBAAmB;IACnB,uBAAuB;IACvB,aAAa;IACb,aAAa;IACb,WAAW;IACX,aAAa;IACb,kBAAkB;IAClB,WAAW;IACX,kBAAkB;IAClB,aAAa;CACd,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ,IAAK,0BAAgD,CAAC,QAAQ,CAAC,KAAK,CAAC,CAC/F,CAAC;AACJ,CAAC"}

package/dist/audience.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Token audiences — the closed registry of `aud` claim values for the
+ * audience-bound signed-token primitive (`SignedTokenPayload`).
+ *
+ * Audience binding (per `docs/doctrine/security-boundaries.md` and
+ * `services/relay/CLAUDE.md` Rule 5) prevents cross-endpoint replay:
+ * a token minted for one purpose cannot be reused for another. Every
+ * signed bearer in motebit carries `aud`; verifiers reject a missing
+ * or unexpected value fail-closed.
+ *
+ * **Closed registry shape** — same closure pattern as `SuiteId`,
+ * `SettlementRail`, `ToolMode`, `ComputerActionKind`. The `TokenAudience`
+ * literal union is the wire law; named constants are the developer
+ * ergonomics. A typo at a signing site (`"task:sumbit"`) is rejected
+ * by the union narrowing AND by the `check-audience-canonical` drift
+ * gate, which scans every `aud: "<literal>"` and
+ * `createSyncToken("<literal>")` call against `ALL_TOKEN_AUDIENCES`.
+ *
+ * Adding an audience is intentional protocol-level work: a new entry
+ * here, a new caller-or-route registration, a doctrine update at
+ * `services/relay/CLAUDE.md` Rule 5. Renaming a literal is a wire
+ * break (verifiers reject the old value); deletions break running
+ * deployments. Same-shape decisions as cryptosuite agility.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+/**
+ * The closed set of audience identifiers motebit currently uses.
+ *
+ * Categories (organizational; the union is flat):
+ *
+ *   **Multi-device + identity lifecycle**
+ *     - `sync` — websocket sync + general relay state operations
+ *     - `device:auth` — per-device auth headers on relay calls
+ *     - `pair` — device-pairing flow (claim, transfer)
+ *     - `rotate-key` — key rotation requests
+ *     - `push:register` — push-notification token registration
+ *
+ *   **Task routing**
+ *     - `task:submit` — submitting a task to a peer via the relay
+ *     - `admin:query` — admin-bound read paths (transparency, etc.)
+ *     - `proposal` — collaborative proposal lifecycle
+ *
+ *   **Virtual accounts (the relay-mediated economic loop)**
+ *     - `account:balance` — read balance
+ *     - `account:deposit` — deposit endpoint (Stripe / x402 / Solana)
+ *     - `account:withdraw` — withdraw endpoint
+ *     - `account:withdrawals` — list withdrawals
+ *     - `account:checkout` — Stripe checkout session create
+ *
+ *   **Browser-sandbox dispatcher token (relay-mediated auth)**
+ *     - `browser-sandbox-grant` — motebit→relay grant request
+ *     - `browser-sandbox` — relay→motebit→sandbox dispatcher token
+ */
+export type TokenAudience = "sync" | "device:auth" | "pair" | "rotate-key" | "push:register" | "task:submit" | "admin:query" | "proposal" | "account:balance" | "account:deposit" | "account:withdraw" | "account:withdrawals" | "account:checkout" | "browser-sandbox-grant" | "browser-sandbox";
+/** Multi-device sync + general relay state operations. */
+export declare const SYNC_AUDIENCE: TokenAudience;
+/** Per-device auth headers on relay calls. Apps mint this for ad-hoc reads. */
+export declare const DEVICE_AUTH_AUDIENCE: TokenAudience;
+/** Device-pairing flow — claim + transfer. */
+export declare const PAIR_AUDIENCE: TokenAudience;
+/** Key rotation requests against the relay. */
+export declare const ROTATE_KEY_AUDIENCE: TokenAudience;
+/** Push-notification token registration (APNs / FCM). */
+export declare const PUSH_REGISTER_AUDIENCE: TokenAudience;
+/** Submitting a task to a peer via the relay. */
+export declare const TASK_SUBMIT_AUDIENCE: TokenAudience;
+/** Admin-bound read paths (transparency, etc.). */
+export declare const ADMIN_QUERY_AUDIENCE: TokenAudience;
+/** Collaborative proposal lifecycle. */
+export declare const PROPOSAL_AUDIENCE: TokenAudience;
+/** Read virtual-account balance. */
+export declare const ACCOUNT_BALANCE_AUDIENCE: TokenAudience;
+/** Deposit endpoint (Stripe / x402 / Solana). */
+export declare const ACCOUNT_DEPOSIT_AUDIENCE: TokenAudience;
+/** Withdraw endpoint. */
+export declare const ACCOUNT_WITHDRAW_AUDIENCE: TokenAudience;
+/** List withdrawals (history). */
+export declare const ACCOUNT_WITHDRAWALS_AUDIENCE: TokenAudience;
+/** Stripe checkout session create. */
+export declare const ACCOUNT_CHECKOUT_AUDIENCE: TokenAudience;
+/**
+ * Audience for the motebit-signed grant request to the relay's
+ * `POST /api/v1/browser-sandbox/token` endpoint. Verified by the relay
+ * via `verifySignedTokenForDevice`.
+ */
+export declare const BROWSER_SANDBOX_GRANT_AUDIENCE: TokenAudience;
+/**
+ * Audience for the relay-signed sandbox token. Verified by
+ * `services/browser-sandbox` against the pinned relay public key.
+ *
+ * See `spec/computer-use-v1.md` §8.2 for the wire-format binding.
+ */
+export declare const BROWSER_SANDBOX_AUDIENCE: TokenAudience;
+/**
+ * Canonical iteration order, frozen. Consumers that need to iterate
+ * (drift gates, tooling, docs) use this so TypeScript sees the narrow
+ * union rather than `string[]`.
+ */
+export declare const ALL_TOKEN_AUDIENCES: readonly TokenAudience[];
+/**
+ * Type guard — narrows `unknown` to `TokenAudience`. Drift-gate-driven
+ * audience-string scanners use this to validate literals; verifiers
+ * call this before dispatch so an unchecked cast is a fail-open path
+ * the gate will flag.
+ */
+export declare function isTokenAudience(value: unknown): value is TokenAudience;
+//# sourceMappingURL=audience.d.ts.map

package/dist/audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../src/audience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,aAAa,GACb,MAAM,GACN,YAAY,GACZ,eAAe,GACf,aAAa,GACb,aAAa,GACb,UAAU,GACV,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,kBAAkB,GAClB,uBAAuB,GACvB,iBAAiB,CAAC;AAStB,0DAA0D;AAC1D,eAAO,MAAM,aAAa,EAAE,aAAsB,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,EAAE,aAA6B,CAAC;AAEjE,8CAA8C;AAC9C,eAAO,MAAM,aAAa,EAAE,aAAsB,CAAC;AAEnD,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,EAAE,aAA4B,CAAC;AAE/D,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,EAAE,aAA+B,CAAC;AAErE,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,EAAE,aAA6B,CAAC;AAEjE,mDAAmD;AACnD,eAAO,MAAM,oBAAoB,EAAE,aAA6B,CAAC;AAEjE,wCAAwC;AACxC,eAAO,MAAM,iBAAiB,EAAE,aAA0B,CAAC;AAE3D,oCAAoC;AACpC,eAAO,MAAM,wBAAwB,EAAE,aAAiC,CAAC;AAEzE,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,EAAE,aAAiC,CAAC;AAEzE,yBAAyB;AACzB,eAAO,MAAM,yBAAyB,EAAE,aAAkC,CAAC;AAE3E,kCAAkC;AAClC,eAAO,MAAM,4BAA4B,EAAE,aAAqC,CAAC;AAEjF,sCAAsC;AACtC,eAAO,MAAM,yBAAyB,EAAE,aAAkC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,aAAuC,CAAC;AAErF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,aAAiC,CAAC;AAIzE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,aAAa,EAgBtD,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE"}

package/dist/audience.js

@@ -0,0 +1,104 @@
+/**
+ * Token audiences — the closed registry of `aud` claim values for the
+ * audience-bound signed-token primitive (`SignedTokenPayload`).
+ *
+ * Audience binding (per `docs/doctrine/security-boundaries.md` and
+ * `services/relay/CLAUDE.md` Rule 5) prevents cross-endpoint replay:
+ * a token minted for one purpose cannot be reused for another. Every
+ * signed bearer in motebit carries `aud`; verifiers reject a missing
+ * or unexpected value fail-closed.
+ *
+ * **Closed registry shape** — same closure pattern as `SuiteId`,
+ * `SettlementRail`, `ToolMode`, `ComputerActionKind`. The `TokenAudience`
+ * literal union is the wire law; named constants are the developer
+ * ergonomics. A typo at a signing site (`"task:sumbit"`) is rejected
+ * by the union narrowing AND by the `check-audience-canonical` drift
+ * gate, which scans every `aud: "<literal>"` and
+ * `createSyncToken("<literal>")` call against `ALL_TOKEN_AUDIENCES`.
+ *
+ * Adding an audience is intentional protocol-level work: a new entry
+ * here, a new caller-or-route registration, a doctrine update at
+ * `services/relay/CLAUDE.md` Rule 5. Renaming a literal is a wire
+ * break (verifiers reject the old value); deletions break running
+ * deployments. Same-shape decisions as cryptosuite agility.
+ *
+ * Permissive floor (Apache-2.0), type-only, zero runtime deps.
+ */
+// === Named constants — same value, narrower type ============================
+//
+// Callers that import these get `TokenAudience` typing without the union
+// being inferred from a string-literal at every site. Two ergonomic shapes:
+// pass a constant (`SYNC_AUDIENCE`) for documentation + grep affordance, or
+// inline the literal — the union narrowing catches typos in either case.
+/** Multi-device sync + general relay state operations. */
+export const SYNC_AUDIENCE = "sync";
+/** Per-device auth headers on relay calls. Apps mint this for ad-hoc reads. */
+export const DEVICE_AUTH_AUDIENCE = "device:auth";
+/** Device-pairing flow — claim + transfer. */
+export const PAIR_AUDIENCE = "pair";
+/** Key rotation requests against the relay. */
+export const ROTATE_KEY_AUDIENCE = "rotate-key";
+/** Push-notification token registration (APNs / FCM). */
+export const PUSH_REGISTER_AUDIENCE = "push:register";
+/** Submitting a task to a peer via the relay. */
+export const TASK_SUBMIT_AUDIENCE = "task:submit";
+/** Admin-bound read paths (transparency, etc.). */
+export const ADMIN_QUERY_AUDIENCE = "admin:query";
+/** Collaborative proposal lifecycle. */
+export const PROPOSAL_AUDIENCE = "proposal";
+/** Read virtual-account balance. */
+export const ACCOUNT_BALANCE_AUDIENCE = "account:balance";
+/** Deposit endpoint (Stripe / x402 / Solana). */
+export const ACCOUNT_DEPOSIT_AUDIENCE = "account:deposit";
+/** Withdraw endpoint. */
+export const ACCOUNT_WITHDRAW_AUDIENCE = "account:withdraw";
+/** List withdrawals (history). */
+export const ACCOUNT_WITHDRAWALS_AUDIENCE = "account:withdrawals";
+/** Stripe checkout session create. */
+export const ACCOUNT_CHECKOUT_AUDIENCE = "account:checkout";
+/**
+ * Audience for the motebit-signed grant request to the relay's
+ * `POST /api/v1/browser-sandbox/token` endpoint. Verified by the relay
+ * via `verifySignedTokenForDevice`.
+ */
+export const BROWSER_SANDBOX_GRANT_AUDIENCE = "browser-sandbox-grant";
+/**
+ * Audience for the relay-signed sandbox token. Verified by
+ * `services/browser-sandbox` against the pinned relay public key.
+ *
+ * See `spec/computer-use-v1.md` §8.2 for the wire-format binding.
+ */
+export const BROWSER_SANDBOX_AUDIENCE = "browser-sandbox";
+// === Iteration + type guard =================================================
+/**
+ * Canonical iteration order, frozen. Consumers that need to iterate
+ * (drift gates, tooling, docs) use this so TypeScript sees the narrow
+ * union rather than `string[]`.
+ */
+export const ALL_TOKEN_AUDIENCES = Object.freeze([
+    "sync",
+    "device:auth",
+    "pair",
+    "rotate-key",
+    "push:register",
+    "task:submit",
+    "admin:query",
+    "proposal",
+    "account:balance",
+    "account:deposit",
+    "account:withdraw",
+    "account:withdrawals",
+    "account:checkout",
+    "browser-sandbox-grant",
+    "browser-sandbox",
+]);
+/**
+ * Type guard — narrows `unknown` to `TokenAudience`. Drift-gate-driven
+ * audience-string scanners use this to validate literals; verifiers
+ * call this before dispatch so an unchecked cast is a fail-open path
+ * the gate will flag.
+ */
+export function isTokenAudience(value) {
+    return typeof value === "string" && ALL_TOKEN_AUDIENCES.includes(value);
+}
+//# sourceMappingURL=audience.js.map

package/dist/audience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.js","sourceRoot":"","sources":["../src/audience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA+CH,+EAA+E;AAC/E,EAAE;AACF,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AAEzE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC;AAEnD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAkB,aAAa,CAAC;AAEjE,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC;AAEnD,+CAA+C;AAC/C,MAAM,CAAC,MAAM,mBAAmB,GAAkB,YAAY,CAAC;AAE/D,yDAAyD;AACzD,MAAM,CAAC,MAAM,sBAAsB,GAAkB,eAAe,CAAC;AAErE,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAkB,aAAa,CAAC;AAEjE,mDAAmD;AACnD,MAAM,CAAC,MAAM,oBAAoB,GAAkB,aAAa,CAAC;AAEjE,wCAAwC;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAkB,UAAU,CAAC;AAE3D,oCAAoC;AACpC,MAAM,CAAC,MAAM,wBAAwB,GAAkB,iBAAiB,CAAC;AAEzE,iDAAiD;AACjD,MAAM,CAAC,MAAM,wBAAwB,GAAkB,iBAAiB,CAAC;AAEzE,yBAAyB;AACzB,MAAM,CAAC,MAAM,yBAAyB,GAAkB,kBAAkB,CAAC;AAE3E,kCAAkC;AAClC,MAAM,CAAC,MAAM,4BAA4B,GAAkB,qBAAqB,CAAC;AAEjF,sCAAsC;AACtC,MAAM,CAAC,MAAM,yBAAyB,GAAkB,kBAAkB,CAAC;AAE3E;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAkB,uBAAuB,CAAC;AAErF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAkB,iBAAiB,CAAC;AAEzE,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA6B,MAAM,CAAC,MAAM,CAAC;IACzE,MAAM;IACN,aAAa;IACb,MAAM;IACN,YAAY;IACZ,eAAe;IACf,aAAa;IACb,aAAa;IACb,UAAU;IACV,iBAAiB;IACjB,iBAAiB;IACjB,kBAAkB;IAClB,qBAAqB;IACrB,kBAAkB;IAClB,uBAAuB;IACvB,iBAAiB;CAClB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,mBAAyC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACjG,CAAC"}