modelrig 0.0.1 → 0.2.0

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

@@ -0,0 +1,32 @@
+/**
+ * Registry-wired capability facts — Phase 3 spec WS6, plan §4. Replaces the
+ * Phase 1 "grant whatever the adapter claims" stub: routing now consumes
+ * declared+probed registry facts from the packaged registry.json
+ * (env-overridable path), with precedence
+ *
+ *   capabilityOverrides (config) > probed > declared
+ *
+ * applied PER FLAG. Discrepancy-aware: a probed-false trumps a declared-true
+ * — the DeepSeek case (declared supports_response_schema, probed
+ * native_rung_rate = 0) finally routes correctly.
+ *
+ * Conservatism rules (measurement honesty):
+ *  - grounded_native: probed can only REVOKE (a declared-true with a low
+ *    probed grounded rate), never grant — high citation rates without
+ *    declared search may be fabricated URLs.
+ *  - Unprobed/undeclared dimensions (explicit caches, cache keys, flex tier,
+ *    trace visibility) fall back to the adapter-static map, which is the
+ *    declared layer for call-shaping facts.
+ */
+import type { CapabilityFlag, ProviderId } from "../types/provider";
+import type { RegistryEntry } from "./build";
+export interface RegistryFacts {
+    /** Capability flags for a (provider, model), or null when the registry has
+     * no entry for it (caller falls back to the adapter-static map). */
+    flagsFor(provider: ProviderId, model: string, staticFlags: ReadonlySet<CapabilityFlag>): ReadonlySet<CapabilityFlag> | null;
+}
+/** Per-flag fact merge for one registry entry. `staticFlags` is the
+ * adapter-static (declared call-shaping) baseline. */
+export declare function capabilityFactsFromEntry(entry: RegistryEntry, staticFlags: ReadonlySet<CapabilityFlag>): Set<CapabilityFlag>;
+export declare function loadRegistryFacts(registryPath?: string): RegistryFacts;
+//# sourceMappingURL=facts.d.ts.map

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

@@ -0,0 +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,CAsErB;AAQD,wBAAgB,iBAAiB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CA8BtE"}

package/dist/registry/facts.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Registry-wired capability facts — Phase 3 spec WS6, plan §4. Replaces the
+ * Phase 1 "grant whatever the adapter claims" stub: routing now consumes
+ * declared+probed registry facts from the packaged registry.json
+ * (env-overridable path), with precedence
+ *
+ *   capabilityOverrides (config) > probed > declared
+ *
+ * applied PER FLAG. Discrepancy-aware: a probed-false trumps a declared-true
+ * — the DeepSeek case (declared supports_response_schema, probed
+ * native_rung_rate = 0) finally routes correctly.
+ *
+ * Conservatism rules (measurement honesty):
+ *  - grounded_native: probed can only REVOKE (a declared-true with a low
+ *    probed grounded rate), never grant — high citation rates without
+ *    declared search may be fabricated URLs.
+ *  - Unprobed/undeclared dimensions (explicit caches, cache keys, flex tier,
+ *    trace visibility) fall back to the adapter-static map, which is the
+ *    declared layer for call-shaping facts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilityFactsFromEntry = capabilityFactsFromEntry;
+exports.loadRegistryFacts = loadRegistryFacts;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Same bar the registry's discrepancy detection uses. */
+const GROUNDED_BAR = 0.5;
+const CONFORMANCE_BAR = 0.9;
+/** Per-flag fact merge for one registry entry. `staticFlags` is the
+ * adapter-static (declared call-shaping) baseline. */
+function capabilityFactsFromEntry(entry, staticFlags) {
+    const flags = new Set(staticFlags);
+    const declared = entry.declared;
+    const probed = entry.probed;
+    // structured_native — probed native_rung_rate is the ground truth when
+    // sampled; else declared (adapter fact first, pricing-map flag second).
+    const nativeRate = probed?.schema?.native_rung_rate ?? null;
+    if (nativeRate !== null) {
+        if (nativeRate > 0)
+            flags.add("structured_native");
+        else
+            flags.delete("structured_native"); // the DeepSeek json_object-vs-schema gap
+    }
+    else if (declared !== null) {
+        const declaredNative = declared.flags.adapter_structured_native ?? declared.flags.supports_response_schema;
+        if (declaredNative === true)
+            flags.add("structured_native");
+        else if (declaredNative === false)
+            flags.delete("structured_native");
+    }
+    // json_mode — probed: a sampled schema class with a decent conform rate on
+    // ANY rung proves the model can emit parseable schema-shaped JSON.
+    const conformRate = probed?.schema?.conform_rate ?? null;
+    if (conformRate !== null && conformRate >= CONFORMANCE_BAR) {
+        flags.add("json_mode");
+    }
+    // grounded_native — probed may REVOKE a declared-true, never grant.
+    const groundedRate = probed?.grounding?.grounded_rate ?? null;
+    const declaredGrounded = declared === null
+        ? null
+        : (declared.flags.adapter_grounded_native ?? declared.flags.supports_web_search);
+    if (declaredGrounded === true)
+        flags.add("grounded_native");
+    else if (declaredGrounded === false)
+        flags.delete("grounded_native");
+    if (flags.has("grounded_native") &&
+        groundedRate !== null &&
+        (probed?.grounding?.samples ?? 0) > 0 &&
+        groundedRate < GROUNDED_BAR) {
+        flags.delete("grounded_native");
+    }
+    // prefix_cache_implicit — probed realized cache behavior wins when sampled.
+    const caching = probed?.caching ?? null;
+    if (caching !== null && caching.samples > 0) {
+        if (caching.cache_hit_rate > 0)
+            flags.add("prefix_cache_implicit");
+        else
+            flags.delete("prefix_cache_implicit");
+    }
+    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;
+}
+/** Packaged registry.json (registry/ at the package root; dist/ and src/
+ * both sit one level below it). */
+function packagedRegistryPath() {
+    return (0, node_path_1.join)(__dirname, "..", "..", "registry", "registry.json");
+}
+function loadRegistryFacts(registryPath) {
+    const path = registryPath ?? packagedRegistryPath();
+    let byKey = new Map();
+    if ((0, node_fs_1.existsSync)(path)) {
+        const registry = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+        byKey = new Map(registry.models.map((m) => [m.model_key, m]));
+    }
+    else if (registryPath !== undefined) {
+        // An EXPLICIT path that doesn't exist is a config error worth failing on;
+        // a missing packaged file just means static fallback (fresh checkout).
+        throw new Error(`registry facts file not found: ${path}`);
+    }
+    const cache = new Map();
+    return {
+        flagsFor(provider, model, staticFlags) {
+            const key = `${provider}/${model}`;
+            const entry = byKey.get(key);
+            if (entry === undefined)
+                return null;
+            let flags = cache.get(key);
+            if (flags === undefined) {
+                flags = capabilityFactsFromEntry(entry, staticFlags);
+                cache.set(key, flags);
+            }
+            return flags;
+        },
+    };
+}

package/dist/registry/fingerprint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema fingerprinting — spec §2 WS6, network-effects instrumentation.
+ * Pure function: JSON schema → bucketed structural features + task category
+ * + a stable cell key. Computed at route load; stored on every telemetry row.
+ * PRIVACY: the fingerprint must be irreversible — features and category only,
+ * never field names, titles, descriptions, or enum values.
+ */
+export type TaskCategory = "extraction" | "generation" | "classification" | "analysis";
+export interface SchemaFingerprint {
+    readonly depthBucket: "1-2" | "3-4" | "5+";
+    readonly fieldCountBucket: "1-5" | "6-20" | "21-60" | "61+";
+    readonly enumDensityBucket: "none" | "low" | "high";
+    readonly lengthFloorCount: number;
+    readonly arrayComplexityBucket: "none" | "flat" | "nested";
+    readonly category: TaskCategory;
+    /** Stable hash of the buckets above — the Conformance Matrix cell key. */
+    readonly cellKey: string;
+}
+export declare function fingerprintSchema(schema: object | null): SchemaFingerprint | null;
+//# sourceMappingURL=fingerprint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/registry/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEvF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IAC5D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AA8GD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,iBAAiB,GAAG,IAAI,CAgDjF"}

package/dist/registry/fingerprint.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Schema fingerprinting — spec §2 WS6, network-effects instrumentation.
+ * Pure function: JSON schema → bucketed structural features + task category
+ * + a stable cell key. Computed at route load; stored on every telemetry row.
+ * PRIVACY: the fingerprint must be irreversible — features and category only,
+ * never field names, titles, descriptions, or enum values.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintSchema = fingerprintSchema;
+const node_crypto_1 = require("node:crypto");
+const MAX_WALK_DEPTH = 12;
+/** minLength at or above this marks a prose field (a deliberate length floor,
+ * not an id/enum constraint) — the "analysis" signal. */
+const PROSE_FLOOR_MIN_LENGTH = 200;
+const LOW_ENUM_RATIO = 0.2;
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+const SCALAR_TYPES = new Set(["string", "number", "integer", "boolean", "null"]);
+function isScalarNode(node) {
+    return typeof node.type === "string" && SCALAR_TYPES.has(node.type);
+}
+function walk(node, depth, stats) {
+    if (!isRecord(node) || depth > MAX_WALK_DEPTH)
+        return;
+    if (depth > stats.maxDepth)
+        stats.maxDepth = depth;
+    if (isScalarNode(node)) {
+        stats.leafCount += 1;
+        if (Array.isArray(node.enum) || node.const !== undefined)
+            stats.enumLeafCount += 1;
+        if (node.type === "string" &&
+            typeof node.minLength === "number" &&
+            node.minLength >= PROSE_FLOOR_MIN_LENGTH) {
+            stats.proseFloorCount += 1;
+        }
+        return;
+    }
+    const properties = node.properties;
+    if (isRecord(properties)) {
+        for (const child of Object.values(properties)) {
+            stats.fieldCount += 1;
+            walk(child, depth + 1, stats);
+        }
+    }
+    const items = node.items;
+    if (items !== undefined) {
+        const itemNodes = Array.isArray(items) ? items : [items];
+        for (const item of itemNodes) {
+            if (isRecord(item) && isScalarNode(item)) {
+                stats.hasFlatArray = true;
+                walk(item, depth + 1, stats);
+            }
+            else {
+                stats.hasNestedArray = true;
+                walk(item, depth + 1, stats);
+            }
+        }
+    }
+    if (isRecord(node.additionalProperties))
+        walk(node.additionalProperties, depth + 1, stats);
+    for (const combinator of ["anyOf", "oneOf", "allOf"]) {
+        const branches = node[combinator];
+        if (Array.isArray(branches)) {
+            // Combinator branches describe the SAME position — no depth increase.
+            for (const branch of branches)
+                walk(branch, depth, stats);
+        }
+    }
+}
+function bucketDepth(depth) {
+    if (depth <= 2)
+        return "1-2";
+    if (depth <= 4)
+        return "3-4";
+    return "5+";
+}
+function bucketFieldCount(count) {
+    if (count <= 5)
+        return "1-5";
+    if (count <= 20)
+        return "6-20";
+    if (count <= 60)
+        return "21-60";
+    return "61+";
+}
+function bucketEnumDensity(ratio) {
+    if (ratio === 0)
+        return "none";
+    if (ratio < LOW_ENUM_RATIO)
+        return "low";
+    return "high";
+}
+function categorize(stats, enumDensity) {
+    // Order matters (v0 heuristic, spec WS6): a deliberate prose floor is the
+    // strongest signal (analysis) → enum dominance (classification) → shallow
+    // typed scalars (extraction) → everything else (generation).
+    if (stats.proseFloorCount > 0)
+        return "analysis";
+    if (enumDensity === "high")
+        return "classification";
+    if (stats.maxDepth <= 2 && !stats.hasNestedArray && stats.leafCount > 0)
+        return "extraction";
+    return "generation";
+}
+function fingerprintSchema(schema) {
+    if (schema === null)
+        return null;
+    const stats = {
+        maxDepth: 0,
+        fieldCount: 0,
+        leafCount: 0,
+        enumLeafCount: 0,
+        proseFloorCount: 0,
+        hasFlatArray: false,
+        hasNestedArray: false,
+    };
+    walk(schema, 1, stats);
+    const enumRatio = stats.leafCount === 0 ? 0 : stats.enumLeafCount / stats.leafCount;
+    const enumDensityBucket = bucketEnumDensity(enumRatio);
+    const arrayComplexityBucket = stats.hasNestedArray
+        ? "nested"
+        : stats.hasFlatArray
+            ? "flat"
+            : "none";
+    const category = categorize(stats, enumDensityBucket);
+    const depthBucket = bucketDepth(stats.maxDepth);
+    const fieldCountBucket = bucketFieldCount(stats.fieldCount);
+    const cellKey = (0, node_crypto_1.createHash)("sha256")
+        .update(JSON.stringify([
+        depthBucket,
+        fieldCountBucket,
+        enumDensityBucket,
+        stats.proseFloorCount,
+        arrayComplexityBucket,
+        category,
+    ]))
+        .digest("hex")
+        .slice(0, 16);
+    return {
+        depthBucket,
+        fieldCountBucket,
+        enumDensityBucket,
+        lengthFloorCount: stats.proseFloorCount,
+        arrayComplexityBucket,
+        category,
+        cellKey,
+    };
+}