modelrig 0.5.0 → 0.7.0

package/dist/query/analytics.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * The analytics evaluator — WI-1b (spec §5, plan §3). Turns a parsed
+ * {@link QueryAst} into (a) a PostgREST read plan over `inferences`, and (b) a
+ * pure JS fold that groups + aggregates the RLS-scoped rows the server reads.
+ *
+ * ── WHY JS AGGREGATION, NOT SQL ──────────────────────────────────────────
+ * The control plane is read through the identity-forwarding PostgREST reader
+ * (T12, cache-stats precedent) — there is no raw-SQL executor and never will be
+ * (a hand-filter is the XOS smell the reader deletes). So the server reads raw
+ * RLS-scoped rows (a bounded scan) and folds them here. The fold's semantics
+ * mirror the SQLite compiler's (grammar.ts) column-for-column, so the local and
+ * hosted `/query` surfaces answer the same question the same way.
+ *
+ * ── NEVER CONTENT ────────────────────────────────────────────────────────
+ * Every selectable column is an enum/number/boolean/hash/identifier/timestamp
+ * (columns.ts). {@link selectableColumnsAreMetaSafe} proves it; the property
+ * test pins it. A caller cannot name a column that would carry a prompt or a
+ * completion, so the query surface cannot return content by construction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANALYTICS_SCAN_CAP = void 0;
+exports.describeAnalyticsSchema = describeAnalyticsSchema;
+exports.selectableColumnsAreMetaSafe = selectableColumnsAreMetaSafe;
+exports.planAnalyticsRead = planAnalyticsRead;
+exports.evaluateAnalyticsQuery = evaluateAnalyticsQuery;
+const columns_1 = require("./columns");
+const attempt_meta_1 = require("../telemetry/attempt-meta");
+/** The bounded scan the analytics reader issues — the newest rows for the org,
+ * folded in JS. A summary surface, not an export; matches the cache-stats
+ * ROLLUP ceiling. When a scan fills this cap, the result is flagged `truncated`. */
+exports.ANALYTICS_SCAN_CAP = 10000;
+/** The fixed row projection the analytics reader selects: the plain columns the
+ * grammar exposes plus the two jsonb envelopes (`tags`, `meta`) it folds. The
+ * whole jsonb objects travel so any reserved-dim / meta.* column resolves in
+ * JS without a per-column PostgREST select. */
+const READ_PROJECTION = "route,provider,model,ts,failure_class,served_variant," +
+    "cost_estimate_usd,tokens_in,tokens_out,tokens_cached,latency_ms,ttfb_ms,tags,meta";
+function fieldOf(def) {
+    return { name: def.name, type: def.classification, classification: def.classification, since: def.since };
+}
+/**
+ * The self-describing schema for `/v1/analytics/meta` (spec §5) — every
+ * dimension and metric the org can query, DERIVED from the grammar registry
+ * (columns.ts), so there is no hand-maintained list to drift. Count(*) is always
+ * available and needs no metric column.
+ */
+function describeAnalyticsSchema() {
+    return {
+        dimensions: columns_1.DIMENSION_COLUMNS.map(fieldOf),
+        metrics: columns_1.METRIC_COLUMNS.map(fieldOf),
+        reserved_tags: [...columns_1.RESERVED_DIMENSION_NAMES],
+    };
+}
+/** The classifications that are, by definition, not free text. If a selectable
+ * column ever carried any other classification, the never-content guarantee
+ * would be broken — so the property test asserts this set covers every column. */
+const META_SAFE = new Set([
+    "enum",
+    "number",
+    "boolean",
+    "hash",
+    "identifier",
+    "timestamp",
+]);
+/**
+ * Prove that EVERY selectable column (dimension + metric) is metadata-safe — an
+ * enum/number/boolean/hash/identifier/timestamp, never content (spec §6.1). The
+ * `/v1/analytics/query` never-returns-content promise rests on this being total.
+ */
+function selectableColumnsAreMetaSafe() {
+    return [...columns_1.DIMENSION_COLUMNS, ...columns_1.METRIC_COLUMNS].every((c) => META_SAFE.has(c.classification));
+}
+// ── The PostgREST read plan ──────────────────────────────────────────────────
+/** PostgREST operator for a grammar operator. Only these six exist. */
+const PGREST_OP = {
+    "=": "eq",
+    "!=": "neq",
+    ">": "gt",
+    ">=": "gte",
+    "<": "lt",
+    "<=": "lte",
+};
+/**
+ * The bounded read the analytics reader issues: the fixed projection, newest
+ * first, capped at {@link ANALYTICS_SCAN_CAP}. A `ts` bound in the query is
+ * pushed down to PostgREST (it narrows the scan cheaply and correctly — `ts` is
+ * a real timestamptz column); every other predicate is applied in the JS fold,
+ * where the grammar's semantics are authoritative regardless of jsonb typing.
+ */
+function planAnalyticsRead(ast) {
+    const parts = [`select=${READ_PROJECTION}`, "order=ts.desc", `limit=${exports.ANALYTICS_SCAN_CAP}`];
+    for (const cond of ast.where) {
+        if (cond.column.source === "plain" && cond.column.key === "ts" && typeof cond.value === "string") {
+            const op = PGREST_OP[cond.op];
+            if (op !== undefined)
+                parts.push(`ts=${op}.${encodeURIComponent(cond.value)}`);
+        }
+    }
+    return { query: parts.join("&") };
+}
+// ── The JS fold (grouping + aggregation), mirroring the SQLite semantics ─────
+/** Extract a column's raw value from a PostgREST row. */
+function extract(row, ref) {
+    if (ref.source === "plain")
+        return row[ref.key];
+    const bag = ref.source === "tag" ? row.tags : row.meta;
+    if (ref.source === "tag")
+        return tagValue(bag, ref.key);
+    if (bag === null || bag === undefined || typeof bag !== "object")
+        return undefined;
+    // A meta key may be a dotted path (`cost.in`); a tag key is a single segment.
+    let cur = bag;
+    for (const seg of ref.key.split(".")) {
+        if (cur === null || cur === undefined || typeof cur !== "object")
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+/** A tag value, or null when it is a string that fails the metadata-safe rule
+ * (tags are unconstrained at ingest; a free-text tag must not surface through
+ * a surface that promises "never content"). */
+function tagValue(bag, key) {
+    if (bag === null || bag === undefined || typeof bag !== "object")
+        return undefined;
+    const v = bag[key];
+    if (typeof v === "string" && !(0, attempt_meta_1.isMetaSafeString)(v))
+        return null;
+    return v;
+}
+/** A finite number, else null (drops null/NaN/non-numeric for aggregation). */
+function toNum(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : null;
+    if (typeof v === "string" && v !== "" && Number.isFinite(Number(v)))
+        return Number(v);
+    return null;
+}
+/** Compare under one operator over already-resolved numeric operands. */
+function cmpNum(l, op, r) {
+    switch (op) {
+        case "=": return l === r;
+        case "!=": return l !== r;
+        case ">": return l > r;
+        case ">=": return l >= r;
+        case "<": return l < r;
+        case "<=": return l <= r;
+    }
+    return false;
+}
+/**
+ * Compare a row value against a grammar literal under one operator, matching the
+ * SQLite compiler. `timestamp` columns are compared by parsed epoch ms so a
+ * PostgREST `+00:00` serialization and a `.000Z` bound agree at the boundary
+ * (the JS re-filter must never drop a row the ts pushdown correctly included);
+ * otherwise numeric when both sides are numbers, else a string compare (correct
+ * for enums/identifiers/hashes).
+ */
+function matches(left, op, right, classification) {
+    if (classification === "timestamp") {
+        const l = Date.parse(String(left));
+        const r = typeof right === "number" ? right : Date.parse(String(right));
+        if (Number.isFinite(l) && Number.isFinite(r))
+            return cmpNum(l, op, r);
+        // fall through to string compare when either side is unparseable
+    }
+    const ln = toNum(left);
+    const rn = typeof right === "number" ? right : toNum(right);
+    if (ln !== null && rn !== null)
+        return cmpNum(ln, op, rn);
+    if (op === "=" || op === "!=") {
+        const eq = stringOf(left) === String(right);
+        return op === "=" ? eq : !eq;
+    }
+    const ls = stringOf(left);
+    const rs = String(right);
+    switch (op) {
+        case ">": return ls > rs;
+        case ">=": return ls >= rs;
+        case "<": return ls < rs;
+        case "<=": return ls <= rs;
+    }
+    return false;
+}
+/** A bake-off replay/shadow row — `tags.replay` is set by the replay path. */
+function isReplayRow(row) {
+    const tags = row.tags;
+    return tags !== null && tags !== undefined && typeof tags === "object" && tags.replay !== undefined;
+}
+/** A row value as a comparable string; undefined/null never equal a literal. */
+function stringOf(v) {
+    if (v === null || v === undefined)
+        return "<null>";
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    return String(v);
+}
+function passesWhere(row, ast) {
+    return ast.where.every((cond) => matches(extract(row, cond.column), cond.op, cond.value, cond.column.classification));
+}
+function projectValue(row, ref) {
+    const v = extract(row, ref);
+    return v === undefined ? null : v;
+}
+function fold(fn, rows, ref) {
+    const nums = rows.map((r) => toNum(extract(r, ref))).filter((n) => n !== null);
+    if (fn === "sum" || fn === "avg") {
+        if (nums.length === 0)
+            return null;
+        const sum = nums.reduce((a, b) => a + b, 0);
+        return fn === "sum" ? sum : sum / nums.length;
+    }
+    // min/max: numeric when the column is a number, else ordered by string
+    // (correct for ISO timestamps and snapshot ids — mirrors SQLite MIN/MAX).
+    if (ref.numeric) {
+        if (nums.length === 0)
+            return null;
+        return fn === "min" ? Math.min(...nums) : Math.max(...nums);
+    }
+    const strs = rows
+        .map((r) => extract(r, ref))
+        .filter((v) => v !== null && v !== undefined)
+        .map((v) => String(v));
+    if (strs.length === 0)
+        return null;
+    return strs.reduce((a, b) => (fn === "min" ? (b < a ? b : a) : b > a ? b : a));
+}
+function projectGroup(items, rows) {
+    const out = {};
+    const rep = rows[0];
+    for (const item of items) {
+        if (item.kind === "count")
+            out.count = rows.length;
+        else if (item.kind === "aggregate")
+            out[item.alias] = fold(item.fn, rows, item.metric);
+        else
+            out[item.column.alias] = rep !== undefined ? projectValue(rep, item.column) : null;
+    }
+    return out;
+}
+const hasAggregate = (ast) => ast.select.some((s) => s.kind === "count" || s.kind === "aggregate");
+/**
+ * Evaluate a parsed query over the rows the analytics reader returned. Filters,
+ * groups, aggregates, and projects exactly as the SQLite compiler would, then
+ * applies the grammar LIMIT. `truncated` is true when the scan filled the cap
+ * (the answer may be partial) OR the grouped result exceeded the limit.
+ */
+function evaluateAnalyticsQuery(ast, rows, opts = {}) {
+    // Live rows only (odometer rule, same as every console surface): bake-off
+    // replay rows run through the production route with `tags.replay` set and
+    // must never move a route's numbers — the grammar cannot express IS NULL, so
+    // the exclusion is unconditional here and in the SQLite compiler alike.
+    const kept = rows.filter((r) => !isReplayRow(r) && passesWhere(r, ast));
+    let grouped;
+    if (ast.groupBy.length > 0) {
+        const groups = new Map();
+        for (const row of kept) {
+            // Join on U+0001 so ("ab","") and ("a","b") never collide into one group —
+            // a control byte cannot appear in a metadata-safe (enum/id/hash) value.
+            const key = ast.groupBy.map((g) => stringOf(extract(row, g))).join("\u0001");
+            const bucket = groups.get(key);
+            if (bucket === undefined)
+                groups.set(key, [row]);
+            else
+                bucket.push(row);
+        }
+        grouped = [...groups.values()].map((g) => projectGroup(ast.select, g));
+    }
+    else if (hasAggregate(ast)) {
+        // Aggregates with no GROUP BY collapse to a single row (SQL semantics).
+        grouped = [projectGroup(ast.select, kept)];
+    }
+    else {
+        // A plain projection — one output row per input row.
+        grouped = kept.map((r) => projectGroup(ast.select, [r]));
+    }
+    const truncated = (opts.scannedAtCap ?? false) || grouped.length > ast.limit;
+    return { rows: grouped.slice(0, ast.limit), truncated, limit: ast.limit };
+}

package/dist/query/columns.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The analytics column/metric registry — WI-1b (spec §5, plan §3).
+ *
+ * ── ONE SOURCE OF TRUTH ──────────────────────────────────────────────────
+ * Every dimension and metric the telemetry grammar exposes is declared HERE,
+ * with its storage source, classification, and "since" version. The SQLite
+ * grammar renderer (grammar.ts), the PostgREST analytics planner
+ * (analytics.ts), and the self-describing `/v1/analytics/meta` endpoint all
+ * read this table — so the grammar, the query surface, and its documentation
+ * can never drift (spec §5: "self-description derived from the grammar").
+ *
+ * ── THE METADATA-SAFE INVARIANT ──────────────────────────────────────────
+ * NO column here is free text. Every `classification` is one of enum | number
+ * | boolean | hash | identifier | timestamp — the classification rule from
+ * spec §2. A reserved dimension (`subject`, …) is an OPAQUE identifier: a
+ * customer-side id, hashed by the caller if it looks like PII. This is what
+ * lets `/v1/analytics/query` promise "never returns content" — there is no
+ * selectable column that could carry a prompt or a completion.
+ */
+/** The metadata-safe classifications (spec §2). A column may only be one of
+ * these — there is deliberately no "text"/"string-freeform" bucket, which is
+ * the invariant the `/query` never-content guarantee rests on. */
+export type Classification = "enum" | "number" | "boolean" | "hash" | "identifier" | "timestamp";
+/** Where a column's value lives on the row. `plain` = a first-class column;
+ * `tag` = a key in the `tags` jsonb (SQLite: `tags_json`); `meta` = a path in
+ * the `meta` jsonb (SQLite: `meta_json`) — the WI-1a attempt envelope. */
+export type ColumnSource = "plain" | "tag" | "meta";
+export interface ColumnDef {
+    /** The grammar identifier a caller types (e.g. `route`, `subject`,
+     * `meta.finish_reason`, `meta.cost.in`). */
+    readonly name: string;
+    readonly source: ColumnSource;
+    /** The leaf key or path within the source. For `meta.cost.in` this is
+     * `cost.in`; for `subject` (tag) it is `subject`; for `route` it is `route`. */
+    readonly key: string;
+    readonly classification: Classification;
+    /** Whether the column is a NUMBER usable as an aggregate metric
+     * (`sum(...)`/`avg(...)`/`min(...)`/`max(...)`). */
+    readonly numeric: boolean;
+    /** The product version the column became queryable in. */
+    readonly since: string;
+}
+/** Plain numeric metrics (Phase 4 WS5) — the original aggregate targets. These
+ * are first-class columns on `inferences`; the grammar names them without a
+ * `meta.` prefix. `key` is the storage column (SQLite + Postgres share it). */
+export declare const PLAIN_METRICS: readonly ColumnDef[];
+/** Every column the grammar can GROUP BY / FILTER by (dimensions). Order is
+ * stable so `/meta` renders deterministically. */
+export declare const DIMENSION_COLUMNS: readonly ColumnDef[];
+/** Every column usable as an aggregate metric (`numeric`), keyed by grammar
+ * name — plain metrics plus the numeric envelope fields. */
+export declare const METRIC_COLUMNS: readonly ColumnDef[];
+/** Grammar name → dimension def (group/filter). */
+export declare const DIMENSIONS_BY_NAME: ReadonlyMap<string, ColumnDef>;
+/** Grammar name → metric def (aggregate target). */
+export declare const METRICS_BY_NAME: ReadonlyMap<string, ColumnDef>;
+/** The reserved tag keys, in declaration order (spec §4). */
+export declare const RESERVED_DIMENSION_NAMES: readonly string[];
+//# sourceMappingURL=columns.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../src/query/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;kEAEkE;AAClE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;AAEjG;;0EAE0E;AAC1E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB;gDAC4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;oFACgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;wDACoD;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AA8CD;;+EAE+E;AAC/E,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAO7C,CAAC;AAEF;kDACkD;AAClD,eAAO,MAAM,iBAAiB,EAAE,SAAS,SAAS,EAAkD,CAAC;AAErG;4DAC4D;AAC5D,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAG9C,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAE7D,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAE1D,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAqC,CAAC"}

package/dist/query/columns.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * The analytics column/metric registry — WI-1b (spec §5, plan §3).
+ *
+ * ── ONE SOURCE OF TRUTH ──────────────────────────────────────────────────
+ * Every dimension and metric the telemetry grammar exposes is declared HERE,
+ * with its storage source, classification, and "since" version. The SQLite
+ * grammar renderer (grammar.ts), the PostgREST analytics planner
+ * (analytics.ts), and the self-describing `/v1/analytics/meta` endpoint all
+ * read this table — so the grammar, the query surface, and its documentation
+ * can never drift (spec §5: "self-description derived from the grammar").
+ *
+ * ── THE METADATA-SAFE INVARIANT ──────────────────────────────────────────
+ * NO column here is free text. Every `classification` is one of enum | number
+ * | boolean | hash | identifier | timestamp — the classification rule from
+ * spec §2. A reserved dimension (`subject`, …) is an OPAQUE identifier: a
+ * customer-side id, hashed by the caller if it looks like PII. This is what
+ * lets `/v1/analytics/query` promise "never returns content" — there is no
+ * selectable column that could carry a prompt or a completion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_DIMENSION_NAMES = exports.METRICS_BY_NAME = exports.DIMENSIONS_BY_NAME = exports.METRIC_COLUMNS = exports.DIMENSION_COLUMNS = exports.PLAIN_METRICS = void 0;
+// ── Plain columns (Phase 4 WS5 — the original grammar) ───────────────────────
+const PLAIN = [
+    { name: "route", source: "plain", key: "route", classification: "identifier", numeric: false, since: "0.1.0" },
+    { name: "provider", source: "plain", key: "provider", classification: "enum", numeric: false, since: "0.1.0" },
+    { name: "model", source: "plain", key: "model", classification: "identifier", numeric: false, since: "0.1.0" },
+    { name: "ts", source: "plain", key: "ts", classification: "timestamp", numeric: false, since: "0.1.0" },
+    { name: "failure_class", source: "plain", key: "failure_class", classification: "enum", numeric: false, since: "0.1.0" },
+    { name: "served_variant", source: "plain", key: "served_variant", classification: "identifier", numeric: false, since: "0.1.0" },
+];
+// ── Reserved dimensions (spec §4) — first-class group/filter columns that
+// remain `tags` keys in storage (GIN-indexed; no DDL). An opaque customer-side
+// id ⇒ identifier classification. ──────────────────────────────────────────
+const RESERVED_DIMS = [
+    { name: "subject", source: "tag", key: "subject", classification: "identifier", numeric: false, since: "0.6.0" },
+    { name: "feature", source: "tag", key: "feature", classification: "identifier", numeric: false, since: "0.6.0" },
+    { name: "user", source: "tag", key: "user", classification: "identifier", numeric: false, since: "0.6.0" },
+    { name: "session", source: "tag", key: "session", classification: "identifier", numeric: false, since: "0.6.0" },
+    { name: "cost_center", source: "tag", key: "cost_center", classification: "identifier", numeric: false, since: "0.6.0" },
+];
+// ── Attempt-envelope scalars (spec §2) — `meta.<field>` columns. Every one is
+// an enum / number / boolean / hash / identifier — never content. ────────────
+const META_SCALARS = [
+    { name: "meta.finish_reason", source: "meta", key: "finish_reason", classification: "enum", numeric: false, since: "0.6.0" },
+    { name: "meta.refusal", source: "meta", key: "refusal", classification: "boolean", numeric: false, since: "0.6.0" },
+    { name: "meta.streaming", source: "meta", key: "streaming", classification: "boolean", numeric: false, since: "0.6.0" },
+    { name: "meta.model_snapshot", source: "meta", key: "model_snapshot", classification: "identifier", numeric: false, since: "0.6.0" },
+    { name: "meta.context_bucket", source: "meta", key: "context_bucket", classification: "enum", numeric: false, since: "0.6.0" },
+    { name: "meta.error_code", source: "meta", key: "error_code", classification: "enum", numeric: false, since: "0.6.0" },
+    { name: "meta.region", source: "meta", key: "region", classification: "identifier", numeric: false, since: "0.6.0" },
+    { name: "meta.input_hash", source: "meta", key: "input_hash", classification: "hash", numeric: false, since: "0.6.0" },
+    { name: "meta.output_hash", source: "meta", key: "output_hash", classification: "hash", numeric: false, since: "0.6.0" },
+    // Numeric envelope fields — group/filter dimensions AND aggregate metrics.
+    { name: "meta.http_status", source: "meta", key: "http_status", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.reasoning_tokens", source: "meta", key: "reasoning_tokens", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.response_chars", source: "meta", key: "response_chars", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.cost.in", source: "meta", key: "cost.in", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.cost.out", source: "meta", key: "cost.out", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.cost.cache_read", source: "meta", key: "cost.cache_read", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.cost.cache_write", source: "meta", key: "cost.cache_write", classification: "number", numeric: true, since: "0.6.0" },
+    { name: "meta.cost.other", source: "meta", key: "cost.other", classification: "number", numeric: true, since: "0.6.0" },
+];
+/** Plain numeric metrics (Phase 4 WS5) — the original aggregate targets. These
+ * are first-class columns on `inferences`; the grammar names them without a
+ * `meta.` prefix. `key` is the storage column (SQLite + Postgres share it). */
+exports.PLAIN_METRICS = [
+    { name: "cost", source: "plain", key: "cost_estimate_usd", classification: "number", numeric: true, since: "0.1.0" },
+    { name: "tokens_in", source: "plain", key: "tokens_in", classification: "number", numeric: true, since: "0.1.0" },
+    { name: "tokens_out", source: "plain", key: "tokens_out", classification: "number", numeric: true, since: "0.1.0" },
+    { name: "tokens_cached", source: "plain", key: "tokens_cached", classification: "number", numeric: true, since: "0.1.0" },
+    { name: "latency_ms", source: "plain", key: "latency_ms", classification: "number", numeric: true, since: "0.1.0" },
+    { name: "ttfb_ms", source: "plain", key: "ttfb_ms", classification: "number", numeric: true, since: "0.1.0" },
+];
+/** Every column the grammar can GROUP BY / FILTER by (dimensions). Order is
+ * stable so `/meta` renders deterministically. */
+exports.DIMENSION_COLUMNS = [...PLAIN, ...RESERVED_DIMS, ...META_SCALARS];
+/** Every column usable as an aggregate metric (`numeric`), keyed by grammar
+ * name — plain metrics plus the numeric envelope fields. */
+exports.METRIC_COLUMNS = [
+    ...exports.PLAIN_METRICS,
+    ...META_SCALARS.filter((c) => c.numeric),
+];
+/** Grammar name → dimension def (group/filter). */
+exports.DIMENSIONS_BY_NAME = new Map(exports.DIMENSION_COLUMNS.map((c) => [c.name, c]));
+/** Grammar name → metric def (aggregate target). */
+exports.METRICS_BY_NAME = new Map(exports.METRIC_COLUMNS.map((c) => [c.name, c]));
+/** The reserved tag keys, in declaration order (spec §4). */
+exports.RESERVED_DIMENSION_NAMES = RESERVED_DIMS.map((c) => c.name);

package/dist/query/grammar.d.ts

@@ -1,21 +1,42 @@
 /**
- * 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.
  */
+import type { Classification, ColumnSource } from "./columns";
+export { describeAnalyticsSchema, evaluateAnalyticsQuery, planAnalyticsRead, ANALYTICS_SCAN_CAP, selectableColumnsAreMetaSafe, } from "./analytics";
+export type { AnalyticsSchema, AnalyticsSchemaField, AnalyticsResult, AnalyticsReadPlan, AnalyticsRow } from "./analytics";
+export { SAVED_QUERIES, savedQueryById, sinceIsoFor } from "./saved";
+export type { SavedQuery } from "./saved";
+export { DIMENSION_COLUMNS, METRIC_COLUMNS, RESERVED_DIMENSION_NAMES } from "./columns";
+export type { ColumnDef, Classification, ColumnSource } from "./columns";
 export declare class QueryGrammarError extends Error {
     constructor(message: string);
 }
@@ -31,5 +52,51 @@ export interface CompiledQuery {
     readonly sql: string;
     readonly params: ReadonlyArray<string | number>;
 }
+export type AggFn = "sum" | "avg" | "min" | "max";
+/** A resolved reference to one column, carrying its storage + classification so
+ * the JS evaluator (analytics.ts) needs no second lookup. */
+export interface AstColumnRef {
+    readonly name: string;
+    readonly source: ColumnSource;
+    readonly key: string;
+    readonly classification: Classification;
+    readonly numeric: boolean;
+    readonly alias: string;
+}
+export type AstSelectItem = {
+    readonly kind: "column";
+    readonly column: AstColumnRef;
+} | {
+    readonly kind: "count";
+    readonly alias: "count";
+} | {
+    readonly kind: "aggregate";
+    readonly fn: AggFn;
+    readonly metric: AstColumnRef;
+    readonly alias: string;
+};
+export interface AstCondition {
+    readonly column: AstColumnRef;
+    readonly op: string;
+    readonly value: string | number;
+}
+export interface QueryAst {
+    readonly select: readonly AstSelectItem[];
+    readonly where: readonly AstCondition[];
+    readonly groupBy: readonly AstColumnRef[];
+    readonly limit: number;
+}
+/**
+ * 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.
+ */
+export declare function parseQuery(input: string): QueryAst;
+/**
+ * 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.
+ */
 export declare function compileQuery(input: string, scope: QueryScope): CompiledQuery;
 //# sourceMappingURL=grammar.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/query/grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,4CAA4C;AAC5C,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;CACjD;AAwHD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,aAAa,CAkJ5E"}
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/query/grammar.ts"],"names":[],"mappings":"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"}