modelrig 0.1.0 → 0.3.0

package/dist/registry/cache-policy.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Cache Policy Registry — cache-aware-routing spec §3, [Briefing §7].
+ *
+ * Per-provider cache SEMANTICS as versioned DATA, never routing code: TTLs,
+ * refresh-on-read, minimum-cacheable prefix, key mechanism, telemetry dialect,
+ * endpoint affinity. A provider rule change (OpenAI shipping paid writes,
+ * Anthropic GA-ing the 1h TTL) becomes a data edit here with a new `as_of`, not
+ * a code change anywhere else — the whole point of the registry.
+ *
+ * TWO HOMES, both pre-existing (spec §3):
+ *   • RATES ride pricing — `ModelPricingV2.base.{cache_read,cache_write,
+ *     cache_write_1h}` and flat `ModelPricing.cacheWrite*UsdPerTok`, entered via
+ *     the pricing sweep with source+as_of. NOT here.
+ *   • POLICY (this file) is the non-price semantics.
+ *
+ * L5 (fail-closed): every field cites a first-party page (research §2.1, fetched
+ * 2026-08-18). A value we could not verify is `null` (or `cache_supported:
+ * false`) — never a guess. `getCachePolicy` returns a fail-closed
+ * `cache_supported: false` policy for any provider not seeded, identical posture
+ * to the zero-coverage gates.
+ *
+ * ── CROSS-REFERENCES (no import — the probes package is standalone since P2) ──
+ *   • `min_cacheable_tokens` is reconciled by hand against the probes package's
+ *     `MIN_CACHEABLE_TOKENS` (packages/modelrig-probes/src/caching.ts, PR #157),
+ *     which cites the same first-party pages. See MIN_CACHEABLE_RECONCILIATION
+ *     below for the value-by-value comparison and the two deliberate deltas
+ *     (anthropic, gemini) flagged for the architect to converge if desired. A
+ *     reciprocal comment lives in caching.ts.
+ *   • OBSERVED cache facts (`cache_hit_rate`, `mean_cached_tokens`,
+ *     `declared_caching_unrealized`) are materialized separately in
+ *     `src/registry/build.ts` from probe/production telemetry — the DECLARED
+ *     policy here is the counterpart truth, and the §5.6 streak alert (WS-C)
+ *     cross-references `declared_caching_unrealized` (same smell, other plane).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failClosedCachePolicy = failClosedCachePolicy;
+exports.getCachePolicy = getCachePolicy;
+exports.seededCachePolicyProviders = seededCachePolicyProviders;
+const AS_OF = "2026-08-18";
+/**
+ * min_cacheable_tokens reconciliation vs probes `MIN_CACHEABLE_TOKENS`
+ * (packages/modelrig-probes/src/caching.ts, PR #157). Same first-party pages;
+ * the two tables cannot share by import (probes is standalone). The probe table
+ * is a conservative PROBE-ELIGIBILITY gate — it decides whether to SPEND a
+ * paired probe call, so it errs toward the larger provider-wide bound. This
+ * registry records the documented minimum for the models ModelRig actually
+ * serves, for accounting/policy. Value-by-value (registry ⇄ probes):
+ *
+ *   anthropic  1024 ⇄ 2048   DELTA — registry = Sonnet 5 / Opus 4.8 minimum
+ *                            (the deployed frontier; Opus 5/Fable 5 = 512,
+ *                            Haiku up to 4096); probes uses a haiku-safe 2048.
+ *   openai     1024 ⇄ 1024   agree (automatic prefix engages ≥1024).
+ *   gemini     4096 ⇄ 2048   DELTA — registry = implicit-caching 4096-token
+ *                            minimum prefix (research §2.1 / spec §1.4); probes
+ *                            uses 2048. FLAGGED for the architect to converge.
+ *   deepseek   64   ⇄ 64     agree (64-token cache blocks).
+ *   grok       null ⇄ 1024*  registry = no documented minimum (L5 null);
+ *   deepinfra  null ⇄ 1024*  probes falls these to DEFAULT_MIN_CACHEABLE_TOKENS
+ *   fireworks  null ⇄ 1024*  (1024) as an operational gate. Deliberate divergence:
+ *                            the registry will not assert a minimum it cannot
+ *                            source first-party.
+ */
+const POLICIES = {
+    // Anthropic — explicit cache_control (≤4 breakpoints) + automatic top-level
+    // mode. Writes 1.25× (5m) / 2× (1h); reads 0.1×. platform.claude.com
+    // prompt-caching, fetched 2026-08-18 (research §2.1).
+    anthropic: {
+        cache_supported: true,
+        mode: "explicit_breakpoints",
+        default_ttl_seconds: 300, // 5-min ephemeral, refreshes free on read
+        extended_ttl_seconds: 3600, // 1h GA at the 2× write multiplier
+        ttl_refresh_on_read: true, // documented: a read refreshes the 5m window
+        min_cacheable_tokens: 1024, // Sonnet 5 / Opus 4.8 (deployed); see reconciliation
+        cache_key_param: "cache_control",
+        reports_read_tokens: true, // cache_read_input_tokens
+        reports_write_tokens: true, // cache_creation_input_tokens (+ 5m/1h split)
+        usage_dialect: "anthropic",
+        provider_affinity_required: false, // model-scoped/workspace-isolated, no endpoint stickiness
+        source: "platform.claude.com/docs prompt-caching (fetched 2026-08-18)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+    // OpenAI — automatic prefix caching (≤5.5 baseline). Reads 0.1×; writes free
+    // ≤5.5, and GPT-5.6+ adds explicit breakpoints + PAID writes (1.25×, exact
+    // 30-min TTL) reported as input_tokens_details.cache_write_tokens.
+    // developers.openai.com prompt-caching, fetched 2026-08-18 (research §2.1).
+    openai: {
+        cache_supported: true,
+        mode: "automatic_prefix", // 5.6+ additionally supports explicit_breakpoints
+        default_ttl_seconds: 600, // 5-10 min inactivity window (5.6+: exact 30 min)
+        extended_ttl_seconds: 86400, // optional 24h retention, same price
+        ttl_refresh_on_read: true, // inactivity-based window — activity extends it (≤5.5)
+        min_cacheable_tokens: 1024, // automatic prefix engages at ≥1024 tokens
+        cache_key_param: "prompt_cache_key", // routing hint (not required to cache)
+        reports_read_tokens: true, // prompt_tokens_details.cached_tokens
+        reports_write_tokens: true, // input_tokens_details.cache_write_tokens (5.6+; 0 on ≤5.5)
+        usage_dialect: "openai_details",
+        provider_affinity_required: true, // ~15 req/min/key affinity (research §2.5)
+        source: "developers.openai.com/docs prompt-caching (fetched 2026-08-18)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+    // DeepSeek — automatic disk cache, always on. Reads ~0.03× (deepest in
+    // market); writes free. Usage is a hit/miss PARTITION (not a subset).
+    // api-docs.deepseek.com, fetched 2026-08-18 (research §2.1).
+    deepseek: {
+        cache_supported: true,
+        mode: "automatic_prefix",
+        default_ttl_seconds: null, // "hours to days", no exact documented TTL
+        extended_ttl_seconds: null,
+        ttl_refresh_on_read: false, // undocumented → conservative
+        min_cacheable_tokens: 64, // 64-token cache blocks (matches probes)
+        cache_key_param: null, // pure automatic, no key
+        reports_read_tokens: true, // prompt_cache_hit_tokens
+        reports_write_tokens: false, // writes free; miss tokens are the non-cached input
+        usage_dialect: "deepseek_partition",
+        provider_affinity_required: false,
+        source: "api-docs.deepseek.com context-caching (fetched 2026-08-18)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+    // Gemini — implicit caching, default-on 2.5+. Reads 0.1×; writes free. TTL is
+    // undocumented best-effort. EXCLUDED from WS-C `cache: auto` (its adapter
+    // treats any cache.key as a cachedContents RESOURCE NAME and drops
+    // systemInstruction+tools — gemini.ts:145). ai.google.dev, fetched 2026-08-18.
+    gemini: {
+        cache_supported: true,
+        mode: "automatic_prefix",
+        default_ttl_seconds: null, // undocumented best-effort
+        extended_ttl_seconds: null,
+        ttl_refresh_on_read: false, // undocumented → conservative
+        min_cacheable_tokens: 4096, // implicit-caching minimum prefix (spec §1.4); see reconciliation
+        cache_key_param: null, // implicit only; the cachedContents API is a different (explicit) product
+        reports_read_tokens: true, // usageMetadata.cachedContentTokenCount
+        reports_write_tokens: false,
+        usage_dialect: "gemini_metadata",
+        provider_affinity_required: false,
+        source: "ai.google.dev/gemini-api context-caching (fetched 2026-08-18)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+    // Grok (xAI) — automatic caching; reads 0.25× (Grok 4.6, model-varying),
+    // writes free. TTL ~5 min (3rd-party). docs.x.ai, fetched 2026-08-18.
+    grok: {
+        cache_supported: true,
+        mode: "automatic_prefix",
+        default_ttl_seconds: 300, // ~5 min (3rd-party; not first-party confirmed)
+        extended_ttl_seconds: null,
+        ttl_refresh_on_read: false, // undocumented → conservative
+        min_cacheable_tokens: null, // no documented minimum (L5)
+        cache_key_param: "prompt_cache_key", // x-grok-conv-id / prompt_cache_key hint
+        reports_read_tokens: true, // prompt_tokens_details.cached_tokens (compat)
+        reports_write_tokens: false,
+        usage_dialect: "openai_details",
+        provider_affinity_required: false, // team-scoped, undocumented
+        source: "docs.x.ai prompt-caching (fetched 2026-08-18)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+    // Fireworks — automatic caching on all models; reads ~0.5× serverless / free
+    // dedicated. Usage rides HTTP HEADERS (fireworks-prompt-tokens /
+    // -cached-prompt-tokens), NOT the usage JSON the openai-compat adapter reads —
+    // so cache tokens are NOT observable on our path today (header lift is a
+    // spec non-goal / flagged follow-up). docs.fireworks.ai, fetched 2026-08-18.
+    fireworks: {
+        cache_supported: true,
+        mode: "automatic_prefix",
+        default_ttl_seconds: null, // minutes-to-hours LRU, no exact
+        extended_ttl_seconds: null,
+        ttl_refresh_on_read: false,
+        min_cacheable_tokens: null,
+        cache_key_param: null,
+        reports_read_tokens: false, // header-based; not read by our usage-JSON path yet
+        reports_write_tokens: false,
+        usage_dialect: "fireworks_headers",
+        provider_affinity_required: true, // x-session-affinity
+        source: "docs.fireworks.ai prompt-caching (fetched 2026-08-18)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+    // DeepInfra — caching on SELECT models only (DeepSeek V3.x, Qwen3, some
+    // Claude), cached rates unverified first-party. Fail-closed to
+    // cache_supported:false, matching DeepInfra's existing pricing posture
+    // (pricing-sweep sweepDeepInfra: base-only, richer fields unverified, L5).
+    deepinfra: {
+        cache_supported: false,
+        mode: "automatic_prefix",
+        default_ttl_seconds: null,
+        extended_ttl_seconds: null,
+        ttl_refresh_on_read: false,
+        min_cacheable_tokens: null,
+        cache_key_param: null,
+        reports_read_tokens: false,
+        reports_write_tokens: false,
+        usage_dialect: "openai_details",
+        provider_affinity_required: false,
+        source: "deepinfra — cached rates unverified first-party (fail-closed, L5)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    },
+};
+/** The fail-closed policy for any provider not seeded (spec §3): caching is
+ * assumed OFF until a first-party source says otherwise — identical posture to
+ * the zero-coverage gates. `usage_dialect` defaults to the OpenAI shape only as
+ * a type-satisfying placeholder; `cache_supported: false` means no consumer
+ * reads it. */
+function failClosedCachePolicy() {
+    return {
+        cache_supported: false,
+        mode: "automatic_prefix",
+        default_ttl_seconds: null,
+        extended_ttl_seconds: null,
+        ttl_refresh_on_read: false,
+        min_cacheable_tokens: null,
+        cache_key_param: null,
+        reports_read_tokens: false,
+        reports_write_tokens: false,
+        usage_dialect: "openai_details",
+        provider_affinity_required: false,
+        source: "unseeded provider — fail-closed (no first-party cache policy)",
+        as_of: AS_OF,
+        policy_version: AS_OF,
+    };
+}
+/**
+ * The cache policy for a provider — the seeded first-party record, or a
+ * fail-closed `cache_supported: false` policy when the provider is not seeded
+ * (spec §3). Provider-level in v1; model-specific overrides land with the
+ * conversational-gateway phase.
+ */
+function getCachePolicy(provider) {
+    return POLICIES[provider] ?? failClosedCachePolicy();
+}
+/** Every seeded provider — for tests and the console policy surface (WS-D). */
+function seededCachePolicyProviders() {
+    return Object.keys(POLICIES);
+}

package/dist/registry/call-notes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"call-notes.d.ts","sourceRoot":"","sources":["../../src/registry/call-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA8BH,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAoChE"}
+{"version":3,"file":"call-notes.d.ts","sourceRoot":"","sources":["../../src/registry/call-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwCH,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAkEhE"}

package/dist/registry/call-notes.js

@@ -15,6 +15,15 @@ const GEMINI_THINKING_CAPABLE = new Set([
     "gemini-3.0-pro-preview",
     "gemini-3.1-flash-preview",
 ]);
+/**
+ * Models whose published probe measurements predate the provider-default
+ * reasoning policy (architect ruling, 2026-08-10): probe cycles 001–002
+ * pinned thinkingConfig thinkingLevel "high" on this set, inflating output
+ * tokens (billed as output) and therefore the effective-cost figure. The only
+ * board model affected. Remove each entry once its cycle-003 re-measure
+ * (provider-default thinking) is published.
+ */
+const GEMINI_PROBED_AT_THINKING_HIGH = new Set(["gemini-3.1-pro-preview"]);
 const GEMINI_COMMON = [
     "temperature must be 1.0 — lower values cause output looping on Gemini 3 models",
     "native strict structured output via responseJsonSchema; very complex schemas can be rejected as INVALID_ARGUMENT (complexity ceiling)",
@@ -47,25 +56,54 @@ function callNotesFor(modelKey) {
                 GEMINI_THINKING_CAPABLE.has(model)
                     ? "accepts thinkingConfig (thinking level); thinking tokens are billed as output and count against maxOutputTokens"
                     : "does NOT accept thinkingConfig — sending it returns 400 (thinking models only)",
+                ...(GEMINI_PROBED_AT_THINKING_HIGH.has(model)
+                    ? [
+                        "probe cycles 001-002 measured this model at thinking level high; probes run at provider-default thinking from cycle 003, and the published cost figure is re-measured then",
+                    ]
+                    : []),
             ];
         case "openai": {
+            // The Pro tier is Responses-API only (v1/chat/completions returns "not a
+            // chat model") — probed via the responses caller (coverage follow-ups
+            // 2026-08-11). Reasoning tokens bill as output at the Pro rate.
+            const responsesOnly = model.endsWith("-pro");
             const flexEligible = !model.includes("-mini") &&
                 !model.includes("-nano") &&
+                !responsesOnly &&
                 ["gpt-5.4", "gpt-5.2", "gpt-5.1", "gpt-5", "gpt-4.1"].some((p) => model.startsWith(p));
             return [
                 ...OPENAI_COMMON,
+                ...(responsesOnly
+                    ? [
+                        "Responses-API only — v1/chat/completions rejects it ('not a chat model'); probed via the v1/responses caller with strict json_schema output; reasoning tokens are billed as output at the Pro rate",
+                    ]
+                    : []),
                 flexEligible
                     ? "flex service tier eligible — discounted, sheddable capacity; served tier is echoed on the stream"
-                    : "NOT flex-eligible (mini/nano and older families) — flex requests are silently served at default tier",
+                    : "NOT flex-eligible (mini/nano, Pro, and older families) — flex requests are silently served at default tier",
             ];
         }
-        case "deepseek":
+        case "deepseek": {
+            // Alias resolution (coverage follow-ups, verified 2026-08-11 against the
+            // live models list + a call to each): DeepSeek's model list now shows only
+            // deepseek-v4-flash / deepseek-v4-pro; the classic `deepseek-chat` and
+            // `deepseek-reasoner` are rolling ALIASES that both currently resolve to
+            // deepseek-v4-flash (the API echoes `model: "deepseek-v4-flash"`). They are
+            // alive, not retired — kept on the board with this note. reasoner is
+            // v4-flash in reasoning mode.
+            const aliasNote = model === "deepseek-chat"
+                ? "rolling alias — currently serves deepseek-v4-flash (API echoes model=deepseek-v4-flash, verified 2026-08-11); alive despite being absent from the models list"
+                : model === "deepseek-reasoner"
+                    ? "rolling alias — currently serves deepseek-v4-flash in reasoning mode (API echoes model=deepseek-v4-flash, verified 2026-08-11); alive despite being absent from the models list"
+                    : "listed as a current DeepSeek model (deepseek-v4-*), 2026-08-11";
             return [
                 ...DEEPSEEK_COMMON,
                 model.includes("reasoner")
                     ? "emits reasoning_content (chain-of-thought) deltas — exclude them from the JSON buffer; only delta.content is the answer"
                     : "max_tokens up to 64K — full capacity for long structured reports",
+                aliasNote,
             ];
+        }
         default:
             return [];
     }

package/dist/registry/effective-rate.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Cache-adjusted route economics — cache-aware-routing spec §4.2–4.3, WS-B.
+ * PURE: no store, no clock, no network. Every function here is total and
+ * deterministic; the whole module is the math the architect reviews pre-merge.
+ *
+ * ── THE REGRESSION PIN (load-bearing, WS-A discipline) ────────────────────
+ * With observed hit rate h = 0 and write rate w = 0, `effectiveInputRate`
+ * returns the LIST input rate BYTE-IDENTICALLY, and every per-call saving
+ * collapses to 0. A route with no cache activity therefore prices exactly as it
+ * did before this module existed. The property test locks this: the cache-aware
+ * lens NEVER changes a number until real cache tokens appear.
+ *
+ * ── FAIL-CLOSED RATES (dev-rule L5) ───────────────────────────────────────
+ * An unverified cache-read or cache-write rate degrades to the INPUT rate
+ * (1.0×), never a guessed premium/discount — the same posture as
+ * `estimateCostUsd`. So an unpriced cache component can only make caching look
+ * NEUTRAL, never spuriously attractive.
+ *
+ * Units: every rate is USD PER TOKEN (matching `ModelPricing.inputUsdPerTok` and
+ * `pricing-shape.ts` `TokenRates`), so callers pass either shape unwidened.
+ */
+/**
+ * The rate components the effective-rate math needs, USD per token. A thin,
+ * self-contained shape so this module imports neither `ModelPricing` nor
+ * `pricing-shape` (both can build one) and — critically — does NOT touch the
+ * UNRELATED local `TokenRates` in `watch/evaluate.ts` (QA name-collision note:
+ * that one is a flat `{inputUsdPerTok, outputUsdPerTok}` blend input; keep them
+ * separate). `cacheRead`/`cacheWrite` null ⇒ fall back to `input` (L5).
+ */
+export interface EffectiveRates {
+    readonly input: number;
+    readonly cacheRead: number | null;
+    readonly cacheWrite: number | null;
+}
+/** Observed cache activity over a trailing window — the aggregate form (spec
+ * §4.2): `h = Σcached/Σin`, `w = Σwrite/Σin`. Both in [0,1]; `h + w ≤ 1` holds
+ * because cached and write tokens are disjoint subsets of input tokens. */
+export interface ObservedCacheRates {
+    readonly h: number;
+    readonly w: number;
+}
+/**
+ * Cache-adjusted effective INPUT rate (spec §4.2, aggregate form):
+ *
+ *   p_eff_in = h·p_read + w·p_write + (1 − h − w)·p_in
+ *
+ * The blend of what a token of input ACTUALLY costs given the window's cache
+ * behavior. Clamps h,w to non-negative and their sum to ≤ 1 (defensive — a
+ * malformed rollup must never produce a negative uncached weight). At h = w = 0
+ * this is exactly `rates.input` (the regression pin).
+ */
+export declare function effectiveInputRate(obs: ObservedCacheRates, rates: EffectiveRates): number;
+/**
+ * Expected per-call saving from READING a warm prefix instead of paying full
+ * input on it (spec §4.2, steady-state form): the cached prefix tokens cost
+ * `p_read` rather than `p_in`, so the saving per call is
+ *
+ *   E[T_read]·(p_in − p_read),  E[T_read] = matchingPrefixTokens · P(hit)
+ *
+ * The one-time write premium is NOT here — it is the switch cost (§4.3). At
+ * P(hit) = 0, or when the read rate has degraded to the input rate (L5), this is
+ * 0: a candidate with no verified read discount shows no per-call saving.
+ */
+export declare function perCallCacheSavingsUsd(matchingPrefixTokens: number, pHit: number, rates: EffectiveRates): number;
+/**
+ * Switch cost of moving a warm workflow from `oldRates` to `newRates` (spec
+ * §4.3):
+ *
+ *   switch_cost = prefix_tok·p_write(new) − prefix_tok·p_read(old)
+ *
+ * The new candidate must WRITE the prefix into its (cold) cache at its write
+ * rate; the incumbent would have READ it at its read rate. Positive ⇒ switching
+ * costs money up front; negative ⇒ the incumbent's read was already dearer than
+ * the challenger's write (rare, but real when the incumbent has no read
+ * discount). With `prefixTokens = 0` this is exactly 0 (the regression pin for a
+ * route with no cacheable prefix).
+ */
+export declare function switchCostUsd(prefixTokens: number, newRates: EffectiveRates, oldRates: EffectiveRates): number;
+/**
+ * Cache option value (spec §4.3): the total warmth advantage a candidate is
+ * expected to accrue over its remaining life — `E[remaining_calls] ×
+ * per_call_cache_savings`. This is the benefit side the switch cost is weighed
+ * against. Non-negative inputs; 0 at either factor 0.
+ */
+export declare function cacheOptionValueUsd(remainingCalls: number, perCallSavingsUsd: number): number;
+/** Floor on the denominator of `breakevenCalls` so a vanishing per-call saving
+ * yields a very large (but finite) break-even rather than Infinity/NaN. */
+export declare const BREAKEVEN_EPSILON_USD = 1e-9;
+/**
+ * Break-even call count (spec §4.3): `switch_cost / max(per_call_savings, ε)` —
+ * how many warm calls a swap must serve before its up-front switch cost is
+ * repaid by per-call savings. Returns `Infinity` when the switch never pays back
+ * (non-positive per-call saving with a positive switch cost) so callers render
+ * "never breaks even" rather than a misleading huge integer. A non-positive
+ * switch cost (free or profitable to switch) breaks even at 0 calls.
+ */
+export declare function breakevenCalls(switchCostUsd_: number, perCallSavingsUsd: number): number;
+/**
+ * The cache-aware verdict on a swap proposal (spec §4.3). Renders on the
+ * console, the `swap execute` approval prompt, and the OTLP decision span.
+ *   • `cache_positive`   — cache-adjusted advantage clears BOTH the absolute
+ *                          floor and the relative threshold; recommended.
+ *   • `cache_marginal`   — a real advantage that does not clear the hysteresis
+ *                          bar; created + labeled, NOT recommended (anti-thrash).
+ *   • `cache_negative`   — cache-adjusted, the challenger is WORSE than list
+ *                          would suggest (incumbent warm, challenger cold).
+ *   • `no_cache_signal`  — no observed cache activity to base a cache-aware
+ *                          verdict on; the ordinary list comparison stands.
+ */
+export type CacheVerdict = "cache_positive" | "cache_marginal" | "cache_negative" | "no_cache_signal";
+/**
+ * Hysteresis config (transaction-cost analogy, [Briefing §16]). A swap is
+ * `cache_positive` only when its advantage clears BOTH bars — an absolute
+ * per-call floor AND a relative fraction of window spend. Defaults per spec
+ * §4.3; lives in `WatchConfig` (same home as `thresholdPct`), which composes
+ * this shape rather than redefining it.
+ */
+export interface CacheHysteresisConfig {
+    /** Absolute floor, USD per call-equivalent (spec default $0.03). */
+    readonly cacheFloorUsdPerCall: number;
+    /** Relative floor, PERCENT of trailing-window spend (spec default 8%). */
+    readonly cacheRelativeThresholdPct: number;
+}
+export declare const DEFAULT_CACHE_HYSTERESIS: CacheHysteresisConfig;
+/** The inputs the verdict classifier weighs (all cache-ADJUSTED). */
+export interface CacheVerdictInput {
+    /** Whether the window carries ANY cache observation (read or write) on either
+     * side — false ⇒ `no_cache_signal` regardless of the numbers below. */
+    readonly hasCacheSignal: boolean;
+    /** Cache-adjusted per-call advantage of the challenger over the incumbent,
+     * USD (incumbent_effective_per_call − challenger_effective_per_call). >0 ⇒
+     * challenger cheaper once warmth + switch cost are counted. */
+    readonly perCallAdvantageUsd: number;
+    /** The same advantage projected over the expected remaining calls, USD — the
+     * quantity weighed against the relative (window-spend) bar. */
+    readonly totalAdvantageUsd: number;
+    /** Trailing-window spend on this route, USD — the base of the relative bar. */
+    readonly windowSpendUsd: number;
+}
+/**
+ * Classify a swap proposal's cache-aware verdict with hysteresis (spec §4.3).
+ * Pure and total. The ordering is deliberate: no signal short-circuits first
+ * (we cannot speak to cache economics we have not observed), then a negative
+ * advantage is `cache_negative`, then the two-bar hysteresis gate separates
+ * `cache_positive` from `cache_marginal`.
+ */
+export declare function classifyCacheVerdict(input: CacheVerdictInput, config?: CacheHysteresisConfig): CacheVerdict;
+/** Human-readable one-liner for a verdict — reused by the console, the approval
+ * prompt, and the definitions page (WS-D) so the phrasing is single-sourced. */
+export declare function describeCacheVerdict(verdict: CacheVerdict): string;
+//# sourceMappingURL=effective-rate.d.ts.map

package/dist/registry/effective-rate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-rate.d.ts","sourceRoot":"","sources":["../../src/registry/effective-rate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;2EAE2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAUzF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,oBAAoB,EAAE,MAAM,EAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,cAAc,GACpB,MAAM,CAKR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,cAAc,GACvB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAE7F;AAED;2EAC2E;AAC3E,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAIxF;AAID;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAEtG;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;CAC5C;AAED,eAAO,MAAM,wBAAwB,EAAE,qBAGtC,CAAC;AAEF,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC;2EACuE;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;mEAE+D;IAC/D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;mEAC+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,iBAAiB,EACxB,MAAM,GAAE,qBAAgD,GACvD,YAAY,CAOd;AAED;gFACgF;AAChF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAWlE"}

package/dist/registry/effective-rate.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Cache-adjusted route economics — cache-aware-routing spec §4.2–4.3, WS-B.
+ * PURE: no store, no clock, no network. Every function here is total and
+ * deterministic; the whole module is the math the architect reviews pre-merge.
+ *
+ * ── THE REGRESSION PIN (load-bearing, WS-A discipline) ────────────────────
+ * With observed hit rate h = 0 and write rate w = 0, `effectiveInputRate`
+ * returns the LIST input rate BYTE-IDENTICALLY, and every per-call saving
+ * collapses to 0. A route with no cache activity therefore prices exactly as it
+ * did before this module existed. The property test locks this: the cache-aware
+ * lens NEVER changes a number until real cache tokens appear.
+ *
+ * ── FAIL-CLOSED RATES (dev-rule L5) ───────────────────────────────────────
+ * An unverified cache-read or cache-write rate degrades to the INPUT rate
+ * (1.0×), never a guessed premium/discount — the same posture as
+ * `estimateCostUsd`. So an unpriced cache component can only make caching look
+ * NEUTRAL, never spuriously attractive.
+ *
+ * Units: every rate is USD PER TOKEN (matching `ModelPricing.inputUsdPerTok` and
+ * `pricing-shape.ts` `TokenRates`), so callers pass either shape unwidened.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CACHE_HYSTERESIS = exports.BREAKEVEN_EPSILON_USD = void 0;
+exports.effectiveInputRate = effectiveInputRate;
+exports.perCallCacheSavingsUsd = perCallCacheSavingsUsd;
+exports.switchCostUsd = switchCostUsd;
+exports.cacheOptionValueUsd = cacheOptionValueUsd;
+exports.breakevenCalls = breakevenCalls;
+exports.classifyCacheVerdict = classifyCacheVerdict;
+exports.describeCacheVerdict = describeCacheVerdict;
+/** Resolve a possibly-null cache rate to its fail-closed fallback (the input
+ * rate). Centralized so every function degrades identically (L5). */
+function readRate(rates) {
+    return rates.cacheRead ?? rates.input;
+}
+function writeRate(rates) {
+    return rates.cacheWrite ?? rates.input;
+}
+/**
+ * Cache-adjusted effective INPUT rate (spec §4.2, aggregate form):
+ *
+ *   p_eff_in = h·p_read + w·p_write + (1 − h − w)·p_in
+ *
+ * The blend of what a token of input ACTUALLY costs given the window's cache
+ * behavior. Clamps h,w to non-negative and their sum to ≤ 1 (defensive — a
+ * malformed rollup must never produce a negative uncached weight). At h = w = 0
+ * this is exactly `rates.input` (the regression pin).
+ */
+function effectiveInputRate(obs, rates) {
+    const h = Math.max(obs.h, 0);
+    const w = Math.max(obs.w, 0);
+    // Cap the combined cache weight at 1: uncached weight never goes negative.
+    const cacheWeight = Math.min(h + w, 1);
+    const scale = h + w > 0 ? cacheWeight / (h + w) : 0;
+    const hh = h * scale;
+    const ww = w * scale;
+    const uncachedWeight = 1 - hh - ww;
+    return hh * readRate(rates) + ww * writeRate(rates) + uncachedWeight * rates.input;
+}
+/**
+ * Expected per-call saving from READING a warm prefix instead of paying full
+ * input on it (spec §4.2, steady-state form): the cached prefix tokens cost
+ * `p_read` rather than `p_in`, so the saving per call is
+ *
+ *   E[T_read]·(p_in − p_read),  E[T_read] = matchingPrefixTokens · P(hit)
+ *
+ * The one-time write premium is NOT here — it is the switch cost (§4.3). At
+ * P(hit) = 0, or when the read rate has degraded to the input rate (L5), this is
+ * 0: a candidate with no verified read discount shows no per-call saving.
+ */
+function perCallCacheSavingsUsd(matchingPrefixTokens, pHit, rates) {
+    const tokens = Math.max(matchingPrefixTokens, 0);
+    const hit = Math.min(Math.max(pHit, 0), 1);
+    const perTokenSaving = Math.max(rates.input - readRate(rates), 0);
+    return tokens * hit * perTokenSaving;
+}
+/**
+ * Switch cost of moving a warm workflow from `oldRates` to `newRates` (spec
+ * §4.3):
+ *
+ *   switch_cost = prefix_tok·p_write(new) − prefix_tok·p_read(old)
+ *
+ * The new candidate must WRITE the prefix into its (cold) cache at its write
+ * rate; the incumbent would have READ it at its read rate. Positive ⇒ switching
+ * costs money up front; negative ⇒ the incumbent's read was already dearer than
+ * the challenger's write (rare, but real when the incumbent has no read
+ * discount). With `prefixTokens = 0` this is exactly 0 (the regression pin for a
+ * route with no cacheable prefix).
+ */
+function switchCostUsd(prefixTokens, newRates, oldRates) {
+    const tokens = Math.max(prefixTokens, 0);
+    return tokens * writeRate(newRates) - tokens * readRate(oldRates);
+}
+/**
+ * Cache option value (spec §4.3): the total warmth advantage a candidate is
+ * expected to accrue over its remaining life — `E[remaining_calls] ×
+ * per_call_cache_savings`. This is the benefit side the switch cost is weighed
+ * against. Non-negative inputs; 0 at either factor 0.
+ */
+function cacheOptionValueUsd(remainingCalls, perCallSavingsUsd) {
+    return Math.max(remainingCalls, 0) * Math.max(perCallSavingsUsd, 0);
+}
+/** Floor on the denominator of `breakevenCalls` so a vanishing per-call saving
+ * yields a very large (but finite) break-even rather than Infinity/NaN. */
+exports.BREAKEVEN_EPSILON_USD = 1e-9;
+/**
+ * Break-even call count (spec §4.3): `switch_cost / max(per_call_savings, ε)` —
+ * how many warm calls a swap must serve before its up-front switch cost is
+ * repaid by per-call savings. Returns `Infinity` when the switch never pays back
+ * (non-positive per-call saving with a positive switch cost) so callers render
+ * "never breaks even" rather than a misleading huge integer. A non-positive
+ * switch cost (free or profitable to switch) breaks even at 0 calls.
+ */
+function breakevenCalls(switchCostUsd_, perCallSavingsUsd) {
+    if (switchCostUsd_ <= 0)
+        return 0;
+    if (perCallSavingsUsd <= 0)
+        return Number.POSITIVE_INFINITY;
+    return switchCostUsd_ / Math.max(perCallSavingsUsd, exports.BREAKEVEN_EPSILON_USD);
+}
+exports.DEFAULT_CACHE_HYSTERESIS = {
+    cacheFloorUsdPerCall: 0.03,
+    cacheRelativeThresholdPct: 8,
+};
+/**
+ * Classify a swap proposal's cache-aware verdict with hysteresis (spec §4.3).
+ * Pure and total. The ordering is deliberate: no signal short-circuits first
+ * (we cannot speak to cache economics we have not observed), then a negative
+ * advantage is `cache_negative`, then the two-bar hysteresis gate separates
+ * `cache_positive` from `cache_marginal`.
+ */
+function classifyCacheVerdict(input, config = exports.DEFAULT_CACHE_HYSTERESIS) {
+    if (!input.hasCacheSignal)
+        return "no_cache_signal";
+    if (input.perCallAdvantageUsd < 0)
+        return "cache_negative";
+    const clearsFloor = input.perCallAdvantageUsd >= config.cacheFloorUsdPerCall;
+    const relativeBar = (config.cacheRelativeThresholdPct / 100) * Math.max(input.windowSpendUsd, 0);
+    const clearsRelative = input.totalAdvantageUsd >= relativeBar;
+    return clearsFloor && clearsRelative ? "cache_positive" : "cache_marginal";
+}
+/** Human-readable one-liner for a verdict — reused by the console, the approval
+ * prompt, and the definitions page (WS-D) so the phrasing is single-sourced. */
+function describeCacheVerdict(verdict) {
+    switch (verdict) {
+        case "cache_positive":
+            return "cache-positive — clears the switch-cost hysteresis; recommended";
+        case "cache_marginal":
+            return "cache-marginal — a real but sub-threshold advantage; not recommended (anti-thrash)";
+        case "cache_negative":
+            return "cache-negative — the incumbent is warm and the challenger is cold; switching costs more than it saves";
+        case "no_cache_signal":
+            return "no cache signal — no observed cache activity; the list-price comparison stands";
+    }
+}

package/dist/registry/facts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/registry/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,SAAS,CAAC;AAMvD,MAAM,WAAW,aAAa;IAC5B;wEACoE;IACpE,QAAQ,CACN,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,GACvC,WAAW,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;CACvC;AAED;sDACsD;AACtD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,GACvC,GAAG,CAAC,cAAc,CAAC,CAsDrB;AAQD,wBAAgB,iBAAiB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CA8BtE"}
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/registry/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,SAAS,CAAC;AAMvD,MAAM,WAAW,aAAa;IAC5B;wEACoE;IACpE,QAAQ,CACN,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,GACvC,WAAW,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;CACvC;AAED;sDACsD;AACtD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,WAAW,CAAC,cAAc,CAAC,GACvC,GAAG,CAAC,cAAc,CAAC,CAsErB;AAQD,wBAAgB,iBAAiB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CA8BtE"}

package/dist/registry/facts.js

@@ -81,6 +81,22 @@ function capabilityFactsFromEntry(entry, staticFlags) {
     else if (declared?.flags.supports_prompt_caching === true) {
         flags.add("prefix_cache_implicit");
     }
+    // zero_retention (G-3) — the opt-in data-governance filter. Authoritative
+    // source is the credential-scoped `facts` layer (claims.ts), NEVER the
+    // adapter-static baseline: ZDR is a policy designation, not an observable
+    // adapter capability. The flag is present only when a fact designates this
+    // endpoint zero-retention under our own (managed) account or unconditionally
+    // (any). A byok-only designation does NOT grant it — a customer's own key
+    // does not inherit our managed-account posture (the credential-scope
+    // compliance rule; product-plan v3.2, phase6-verification.md). Absence, a
+    // value:false, and a stray baseline flag all fail closed: no cited managed/any
+    // ZDR fact => the model is excluded from a `zero_retention` route.
+    const zdrFacts = entry.facts?.zero_retention;
+    const zdrDesignated = zdrFacts?.some((f) => f.value === true && (f.scope === "managed" || f.scope === "any")) ?? false;
+    if (zdrDesignated)
+        flags.add("zero_retention");
+    else
+        flags.delete("zero_retention");
     // context_cache_explicit / prompt_cache_key / tier_flex / trace_visible:
     // unprobed dimensions — the adapter-static baseline stands.
     return flags;