modelrig 0.4.0 → 0.6.0

package/dist/query/grammar.js

@@ -1,25 +1,57 @@
 "use strict";
 /**
- * The telemetry query grammar — Phase 4 WS5 ("your exhaust is your data").
+ * The telemetry query grammar — Phase 4 WS5 ("your exhaust is your data"),
+ * extended for WI-1b (the attempt-envelope analytics surface).
+ *
  * A hand-rolled recursive-descent parser over a DELIBERATELY tiny SQL-ish
  * language:
  *
  *   SELECT item (, item)* FROM inferences
  *     [WHERE cond (AND cond)*] [GROUP BY col (, col)*] [LIMIT n]
  *   item := col | count(*) | sum(m)|avg(m)|min(m)|max(m)
- *   col  := route|provider|model|ts|failure_class|served_variant|tag.<name>
+ *   col  := route|provider|model|ts|failure_class|served_variant
+ *         | subject|feature|user|session|cost_center            (reserved dims)
+ *         | meta.<field>                                        (attempt envelope)
+ *         | tag.<name>
  *   m    := cost|tokens_in|tokens_out|tokens_cached|latency_ms|ttfb_ms
+ *         | meta.http_status|meta.reasoning_tokens|meta.response_chars
+ *         | meta.cost.in|meta.cost.out|meta.cost.cache_read|meta.cost.cache_write|meta.cost.other
  *   cond := col op literal      op := = != > < >= <=
  *
- * Security model = the allowlist: unknown tokens throw, string literals
- * only ever travel as bind parameters, the output is a single read-only
- * SELECT. There is no raw-SQL path — by construction, not by filtering.
- * Row scoping: a token's scope is ANDed into WHERE as one more bind
- * parameter; the caller cannot opt out of it.
+ * ── TWO EXECUTION TARGETS, ONE PARSER (S1: extend, don't twin) ────────────
+ * `parseQuery` produces a {@link QueryAst}. `compileQuery` renders that AST to a
+ * single read-only SQLite SELECT (the local `/query` surface, `runTelemetryQuery`).
+ * The server analytics surface (`/v1/analytics/query`) evaluates the SAME AST
+ * over PostgREST-read rows in JS (query/analytics.ts) — so the grammar, its
+ * SQLite semantics, and its multi-tenant semantics can never disagree.
+ *
+ * Security model = the allowlist (columns.ts): unknown tokens throw, string
+ * literals only ever travel as bind parameters, the SQLite output is a single
+ * read-only SELECT. There is no raw-SQL path — by construction, not by filtering.
+ * The metadata-safe invariant is structural: every selectable column is an
+ * enum/number/boolean/hash/identifier/timestamp (columns.ts), never content.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryGrammarError = void 0;
+exports.QueryGrammarError = exports.RESERVED_DIMENSION_NAMES = exports.METRIC_COLUMNS = exports.DIMENSION_COLUMNS = exports.sinceIsoFor = exports.savedQueryById = exports.SAVED_QUERIES = exports.selectableColumnsAreMetaSafe = exports.ANALYTICS_SCAN_CAP = exports.planAnalyticsRead = exports.evaluateAnalyticsQuery = exports.describeAnalyticsSchema = void 0;
+exports.parseQuery = parseQuery;
 exports.compileQuery = compileQuery;
+const columns_1 = require("./columns");
+// Re-surface the analytics + saved-query symbols through this module so the
+// package barrel (index.ts) can name them without a new export line (LOC cap).
+var analytics_1 = require("./analytics");
+Object.defineProperty(exports, "describeAnalyticsSchema", { enumerable: true, get: function () { return analytics_1.describeAnalyticsSchema; } });
+Object.defineProperty(exports, "evaluateAnalyticsQuery", { enumerable: true, get: function () { return analytics_1.evaluateAnalyticsQuery; } });
+Object.defineProperty(exports, "planAnalyticsRead", { enumerable: true, get: function () { return analytics_1.planAnalyticsRead; } });
+Object.defineProperty(exports, "ANALYTICS_SCAN_CAP", { enumerable: true, get: function () { return analytics_1.ANALYTICS_SCAN_CAP; } });
+Object.defineProperty(exports, "selectableColumnsAreMetaSafe", { enumerable: true, get: function () { return analytics_1.selectableColumnsAreMetaSafe; } });
+var saved_1 = require("./saved");
+Object.defineProperty(exports, "SAVED_QUERIES", { enumerable: true, get: function () { return saved_1.SAVED_QUERIES; } });
+Object.defineProperty(exports, "savedQueryById", { enumerable: true, get: function () { return saved_1.savedQueryById; } });
+Object.defineProperty(exports, "sinceIsoFor", { enumerable: true, get: function () { return saved_1.sinceIsoFor; } });
+var columns_2 = require("./columns");
+Object.defineProperty(exports, "DIMENSION_COLUMNS", { enumerable: true, get: function () { return columns_2.DIMENSION_COLUMNS; } });
+Object.defineProperty(exports, "METRIC_COLUMNS", { enumerable: true, get: function () { return columns_2.METRIC_COLUMNS; } });
+Object.defineProperty(exports, "RESERVED_DIMENSION_NAMES", { enumerable: true, get: function () { return columns_2.RESERVED_DIMENSION_NAMES; } });
 class QueryGrammarError extends Error {
     constructor(message) {
         super(message);
@@ -27,22 +59,6 @@ class QueryGrammarError extends Error {
     }
 }
 exports.QueryGrammarError = QueryGrammarError;
-const PLAIN_COLUMNS = {
-    route: "route",
-    provider: "provider",
-    model: "model",
-    ts: "ts",
-    failure_class: "failure_class",
-    served_variant: "served_variant",
-};
-const METRICS = {
-    cost: "cost_estimate_usd",
-    tokens_in: "tokens_in",
-    tokens_out: "tokens_out",
-    tokens_cached: "tokens_cached",
-    latency_ms: "latency_ms",
-    ttfb_ms: "ttfb_ms",
-};
 const FUNCTIONS = new Set(["sum", "avg", "min", "max", "count"]);
 const OPERATORS = new Set(["=", "!=", ">", "<", ">=", "<="]);
 const TAG_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -121,23 +137,69 @@ function tokenize(input) {
     }
     return tokens;
 }
-/** Column reference → SQL expression. tag.<name> compiles to a
- * json_extract over tags_json with a VALIDATED identifier (never
- * interpolated user text beyond the identifier alphabet). */
-function columnSql(word) {
+/** The alias a column reads out under — `tag.client`/`meta.finish_reason` lose
+ * their prefix so result keys read naturally (`client`, `finish_reason`). */
+function aliasFor(word) {
+    if (word.startsWith("tag."))
+        return word.slice(4);
+    if (word.startsWith("meta."))
+        return word.slice(5);
+    return word;
+}
+/** Resolve a grammar word to a DIMENSION reference (group/filter), or throw. A
+ * `tag.<name>` compiles to a validated tags key; every other name must be a
+ * registered dimension (columns.ts). */
+function resolveDimension(word) {
     if (word.startsWith("tag.")) {
         const tag = word.slice(4);
         if (!TAG_NAME.test(tag))
             throw new QueryGrammarError(`bad tag name: ${tag}`);
-        return `json_extract(tags_json, '$.${tag}')`;
+        return { name: word, source: "tag", key: tag, classification: "identifier", numeric: false, alias: tag };
     }
-    const column = PLAIN_COLUMNS[word];
-    if (column === undefined) {
-        throw new QueryGrammarError(`unknown column "${word}" — allowed: ${Object.keys(PLAIN_COLUMNS).join(", ")}, tag.<name>`);
+    const def = columns_1.DIMENSIONS_BY_NAME.get(word);
+    if (def === undefined) {
+        throw new QueryGrammarError(`unknown column "${word}" — allowed: ${[...columns_1.DIMENSIONS_BY_NAME.keys()].join(", ")}, tag.<name>`);
     }
-    return column;
+    return refOf(def);
 }
-function compileQuery(input, scope) {
+/** Resolve a grammar word to a METRIC reference (aggregate target), or throw. */
+function resolveMetric(word) {
+    const def = columns_1.METRICS_BY_NAME.get(word);
+    if (def === undefined) {
+        throw new QueryGrammarError(`unknown metric "${word}" — allowed: ${[...columns_1.METRICS_BY_NAME.keys()].join(", ")}`);
+    }
+    return refOf(def);
+}
+/**
+ * Resolve the argument of an aggregate. `sum`/`avg` require a NUMERIC metric.
+ * `min`/`max` also accept a dimension (e.g. `min(ts)` for first-seen) — MIN/MAX
+ * over an ordered non-numeric column is well-defined (SQL + the JS fold agree).
+ */
+function resolveAggArg(fn, word) {
+    if (fn === "sum" || fn === "avg")
+        return resolveMetric(word);
+    const metric = columns_1.METRICS_BY_NAME.get(word);
+    if (metric !== undefined)
+        return refOf(metric);
+    return resolveDimension(word);
+}
+function refOf(def) {
+    return {
+        name: def.name,
+        source: def.source,
+        key: def.key,
+        classification: def.classification,
+        numeric: def.numeric,
+        alias: aliasFor(def.name),
+    };
+}
+/**
+ * Parse a query string into a {@link QueryAst}. Pure and total: every path
+ * either returns a validated AST or throws {@link QueryGrammarError}. This is
+ * the single parser — both the SQLite compiler (below) and the PostgREST
+ * evaluator (analytics.ts) consume its output.
+ */
+function parseQuery(input) {
     const tokens = tokenize(input);
     let pos = 0;
     const peek = () => tokens[pos];
@@ -161,7 +223,7 @@ function compileQuery(input, scope) {
         }
     }
     expectWord("select");
-    const selectSql = [];
+    const select = [];
     for (;;) {
         const token = next();
         if (token.kind !== "word")
@@ -175,22 +237,19 @@ function compileQuery(input, scope) {
                 if (arg.kind !== "punct" || arg.text !== "*") {
                     throw new QueryGrammarError("count takes exactly count(*)");
                 }
-                selectSql.push(`COUNT(*) AS "count"`);
+                select.push({ kind: "count", alias: "count" });
             }
             else {
                 if (arg.kind !== "word")
                     throw new QueryGrammarError(`bad metric in ${lower}()`);
-                const metric = METRICS[arg.text.toLowerCase()];
-                if (metric === undefined) {
-                    throw new QueryGrammarError(`unknown metric "${arg.text}" — allowed: ${Object.keys(METRICS).join(", ")}`);
-                }
-                selectSql.push(`${lower.toUpperCase()}(${metric}) AS "${lower}_${arg.text.toLowerCase()}"`);
+                const fn = lower;
+                const metric = resolveAggArg(fn, arg.text.toLowerCase());
+                const aliasBase = metric.alias.replace(/\./g, "_");
+                select.push({ kind: "aggregate", fn, metric, alias: `${fn}_${aliasBase}` });
             }
         }
         else {
-            // tag.client aliases to "client" — result keys read naturally.
-            const alias = token.text.startsWith("tag.") ? token.text.slice(4) : token.text;
-            selectSql.push(`${columnSql(token.text)} AS "${alias}"`);
+            select.push({ kind: "column", column: resolveDimension(token.text) });
         }
         if (peek()?.kind === "punct" && peek()?.text === ",") {
             pos += 1;
@@ -203,32 +262,35 @@ function compileQuery(input, scope) {
     if (table.kind !== "word" || table.text.toLowerCase() !== "inferences") {
         throw new QueryGrammarError(`only "inferences" is queryable, got "${table.text}"`);
     }
-    const whereSql = [];
-    const params = [];
+    const where = [];
     if (peek()?.kind === "word" && peek()?.text.toLowerCase() === "where") {
         pos += 1;
         for (;;) {
-            const column = next();
-            if (column.kind !== "word")
+            const columnTok = next();
+            if (columnTok.kind !== "word")
                 throw new QueryGrammarError(`bad condition column`);
-            const columnExpr = METRICS[column.text.toLowerCase()] !== undefined
-                ? METRICS[column.text.toLowerCase()]
-                : columnSql(column.text);
+            // A condition may target a metric (cost > 0.01) or a dimension (route = 'x').
+            const column = columns_1.METRICS_BY_NAME.has(columnTok.text.toLowerCase())
+                ? resolveMetric(columnTok.text.toLowerCase())
+                : resolveDimension(columnTok.text);
             const op = next();
             if (op.kind !== "punct" || !OPERATORS.has(op.text)) {
                 throw new QueryGrammarError(`bad operator "${op.text}" — allowed: ${[...OPERATORS].join(" ")}`);
             }
             const value = next();
-            if (value.kind === "string") {
-                params.push(value.text);
-            }
-            else if (value.kind === "number") {
-                params.push(Number(value.text));
-            }
-            else {
+            let literal;
+            if (value.kind === "string")
+                literal = value.text;
+            else if (value.kind === "number")
+                literal = Number(value.text);
+            else
                 throw new QueryGrammarError(`condition value must be a 'string' or number, got "${value.text}"`);
+            // A `ts` bound is pushed down to PostgREST by the hosted read: validate it
+            // here so a bad literal is a 422 teaching error, never an upstream 400.
+            if (column.source === "plain" && column.key === "ts" && typeof literal === "string" && Number.isNaN(Date.parse(literal))) {
+                throw new QueryGrammarError(`ts bound must be an ISO-8601 timestamp (got '${literal}')`);
             }
-            whereSql.push(`${columnExpr} ${op.text} ?`);
+            where.push({ column, op: op.text, value: literal });
             if (peek()?.kind === "word" && peek()?.text.toLowerCase() === "and") {
                 pos += 1;
                 continue;
@@ -236,22 +298,15 @@ function compileQuery(input, scope) {
             break;
         }
     }
-    // Row scoping — ANDed in unconditionally; the caller cannot remove it.
-    if (scope.kind === "tag") {
-        if (!TAG_NAME.test(scope.tag))
-            throw new QueryGrammarError(`bad scope tag: ${scope.tag}`);
-        whereSql.push(`json_extract(tags_json, '$.${scope.tag}') = ?`);
-        params.push(scope.value);
-    }
-    const groupSql = [];
+    const groupBy = [];
     if (peek()?.kind === "word" && peek()?.text.toLowerCase() === "group") {
         pos += 1;
         expectWord("by");
         for (;;) {
-            const column = next();
-            if (column.kind !== "word")
+            const columnTok = next();
+            if (columnTok.kind !== "word")
                 throw new QueryGrammarError("bad GROUP BY column");
-            groupSql.push(columnSql(column.text));
+            groupBy.push(resolveDimension(columnTok.text));
             if (peek()?.kind === "punct" && peek()?.text === ",") {
                 pos += 1;
                 continue;
@@ -271,9 +326,62 @@ function compileQuery(input, scope) {
     if (pos !== tokens.length) {
         throw new QueryGrammarError(`unexpected trailing input: "${tokens[pos].text}"`);
     }
+    return { select, where, groupBy, limit };
+}
+// ── SQLite rendering (the local `/query` surface) ────────────────────────────
+/** A column reference → SQLite expression. `meta.<field>` and reserved dims read
+ * out of `meta_json` / `tags_json` via json_extract with a VALIDATED path. */
+function sqliteColumnSql(ref) {
+    if (ref.source === "tag")
+        return `json_extract(tags_json, '$.${ref.key}')`;
+    if (ref.source === "meta")
+        return `json_extract(meta_json, '$.${ref.key}')`;
+    return ref.key;
+}
+/** An aggregate's SQLite argument. A `meta.*` value under a NUMERIC aggregate
+ * (`sum`/`avg`) is cast to REAL so the fold is numeric on the json_extract text;
+ * `min`/`max` over an ordered column (ts, a snapshot id) keep the raw expression
+ * so the comparison stays lexicographic — matching the JS fold. */
+function sqliteAggArgSql(fn, ref) {
+    if ((fn === "sum" || fn === "avg") && ref.source === "meta") {
+        return `CAST(json_extract(meta_json, '$.${ref.key}') AS REAL)`;
+    }
+    return sqliteColumnSql(ref);
+}
+/**
+ * Compile a query string to a single read-only SQLite SELECT (the local
+ * telemetry store). Row scoping is ANDed into WHERE unconditionally — the caller
+ * cannot opt out of it.
+ */
+function compileQuery(input, scope) {
+    const ast = parseQuery(input);
+    const params = [];
+    const selectSql = ast.select.map((item) => {
+        if (item.kind === "count")
+            return `COUNT(*) AS "count"`;
+        if (item.kind === "aggregate") {
+            return `${item.fn.toUpperCase()}(${sqliteAggArgSql(item.fn, item.metric)}) AS "${item.alias}"`;
+        }
+        return `${sqliteColumnSql(item.column)} AS "${item.column.alias}"`;
+    });
+    const whereSql = ast.where.map((cond) => {
+        params.push(cond.value);
+        return `${sqliteColumnSql(cond.column)} ${cond.op} ?`;
+    });
+    // Live rows only — bake-off replay rows (`tags.replay`) never move a route's
+    // numbers; mirrored in the JS fold (evaluateAnalyticsQuery).
+    whereSql.push("json_extract(tags_json, '$.replay') IS NULL");
+    // Row scoping — ANDed in unconditionally; the caller cannot remove it.
+    if (scope.kind === "tag") {
+        if (!TAG_NAME.test(scope.tag))
+            throw new QueryGrammarError(`bad scope tag: ${scope.tag}`);
+        whereSql.push(`json_extract(tags_json, '$.${scope.tag}') = ?`);
+        params.push(scope.value);
+    }
+    const groupSql = ast.groupBy.map((ref) => sqliteColumnSql(ref));
     const sql = `SELECT ${selectSql.join(", ")} FROM inferences` +
         (whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "") +
         (groupSql.length > 0 ? ` GROUP BY ${groupSql.join(", ")}` : "") +
-        ` LIMIT ${limit}`;
+        ` LIMIT ${ast.limit}`;
     return { sql, params };
 }

package/dist/query/saved.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The three saved analytics questions — WI-1b (spec §5). ONE shared module the
+ * server, console, and CLI import, so the console chip, the CLI `--saved <id>`,
+ * and any docs answer the SAME grammar. Each question is a trailing-window
+ * query; the ts bound is filled at call time (`grammar(sinceIso)`) so the module
+ * stays pure and testable — the caller computes `sinceIso = now − windowDays`.
+ *
+ * The questions return COUNTS and components; a RATE (truncation %, refusal %)
+ * is derived by the surface from those counts — the grammar measures, it never
+ * editorializes (F5: measured-only).
+ */
+export interface SavedQuery {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    /** The trailing window the question asks over, in days. */
+    readonly windowDays: number;
+    /** The grammar string with the `ts` lower bound filled in. */
+    grammar(sinceIso: string): string;
+}
+export declare const SAVED_QUERIES: readonly SavedQuery[];
+/** Look up a saved question by id, or null. */
+export declare function savedQueryById(id: string): SavedQuery | null;
+/** The ISO lower bound for a trailing window of `windowDays` ending at `now`. */
+export declare function sinceIsoFor(windowDays: number, now: Date): string;
+//# sourceMappingURL=saved.d.ts.map

package/dist/query/saved.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved.d.ts","sourceRoot":"","sources":["../../src/query/saved.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,EA8B9C,CAAC;AAEF,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAE5D;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAEjE"}

package/dist/query/saved.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * The three saved analytics questions — WI-1b (spec §5). ONE shared module the
+ * server, console, and CLI import, so the console chip, the CLI `--saved <id>`,
+ * and any docs answer the SAME grammar. Each question is a trailing-window
+ * query; the ts bound is filled at call time (`grammar(sinceIso)`) so the module
+ * stays pure and testable — the caller computes `sinceIso = now − windowDays`.
+ *
+ * The questions return COUNTS and components; a RATE (truncation %, refusal %)
+ * is derived by the surface from those counts — the grammar measures, it never
+ * editorializes (F5: measured-only).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAVED_QUERIES = void 0;
+exports.savedQueryById = savedQueryById;
+exports.sinceIsoFor = sinceIsoFor;
+exports.SAVED_QUERIES = [
+    {
+        id: "cost-per-subject",
+        title: "Cost per subject this week",
+        description: "Total estimated spend grouped by the reserved `subject` dimension over the last 7 days.",
+        windowDays: 7,
+        grammar: (since) => `SELECT subject, sum(cost), count(*) FROM inferences WHERE ts >= '${since}' GROUP BY subject`,
+    },
+    {
+        id: "truncation-refusal",
+        title: "Truncation & refusal rate by task × model",
+        description: "Attempt counts grouped by route (task), model, and finish reason over the last 7 days — the surface " +
+            "derives truncation (finish_reason=length) and refusal rates from the counts.",
+        windowDays: 7,
+        grammar: (since) => `SELECT route, model, meta.finish_reason, count(*) FROM inferences ` +
+            `WHERE ts >= '${since}' GROUP BY route, model, meta.finish_reason`,
+    },
+    {
+        id: "snapshots-seen",
+        title: "Model snapshots seen per route (28 d)",
+        description: "Distinct provider-reported model snapshots per route over the last 28 days, with first-seen (min ts) and " +
+            "last-seen (max ts) and the attempt count — a drift signal, not proof (spec §7).",
+        windowDays: 28,
+        grammar: (since) => `SELECT route, meta.model_snapshot, min(ts), max(ts), count(*) FROM inferences ` +
+            `WHERE ts >= '${since}' GROUP BY route, meta.model_snapshot`,
+    },
+];
+/** Look up a saved question by id, or null. */
+function savedQueryById(id) {
+    return exports.SAVED_QUERIES.find((q) => q.id === id) ?? null;
+}
+/** The ISO lower bound for a trailing window of `windowDays` ending at `now`. */
+function sinceIsoFor(windowDays, now) {
+    return new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000).toISOString();
+}

package/dist/registry/select.d.ts

@@ -14,6 +14,8 @@
  * 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).
  */
+import type { CapabilityFlag } from "../types/provider";
+import type { Requirement } from "../types/route";
 /** 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";
@@ -62,6 +64,63 @@ export interface SelectCriteria {
     readonly limit?: number;
 }
 export declare function selectModels(rows: readonly ModelSelectRow[], criteria?: SelectCriteria): ModelSelectRow[];
+/**
+ * Declare-first challenger eligibility (routing-console spec §4.4, R3) — the ONE
+ * place that answers "can this model be a trial challenger for route X?", called
+ * by the console picker (`GET …/routes/:route/challengers`) AND the oracle
+ * `propose_candidates`. Kept here beside `selectModels` so eligibility and the
+ * registry grammar never drift between surfaces.
+ *
+ * It decomposes a route's `require` + json rung into registry CAPABILITY FLAGS
+ * (the same mechanism the live resolver's `satisfiesRequirements` uses — an
+ * eligible challenger is one that could actually SERVE) rather than probed
+ * rates: probes GATE CLAIMS, not serving, so an UNPROBED model that carries the
+ * flags is eligible (the picker badges it `unprobed`; the caller sees there's no
+ * measured evidence yet). Types are imported type-only so select.ts stays
+ * dependency-free (browser-safe).
+ */
+/** A flag OR-group: the challenger must carry AT LEAST ONE flag in the group.
+ * `json_mode` routes accept native strict OR syntactic json forcing, so that is
+ * a two-flag group; everything else is a singleton. */
+export type RequirementFlagGroup = readonly CapabilityFlag[];
+export interface RouteRequirement {
+    /** Flag OR-groups, ANDed together. Empty ⇒ no capability requirement. */
+    readonly flagGroups: readonly RequirementFlagGroup[];
+    /** The route requires `grounded`: satisfied by a `grounded_native` model OR —
+     * when the deployment has a search provider configured — by ANY model (the run
+     * loop orchestrates search-and-inject). Carried separately so the picker can
+     * apply the "or any model when search is configured" relaxation. */
+    readonly grounded: boolean;
+}
+/**
+ * Map a route's `require` + json rung to the capability-flag requirement a
+ * challenger must satisfy (spec §4.4). Mirrors `run/resolve.ts`
+ * `satisfiesRequirements` flag-for-flag (an invariant test pins the agreement):
+ *   schema_conformant + json:native  → structured_native
+ *   schema_conformant + json:json_mode → structured_native | json_mode
+ *   grounded                          → grounded_native (or search-configured)
+ *   trace_visible                     → trace_visible
+ *   zero_retention                    → zero_retention
+ */
+export declare function requirementPredicates(route: {
+    readonly require: readonly Requirement[];
+    readonly policy: {
+        readonly json: "native" | "json_mode";
+    };
+}): RouteRequirement;
+export interface ChallengerEligibility {
+    readonly eligible: boolean;
+    /** Present only when NOT eligible — the missing capability, in plain words. */
+    readonly why?: string;
+}
+/**
+ * Evaluate one candidate model's eligibility against a route's requirement
+ * (spec §4.4). `flags` is the registry capability set for that model (the
+ * server's `RegistryFacts.flagsFor`, the SDK's `CapabilityLookup`).
+ * `searchAvailable` lets `grounded` be satisfied by any model when a search
+ * provider is configured. Returns `{eligible:true}` or `{eligible:false, why}`.
+ */
+export declare function evaluateChallengerEligibility(req: RouteRequirement, flags: ReadonlySet<CapabilityFlag>, searchAvailable?: boolean): ChallengerEligibility;
 /** 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;

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

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

package/dist/registry/select.js

@@ -20,6 +20,8 @@ exports.PREDICATE_GLOSS = exports.ALL_CAPABILITY_PREDICATES = void 0;
 exports.hasCapability = hasCapability;
 exports.parseCapabilityQuery = parseCapabilityQuery;
 exports.selectModels = selectModels;
+exports.requirementPredicates = requirementPredicates;
+exports.evaluateChallengerEligibility = evaluateChallengerEligibility;
 exports.explainEmptySelection = explainEmptySelection;
 exports.ALL_CAPABILITY_PREDICATES = [
     "structured-native",
@@ -124,6 +126,70 @@ function selectModels(rows, criteria = {}) {
         out = out.slice(0, criteria.limit);
     return out;
 }
+/**
+ * Map a route's `require` + json rung to the capability-flag requirement a
+ * challenger must satisfy (spec §4.4). Mirrors `run/resolve.ts`
+ * `satisfiesRequirements` flag-for-flag (an invariant test pins the agreement):
+ *   schema_conformant + json:native  → structured_native
+ *   schema_conformant + json:json_mode → structured_native | json_mode
+ *   grounded                          → grounded_native (or search-configured)
+ *   trace_visible                     → trace_visible
+ *   zero_retention                    → zero_retention
+ */
+function requirementPredicates(route) {
+    const flagGroups = [];
+    let grounded = false;
+    for (const requirement of route.require) {
+        switch (requirement) {
+            case "schema_conformant":
+                flagGroups.push(route.policy.json === "native" ? ["structured_native"] : ["structured_native", "json_mode"]);
+                break;
+            case "grounded":
+                grounded = true;
+                break;
+            case "trace_visible":
+                flagGroups.push(["trace_visible"]);
+                break;
+            case "zero_retention":
+                flagGroups.push(["zero_retention"]);
+                break;
+        }
+    }
+    return { flagGroups, grounded };
+}
+/** Human label for a flag requirement, used in the picker's `why` line. */
+const FLAG_LABEL = {
+    structured_native: "native strict JSON-schema enforcement",
+    json_mode: "JSON-mode forcing",
+    grounded_native: "native web grounding",
+    context_cache_explicit: "explicit context caching",
+    prompt_cache_key: "key-based prompt caching",
+    prefix_cache_implicit: "implicit prefix caching",
+    tier_flex: "a discounted flex tier",
+    trace_visible: "a visible reasoning trace",
+    zero_retention: "a zero-retention endpoint",
+};
+/**
+ * Evaluate one candidate model's eligibility against a route's requirement
+ * (spec §4.4). `flags` is the registry capability set for that model (the
+ * server's `RegistryFacts.flagsFor`, the SDK's `CapabilityLookup`).
+ * `searchAvailable` lets `grounded` be satisfied by any model when a search
+ * provider is configured. Returns `{eligible:true}` or `{eligible:false, why}`.
+ */
+function evaluateChallengerEligibility(req, flags, searchAvailable = false) {
+    const missing = [];
+    for (const group of req.flagGroups) {
+        if (!group.some((f) => flags.has(f))) {
+            missing.push(group.map((f) => FLAG_LABEL[f]).join(" or "));
+        }
+    }
+    if (req.grounded && !flags.has("grounded_native") && !searchAvailable) {
+        missing.push("native web grounding (or a configured search provider)");
+    }
+    if (missing.length === 0)
+        return { eligible: true };
+    return { eligible: false, why: `needs ${missing.join("; and ")}` };
+}
 /** 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. */
 function explainEmptySelection(criteria) {

package/dist/routes/loader-warnings.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Non-fatal loader advisories — extracted from loader.ts (kept it under the
+ * 700-LOC cap). Each is a pure function returning a warning line or null; the
+ * loader console.warns them after a bundle loads. Unit-tested directly.
+ */
+import type { CandidateSpec, RouteVariant } from "../types/route";
+/**
+ * CE-2 A5 co-item: warn (non-fatal) when a route's output schema has an ARRAY
+ * root. OpenAI strict structured output (`response_format: json_schema`, strict)
+ * requires a top-level OBJECT — an array-root schema cannot use strict
+ * enforcement on OpenAI candidates and silently falls back to non-strict there
+ * (the walkthrough §10 provider-matrix gap). The route still LOADS and serves as
+ * declared; the fix is to wrap the array in an object property so strict
+ * enforcement holds across every provider. Returns the warning line, or null.
+ */
+export declare function arrayRootSchemaWarning(route: string, outputSchema: object | null): string | null;
+/**
+ * Declare-first dead-declaration warning (routing-console spec §4.4): a `trial`
+ * candidate that no variant references can never be reached — not live (trial
+ * candidates are dropped on every live path) and not in a bake-off (a bake-off
+ * replays a NAMED variant, and no variant narrows to it). Warn so the author
+ * either adds the `trial-<provider>-<model>` variant the declare flow emits or
+ * removes the dangling candidate. Non-fatal (the route still loads and serves
+ * its live candidates as declared). Pure — unit-tested directly. Returns the
+ * warning line, or null when every trial candidate is referenced.
+ */
+export declare function unreferencedTrialCandidatesWarning(route: string, candidates: readonly CandidateSpec[], variants: readonly RouteVariant[]): string | null;
+//# sourceMappingURL=loader-warnings.d.ts.map

package/dist/routes/loader-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-warnings.d.ts","sourceRoot":"","sources":["../../src/routes/loader-warnings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAElE;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWhG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,MAAM,GAAG,IAAI,CAef"}