@motebit/protocol 1.2.0 → 2.0.0

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

@@ -0,0 +1,123 @@
+/**
+ * Sensitivity ladder algebra — pure math over the closed
+ * `SensitivityLevel` enum.
+ *
+ * The ladder is interop law. Every motebit implementation must agree
+ * on which tier dominates which, or the cross-implementation gate
+ * isn't interoperable: device A persisting a turn at "secret" must
+ * mean the same thing to device B's session-tier filter.
+ *
+ * Pure deterministic math over a closed enum — qualifies as a
+ * permissive-floor primitive per `packages/protocol/CLAUDE.md` rule 1
+ * ("deterministic math (semiring algebra, canonical JSON, hash
+ * primitives)"). The functions don't decide policy; they compose
+ * ordered values. Policy thresholds (e.g. "medical+ requires
+ * sovereign provider") live at the call site so call sites express
+ * intent at the right level.
+ *
+ * Graduation history: `rankSensitivity` had three local definitions
+ * by 2026-05-07 (runtime/motebit-runtime.ts, runtime/conversation.ts,
+ * ai-core/loop.ts) plus a fourth-shaped table (`LEVEL_RANK` +
+ * `higherLevel` in policy-invariants/computer-sensitivity.ts). The
+ * ai-core copy's JSDoc explicitly named graduation as the trigger:
+ * "if a third reader appears, the helper graduates." Past trigger.
+ *
+ * Naming distinction:
+ * - `rankSensitivity` — load-bearing primitive; ordinal int over the
+ *   closed union. Comparable, hashable, monotonic.
+ * - `maxSensitivity` — typed wrapper for the join-semilattice
+ *   composition (`max(a, b)`). Identity element is `None`. Used at
+ *   every egress write boundary that floors message tier at
+ *   `max(default, effective)`.
+ * - `sensitivityPermits` — typed wrapper for the read-side filter
+ *   (`candidate <= upper`). Used at every egress READ boundary that
+ *   excludes content tagged above the current effective tier.
+ *
+ * Not a semiring. There's only one operation (max-monoid / join-
+ * semilattice). Calling it a semiring would be a category error.
+ */
+import type { SensitivityLevel } from "./index.js";
+/**
+ * Ordinal rank for a `SensitivityLevel`. Returns 0 (`None`) through
+ * 4 (`Secret`) — see `SENSITIVITY_RANK` above. Use this as the
+ * comparison primitive; prefer `maxSensitivity` / `sensitivityPermits`
+ * at call sites that compose or filter.
+ */
+export declare function rankSensitivity(level: SensitivityLevel): number;
+/**
+ * Compose two sensitivity tiers: returns whichever has the higher
+ * rank. The join-semilattice composition that the egress-write floor
+ * arc depends on at every boundary (session × slab, default ×
+ * effective, persisted-tier × runtime-tier). Identity is `None`.
+ *
+ * Property: `maxSensitivity(a, None) === a` for all `a`.
+ */
+export declare function maxSensitivity(a: SensitivityLevel, b: SensitivityLevel): SensitivityLevel;
+/**
+ * Does the upper tier permit content tagged at `candidate`? Returns
+ * `true` iff `candidate <= upper` in the ladder. Used at every
+ * egress READ boundary (trimmed conversation history, memory-
+ * candidate filter at AI-context construction, future cross-device-
+ * sync filters).
+ *
+ * The dual of `maxSensitivity`: write-side floor stamps with
+ * `maxSensitivity`, read-side filter excludes via
+ * `!sensitivityPermits`. Both routes derive from the same single
+ * source of truth (`SENSITIVITY_RANK`), so a tier insertion remains
+ * a one-file change at the protocol layer.
+ *
+ * Property: `sensitivityPermits(upper, None) === true` for all
+ * `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

@@ -0,0 +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;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

@@ -0,0 +1,154 @@
+/**
+ * Sensitivity ladder algebra — pure math over the closed
+ * `SensitivityLevel` enum.
+ *
+ * The ladder is interop law. Every motebit implementation must agree
+ * on which tier dominates which, or the cross-implementation gate
+ * isn't interoperable: device A persisting a turn at "secret" must
+ * mean the same thing to device B's session-tier filter.
+ *
+ * Pure deterministic math over a closed enum — qualifies as a
+ * permissive-floor primitive per `packages/protocol/CLAUDE.md` rule 1
+ * ("deterministic math (semiring algebra, canonical JSON, hash
+ * primitives)"). The functions don't decide policy; they compose
+ * ordered values. Policy thresholds (e.g. "medical+ requires
+ * sovereign provider") live at the call site so call sites express
+ * intent at the right level.
+ *
+ * Graduation history: `rankSensitivity` had three local definitions
+ * by 2026-05-07 (runtime/motebit-runtime.ts, runtime/conversation.ts,
+ * ai-core/loop.ts) plus a fourth-shaped table (`LEVEL_RANK` +
+ * `higherLevel` in policy-invariants/computer-sensitivity.ts). The
+ * ai-core copy's JSDoc explicitly named graduation as the trigger:
+ * "if a third reader appears, the helper graduates." Past trigger.
+ *
+ * Naming distinction:
+ * - `rankSensitivity` — load-bearing primitive; ordinal int over the
+ *   closed union. Comparable, hashable, monotonic.
+ * - `maxSensitivity` — typed wrapper for the join-semilattice
+ *   composition (`max(a, b)`). Identity element is `None`. Used at
+ *   every egress write boundary that floors message tier at
+ *   `max(default, effective)`.
+ * - `sensitivityPermits` — typed wrapper for the read-side filter
+ *   (`candidate <= upper`). Used at every egress READ boundary that
+ *   excludes content tagged above the current effective tier.
+ *
+ * Not a semiring. There's only one operation (max-monoid / join-
+ * semilattice). Calling it a semiring would be a category error.
+ */
+/**
+ * Ordinal rank for `SensitivityLevel`: `none(0) < personal(1) <
+ * medical(2) < financial(3) < secret(4)`. The single source of truth
+ * for the ladder ordering — every consumer must derive comparison
+ * decisions from this rank, not from local enum-equality chains
+ * (`x === Medical || x === Financial || x === Secret`), so a future
+ * tier insertion remains a one-file change at the protocol layer.
+ *
+ * Keys are the enum's string values (not enum members) to avoid the
+ * init-order cycle described above. The `Record<SensitivityLevel,
+ * number>` type still binds the keys to the enum at the type layer.
+ */
+const SENSITIVITY_RANK = Object.freeze({
+    none: 0,
+    personal: 1,
+    medical: 2,
+    financial: 3,
+    secret: 4,
+});
+/**
+ * Ordinal rank for a `SensitivityLevel`. Returns 0 (`None`) through
+ * 4 (`Secret`) — see `SENSITIVITY_RANK` above. Use this as the
+ * comparison primitive; prefer `maxSensitivity` / `sensitivityPermits`
+ * at call sites that compose or filter.
+ */
+export function rankSensitivity(level) {
+    return SENSITIVITY_RANK[level];
+}
+/**
+ * Compose two sensitivity tiers: returns whichever has the higher
+ * rank. The join-semilattice composition that the egress-write floor
+ * arc depends on at every boundary (session × slab, default ×
+ * effective, persisted-tier × runtime-tier). Identity is `None`.
+ *
+ * Property: `maxSensitivity(a, None) === a` for all `a`.
+ */
+export function maxSensitivity(a, b) {
+    return rankSensitivity(a) >= rankSensitivity(b) ? a : b;
+}
+/**
+ * Does the upper tier permit content tagged at `candidate`? Returns
+ * `true` iff `candidate <= upper` in the ladder. Used at every
+ * egress READ boundary (trimmed conversation history, memory-
+ * candidate filter at AI-context construction, future cross-device-
+ * sync filters).
+ *
+ * The dual of `maxSensitivity`: write-side floor stamps with
+ * `maxSensitivity`, read-side filter excludes via
+ * `!sensitivityPermits`. Both routes derive from the same single
+ * source of truth (`SENSITIVITY_RANK`), so a tier insertion remains
+ * a one-file change at the protocol layer.
+ *
+ * Property: `sensitivityPermits(upper, None) === true` for all
+ * `upper` (None content is admissible at every tier).
+ */
+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

@@ -0,0 +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;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"}