modelrig 0.1.0 → 0.3.0

package/dist/status.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Rig posture — the boot banner + `/status` report (settings-plane §2).
+ *
+ * WS1's lesson, made a rule: "a default nobody can observe gets asked about
+ * instead of answered." The artifact namespace now defaults ON when a control
+ * plane is configured (§2 flip), so a user must be able to SEE whether it is on
+ * and WHY, without reading source. This module derives that posture from the
+ * resolved config (plus, for `/status`, the settings resolver's snapshot) and
+ * shapes it for a one-line boot banner and a fuller `/status` report.
+ *
+ * Pure formatters (no env, no network) except `emitBootBanner`, which writes the
+ * one banner line to stderr — kept here so index.ts calls it in a single line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachePosture = cachePosture;
+exports.exportModeOf = exportModeOf;
+exports.artifactsPosture = artifactsPosture;
+exports.buildRigStatus = buildRigStatus;
+exports.formatBootBanner = formatBootBanner;
+exports.emitBootBanner = emitBootBanner;
+exports.formatStatusReport = formatStatusReport;
+const cache_policy_1 = require("./registry/cache-policy");
+/** The cache posture from the policy registry alone (WS-A) — which providers
+ * ModelRig accounts caching for, and the policy version. No telemetry: live
+ * hit rates live behind the control-plane rollup (WS-B / the console). */
+function cachePosture() {
+    const eligible = (0, cache_policy_1.seededCachePolicyProviders)().filter((p) => (0, cache_policy_1.getCachePolicy)(p).cache_supported);
+    const policyVersion = eligible.length > 0 ? (0, cache_policy_1.getCachePolicy)(eligible[0]).policy_version : "n/a";
+    return { policyVersion, eligibleProviders: eligible };
+}
+function exportModeOf(config) {
+    return config.export?.mode ?? "local-only";
+}
+/**
+ * The artifact-namespace posture as a boolean + a reason, derivable from config
+ * ALONE (so both the banner and `/status` agree). The four cases the §2 flip
+ * creates, each named honestly:
+ *   on  + control plane → the default is now on (a sink exists to ship to)
+ *   on  + local-only    → an explicit MODELRIG_ARTIFACTS opt-in
+ *   off + control plane → an explicit MODELRIG_ARTIFACTS=0 opt-out
+ *   off + local-only    → nothing to ship to; off is the local-only default
+ */
+function artifactsPosture(config) {
+    const enabled = config.artifacts?.enabled === true;
+    const localOnly = exportModeOf(config) === "local-only";
+    if (enabled) {
+        return {
+            enabled,
+            reason: localOnly ? "MODELRIG_ARTIFACTS opt-in (local-only rig)" : "control plane configured",
+        };
+    }
+    return {
+        enabled,
+        reason: localOnly ? "local-only rig — no control plane to ship to" : "MODELRIG_ARTIFACTS=0 opt-out",
+    };
+}
+/** Build the full status snapshot from config + the resolver's per-task cache. */
+function buildRigStatus(config, tasks = new Map()) {
+    return {
+        exportMode: exportModeOf(config),
+        artifacts: artifactsPosture(config),
+        contentCustody: config.artifacts?.content !== undefined,
+        otlp: config.otlp ? "configured" : "disabled",
+        cache: cachePosture(),
+        tasks: [...tasks].map(([task, s]) => ({ task, ...s })),
+    };
+}
+/** The one-line boot banner (§2). Concise on purpose — mode, artifacts (+why),
+ * content, otlp. */
+function formatBootBanner(config) {
+    const a = artifactsPosture(config);
+    const content = config.artifacts?.content !== undefined ? "on" : "off";
+    const otlp = config.otlp ? "on" : "off";
+    return (`[modelrig] telemetry: ${exportModeOf(config)} · ` +
+        `artifacts: ${a.enabled ? "on" : "off"} (${a.reason}) · ` +
+        `content: ${content} · otlp: ${otlp}`);
+}
+/**
+ * Emit the boot banner to stderr — ONCE at rig construction, and ONLY when a
+ * control plane is configured (the case where the §2 default flip is in effect
+ * and the posture is non-obvious). A pure local-only rig with artifacts off is
+ * the boring, expected default and stays silent (no banner noise in tests or
+ * embedders). Stderr, so it never pollutes a command's stdout.
+ */
+function emitBootBanner(config) {
+    if (config.export === undefined)
+        return;
+    console.warn(formatBootBanner(config));
+}
+/** Render a `/status` report as multi-line text for the CLI. */
+function formatStatusReport(status) {
+    const lines = [
+        "modelrig status",
+        `  telemetry export : ${status.exportMode}`,
+        `  artifacts        : ${status.artifacts.enabled ? "enabled" : "disabled"} (${status.artifacts.reason})`,
+        `  content custody  : ${status.contentCustody ? "enabled" : "disabled"}`,
+        `  otlp span export : ${status.otlp}`,
+        `  cache accounting : on (policy ${status.cache.policyVersion}) — cache-eligible: ${status.cache.eligibleProviders.length > 0 ? status.cache.eligibleProviders.join(", ") : "none"}`,
+        "                     (live hit rate + effective input rate: console route cache page)",
+    ];
+    if (status.tasks.length === 0) {
+        lines.push("  task settings    : (none pulled yet — settings load on the first run of each task)");
+    }
+    else {
+        lines.push("  task settings (control plane):");
+        for (const t of status.tasks) {
+            lines.push(`    ${t.task}: capture=${t.capture} artifacts=${t.artifacts_enabled ?? "inherit"} ` +
+                `content=${t.artifact_content} scrub=${t.scrub}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/telemetry/artifact-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Local artifact-metadata buffer — Expansion E2 chunk B (spec §2).
+ *
+ * A SEPARATE better-sqlite3 handle over the same telemetry file (the captures.ts
+ * pattern), kept out of `store.ts` for cohesion and the LOC cap (P1). UNLIKE
+ * captures, these rows ARE exported: artifact METADATA is a cloud surface by
+ * ruling (the 00030 counter-annotation). What is NEVER stored — here or anywhere
+ * — is artifact CONTENT: `contentRef` is the customer's opaque URI, `contentHash`
+ * a sha256 of bytes hashed-then-discarded. Rows are immutable facts: INSERT OR
+ * IGNORE, read past a rowid watermark exactly like inferences.
+ */
+import type { ArtifactEdgeRow, ArtifactEvaluationRow, ArtifactRow, EvalCaseRow } from "../types/telemetry";
+export interface ArtifactStore {
+    recordArtifact(row: ArtifactRow): void;
+    recordArtifactEdge(row: ArtifactEdgeRow): void;
+    recordArtifactEvaluation(row: ArtifactEvaluationRow): void;
+    /** Record a promoted eval case (E4 chunk A) — rides the `:eval_cases` export
+     * stream to the control plane, exactly like the other artifact-graph rows. */
+    recordEvalCase(row: EvalCaseRow): void;
+    readArtifactsAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: ArtifactRow;
+    }>;
+    readEdgesAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: ArtifactEdgeRow;
+    }>;
+    readEvaluationsAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: ArtifactEvaluationRow;
+    }>;
+    readEvalCasesAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: EvalCaseRow;
+    }>;
+    /** All eval cases for a task, newest first (E4 chunk A, bake-off selection). */
+    readEvalCasesByTask(task: string): EvalCaseRow[];
+    /** One artifact row by id, or null (E4 chunk A rehydration — resolves a case's
+     * source artifact to its run/step for the input lookup). */
+    getArtifactById(id: string): ArtifactRow | null;
+    /** Run `fn` inside a single SQLite transaction and return its value (H8).
+     * A step's ~9 record* writes then commit with ONE fsync instead of nine.
+     * Nestable (better-sqlite3 uses SAVEPOINTs); throws propagate and roll back. */
+    batch<T>(fn: () => T): T;
+    close(): void;
+}
+export declare function openArtifactStore(dbPath: string): ArtifactStore;
+//# sourceMappingURL=artifact-store.d.ts.map

package/dist/telemetry/artifact-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-store.d.ts","sourceRoot":"","sources":["../../src/telemetry/artifact-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/C,wBAAwB,CAAC,GAAG,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC3D;kFAC8E;IAC9E,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IAClG,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IAClG,oBAAoB,CAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC;IACxD,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IAClG,gFAAgF;IAChF,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IACjD;gEAC4D;IAC5D,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAChD;;oFAEgF;IAChF,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACf;AAwED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAwH/D"}

package/dist/telemetry/artifact-store.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Local artifact-metadata buffer — Expansion E2 chunk B (spec §2).
+ *
+ * A SEPARATE better-sqlite3 handle over the same telemetry file (the captures.ts
+ * pattern), kept out of `store.ts` for cohesion and the LOC cap (P1). UNLIKE
+ * captures, these rows ARE exported: artifact METADATA is a cloud surface by
+ * ruling (the 00030 counter-annotation). What is NEVER stored — here or anywhere
+ * — is artifact CONTENT: `contentRef` is the customer's opaque URI, `contentHash`
+ * a sha256 of bytes hashed-then-discarded. Rows are immutable facts: INSERT OR
+ * IGNORE, read past a rowid watermark exactly like inferences.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openArtifactStore = openArtifactStore;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ARTIFACTS_SQL = `
+CREATE TABLE IF NOT EXISTS artifacts (
+  id TEXT PRIMARY KEY, run_id TEXT, step_key TEXT, attempt_no INTEGER, task TEXT,
+  name TEXT NOT NULL, type TEXT NOT NULL, version INTEGER NOT NULL,
+  supersedes_artifact_id TEXT, declared_schema TEXT, fingerprint_cell TEXT,
+  content_ref TEXT, content_hash TEXT, content_bytes INTEGER,
+  data_classification TEXT, expires_at TEXT, scrub TEXT
+);
+CREATE TABLE IF NOT EXISTS artifact_edges (
+  from_artifact_id TEXT NOT NULL, to_artifact_id TEXT NOT NULL, kind TEXT NOT NULL,
+  PRIMARY KEY (from_artifact_id, to_artifact_id, kind)
+);
+CREATE TABLE IF NOT EXISTS artifact_evaluations (
+  id TEXT PRIMARY KEY, artifact_id TEXT, run_id TEXT, evaluator TEXT NOT NULL,
+  evaluator_kind TEXT NOT NULL, score REAL, passed INTEGER, label TEXT,
+  explanation TEXT, created_by TEXT
+);
+CREATE TABLE IF NOT EXISTS eval_cases (
+  id TEXT PRIMARY KEY, task TEXT NOT NULL, source_artifact_id TEXT NOT NULL,
+  corrected_artifact_id TEXT, origin TEXT NOT NULL, note TEXT, created_by TEXT
+);
+`;
+function toArtifact(r) {
+    return {
+        id: r.id, runId: r.run_id, stepKey: r.step_key, attemptNo: r.attempt_no, task: r.task,
+        name: r.name, type: r.type, version: r.version, supersedesArtifactId: r.supersedes_artifact_id,
+        declaredSchema: r.declared_schema === null ? null : JSON.parse(r.declared_schema),
+        fingerprintCell: r.fingerprint_cell, contentRef: r.content_ref, contentHash: r.content_hash,
+        contentBytes: r.content_bytes, dataClassification: r.data_classification, expiresAt: r.expires_at,
+        scrub: r.scrub === null ? null : JSON.parse(r.scrub),
+    };
+}
+function toEdge(r) {
+    return { fromArtifactId: r.from_artifact_id, toArtifactId: r.to_artifact_id, kind: r.kind };
+}
+function toEval(r) {
+    return {
+        id: r.id, artifactId: r.artifact_id, runId: r.run_id, evaluator: r.evaluator,
+        evaluatorKind: r.evaluator_kind,
+        score: r.score, passed: r.passed === null ? null : r.passed !== 0,
+        label: r.label, explanation: r.explanation, createdBy: r.created_by,
+    };
+}
+function toEvalCase(r) {
+    return {
+        id: r.id, task: r.task, sourceArtifactId: r.source_artifact_id,
+        correctedArtifactId: r.corrected_artifact_id,
+        origin: r.origin, note: r.note, createdBy: r.created_by,
+    };
+}
+function openArtifactStore(dbPath) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dbPath), { recursive: true });
+    const db = new better_sqlite3_1.default(dbPath);
+    db.pragma("journal_mode = WAL");
+    // Fail-open telemetry does not need FULL fsync durability — NORMAL is the
+    // WAL-recommended setting and drops the per-write fsync that made a step's
+    // ~9 inserts nine fsyncs (H8). Durability across a power loss is not a
+    // telemetry guarantee; the cloud exporter is the durable copy.
+    db.pragma("synchronous = NORMAL");
+    db.exec(ARTIFACTS_SQL);
+    // Additive column for a dev DB that predates E4 (CREATE TABLE IF NOT EXISTS
+    // won't add it to an existing table). SQLite has no ADD COLUMN IF NOT EXISTS;
+    // a duplicate-column error on re-run is expected and swallowed.
+    try {
+        db.exec("ALTER TABLE artifacts ADD COLUMN scrub TEXT");
+    }
+    catch {
+        /* column already present — no-op */
+    }
+    // Additive run_id on evaluations (E5 chunk V, subject-one-of). A dev DB that
+    // predates E5 keeps artifact_id NOT NULL — only run-subject inserts (new this
+    // phase) would need the relaxed column, and a fresh .modelrig DB gets it from
+    // CREATE TABLE above. Same swallow-on-duplicate pattern as scrub.
+    try {
+        db.exec("ALTER TABLE artifact_evaluations ADD COLUMN run_id TEXT");
+    }
+    catch {
+        /* column already present — no-op */
+    }
+    // One reusable transaction wrapper for batch() (better-sqlite3 wraps a fn).
+    const runInTransaction = db.transaction((fn) => fn());
+    const insArtifact = db.prepare(`
+    INSERT OR IGNORE INTO artifacts (
+      id, run_id, step_key, attempt_no, task, name, type, version, supersedes_artifact_id,
+      declared_schema, fingerprint_cell, content_ref, content_hash, content_bytes,
+      data_classification, expires_at, scrub
+    ) VALUES (
+      @id, @run_id, @step_key, @attempt_no, @task, @name, @type, @version, @supersedes_artifact_id,
+      @declared_schema, @fingerprint_cell, @content_ref, @content_hash, @content_bytes,
+      @data_classification, @expires_at, @scrub
+    )`);
+    const insEdge = db.prepare("INSERT OR IGNORE INTO artifact_edges (from_artifact_id, to_artifact_id, kind) VALUES (@from_artifact_id, @to_artifact_id, @kind)");
+    const insEval = db.prepare(`
+    INSERT OR IGNORE INTO artifact_evaluations (
+      id, artifact_id, run_id, evaluator, evaluator_kind, score, passed, label, explanation, created_by
+    ) VALUES (@id, @artifact_id, @run_id, @evaluator, @evaluator_kind, @score, @passed, @label, @explanation, @created_by)`);
+    const insEvalCase = db.prepare(`
+    INSERT OR IGNORE INTO eval_cases (
+      id, task, source_artifact_id, corrected_artifact_id, origin, note, created_by
+    ) VALUES (@id, @task, @source_artifact_id, @corrected_artifact_id, @origin, @note, @created_by)`);
+    return {
+        recordArtifact(row) {
+            insArtifact.run({
+                id: row.id, run_id: row.runId, step_key: row.stepKey, attempt_no: row.attemptNo,
+                task: row.task, name: row.name, type: row.type, version: row.version,
+                supersedes_artifact_id: row.supersedesArtifactId,
+                declared_schema: row.declaredSchema === null || row.declaredSchema === undefined
+                    ? null : JSON.stringify(row.declaredSchema),
+                fingerprint_cell: row.fingerprintCell, content_ref: row.contentRef,
+                content_hash: row.contentHash, content_bytes: row.contentBytes,
+                data_classification: row.dataClassification, expires_at: row.expiresAt,
+                scrub: row.scrub === null || row.scrub === undefined ? null : JSON.stringify(row.scrub),
+            });
+        },
+        recordArtifactEdge(row) {
+            insEdge.run({ from_artifact_id: row.fromArtifactId, to_artifact_id: row.toArtifactId, kind: row.kind });
+        },
+        recordArtifactEvaluation(row) {
+            insEval.run({
+                id: row.id, artifact_id: row.artifactId, run_id: row.runId, evaluator: row.evaluator,
+                evaluator_kind: row.evaluatorKind, score: row.score,
+                passed: row.passed === null ? null : row.passed ? 1 : 0,
+                label: row.label, explanation: row.explanation, created_by: row.createdBy,
+            });
+        },
+        recordEvalCase(row) {
+            insEvalCase.run({
+                id: row.id, task: row.task, source_artifact_id: row.sourceArtifactId,
+                corrected_artifact_id: row.correctedArtifactId, origin: row.origin,
+                note: row.note, created_by: row.createdBy,
+            });
+        },
+        readArtifactsAfter(afterRowid, limit) {
+            const rows = db.prepare("SELECT rowid AS __r, * FROM artifacts WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__r, row: toArtifact(r) }));
+        },
+        readEdgesAfter(afterRowid, limit) {
+            const rows = db.prepare("SELECT rowid AS __r, * FROM artifact_edges WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__r, row: toEdge(r) }));
+        },
+        readEvaluationsAfter(afterRowid, limit) {
+            const rows = db.prepare("SELECT rowid AS __r, * FROM artifact_evaluations WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__r, row: toEval(r) }));
+        },
+        readEvalCasesAfter(afterRowid, limit) {
+            const rows = db.prepare("SELECT rowid AS __r, * FROM eval_cases WHERE rowid > ? ORDER BY rowid LIMIT ?")
+                .all(afterRowid, limit);
+            return rows.map((r) => ({ rowid: r.__r, row: toEvalCase(r) }));
+        },
+        readEvalCasesByTask(task) {
+            const rows = db.prepare("SELECT * FROM eval_cases WHERE task = ? ORDER BY rowid DESC")
+                .all(task);
+            return rows.map(toEvalCase);
+        },
+        getArtifactById(id) {
+            const r = db.prepare("SELECT * FROM artifacts WHERE id = ?").get(id);
+            return r === undefined ? null : toArtifact(r);
+        },
+        batch(fn) {
+            return runInTransaction(fn);
+        },
+        close() {
+            db.close();
+        },
+    };
+}

package/dist/telemetry/cache-miss-streak.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Full-price cache-miss streak detection — cache-aware-routing WS-C step 5
+ * (spec §5.6, research §2.3 differentiator: "paying full price and don't know it").
+ *
+ * A route that opted into `cache: auto` but keeps reading ZERO cached tokens on
+ * cacheable-size prompts is silently paying the write premium forever. This
+ * module is the PURE DETECTION over telemetry rows — a `EndpointHealth`-style
+ * companion to health.ts. It produces a structured `CacheMissStreak` per
+ * (route, provider); turning that into a `cache_miss_streak` health event + the
+ * console badge is the WIRING step, deliberately DEFERRED: per the WS-C fence,
+ * `src/watch/monitor.ts` is not touched while WS-B is in flight — this module is
+ * wired on the rebase after WS-B merges (never-simultaneous-in-src/watch rule).
+ *
+ * Opt-in signal WITHOUT a route lookup: a telemetry row carries a non-null
+ * `prefixFingerprint` iff its route opted into `cache: auto` (the run loop stamps
+ * it for every provider on such a route — cache-stamp.ts). So this detector keys
+ * off `prefixFingerprint !== null`; it needs no route registry.
+ *
+ * Fail-closed, per L5:
+ *   • only providers whose policy REPORTS read tokens are eligible — where reads
+ *     ride HTTP headers we don't lift (fireworks), `tokensCached` is structurally
+ *     0 and a "miss" is unobservable, so those rows are skipped (never a false alarm);
+ *   • only providers with a documented `min_cacheable_tokens` are eligible — with
+ *     no first-party minimum we cannot assert a prompt was large enough to cache,
+ *     so no streak is claimed;
+ *   • a row only counts toward the streak if it is BIG ENOUGH to cache
+ *     (`tokensIn > min_cacheable`); small prompts legitimately never cache.
+ *
+ * Cross-reference: this is the PRODUCTION-ROUTE-TELEMETRY plane of the same smell
+ * the registry surfaces on the PROBE/DECLARED plane as `declared_caching_unrealized`
+ * (registry/build.ts): a model that declares caching but shows no observed hits.
+ * Same signal, different plane — WS-D's badge should note both.
+ */
+import type { ProviderId } from "../types/provider";
+import type { CachePolicy } from "../registry/cache-policy";
+/** The minimal telemetry projection the detector needs. Both the local SQLite
+ * store and the hosted rollup can project rows onto this. */
+export interface CacheMissRow {
+    readonly route: string;
+    readonly provider: string;
+    readonly ts: string;
+    readonly tokensIn: number;
+    readonly tokensCached: number;
+    /** Non-null ⇒ the route opted into `cache: auto` (run loop stamps it). */
+    readonly prefixFingerprint: string | null;
+    /** Replay/shadow rows are excluded (odometer rule: tags.replay !== undefined).
+     * The caller computes this from `tagsJson`; the detector treats it as ground. */
+    readonly isReplay: boolean;
+}
+/** A detected full-price streak on one (route, provider). */
+export interface CacheMissStreak {
+    readonly route: string;
+    readonly provider: ProviderId;
+    /** How many consecutive recent cacheable-size rows read zero cached tokens. */
+    readonly streakLength: number;
+    /** The policy minimum the streak rows all exceeded. */
+    readonly minCacheableTokens: number;
+    /** Mean input tokens across the streak (how much is being paid full price). */
+    readonly meanTokensIn: number;
+    /** ISO ts of the most recent row in the streak. */
+    readonly lastSeenAt: string;
+}
+export interface CacheMissStreakOptions {
+    /** Consecutive full-price rows required to raise the alert (spec §5.6: 50). */
+    readonly streakLength?: number;
+    /** Policy accessor — injectable for tests; defaults to the registry. */
+    readonly getPolicy?: (provider: ProviderId) => CachePolicy;
+}
+export declare const DEFAULT_STREAK_LENGTH = 50;
+/**
+ * Detect full-price cache-miss streaks across `rows`. Pure and total.
+ *
+ * Groups eligible rows (cache:auto, production, observable provider, cacheable
+ * size) by (route, provider); a group raises a streak when its most recent
+ * `streakLength` such rows ALL read zero cached tokens. Output is sorted by
+ * route then provider for deterministic rollups.
+ */
+export declare function detectCacheMissStreaks(rows: readonly CacheMissRow[], opts?: CacheMissStreakOptions): CacheMissStreak[];
+//# sourceMappingURL=cache-miss-streak.d.ts.map

package/dist/telemetry/cache-miss-streak.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-miss-streak.d.ts","sourceRoot":"","sources":["../../src/telemetry/cache-miss-streak.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;6DAC6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;qFACiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,WAAW,CAAC;CAC5D;AAED,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,IAAI,GAAE,sBAA2B,GAChC,eAAe,EAAE,CAmDnB"}

package/dist/telemetry/cache-miss-streak.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Full-price cache-miss streak detection — cache-aware-routing WS-C step 5
+ * (spec §5.6, research §2.3 differentiator: "paying full price and don't know it").
+ *
+ * A route that opted into `cache: auto` but keeps reading ZERO cached tokens on
+ * cacheable-size prompts is silently paying the write premium forever. This
+ * module is the PURE DETECTION over telemetry rows — a `EndpointHealth`-style
+ * companion to health.ts. It produces a structured `CacheMissStreak` per
+ * (route, provider); turning that into a `cache_miss_streak` health event + the
+ * console badge is the WIRING step, deliberately DEFERRED: per the WS-C fence,
+ * `src/watch/monitor.ts` is not touched while WS-B is in flight — this module is
+ * wired on the rebase after WS-B merges (never-simultaneous-in-src/watch rule).
+ *
+ * Opt-in signal WITHOUT a route lookup: a telemetry row carries a non-null
+ * `prefixFingerprint` iff its route opted into `cache: auto` (the run loop stamps
+ * it for every provider on such a route — cache-stamp.ts). So this detector keys
+ * off `prefixFingerprint !== null`; it needs no route registry.
+ *
+ * Fail-closed, per L5:
+ *   • only providers whose policy REPORTS read tokens are eligible — where reads
+ *     ride HTTP headers we don't lift (fireworks), `tokensCached` is structurally
+ *     0 and a "miss" is unobservable, so those rows are skipped (never a false alarm);
+ *   • only providers with a documented `min_cacheable_tokens` are eligible — with
+ *     no first-party minimum we cannot assert a prompt was large enough to cache,
+ *     so no streak is claimed;
+ *   • a row only counts toward the streak if it is BIG ENOUGH to cache
+ *     (`tokensIn > min_cacheable`); small prompts legitimately never cache.
+ *
+ * Cross-reference: this is the PRODUCTION-ROUTE-TELEMETRY plane of the same smell
+ * the registry surfaces on the PROBE/DECLARED plane as `declared_caching_unrealized`
+ * (registry/build.ts): a model that declares caching but shows no observed hits.
+ * Same signal, different plane — WS-D's badge should note both.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STREAK_LENGTH = void 0;
+exports.detectCacheMissStreaks = detectCacheMissStreaks;
+const cache_policy_1 = require("../registry/cache-policy");
+exports.DEFAULT_STREAK_LENGTH = 50;
+const KEY_SEP = "|";
+/**
+ * Detect full-price cache-miss streaks across `rows`. Pure and total.
+ *
+ * Groups eligible rows (cache:auto, production, observable provider, cacheable
+ * size) by (route, provider); a group raises a streak when its most recent
+ * `streakLength` such rows ALL read zero cached tokens. Output is sorted by
+ * route then provider for deterministic rollups.
+ */
+function detectCacheMissStreaks(rows, opts = {}) {
+    const streakLength = opts.streakLength ?? exports.DEFAULT_STREAK_LENGTH;
+    const getPolicy = opts.getPolicy ?? cache_policy_1.getCachePolicy;
+    // Bucket eligible rows by (route, provider), remembering each provider's
+    // documented minimum (looked up once per provider).
+    const byKey = new Map();
+    const minByProvider = new Map();
+    for (const row of rows) {
+        if (row.prefixFingerprint === null)
+            continue; // route didn't opt into cache:auto
+        if (row.isReplay)
+            continue; // odometer replay-exclusion rule
+        let min = minByProvider.get(row.provider);
+        if (min === undefined) {
+            const policy = getPolicy(row.provider);
+            // Only providers we can OBSERVE hits for, with a sourced minimum, are eligible.
+            min =
+                policy.cache_supported && policy.reports_read_tokens ? policy.min_cacheable_tokens : null;
+            minByProvider.set(row.provider, min);
+        }
+        if (min === null)
+            continue; // unobservable or no first-party minimum → fail-closed
+        if (row.tokensIn <= min)
+            continue; // too small to cache — not a "miss"
+        const key = `${row.route}${KEY_SEP}${row.provider}`;
+        const list = byKey.get(key) ?? [];
+        list.push(row);
+        byKey.set(key, list);
+    }
+    const out = [];
+    for (const [key, group] of byKey) {
+        if (group.length < streakLength)
+            continue; // not enough evidence yet
+        // Most-recent `streakLength` rows (ascending ts, take the tail).
+        const sorted = [...group].sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+        const recent = sorted.slice(sorted.length - streakLength);
+        if (!recent.every((r) => r.tokensCached === 0))
+            continue; // a hit broke the streak
+        const [route, provider] = key.split(KEY_SEP);
+        const meanTokensIn = Math.round(recent.reduce((sum, r) => sum + r.tokensIn, 0) / recent.length);
+        out.push({
+            route,
+            provider: provider,
+            streakLength,
+            minCacheableTokens: minByProvider.get(provider),
+            meanTokensIn,
+            lastSeenAt: recent[recent.length - 1].ts,
+        });
+    }
+    return out.sort((a, b) => a.route === b.route ? a.provider.localeCompare(b.provider) : a.route.localeCompare(b.route));
+}

package/dist/telemetry/capture.d.ts

@@ -17,6 +17,9 @@ export interface CaptureStore {
     record(row: CaptureRow): void;
     /** Most recent N captures for a route (replay's read path). */
     readLast(route: string, n: number): CaptureRow[];
+    /** One capture by its inference id, or null (E4 chunk A: rehydrate an eval
+     * case's input from the inference that produced its source artifact). */
+    getByInferenceId(inferenceId: string): CaptureRow | null;
     close(): void;
 }
 /**

package/dist/telemetry/capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/telemetry/capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IACjD,KAAK,IAAI,IAAI,CAAC;CACf;AAyBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CA2C7D"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/telemetry/capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAAC;IACjD;6EACyE;IACzE,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACzD,KAAK,IAAI,IAAI,CAAC;CACf;AAyBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAoD7D"}

package/dist/telemetry/capture.js

@@ -45,6 +45,14 @@ function openCaptureStore(dbPath) {
     const selectLast = db.prepare(`
     SELECT * FROM captures WHERE route = ? ORDER BY ts DESC, rowid DESC LIMIT ?
   `);
+    const toRow = (r) => ({
+        inferenceId: r.inference_id,
+        ts: r.ts,
+        route: r.route,
+        routeVersion: r.route_version,
+        variablesJson: r.variables_json,
+        outputText: r.output_text,
+    });
     return {
         record(row) {
             insert.run({
@@ -58,14 +66,13 @@ function openCaptureStore(dbPath) {
         },
         readLast(route, n) {
             const rows = selectLast.all(route, n);
-            return rows.map((r) => ({
-                inferenceId: r.inference_id,
-                ts: r.ts,
-                route: r.route,
-                routeVersion: r.route_version,
-                variablesJson: r.variables_json,
-                outputText: r.output_text,
-            }));
+            return rows.map(toRow);
+        },
+        getByInferenceId(inferenceId) {
+            const r = db
+                .prepare("SELECT * FROM captures WHERE inference_id = ?")
+                .get(inferenceId);
+            return r === undefined ? null : toRow(r);
         },
         close() {
             db.close();

package/dist/telemetry/exporter-setup.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Build-and-start the telemetry exporter from resolved config. Extracted from
+ * index.ts (the SDK entrypoint) so that file stays under the LOC cap while
+ * Phase 2 adds the settings resolver + boot banner beside it — the exporter
+ * wiring is mechanical and has one caller, so it lives here rather than inline.
+ */
+import type { RigManifest } from "../routes/manifest";
+import type { ServeabilityWarning } from "../routes/serveability";
+import type { ApiExportConfig, DirectExportConfig } from "../config";
+import type { Exporter, ExportedRouteMirror } from "./exporter";
+import type { ArtifactStore } from "./artifact-store";
+import type { ExportableTelemetryStore } from "./store";
+export interface ExporterSetupExtras {
+    readonly routes: readonly ExportedRouteMirror[];
+    readonly manifest: RigManifest | null;
+    readonly serveability: readonly ServeabilityWarning[];
+    /** v2 wire + runs/steps/artifact streams only when the namespace is enabled. */
+    readonly artifactsEnabled: boolean;
+    readonly artifactStore: ArtifactStore | null;
+    /** E4 chunk 0: retry 404'd content after a confirmed artifacts flush. */
+    readonly onArtifactsFlushed?: () => Promise<void>;
+}
+/**
+ * Construct the sink for the configured mode, wire the exporter, and start its
+ * flush loop. Returns the running exporter (the caller stops it on close()).
+ */
+export declare function startTelemetryExporter(telemetry: ExportableTelemetryStore, exportConfig: ApiExportConfig | DirectExportConfig, extras: ExporterSetupExtras): Exporter;
+//# sourceMappingURL=exporter-setup.d.ts.map

package/dist/telemetry/exporter-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter-setup.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporter-setup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAErE,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtD,gFAAgF;IAChF,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,wBAAwB,EACnC,YAAY,EAAE,eAAe,GAAG,kBAAkB,EAClD,MAAM,EAAE,mBAAmB,GAC1B,QAAQ,CAiBV"}