modelrig 0.0.1 → 0.1.0

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

package/dist/registry/parity.d.ts

@@ -0,0 +1,26 @@
+/**
+ * parity-50 — addendum A1 / provider-coverage-plan §3. The honest coverage
+ * KPI: how much of OpenRouter's top-50-by-usage list is PROBED (not merely
+ * listed) in our registry. A model counts as probed when ANY of its mapped
+ * registry keys carries probed schema samples — same weights on any host.
+ * Gaps are named on the leaderboard ("not yet probed"), never invisible.
+ */
+import type { Registry } from "./build";
+export interface ParityListEntry {
+    readonly name: string;
+    readonly registry_keys: readonly string[];
+}
+export interface ParityGap {
+    readonly name: string;
+    readonly status: "not yet probed" | "not in registry";
+}
+export interface ParityReport {
+    readonly total: number;
+    readonly probed: number;
+    readonly listedUnprobed: number;
+    readonly missing: number;
+    readonly probedPct: number;
+    readonly gaps: readonly ParityGap[];
+}
+export declare function computeParity(list: readonly ParityListEntry[], registry: Registry): ParityReport;
+//# sourceMappingURL=parity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parity.d.ts","sourceRoot":"","sources":["../../src/registry/parity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAAC;CACvD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;CACrC;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,CA4BhG"}

package/dist/registry/parity.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * parity-50 — addendum A1 / provider-coverage-plan §3. The honest coverage
+ * KPI: how much of OpenRouter's top-50-by-usage list is PROBED (not merely
+ * listed) in our registry. A model counts as probed when ANY of its mapped
+ * registry keys carries probed schema samples — same weights on any host.
+ * Gaps are named on the leaderboard ("not yet probed"), never invisible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeParity = computeParity;
+function computeParity(list, registry) {
+    const byKey = new Map(registry.models.map((m) => [m.model_key, m]));
+    let probed = 0;
+    let listedUnprobed = 0;
+    let missing = 0;
+    const gaps = [];
+    for (const entry of list) {
+        const matches = entry.registry_keys
+            .map((k) => byKey.get(k))
+            .filter((m) => m !== undefined);
+        if (matches.some((m) => (m.probed?.schema?.samples ?? 0) > 0)) {
+            probed += 1;
+        }
+        else if (matches.length > 0) {
+            listedUnprobed += 1;
+            gaps.push({ name: entry.name, status: "not yet probed" });
+        }
+        else {
+            missing += 1;
+            gaps.push({ name: entry.name, status: "not in registry" });
+        }
+    }
+    return {
+        total: list.length,
+        probed,
+        listedUnprobed,
+        missing,
+        probedPct: list.length === 0 ? 0 : probed / list.length,
+        gaps,
+    };
+}

package/dist/registry/pricing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Thin pricing accessor over the vendored LiteLLM pricing snapshot
+ * (data/pricing-map.json, extracted at the pinned SHA — see
+ * upstream/litellm.pin.json). The full three-layer registry is Phase 2;
+ * Phase 1 needs only cost-per-token lookups for envelopes, prefer:[cost]
+ * ordering, and telemetry cost estimates.
+ *
+ * Data source: model_prices_and_context_window.json,
+ * Copyright (c) 2023 Berri AI, MIT License (https://github.com/BerriAI/litellm).
+ */
+import type { ProviderId } from "../types/provider";
+export interface ModelPricing {
+    readonly inputUsdPerTok: number;
+    readonly outputUsdPerTok: number;
+    readonly cachedInputUsdPerTok: number | null;
+}
+export declare function getPricing(provider: ProviderId, model: string): ModelPricing | null;
+export declare function estimateCostUsd(pricing: ModelPricing, tokensIn: number, tokensOut: number, tokensCached: number): number;
+//# sourceMappingURL=pricing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/registry/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAmCD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAqBnF;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,CAWR"}

package/dist/registry/pricing.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Thin pricing accessor over the vendored LiteLLM pricing snapshot
+ * (data/pricing-map.json, extracted at the pinned SHA — see
+ * upstream/litellm.pin.json). The full three-layer registry is Phase 2;
+ * Phase 1 needs only cost-per-token lookups for envelopes, prefer:[cost]
+ * ordering, and telemetry cost estimates.
+ *
+ * Data source: model_prices_and_context_window.json,
+ * Copyright (c) 2023 Berri AI, MIT License (https://github.com/BerriAI/litellm).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPricing = getPricing;
+exports.estimateCostUsd = estimateCostUsd;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** LiteLLM key prefixes per provider, most-specific first. Verified against
+ * the snapshot (see data/PROVENANCE.md): Gemini API entries live under
+ * "gemini/" (bare ids resolve to Vertex pricing — different product), OpenAI
+ * under bare ids, DeepSeek under both. */
+const KEY_PREFIXES = {
+    gemini: ["gemini/"],
+    openai: ["", "openai/"],
+    deepseek: ["deepseek/", ""],
+    anthropic: ["anthropic/", ""],
+    grok: ["xai/"],
+    // A1 hosts: DeepInfra models keep their org path ("Qwen/QwQ-32B");
+    // Fireworks pricing keys carry the accounts/… wire prefix.
+    deepinfra: ["deepinfra/"],
+    fireworks: ["fireworks_ai/accounts/fireworks/models/", "fireworks_ai/"],
+};
+let cachedMap = null;
+function loadMap() {
+    if (cachedMap === null) {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "..", "data", "pricing-map.json"), "utf8");
+        cachedMap = JSON.parse(raw);
+    }
+    return cachedMap;
+}
+function getPricing(provider, model) {
+    if (model === "")
+        return null;
+    const map = loadMap();
+    for (const prefix of KEY_PREFIXES[provider]) {
+        const entry = map[`${prefix}${model}`];
+        if (entry !== undefined &&
+            typeof entry.input_cost_per_token === "number" &&
+            typeof entry.output_cost_per_token === "number") {
+            return {
+                inputUsdPerTok: entry.input_cost_per_token,
+                outputUsdPerTok: entry.output_cost_per_token,
+                cachedInputUsdPerTok: typeof entry.cache_read_input_token_cost === "number"
+                    ? entry.cache_read_input_token_cost
+                    : null,
+            };
+        }
+    }
+    return null;
+}
+function estimateCostUsd(pricing, tokensIn, tokensOut, tokensCached) {
+    // Providers report tokensCached as a subset of tokensIn; bill the cached
+    // part at the cached rate (input rate when none) and never negatively.
+    const cached = Math.min(Math.max(tokensCached, 0), Math.max(tokensIn, tokensCached));
+    const uncachedIn = Math.max(tokensIn - cached, 0);
+    const cachedRate = pricing.cachedInputUsdPerTok ?? pricing.inputUsdPerTok;
+    return (uncachedIn * pricing.inputUsdPerTok +
+        cached * cachedRate +
+        Math.max(tokensOut, 0) * pricing.outputUsdPerTok);
+}

package/dist/registry/rows.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Registry → selection rows. One projection, used by every surface that
+ * asks a capability question from the FILES (the CLI, `modelrig init`, the
+ * docs build). The console projects from its Supabase mirror and the oracle
+ * from its own loader, but all three land on the same `ModelSelectRow`
+ * shape so the three cannot answer differently.
+ */
+import type { ModelSelectRow } from "./select";
+/**
+ * Load selection rows from registry.json (+ leaderboard.json for effective
+ * cost). Returns [] rather than throwing when the registry is absent or
+ * unreadable — a repo without a built registry should still get drafts,
+ * carrying the incumbent alone.
+ */
+export declare function loadRegistryRows(registryPath?: string): ModelSelectRow[];
+//# sourceMappingURL=rows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../../src/registry/rows.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAyC/C;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CA2BxE"}

package/dist/registry/rows.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Registry → selection rows. One projection, used by every surface that
+ * asks a capability question from the FILES (the CLI, `modelrig init`, the
+ * docs build). The console projects from its Supabase mirror and the oracle
+ * from its own loader, but all three land on the same `ModelSelectRow`
+ * shape so the three cannot answer differently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadRegistryRows = loadRegistryRows;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+function packagedRegistryDir() {
+    // dist/ and src/ both sit one level under the package root.
+    return (0, node_path_1.join)(__dirname, "..", "..", "registry");
+}
+function readJson(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load selection rows from registry.json (+ leaderboard.json for effective
+ * cost). Returns [] rather than throwing when the registry is absent or
+ * unreadable — a repo without a built registry should still get drafts,
+ * carrying the incumbent alone.
+ */
+function loadRegistryRows(registryPath) {
+    const registryFile = registryPath ?? (0, node_path_1.join)(packagedRegistryDir(), "registry.json");
+    const registry = readJson(registryFile);
+    if (registry === null)
+        return [];
+    const dir = registryFile.slice(0, Math.max(registryFile.lastIndexOf("/"), 0));
+    const leaderboard = readJson((0, node_path_1.join)(dir, "leaderboard.json")) ?? [];
+    const effective = new Map(leaderboard.map((r) => [r.model_key, r.effective_usd_per_1k_conformant ?? null]));
+    return (registry.models ?? []).map((entry) => {
+        const [provider] = entry.model_key.split("/");
+        return {
+            key: entry.model_key,
+            provider: provider ?? entry.model_key,
+            inputUsdPerMtok: entry.declared?.pricing?.input_usd_per_mtok ?? null,
+            outputUsdPerMtok: entry.declared?.pricing?.output_usd_per_mtok ?? null,
+            conformRate: entry.probed?.schema?.conform_rate ?? null,
+            nativeRungRate: entry.probed?.schema?.native_rung_rate ?? null,
+            groundedRate: entry.probed?.grounding?.grounded_rate ?? null,
+            cacheHitRate: entry.probed?.caching?.cache_hit_rate ?? null,
+            effectiveUsdPer1k: effective.get(entry.model_key) ?? null,
+            discrepancies: entry.discrepancies?.length ?? 0,
+            probedAsOf: entry.probed?.as_of ?? null,
+        };
+    });
+}

package/dist/registry/seed.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Candidate seeding — the "what should serve this route?" answer, from the
+ * registry rather than from taste. Shared by `modelrig init` (WS2) and the
+ * oracle's `create_route` (WS1), so a drafted route looks the same however
+ * it was drafted.
+ *
+ * The rule: the INCUMBENT leads. The model you already call goes first, so
+ * the drafted route reproduces today's behavior on its first run; the
+ * cheapest probed models that satisfy the inferred capability needs follow
+ * as challengers a bake-off can put to the test. We never silently promote
+ * a cheaper model into first position — that decision belongs to evidence
+ * and a human.
+ */
+import type { CapabilityPredicate, ModelSelectRow } from "./select";
+import type { DraftCandidate } from "../routes/draft";
+export interface SeedCandidatesInput {
+    readonly capabilities: readonly CapabilityPredicate[];
+    /** "provider/model" the caller uses today, if known. */
+    readonly incumbent: string | null;
+    readonly maxInputUsdPerMtok: number | null;
+    /** Caller-supplied candidates short-circuit seeding entirely. */
+    readonly explicit: ReadonlyArray<{
+        readonly provider: string;
+        readonly model: string;
+    }> | null;
+    /** How many challengers to add behind the incumbent. */
+    readonly challengerCount?: number;
+}
+export interface SeededCandidates {
+    readonly candidates: readonly DraftCandidate[];
+    readonly incumbent: {
+        readonly provider: string;
+        readonly model: string;
+    } | null;
+    /** Human-readable account of why this list looks like it does. */
+    readonly reasoning: readonly string[];
+}
+export declare function splitModelKey(modelKey: string): {
+    provider: string;
+    model: string;
+} | null;
+export declare function seedCandidates(rows: readonly ModelSelectRow[], input: SeedCandidatesInput): SeededCandidates;
+//# sourceMappingURL=seed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../src/registry/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtD,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAC/F,wDAAwD;IACxD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjF,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI1F;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,cAAc,EAAE,EAC/B,KAAK,EAAE,mBAAmB,GACzB,gBAAgB,CAqFlB"}

package/dist/registry/seed.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Candidate seeding — the "what should serve this route?" answer, from the
+ * registry rather than from taste. Shared by `modelrig init` (WS2) and the
+ * oracle's `create_route` (WS1), so a drafted route looks the same however
+ * it was drafted.
+ *
+ * The rule: the INCUMBENT leads. The model you already call goes first, so
+ * the drafted route reproduces today's behavior on its first run; the
+ * cheapest probed models that satisfy the inferred capability needs follow
+ * as challengers a bake-off can put to the test. We never silently promote
+ * a cheaper model into first position — that decision belongs to evidence
+ * and a human.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitModelKey = splitModelKey;
+exports.seedCandidates = seedCandidates;
+const select_1 = require("./select");
+function splitModelKey(modelKey) {
+    const slash = modelKey.indexOf("/");
+    if (slash <= 0 || slash === modelKey.length - 1)
+        return null;
+    return { provider: modelKey.slice(0, slash), model: modelKey.slice(slash + 1) };
+}
+function seedCandidates(rows, input) {
+    if (input.explicit !== null && input.explicit.length > 0) {
+        return {
+            candidates: input.explicit.map((c) => ({ ...c })),
+            incumbent: input.explicit[0] ?? null,
+            reasoning: ["Candidates were given explicitly — the registry was not consulted."],
+        };
+    }
+    const reasoning = [];
+    const candidates = [];
+    let incumbent = null;
+    if (input.incumbent !== null && input.incumbent !== "") {
+        const parsed = splitModelKey(input.incumbent);
+        if (parsed === null) {
+            reasoning.push(`Could not read "${input.incumbent}" as an incumbent — model keys are "provider/model". ` +
+                "Drafted without one, so review the ordering before you run it.");
+        }
+        else {
+            incumbent = parsed;
+            const known = rows.some((r) => r.key === input.incumbent);
+            candidates.push({
+                ...parsed,
+                note: known
+                    ? "incumbent — your current model, listed first so behavior is unchanged on the first run"
+                    : "incumbent — your current model (not in our probed registry, so unmeasured here)",
+            });
+            reasoning.push(`Incumbent ${input.incumbent} leads: the drafted route reproduces what you do today.`);
+        }
+    }
+    else {
+        reasoning.push("No incumbent was identified, so the cheapest probed model that meets the requirements " +
+            "leads. If you already use a specific model, put it first before running this.");
+    }
+    const challengerCount = input.challengerCount ?? 2;
+    const wanted = challengerCount + (incumbent === null ? 0 : 1);
+    const hits = (0, select_1.selectModels)(rows, {
+        caps: input.capabilities,
+        maxInputUsdPerMtok: input.maxInputUsdPerMtok,
+        limit: challengerCount + 1,
+    });
+    for (const row of hits) {
+        if (candidates.length >= wanted)
+            break;
+        if (incumbent !== null && row.key === `${incumbent.provider}/${incumbent.model}`)
+            continue;
+        const parsed = splitModelKey(row.key);
+        if (parsed === null)
+            continue;
+        const effective = row.effectiveUsdPer1k;
+        candidates.push({
+            ...parsed,
+            note: effective === null
+                ? "probed, but no effective-cost figure yet"
+                : `probed: $${effective.toFixed(4)} per 1k conformant outputs`,
+        });
+    }
+    if (input.capabilities.length > 0) {
+        reasoning.push(`Challengers had to satisfy every requirement asked for (${input.capabilities.join(", ")}) ` +
+            "in probing — declared support alone was not enough.");
+    }
+    if (input.maxInputUsdPerMtok !== null) {
+        reasoning.push(`Challengers were capped at $${input.maxInputUsdPerMtok}/M input tokens.`);
+    }
+    if (candidates.length === 0) {
+        reasoning.push("No probed model satisfied the requirements, so this draft has no candidates and will not " +
+            "load — name a model explicitly, or loosen the requirements.");
+    }
+    else {
+        reasoning.push("Challengers are ranked by effective cost of conformance, not list price. Nothing switches " +
+            "to them without a bake-off and an explicit approval.");
+    }
+    return { candidates, incumbent, reasoning };
+}

package/dist/registry/select.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Model selection — the capability-first question, answered once.
+ *
+ * "Which models can serve strict JSON under $1/M?" is asked in three places:
+ * the console's query box, the MCP oracle's `query_registry` tool, and the
+ * docs. Phase 5 plan §10 names the risk by name — oracle answers drifting
+ * from console answers — so the grammar and the predicates live HERE and
+ * both surfaces call in. If this file changes, every surface changes.
+ *
+ * Dependency-free on purpose: the console imports this source directly (its
+ * tsconfig path alias) and must not drag SQLite or the adapters into a
+ * browser bundle.
+ *
+ * Bars are the registry's own, not new judgments: 0.9 conformance (the
+ * discrepancy detector's bar) and 0.5 grounding (facts.ts's GROUNDED_BAR).
+ */
+/** The capability predicates a question can carry. Deliberately the probed
+ * dimensions only — we answer from measurement, not from provider claims. */
+export type CapabilityPredicate = "structured-native" | "structured-coached" | "grounding" | "caching";
+export declare const ALL_CAPABILITY_PREDICATES: readonly CapabilityPredicate[];
+/** Plain-language gloss per predicate — the explainability layer travels
+ * WITH the answer (console-explainability.md §1), it is not a separate doc. */
+export declare const PREDICATE_GLOSS: Readonly<Record<CapabilityPredicate, string>>;
+/** The row shape selection needs. A projection, not the registry entry —
+ * console (Supabase mirror) and oracle (registry.json) both flatten into it. */
+export interface ModelSelectRow {
+    readonly key: string;
+    readonly provider: string;
+    readonly inputUsdPerMtok: number | null;
+    readonly outputUsdPerMtok: number | null;
+    readonly conformRate: number | null;
+    readonly nativeRungRate: number | null;
+    readonly groundedRate: number | null;
+    readonly cacheHitRate: number | null;
+    readonly effectiveUsdPer1k: number | null;
+    readonly discrepancies: number;
+    readonly probedAsOf: string | null;
+}
+export declare function hasCapability(row: ModelSelectRow, cap: CapabilityPredicate): boolean;
+export interface ParsedQuery {
+    readonly caps: readonly CapabilityPredicate[];
+    readonly maxInputUsdPerMtok: number | null;
+    /** Leftover words — substring-matched against the model key. */
+    readonly text: readonly string[];
+}
+/** The tiny grammar behind the query box and the oracle's free-text input:
+ * capability words + an "under $N/M" price cap; everything else is a
+ * substring match on the model key. Small on purpose — a question we cannot
+ * parse should fall through to text, not guess. */
+export declare function parseCapabilityQuery(query: string): ParsedQuery;
+export interface SelectCriteria {
+    /** Capability predicates ANDed together — every one must hold. */
+    readonly caps?: readonly CapabilityPredicate[];
+    readonly maxInputUsdPerMtok?: number | null;
+    readonly provider?: string | null;
+    readonly discrepanciesOnly?: boolean;
+    /** Substring terms ANDed against the model key. */
+    readonly text?: readonly string[];
+    /** Sort by effective cost of conformance ascending (default true) — the
+     * only ranking that answers "cheapest that actually works". */
+    readonly sortByEffectiveCost?: boolean;
+    readonly limit?: number;
+}
+export declare function selectModels(rows: readonly ModelSelectRow[], criteria?: SelectCriteria): ModelSelectRow[];
+/** Why a question found nothing — the difference between "no such model" and
+ * "we have not probed one yet" is the whole point of the demand meter. */
+export declare function explainEmptySelection(criteria: SelectCriteria): string;
+//# sourceMappingURL=select.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/registry/select.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;6EAC6E;AAC7E,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,oBAAoB,GACpB,WAAW,GACX,SAAS,CAAC;AAEd,eAAO,MAAM,yBAAyB,EAAE,SAAS,mBAAmB,EAKnE,CAAC;AAEF;+EAC+E;AAC/E,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAQzE,CAAC;AAEF;gFACgF;AAChF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAKD,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAWpF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AA0BD;;;mDAGmD;AACnD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAkB/D;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;mEAC+D;IAC/D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,cAAc,EAAE,EAC/B,QAAQ,GAAE,cAAmB,GAC5B,cAAc,EAAE,CA6BlB;AAED;0EAC0E;AAC1E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAatE"}