@motebit/protocol 1.3.0 → 2.0.1

package/dist/routing.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Routing primitive — closed-registry types for the auto-router.
+ *
+ * The auto-router is the model-selection counterpart to the chrome
+ * matrix: `f(TaskShape × ProviderCapability × Constraints) →
+ * RoutingDecision`. This module defines the wire-shape types; the
+ * judgment-layer dispatcher (`dispatchRouting`) lives in BSL
+ * `@motebit/policy/src/auto-router.ts`. Consumers (motebit-cloud
+ * proxy, BYOK web layer, on-device runtime) call the dispatcher
+ * with their own provider catalogs.
+ *
+ * **Closed registry shape** — same closure pattern as `SuiteId`,
+ * `TokenAudience`, `ToolMode`, `ContentArtifactType`. The `TaskShape`
+ * literal union is the wire law; named constants are developer
+ * ergonomics; `ALL_TASK_SHAPES` is the canonical iteration order.
+ * Adding a task shape is intentional protocol-level work: a new
+ * entry here, a new arm in `REFERENCE_ROUTING_POLICY`, drift-gate
+ * coverage on every consumer.
+ *
+ * **TaskShape agility — the 7th instance of agility-as-role.**
+ * Per [`docs/doctrine/agility-as-role.md`], `TaskShape` is the
+ * closed registry (the role); the routing-policy itself is a
+ * consumer-side function (`Record<TaskShape, string>` today,
+ * potentially a learned function in the future) that branches on
+ * it. Distinguishing role (registry-shape) from policy
+ * (function-shape) avoids the conflation the codebase corrected
+ * for `Provider → InferenceHost`.
+ *
+ * **Lifted from `services/proxy/src/validation.ts`** (commit
+ * 95e3b7af's intelligence-source-agility refactor anticipated this
+ * landing site — the three unions `InferenceHost`, `ModelLab`,
+ * `Jurisdiction` were always destined for the protocol layer once
+ * a second consumer arrived):
+ *   - `InferenceHost` — where the HTTP request actually goes.
+ *   - `ModelLab` — who trained the weights.
+ *   - `Jurisdiction` — legal locus of the host.
+ *
+ * Permissive floor, type-only, zero runtime deps. The dispatcher's
+ * judgment lives in `@motebit/policy`; this file stays pure types
+ * + closed-registry constants.
+ */
+import type { SensitivityLevel } from "./index.js";
+/**
+ * Where the HTTP request actually goes. The processor that receives
+ * the prompt bytes. Anthropic/OpenAI/Google appear here because they
+ * run their own hosted inference; Groq appears here because they
+ * host other labs' open-source weights on LPU hardware. `local-server`
+ * is the on-device case: the request goes to the user's own
+ * inference server (Ollama, LM Studio, llama.cpp, Jan, vLLM,
+ * text-generation-webui — all expose `/v1/chat/completions` via
+ * the OpenAI-compat shim), so the "host" is the user's own
+ * machine. Mirrors the `OnDeviceBackend` value of the same name
+ * in `@motebit/sdk`.
+ *
+ * The proxy NEVER routes to `local-server` — it's the on-device
+ * consumer's host. The proxy's exhaustive switches throw
+ * defensively when they encounter this value, naming the
+ * structural violation rather than silently degrading. Doctrine:
+ * `docs/doctrine/auto-routing-as-protocol-primitive.md` § "PR 3 —
+ * on-device consumer".
+ *
+ * Closed registry — adding a host is a protocol-level append +
+ * `MOTEBIT_CLOUD_ALLOWED_JURISDICTIONS` admission decision +
+ * downstream consumer updates.
+ */
+export type InferenceHost = "anthropic" | "openai" | "google" | "groq" | "local-server";
+/**
+ * Who trained the weights. Anthropic/OpenAI/Google appear here
+ * because they trained Claude/GPT/Gemini respectively; Meta appears
+ * here because Llama 3.3 70B is Meta's model (Groq just hosts it).
+ * OpenAI appears in BOTH this union AND `InferenceHost` (host =
+ * "openai" for gpt-5.4 at api.openai.com; lab = "openai" for
+ * gpt-oss-120b released as open weights and hosted by Groq). That's
+ * structurally correct — same entity can serve different roles.
+ *
+ * Mistral / Microsoft / Alibaba added 2026-05-14 alongside the PR 3
+ * on-device consumer landing: Mistral AI trains Mistral models,
+ * Microsoft trains Phi, Alibaba trains Qwen. All three appear as
+ * `lab` in the `ON_DEVICE_MODEL_CATALOG` (`@motebit/policy/on-device-router.ts`)
+ * since the canonical local-server suggested-models list
+ * (`@motebit/sdk::LOCAL_SERVER_SUGGESTED_MODELS`) includes Mistral,
+ * Phi-3, and Qwen2 alongside the existing Meta/Google entries. The
+ * proxy never sees these labs (it doesn't host their models); the
+ * registry expansion is purely consumer-side (the on-device
+ * dispatcher's catalog), which is why the registry's stated semantic
+ * "who trained the weights" generalizes cleanly without protocol-
+ * layer churn.
+ *
+ * Closed registry — adding a lab requires a model entry citing it.
+ */
+export type ModelLab = "anthropic" | "openai" | "google" | "meta" | "mistral" | "microsoft" | "alibaba";
+/**
+ * Legal locus of the host. Reflective of physical/legal reality,
+ * not pluggable. Drives the motebit-cloud admission predicate
+ * (`MOTEBIT_CLOUD_ALLOWED_JURISDICTIONS` in
+ * `services/proxy/src/validation.ts`). You can't swap a host's
+ * jurisdiction; the registry reflects legal reality.
+ *
+ * NOT an agility-as-role instance — it's a typed admission
+ * predicate, not a swappable role. Per
+ * [`docs/doctrine/agility-as-role.md`], jurisdiction lifts the
+ * previously-tribal "DeepSeek-is-BYOK-only-because-Chinese-hosted"
+ * decision into structural enforcement.
+ */
+export type Jurisdiction = "US" | "CN" | "EU";
+/**
+ * The closed set of task categories the auto-router branches on.
+ * Each task shape maps to a preferred model via
+ * `REFERENCE_ROUTING_POLICY` (in `@motebit/policy`); consumers
+ * (motebit-cloud / BYOK / on-device) override the policy as
+ * needed but the shape registry is interop law.
+ *
+ * Lifted verbatim from `services/proxy/src/validation.ts`'s
+ * `TASK_MODEL_MAP` keys (the seven task types the proxy's
+ * classifyTask-based router already produces in production).
+ *
+ * Adding a shape (e.g., `"voice-conversation"`, `"image-generation"`)
+ * is intentional protocol-level work: new entry here + new arm in
+ * `REFERENCE_ROUTING_POLICY` + drift-gate-induced coverage in
+ * every CONSUMER (motebit-cloud proxy + BYOK + on-device). The
+ * TaskShape registry is what's role-shaped; the routing-policy
+ * itself is a consumer-side function, not a role.
+ */
+export type TaskShape = "quick" | "chat" | "reasoning" | "code" | "research" | "creative" | "math";
+/** Fast / low-latency tasks (tool-heavy, short responses, sub-second feel). */
+export declare const QUICK_TASK_SHAPE: TaskShape;
+/** Conversational back-and-forth — the default. */
+export declare const CHAT_TASK_SHAPE: TaskShape;
+/** Deep reasoning — chain-of-thought, multi-step inference. */
+export declare const REASONING_TASK_SHAPE: TaskShape;
+/** Code-related — completion, review, debugging. */
+export declare const CODE_TASK_SHAPE: TaskShape;
+/** Research / long-context — synthesis across many sources. */
+export declare const RESEARCH_TASK_SHAPE: TaskShape;
+/** Creative writing — open-ended generation, voice, prose. */
+export declare const CREATIVE_TASK_SHAPE: TaskShape;
+/** Math / scientific — symbolic reasoning, calculation, proofs. */
+export declare const MATH_TASK_SHAPE: TaskShape;
+/**
+ * Canonical iteration order, frozen. Consumers that need to
+ * enumerate (drift gates, REFERENCE_ROUTING_POLICY validation,
+ * docs) use this so TypeScript sees the narrow union rather than
+ * `string[]`.
+ */
+export declare const ALL_TASK_SHAPES: readonly TaskShape[];
+/**
+ * Type guard — narrows `unknown` to `TaskShape`. Drift-gate-driven
+ * literal scanners use this to validate shapes; consumers that
+ * detect task shape from user intent (LLM classification,
+ * heuristics) call this before dispatching so an unchecked cast
+ * is a fail-open path the type system can't catch.
+ */
+export declare function isTaskShape(value: unknown): value is TaskShape;
+/**
+ * A model's capability profile — what the dispatcher needs to know
+ * to pick it. Lifted from `services/proxy/src/validation.ts`'s
+ * `ModelEntry` interface; the proxy now declares its
+ * `MODEL_CONFIG` entries satisfying `ProviderCapability[]`.
+ *
+ * Cost units: USD per million tokens. Same precision the proxy's
+ * `calculateCostMicro` consumes (input vs output billed
+ * separately).
+ */
+export interface ProviderCapability {
+    /** Canonical model identifier — opaque to the dispatcher except as a return value. */
+    readonly modelName: string;
+    /** Where requests route. */
+    readonly host: InferenceHost;
+    /** Who trained the weights. */
+    readonly lab: ModelLab;
+    /** Legal locus of the host. */
+    readonly jurisdiction: Jurisdiction;
+    /** Input price (USD per million tokens). */
+    readonly inputCostPerMillion: number;
+    /** Output price (USD per million tokens). */
+    readonly outputCostPerMillion: number;
+    /**
+     * Maximum prompt+completion tokens the model will accept in a single
+     * call. Optional + additive per
+     * [`docs/doctrine/intelligence-pluggability-contract.md`](../../../docs/doctrine/intelligence-pluggability-contract.md) —
+     * consumers performing pre-flight admission (system-prompt + tools +
+     * rendered state + user message + output reserve ≤ window) read this
+     * to decide whether to deny honestly before invoking the model.
+     * Auto-routing dispatch does not consume this field today; admission
+     * is a sibling deny semantic to auto-router deny ("I can't pick"
+     * vs "the picked model can't carry").
+     */
+    readonly contextWindowTokens?: number;
+}
+/**
+ * Consumer-neutral constraints the dispatcher honors. **No
+ * motebit-cloud-specific fields** — balance-based filtering lives
+ * in `@motebit/policy::applyBalanceFilter` (a higher-order wrapper
+ * the proxy uses); BYOK and on-device consumers don't have balance
+ * and shouldn't see it in the protocol-layer constraint type.
+ *
+ * All fields optional — an empty constraint means "any
+ * jurisdiction, any cost, any capability." The dispatcher returns
+ * `{ kind: "deny", reason }` when constraints make every catalog
+ * entry ineligible.
+ */
+export interface RoutingConstraint {
+    /**
+     * Restrict to this jurisdiction. Useful for compliance-bound
+     * tasks ("US-only routing") and the motebit-cloud admission
+     * predicate. Omit for "any jurisdiction the catalog offers."
+     */
+    readonly jurisdiction?: Jurisdiction;
+    /**
+     * Maximum acceptable input cost in USD per million tokens.
+     * Filters the catalog before policy lookup. Useful for
+     * cost-aware routing (operator-side budget caps,
+     * consumer-side cheap-tier preferences).
+     */
+    readonly maxInputCostPerMillion?: number;
+    /** Maximum acceptable output cost in USD per million tokens. */
+    readonly maxOutputCostPerMillion?: number;
+    /**
+     * Task requires tool-calling capability. When true, providers
+     * known not to support tools are excluded. Today the dispatcher
+     * treats all entries as tool-capable; this field is shipped for
+     * future capability-aware filtering when a provider that lacks
+     * tool support lands.
+     */
+    readonly requiresToolUse?: boolean;
+    /**
+     * Maximum acceptable sensitivity tier the routing target can
+     * handle. Sensitivity-elevated tasks (medical / financial /
+     * secret) MUST stay on sovereign or on-device routes — the
+     * dispatcher's caller is responsible for pre-filtering the
+     * catalog accordingly; this field documents the contract.
+     */
+    readonly sensitivityCeiling?: SensitivityLevel;
+}
+/**
+ * The dispatcher's typed output. Discriminated union — consumers
+ * pattern-match on `kind`:
+ *
+ *   - `route`: a single provider was chosen. The caller invokes
+ *     it directly.
+ *   - `fallback`: a primary was preferred but cost / constraint
+ *     forced a backup. The caller invokes `backup`; the `primary`
+ *     and `reason` fields are observability surfaces (audit logs,
+ *     chrome narration in PR 4+).
+ *   - `deny`: no catalog entry satisfies the constraints. The
+ *     caller is responsible for surfacing the denial (HTTP 4xx,
+ *     UI message, etc.).
+ *
+ * Every variant carries `reason` for observability — the
+ * dispatcher's choice should always be human-legible, even when
+ * the choice is "I couldn't pick anything."
+ */
+export type RoutingDecision = {
+    readonly kind: "route";
+    readonly model: string;
+    readonly reason: string;
+} | {
+    readonly kind: "fallback";
+    readonly primary: string;
+    readonly backup: string;
+    readonly reason: string;
+} | {
+    readonly kind: "deny";
+    readonly reason: string;
+};
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"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"}

package/dist/routing.js

@@ -0,0 +1,88 @@
+/**
+ * Routing primitive — closed-registry types for the auto-router.
+ *
+ * The auto-router is the model-selection counterpart to the chrome
+ * matrix: `f(TaskShape × ProviderCapability × Constraints) →
+ * RoutingDecision`. This module defines the wire-shape types; the
+ * judgment-layer dispatcher (`dispatchRouting`) lives in BSL
+ * `@motebit/policy/src/auto-router.ts`. Consumers (motebit-cloud
+ * proxy, BYOK web layer, on-device runtime) call the dispatcher
+ * with their own provider catalogs.
+ *
+ * **Closed registry shape** — same closure pattern as `SuiteId`,
+ * `TokenAudience`, `ToolMode`, `ContentArtifactType`. The `TaskShape`
+ * literal union is the wire law; named constants are developer
+ * ergonomics; `ALL_TASK_SHAPES` is the canonical iteration order.
+ * Adding a task shape is intentional protocol-level work: a new
+ * entry here, a new arm in `REFERENCE_ROUTING_POLICY`, drift-gate
+ * coverage on every consumer.
+ *
+ * **TaskShape agility — the 7th instance of agility-as-role.**
+ * Per [`docs/doctrine/agility-as-role.md`], `TaskShape` is the
+ * closed registry (the role); the routing-policy itself is a
+ * consumer-side function (`Record<TaskShape, string>` today,
+ * potentially a learned function in the future) that branches on
+ * it. Distinguishing role (registry-shape) from policy
+ * (function-shape) avoids the conflation the codebase corrected
+ * for `Provider → InferenceHost`.
+ *
+ * **Lifted from `services/proxy/src/validation.ts`** (commit
+ * 95e3b7af's intelligence-source-agility refactor anticipated this
+ * landing site — the three unions `InferenceHost`, `ModelLab`,
+ * `Jurisdiction` were always destined for the protocol layer once
+ * a second consumer arrived):
+ *   - `InferenceHost` — where the HTTP request actually goes.
+ *   - `ModelLab` — who trained the weights.
+ *   - `Jurisdiction` — legal locus of the host.
+ *
+ * Permissive floor, type-only, zero runtime deps. The dispatcher's
+ * judgment lives in `@motebit/policy`; this file stays pure types
+ * + closed-registry constants.
+ */
+// === Named constants — same value, narrower type ============================
+//
+// Callers that import these get `TaskShape` typing without the union
+// being inferred at every site. Two ergonomic shapes: pass a constant
+// (`QUICK_TASK_SHAPE`) for documentation + grep affordance, or inline
+// the literal — the union narrowing catches typos in either case.
+/** Fast / low-latency tasks (tool-heavy, short responses, sub-second feel). */
+export const QUICK_TASK_SHAPE = "quick";
+/** Conversational back-and-forth — the default. */
+export const CHAT_TASK_SHAPE = "chat";
+/** Deep reasoning — chain-of-thought, multi-step inference. */
+export const REASONING_TASK_SHAPE = "reasoning";
+/** Code-related — completion, review, debugging. */
+export const CODE_TASK_SHAPE = "code";
+/** Research / long-context — synthesis across many sources. */
+export const RESEARCH_TASK_SHAPE = "research";
+/** Creative writing — open-ended generation, voice, prose. */
+export const CREATIVE_TASK_SHAPE = "creative";
+/** Math / scientific — symbolic reasoning, calculation, proofs. */
+export const MATH_TASK_SHAPE = "math";
+// === Iteration + type guard =================================================
+/**
+ * Canonical iteration order, frozen. Consumers that need to
+ * enumerate (drift gates, REFERENCE_ROUTING_POLICY validation,
+ * docs) use this so TypeScript sees the narrow union rather than
+ * `string[]`.
+ */
+export const ALL_TASK_SHAPES = Object.freeze([
+    "quick",
+    "chat",
+    "reasoning",
+    "code",
+    "research",
+    "creative",
+    "math",
+]);
+/**
+ * Type guard — narrows `unknown` to `TaskShape`. Drift-gate-driven
+ * literal scanners use this to validate shapes; consumers that
+ * detect task shape from user intent (LLM classification,
+ * heuristics) call this before dispatching so an unchecked cast
+ * is a fail-open path the type system can't catch.
+ */
+export function isTaskShape(value) {
+    return typeof value === "string" && ALL_TASK_SHAPES.includes(value);
+}
+//# sourceMappingURL=routing.js.map

package/dist/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../src/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAqGH,+EAA+E;AAC/E,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,kEAAkE;AAElE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,gBAAgB,GAAc,OAAO,CAAC;AAEnD,mDAAmD;AACnD,MAAM,CAAC,MAAM,eAAe,GAAc,MAAM,CAAC;AAEjD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAc,WAAW,CAAC;AAE3D,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAAc,MAAM,CAAC;AAEjD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAc,UAAU,CAAC;AAEzD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAc,UAAU,CAAC;AAEzD,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAc,MAAM,CAAC;AAEjD,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAyB,MAAM,CAAC,MAAM,CAAC;IACjE,OAAO;IACP,MAAM;IACN,WAAW;IACX,MAAM;IACN,UAAU;IACV,UAAU;IACV,MAAM;CACP,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7F,CAAC"}

package/dist/sensitivity.d.ts

@@ -70,4 +70,54 @@ export declare function maxSensitivity(a: SensitivityLevel, b: SensitivityLevel)
  * `upper` (None content is admissible at every tier).
  */
 export declare function sensitivityPermits(upper: SensitivityLevel, candidate: SensitivityLevel): boolean;
+/**
+ * Canonical iteration order over `SensitivityLevel`, frozen. The
+ * single source of truth for "every level" — drift gates,
+ * consumer-coverage scans, exhaustive switches, and the protocol's
+ * registry-coverage gate (`check-sensitivity-canonical`) all
+ * enumerate through this array.
+ *
+ * Ordered low → high to mirror `SENSITIVITY_RANK`: a consumer
+ * iterating in declaration order sees the ladder in the same order
+ * the algebra ranks it. Same shape as `ALL_SUITE_IDS`,
+ * `ALL_TOKEN_AUDIENCES`, `ALL_CONTENT_ARTIFACT_TYPES`,
+ * `ALL_TASK_SHAPES`. Adding a level is intentional protocol-level
+ * work: new enum member + new entry here + new entry in
+ * `SENSITIVITY_RANK` + drift-gate update.
+ *
+ * Values are the enum's string literals (not enum members) to avoid
+ * the init-order cycle the file's `import type` already documents.
+ */
+export declare const ALL_SENSITIVITY_LEVELS: readonly SensitivityLevel[];
+/**
+ * Type guard — narrows `unknown` to `SensitivityLevel`. Drift-gate-
+ * driven literal scanners use this to validate values pulled from
+ * wire-format payloads; consumers that derive sensitivity from
+ * user input call this before dispatching so an unchecked cast is
+ * a fail-open path the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`,
+ * `isContentArtifactType`, `isTaskShape`.
+ */
+export declare function isSensitivityLevel(value: unknown): value is SensitivityLevel;
+declare const __sensitivityCleared: unique symbol;
+/**
+ * Precondition brand: `T` carrying the type-level proof that
+ * `assertSensitivityPermitsAiCall()` fired before the value left
+ * the gate.
+ *
+ * Produced only inside the runtime's gate method (the single
+ * authorized `as SensitivityCleared<T>` cast). Required as the
+ * deps parameter on `runTurn` / `runTurnStreaming`. Propagates
+ * through every indirect AI-egress path (`StreamingManager` resume,
+ * `PlanEngine` per-step) so the brand is the type-level proof a
+ * sensitivity check happened at the right moment.
+ *
+ * Doctrine: `docs/doctrine/security-boundaries.md` (privacy gate),
+ * CLAUDE.md ("Medical/financial/secret never reach external AI").
+ */
+export type SensitivityCleared<T> = T & {
+    readonly [__sensitivityCleared]: true;
+};
+export {};
 //# sourceMappingURL=sensitivity.d.ts.map

package/dist/sensitivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sensitivity.d.ts","sourceRoot":"","sources":["../src/sensitivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAsBnD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAEzF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAEhG"}
+{"version":3,"file":"sensitivity.d.ts","sourceRoot":"","sources":["../src/sensitivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAsBnD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAEzF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAEhG;AAsBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,gBAAgB,EAMtC,CAAC;AAEzB;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AA4BD,OAAO,CAAC,MAAM,oBAAoB,EAAE,OAAO,MAAM,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC"}

package/dist/sensitivity.js

@@ -94,4 +94,61 @@ export function maxSensitivity(a, b) {
 export function sensitivityPermits(upper, candidate) {
     return rankSensitivity(candidate) <= rankSensitivity(upper);
 }
+// ── Canonical registry tooling ─────────────────────────────────────
+//
+// Closed-registry / structural-lock shape. Same five artifacts as
+// `SuiteId` (`crypto-suite.ts`), `TokenAudience` (`audience.ts`),
+// `ContentArtifactType` (`artifact-type.ts`), `TaskShape`
+// (`routing.ts`):
+//
+//   1. closed type (the `SensitivityLevel` enum in `index.ts`)
+//   2. canonical ordering (`SENSITIVITY_RANK` above)
+//   3. frozen iteration array (`ALL_SENSITIVITY_LEVELS` below)
+//   4. type guard (`isSensitivityLevel` below)
+//   5. drift gate (`check-sensitivity-canonical` per `scripts/`)
+//
+// Pre-this-block, `SensitivityLevel` was the only top-tier closed
+// registry without the iteration + guard pair — the gap surfaced in
+// the registry-gate-family audit on 2026-05-14 (post panels-registry
+// arc). The enum is preserved for back-compat with the ~900
+// pre-existing literal sites; this block adds the missing canonical
+// tooling next to it without converting the enum.
+/**
+ * Canonical iteration order over `SensitivityLevel`, frozen. The
+ * single source of truth for "every level" — drift gates,
+ * consumer-coverage scans, exhaustive switches, and the protocol's
+ * registry-coverage gate (`check-sensitivity-canonical`) all
+ * enumerate through this array.
+ *
+ * Ordered low → high to mirror `SENSITIVITY_RANK`: a consumer
+ * iterating in declaration order sees the ladder in the same order
+ * the algebra ranks it. Same shape as `ALL_SUITE_IDS`,
+ * `ALL_TOKEN_AUDIENCES`, `ALL_CONTENT_ARTIFACT_TYPES`,
+ * `ALL_TASK_SHAPES`. Adding a level is intentional protocol-level
+ * work: new enum member + new entry here + new entry in
+ * `SENSITIVITY_RANK` + drift-gate update.
+ *
+ * Values are the enum's string literals (not enum members) to avoid
+ * the init-order cycle the file's `import type` already documents.
+ */
+export const ALL_SENSITIVITY_LEVELS = Object.freeze([
+    "none",
+    "personal",
+    "medical",
+    "financial",
+    "secret",
+]);
+/**
+ * Type guard — narrows `unknown` to `SensitivityLevel`. Drift-gate-
+ * driven literal scanners use this to validate values pulled from
+ * wire-format payloads; consumers that derive sensitivity from
+ * user input call this before dispatching so an unchecked cast is
+ * a fail-open path the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`,
+ * `isContentArtifactType`, `isTaskShape`.
+ */
+export function isSensitivityLevel(value) {
+    return typeof value === "string" && ALL_SENSITIVITY_LEVELS.includes(value);
+}
 //# sourceMappingURL=sensitivity.js.map

package/dist/sensitivity.js.map

@@ -1 +1 @@
-{"version":3,"file":"sensitivity.js","sourceRoot":"","sources":["../src/sensitivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AASH;;;;;;;;;;;GAWG;AACH,MAAM,gBAAgB,GAA+C,MAAM,CAAC,MAAM,CAAC;IACjF,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,CAAC;CACV,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuB;IACrD,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,CAAmB,EAAE,CAAmB;IACrE,OAAO,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB,EAAE,SAA2B;IACrF,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"sensitivity.js","sourceRoot":"","sources":["../src/sensitivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AASH;;;;;;;;;;;GAWG;AACH,MAAM,gBAAgB,GAA+C,MAAM,CAAC,MAAM,CAAC;IACjF,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,MAAM,EAAE,CAAC;CACV,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuB;IACrD,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,CAAmB,EAAE,CAAmB;IACrE,OAAO,eAAe,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB,EAAE,SAA2B;IACrF,OAAO,eAAe,CAAC,SAAS,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,sEAAsE;AACtE,EAAE;AACF,kEAAkE;AAClE,kEAAkE;AAClE,0DAA0D;AAC1D,kBAAkB;AAClB,EAAE;AACF,+DAA+D;AAC/D,qDAAqD;AACrD,+DAA+D;AAC/D,+CAA+C;AAC/C,iEAAiE;AACjE,EAAE;AACF,kEAAkE;AAClE,oEAAoE;AACpE,qEAAqE;AACrE,4DAA4D;AAC5D,oEAAoE;AACpE,kDAAkD;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgC,MAAM,CAAC,MAAM,CAAC;IAC/E,MAAM;IACN,UAAU;IACV,SAAS;IACT,WAAW;IACX,QAAQ;CACa,CAAC,CAAC;AAEzB;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAA4C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpG,CAAC"}

package/dist/settlement-asset.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Settlement-asset types — the closed vocabulary of stablecoin assets
+ * the protocol clears settlement in.
+ *
+ * Permissive floor (Apache-2.0). Layer 0. Sub-phase A of the
+ * asset-pluggability commitment named in
+ * [`docs/doctrine/off-ramp-as-user-action.md`](../../../docs/doctrine/off-ramp-as-user-action.md)
+ * § "Asset pluggability":
+ *
+ *   > "settlement is asset-pluggable. USDC is the bootstrap stablecoin.
+ *   > A `SettlementAsset` closed union (`"USDC"` only at land) with a
+ *   > bespoke coverage test should ship as sub-phase A of this arc — a
+ *   > typed vocabulary consumers can reference, promoted to the 8th
+ *   > registered registry per `registry-pattern-canonical.md` when a
+ *   > second asset (PYUSD, USDP, etc.) arrives as a real consumer
+ *   > (sub-phase B)."
+ *
+ * Sub-phase A intentionally stops short of the full eight-artifact
+ * registered-registry set: the per-registry coverage gate, perturbation
+ * probe, drift-defenses inventory entry, and `REGISTERED_REGISTRIES`
+ * append are deferred until a second asset materializes as a real
+ * consumer. With a single literal there is no cross-implementation
+ * drift surface to defend against yet; the four criteria in
+ * [`docs/doctrine/registry-pattern-canonical.md`](../../../docs/doctrine/registry-pattern-canonical.md)
+ * § "When to add a registry to `REGISTERED_REGISTRIES`" require "real
+ * or anticipated drift," which this sub-phase does not meet. What it
+ * does meet: interop law (the field is signed on `SovereignRail` and
+ * read by independent verifiers), multi-consumer (rail + relay book-
+ * keeping + agent discovery), wire-format presence (`SovereignRail.asset`
+ * is the protocol-shaped boundary). Three of four criteria → bespoke
+ * coverage; the fourth criterion gates the registry promotion.
+ *
+ * **The registry membership IS the protocol-vs-product wall** (per the
+ * off-ramp doctrine memo's "asset-pluggability" section): if `"MOTE"`
+ * is ever added to `ALL_SETTLEMENT_ASSETS`, it's protocol; if it
+ * isn't, it's a motebit-cloud product overlay that converts to/from a
+ * protocol-level asset at its boundaries. A future MOTE stablecoin is
+ * **not** an architectural endpoint — it's a candidate motebit-cloud
+ * convenience product, evaluated against asset-pluggability when its
+ * compliance, market, and economic case can stand on its own
+ * (deferred per the `feedback_no_mote_stablecoin` memory).
+ *
+ * Semantic note — `SettlementAsset` is distinct from "currency".
+ * `BatchWithdrawalItem.currency`, `DepositResult.currency`,
+ * `WithdrawalResult.currency`, `CapabilityPrice.currency`, and
+ * `BudgetAllocation.currency` retain `string` typing because they
+ * mix fiat ("USD" via Stripe) and stablecoin ("USDC" via x402) across
+ * guest-rail kinds. Only fields whose semantic is unambiguously a
+ * settlement asset — `SovereignRail.asset` is the canonical site —
+ * tighten to this closed union. The fiat/stablecoin distinction lives
+ * at the rail-kind boundary, not in this vocabulary.
+ */
+/**
+ * The closed set of stablecoin assets the protocol clears settlement in.
+ *
+ * Single member at land — USDC is the bootstrap stablecoin. Additions
+ * are intentional protocol-level work (sub-phase B): new union member +
+ * `ALL_SETTLEMENT_ASSETS` entry + sibling-rail support + registry-
+ * pattern-canonical promotion to the 8th registered registry.
+ *
+ * Why a closed union, not `string`: a third-party motebit implementation
+ * receiving a `SovereignRail.asset` value of `"USDT"` or `"DAI"` from a
+ * peer should fail-closed (unknown asset) rather than silently continue.
+ * The vocabulary IS the interop boundary.
+ */
+export type SettlementAsset = "USDC";
+/**
+ * Canonical iteration order over `SettlementAsset`, frozen. The single
+ * source of truth for "every settlement asset" — exhaustive switches,
+ * bookkeeping enumerations, and the future per-registry coverage gate
+ * (sub-phase B) enumerate through this array.
+ *
+ * Same shape as `ALL_SUITE_IDS`, `ALL_TOKEN_AUDIENCES`,
+ * `ALL_CONTENT_ARTIFACT_TYPES`, `ALL_TASK_SHAPES`,
+ * `ALL_SENSITIVITY_LEVELS`, `ALL_EVENT_TYPES`, `ALL_SETTLEMENT_MODES`.
+ * The array shape is established before the registry is registered so
+ * that the sub-phase B promotion is a one-line `REGISTERED_REGISTRIES`
+ * append, not a refactor.
+ */
+export declare const ALL_SETTLEMENT_ASSETS: readonly SettlementAsset[];
+/**
+ * Type guard — narrows `unknown` to `SettlementAsset`. Consumers that
+ * derive settlement-asset values from external sources (peer rail
+ * announcements, signed `SovereignRail` declarations, discovery
+ * responses) call this before dispatching so an unchecked cast is a
+ * fail-open path the type system can't catch.
+ *
+ * Same shape as `isSuiteId`, `isTokenAudience`, `isContentArtifactType`,
+ * `isTaskShape`, `isSensitivityLevel`, `isEventType`, `isSettlementMode`.
+ */
+export declare function isSettlementAsset(value: unknown): value is SettlementAsset;
+//# sourceMappingURL=settlement-asset.d.ts.map

package/dist/settlement-asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-asset.d.ts","sourceRoot":"","sources":["../src/settlement-asset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,eAAe,EAErC,CAAC;AAExB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}