@getrift/rift 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/src/mcp/tools/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../../src/mcp/tools/search.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EACL,qBAAqB,GAEtB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC;IACjD,KAAK,EAAE,CAAC;SACL,IAAI,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,CAAC,CAAC;SAClE,QAAQ,EAAE;SACV,QAAQ,CAAC,gCAAgC,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC1E,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;IACxE,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,yCAAyC,CAAC;IACtD,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,yEAAyE,CAC1E;IACH,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;SACzB,QAAQ,EAAE;SACV,QAAQ,CACP,qGAAqG,CACtG;IACH,EAAE,EAAE,CAAC;SACF,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,gDAAgD,CAAC;CAC9D,CAAC;AAUF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA6B,EAC7B,MAAkB;IAElB,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACpD,MAAM,IAAI,GAAG,IAA6B,CAAC;QAC3C,MAAM,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,EAAE;YAC/C,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;YAC1C,iBAAiB,EAAE,IAA0C;SAC9D,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../../src/mcp/tools/search.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/embedding-events.d.ts

@@ -0,0 +1,52 @@
+import type { EmbeddingProvider } from "../providers/types.js";
+export declare const EMBEDDING_PIPELINES: readonly ["watcher", "scheduled_scan", "reconcile", "ingest_job", "compact", "backfill", "capture", "reindex"];
+export type EmbeddingPipeline = (typeof EMBEDDING_PIPELINES)[number];
+export type EmbeddingOutcome = "success" | "error";
+export interface EmbeddingEvent {
+    ts: string;
+    provider: string;
+    model: string;
+    pipeline: EmbeddingPipeline;
+    /**
+     * Free-form caller label (e.g. "document_embedding", "conversation",
+     * "digest", "reindex_conversation"). Helps debug "which write path"
+     * when scanning the log; does not gate any status logic today.
+     */
+    operation: string;
+    outcome: EmbeddingOutcome;
+    input_count: number;
+    ms: number;
+    /** Compact error class (e.g. "provider_400"). Present when outcome === "error". */
+    error_class?: string;
+    /** Truncated error message (≤ 512 chars). Present when outcome === "error". */
+    error_message?: string;
+}
+export interface EmbedContext {
+    pipeline: EmbeddingPipeline;
+    operation: string;
+    /** Number of inputs in this call (1 for embed, N for embedBatch). */
+    input_count: number;
+}
+export declare function eventsFilePath(dataDir: string): string;
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break embedding. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export declare function appendEmbeddingEvent(dataDir: string, event: EmbeddingEvent): void;
+/**
+ * Run an embedding call and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this at every ingest call site. Do NOT use it for search-time
+ * embedding — keeping search out of the lane is what makes
+ * `last_embed_at` meaningful.
+ */
+export declare function recordEmbed<T>(dataDir: string, provider: EmbeddingProvider, ctx: EmbedContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export declare function readEmbeddingEvents(dataDir: string): EmbeddingEvent[];
+//# sourceMappingURL=embedding-events.d.ts.map

package/dist/src/observability/embedding-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-events.d.ts","sourceRoot":"","sources":["../../../src/observability/embedding-events.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,eAAO,MAAM,mBAAmB,gHAStB,CAAC;AACX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,cAAc,GACpB,IAAI,CAUN;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,EAAE,YAAY,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CA+BZ;AAkBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAoBrE"}

package/dist/src/observability/embedding-events.js

@@ -0,0 +1,149 @@
+/**
+ * Embedding-events lane — append-only JSONL.
+ *
+ * One row per call to an embedding provider on an *ingest* code path
+ * (watcher / scheduled-scan / reconcile / ingest-job / compact / backfill).
+ * Search-time embedding calls (search routes, hybrid retrieval) are
+ * deliberately NOT logged here — otherwise a user search would refresh
+ * `voyage.last_embed_at` and mask an ingestion outage.
+ *
+ * Provider-agnostic on purpose: `provider` and `model` are payload
+ * fields, not the file name, so a future Ollama/local-embedding swap
+ * shares the same lane and the same `/status/friend` consumer.
+ *
+ * Failure mode: writes are best-effort and never throw — embedding must
+ * not be observably blocked by telemetry. Reads are tolerant of bad
+ * lines so one corrupt row doesn't blank the status dashboard.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const EMBEDDING_PIPELINES = [
+    "watcher",
+    "scheduled_scan",
+    "reconcile",
+    "ingest_job",
+    "compact",
+    "backfill",
+    "capture",
+    "reindex",
+];
+const MAX_ERROR_MESSAGE_LEN = 512;
+export function eventsFilePath(dataDir) {
+    return path.join(dataDir, "observability", "embedding-events.jsonl");
+}
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break embedding. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export function appendEmbeddingEvent(dataDir, event) {
+    const filePath = eventsFilePath(dataDir);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify(event) + "\n");
+    }
+    catch (err) {
+        process.stderr.write(`[embedding-events] write failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Run an embedding call and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this at every ingest call site. Do NOT use it for search-time
+ * embedding — keeping search out of the lane is what makes
+ * `last_embed_at` meaningful.
+ */
+export async function recordEmbed(dataDir, provider, ctx, fn) {
+    const start = Date.now();
+    try {
+        const result = await fn();
+        appendEmbeddingEvent(dataDir, {
+            ts: new Date().toISOString(),
+            provider: provider.name,
+            model: provider.model,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "success",
+            input_count: ctx.input_count,
+            ms: Date.now() - start,
+        });
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        appendEmbeddingEvent(dataDir, {
+            ts: new Date().toISOString(),
+            provider: provider.name,
+            model: provider.model,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "error",
+            input_count: ctx.input_count,
+            ms: Date.now() - start,
+            error_class: classifyError(err),
+            error_message: message.slice(0, MAX_ERROR_MESSAGE_LEN),
+        });
+        throw err;
+    }
+}
+/**
+ * Best-effort classification for the `error_class` field.
+ * Voyage / Ollama errors carry `Voyage API <code>: ...` /
+ * `Ollama embed API <code>: ...` shapes — extract the status code so
+ * status views can group by class without parsing free-text.
+ */
+function classifyError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const httpMatch = msg.match(/\b(\d{3})\b/);
+    if (httpMatch && msg.toLowerCase().includes("api")) {
+        return `provider_${httpMatch[1]}`;
+    }
+    if (err instanceof TypeError)
+        return "network";
+    return "unknown";
+}
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export function readEmbeddingEvents(dataDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(eventsFilePath(dataDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isEmbeddingEvent(parsed))
+            continue;
+        out.push(parsed);
+    }
+    return out;
+}
+function isEmbeddingEvent(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v["ts"] === "string" &&
+        typeof v["provider"] === "string" &&
+        typeof v["model"] === "string" &&
+        typeof v["pipeline"] === "string" &&
+        typeof v["operation"] === "string" &&
+        (v["outcome"] === "success" || v["outcome"] === "error") &&
+        typeof v["input_count"] === "number" &&
+        typeof v["ms"] === "number");
+}
+//# sourceMappingURL=embedding-events.js.map

package/dist/src/observability/embedding-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-events.js","sourceRoot":"","sources":["../../../src/observability/embedding-events.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/index-events.d.ts

@@ -0,0 +1,70 @@
+import type { EmbeddingPipeline } from "./embedding-events.js";
+export type IndexOutcome = "success" | "error";
+export interface IndexEvent {
+    ts: string;
+    /**
+     * Target LanceDB table. Free-form string (not `TableName`) so shadow
+     * writes can record their target without coupling to the live table
+     * name set.
+     */
+    table: string;
+    pipeline: EmbeddingPipeline;
+    /**
+     * Free-form caller label (e.g. "structured_doc_upsert",
+     * "conversation_upsert", "digest_upsert"). Helps debug "which write
+     * path"; does not gate any status logic today.
+     */
+    operation: string;
+    outcome: IndexOutcome;
+    /** Number of rows in this `table.add(...)` call (or rollback batch). */
+    row_count: number;
+    ms: number;
+    /**
+     * Lifecycle phase.
+     * - "live" (default when omitted) — the row is now searchable.
+     *   Direct writes are always "live"; shadow rebuilds emit a single
+     *   "live" event per table after `commitAllSwaps` succeeds.
+     * - "shadow" — the row was written to a pre-commit shadow table. If
+     *   the subsequent swap fails the row is NOT searchable, so
+     *   `computeIndexHealth` does NOT credit `last_update_at` from
+     *   shadow successes. Shadow errors still surface as `last_error_at`
+     *   because they represent real LanceDB write failures regardless of
+     *   the eventual swap outcome.
+     */
+    phase?: "live" | "shadow";
+    /** Compact error class. Present when outcome === "error". */
+    error_class?: string;
+    /** Truncated error message (≤ 512 chars). Present when outcome === "error". */
+    error_message?: string;
+}
+export interface IndexWriteContext {
+    table: string;
+    pipeline: EmbeddingPipeline;
+    operation: string;
+    row_count: number;
+    /** Defaults to "live". Set "shadow" for pre-commit shadow-table writes. */
+    phase?: "live" | "shadow";
+}
+export declare function indexEventsFilePath(dataDir: string): string;
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break indexing. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export declare function appendIndexEvent(dataDir: string, event: IndexEvent): void;
+/**
+ * Run a LanceDB write and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this only at write boundaries (`table.add(...)`). Do NOT use it
+ * for reads, queries, or deletes — keeping the lane write-only is what
+ * makes `last_update_at` meaningful.
+ */
+export declare function recordIndexWrite<T>(dataDir: string, ctx: IndexWriteContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export declare function readIndexEvents(dataDir: string): IndexEvent[];
+//# sourceMappingURL=index-events.d.ts.map

package/dist/src/observability/index-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-events.d.ts","sourceRoot":"","sources":["../../../src/observability/index-events.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC3B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,UAAU,GAChB,IAAI,CAUN;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,iBAAiB,EACtB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAgCZ;AAmBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAoB7D"}

package/dist/src/observability/index-events.js

@@ -0,0 +1,148 @@
+/**
+ * Index-events lane — append-only JSONL.
+ *
+ * One row per write boundary against LanceDB (`table.add(...)`). This
+ * complements `embedding-events.jsonl`: the embedding lane proves the
+ * vector was produced, this lane proves the row was actually persisted
+ * to LanceDB and is searchable. Without it, `/status/friend` cannot
+ * distinguish "embedded but not indexed yet" from "fully searchable".
+ *
+ * Provider-agnostic and table-agnostic: `table` and `pipeline` are
+ * payload fields. Reads / search queries are deliberately NOT wrapped —
+ * they're not write events and would muddy `index.last_update_at`.
+ *
+ * Failure mode: writes are best-effort and never throw — observability
+ * must not break indexing. The reader is tolerant of bad lines so one
+ * corrupt row doesn't blank the status dashboard.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const MAX_ERROR_MESSAGE_LEN = 512;
+export function indexEventsFilePath(dataDir) {
+    return path.join(dataDir, "observability", "index-events.jsonl");
+}
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break indexing. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export function appendIndexEvent(dataDir, event) {
+    const filePath = indexEventsFilePath(dataDir);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify(event) + "\n");
+    }
+    catch (err) {
+        process.stderr.write(`[index-events] write failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Run a LanceDB write and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this only at write boundaries (`table.add(...)`). Do NOT use it
+ * for reads, queries, or deletes — keeping the lane write-only is what
+ * makes `last_update_at` meaningful.
+ */
+export async function recordIndexWrite(dataDir, ctx, fn) {
+    const start = Date.now();
+    const phase = ctx.phase ?? "live";
+    try {
+        const result = await fn();
+        appendIndexEvent(dataDir, {
+            ts: new Date().toISOString(),
+            table: ctx.table,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "success",
+            row_count: ctx.row_count,
+            ms: Date.now() - start,
+            phase,
+        });
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        appendIndexEvent(dataDir, {
+            ts: new Date().toISOString(),
+            table: ctx.table,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "error",
+            row_count: ctx.row_count,
+            ms: Date.now() - start,
+            phase,
+            error_class: classifyError(err),
+            error_message: message.slice(0, MAX_ERROR_MESSAGE_LEN),
+        });
+        throw err;
+    }
+}
+/**
+ * Best-effort classification for the `error_class` field. LanceDB
+ * surfaces schema mismatches, IO errors, and lock contention with
+ * different shapes — pick a coarse class so dashboards can group.
+ */
+function classifyError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const lower = msg.toLowerCase();
+    if (lower.includes("schema"))
+        return "schema_mismatch";
+    if (lower.includes("lock") || lower.includes("conflict"))
+        return "lock_conflict";
+    if (lower.includes("enoent") || lower.includes("eacces") || lower.includes("eio")) {
+        return "io";
+    }
+    if (err instanceof TypeError)
+        return "type";
+    return "unknown";
+}
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export function readIndexEvents(dataDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(indexEventsFilePath(dataDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isIndexEvent(parsed))
+            continue;
+        out.push(parsed);
+    }
+    return out;
+}
+function isIndexEvent(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    if (!(typeof v["ts"] === "string" &&
+        typeof v["table"] === "string" &&
+        typeof v["pipeline"] === "string" &&
+        typeof v["operation"] === "string" &&
+        (v["outcome"] === "success" || v["outcome"] === "error") &&
+        typeof v["row_count"] === "number" &&
+        typeof v["ms"] === "number")) {
+        return false;
+    }
+    const phase = v["phase"];
+    if (phase !== undefined && phase !== "live" && phase !== "shadow")
+        return false;
+    return true;
+}
+//# sourceMappingURL=index-events.js.map

package/dist/src/observability/index-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-events.js","sourceRoot":"","sources":["../../../src/observability/index-events.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/tool-usage-stats.d.ts

@@ -3,14 +3,78 @@
  *
  * No filesystem reads, no parsing — callers pass an already-decoded
  * `ToolUsageEntry[]` (typically via `readToolUsageEntriesTolerant`).
- * Buckets calls into today/week/month/all-time and applies a fixed
- * per-tool tokens-saved heuristic so historical entries (which were
- * never instrumented for size) yield a usable estimate.
+ * Buckets calls into today/week/month/all-time. The headline retrieval
+ * metric is `context_tokens_delivered_estimate` — the measured size of
+ * the text channel actually returned on context hits, divided by 4 for
+ * a rough tokens estimate.
  */
 import type { ToolUsageEntry } from "./tool-usage.js";
 export interface UsageWindow {
     calls: number;
-    tokens_saved: number;
+    /**
+     * Successful retrieval calls that returned at least one item and were not
+     * marked `degraded`. Captures rift_search, rift_conversations_search, and
+     * rift_context_pack — the tools whose job is to surface relevant context.
+     * Non-retrieval calls (rift_save, rift_status) are excluded.
+     */
+    context_hits: number;
+    /**
+     * Cheap tokens estimate (`ceil(bytes / 4)`) over the MCP text channel of
+     * every call that counts toward `context_hits`. Measured from the response
+     * we actually returned — not a per-tool flat constant. Empty results,
+     * degraded retrievals, failures, and non-retrieval tools contribute 0.
+     * Legacy log rows written before response size was recorded contribute 0
+     * (no fabricated number) and naturally age out as fresh rows accumulate.
+     */
+    context_tokens_delivered_estimate: number;
+}
+/**
+ * Precise-lookup health: aggregates over rift_search calls whose
+ * `search_mode` was recorded as `"exact_id"`. Surfaces the leading
+ * indicators that the strict direct-lookup gate on `/search` is or
+ * isn't earning agent trust — high success ratio + rare typed failures
+ * is healthy; rising `typed_failures` (`id_not_found`/`ambiguous_id`)
+ * or large `max_content_tokens_estimate` paired with low success is
+ * the shape of a flow where an agent may stop trusting Rift for precise
+ * lookup. Trust risk is named precisely:
+ * we cannot tell from Rift alone that the agent went on to read JSONL
+ * from disk, only that the lookup it asked for here failed.
+ */
+export interface PreciseLookupStats {
+    /** Total rift_search calls with search_mode = exact_id (success or not). */
+    total: number;
+    /** Subset of `total` where success = true. */
+    successes: number;
+    /**
+     * Failures bucketed by the typed `error` field parsed from the response
+     * body (e.g. `id_not_found`, `ambiguous_id`). Transport / untyped
+     * failures do not appear here — they only count toward `total - successes`.
+     */
+    typed_failures: Record<string, number>;
+    /**
+     * Detail-level split among exact-id calls. `summary` is impossible by
+     * definition (exact-id requires middle|full), so only `middle` and
+     * `full` appear. Useful for seeing whether agents prefer the bounded
+     * middle path or still default to full-body expansion.
+     */
+    by_detail: {
+        middle: number;
+        full: number;
+    };
+    /**
+     * Count of successful exact-id calls that returned at least one hit
+     * with `content_truncated === true` — a leading indicator that the
+     * agent received a bounded excerpt and may decide to escalate to
+     * `detail=full`. Bounded to successful calls because truncation only
+     * makes sense for returned content.
+     */
+    truncated_count: number;
+    /**
+     * Maximum `content_tokens_estimate` observed across all exact-id
+     * calls (successful or not, when the field was present). Captures the
+     * worst-case "this row would blow context if expanded" signal.
+     */
+    max_content_tokens_estimate: number;
 }
 export interface UsageSummary {
     today: UsageWindow;
@@ -18,6 +82,7 @@ export interface UsageSummary {
     month: UsageWindow;
     all_time: UsageWindow;
     by_tool: Record<string, number>;
+    precise_lookup: PreciseLookupStats;
 }
 export declare function aggregateUsage(entries: ToolUsageEntry[], now?: Date): UsageSummary;
 //# sourceMappingURL=tool-usage-stats.d.ts.map

package/dist/src/observability/tool-usage-stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-usage-stats.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAyCtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAkBD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,GAAG,GAAE,IAAiB,GACrB,YAAY,CA4Cd"}
+{"version":3,"file":"tool-usage-stats.d.ts","sourceRoot":"","sources":["../../../src/observability/tool-usage-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAsBtD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,iCAAiC,EAAE,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,EAAE,kBAAkB,CAAC;CACpC;AA+DD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,GAAG,GAAE,IAAiB,GACrB,YAAY,CAiFd"}