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

package/dist/src/server/routes/friend-status.js

@@ -2,6 +2,13 @@ import { getBuildInfo } from "../build-info.js";
 import { readAutoCaptureRunSummary, } from "../../capture/observability.js";
 import { loadFeedbackConfig } from "../../cli/feedback/feedback-config.js";
 import { sanitizeProjectLabel } from "../../runtime/legacy-name-guard.js";
+import { readEmbeddingEvents, } from "../../observability/embedding-events.js";
+import { readIndexEvents, } from "../../observability/index-events.js";
+import { compareBetaVersions, readVersionCheck, } from "../../observability/version-check.js";
+const VOYAGE_ERROR_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+const INDEX_ERROR_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+const INBOX_ERROR_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+const INBOX_IDEMPOTENCY_PREFIX = "inbox:";
 export function buildFriendStatusPayload(deps) {
     const build = getBuildInfo();
     const voyageKey = process.env["VOYAGE_API_KEY"];
@@ -24,12 +31,9 @@ export function buildFriendStatusPayload(deps) {
             captureTotals.quarantined += counts.quarantined ?? 0;
         }
     }
-    let lastEmbedAt = null;
-    for (const success of Object.values(summary.last_success_by_source)) {
-        if (success && (!lastEmbedAt || success.timestamp > lastEmbedAt)) {
-            lastEmbedAt = success.timestamp;
-        }
-    }
+    const voyageHealth = computeVoyageHealth(dataDir, Date.now());
+    const indexHealth = computeIndexHealth(dataDir, Date.now());
+    const inboxHealth = computeInboxHealth(deps.jobQueue, Date.now());
     let relayEnabled = false;
     try {
         relayEnabled = loadFeedbackConfig(dataDir).enabled === true;
@@ -43,11 +47,20 @@ export function buildFriendStatusPayload(deps) {
             uptime_seconds: Math.floor((Date.now() - deps.startTime) / 1000),
             port: deps.config.server.port,
             voyage_key_present: typeof voyageKey === "string" && voyageKey.length > 0,
+            data_dir: dataDir,
         },
         voyage: {
             project_label: sanitizeProjectLabel(deps.config.voyage?.project_label),
-            last_embed_at: lastEmbedAt,
+            last_embed_at: voyageHealth.last_embed_at,
+            last_error_at: voyageHealth.last_error_at,
+            last_error_reason: voyageHealth.last_error_reason,
+        },
+        index: {
+            last_update_at: indexHealth.last_update_at,
+            last_error_at: indexHealth.last_error_at,
+            last_error_reason: indexHealth.last_error_reason,
         },
+        inbox: inboxHealth,
         codex: {
             last_preflight_at: last?.timestamp ?? null,
             last_preflight_ok: last ? last.preflight_ok : null,
@@ -59,10 +72,280 @@ export function buildFriendStatusPayload(deps) {
             last_review: captureTotals.review,
             last_errors: last?.errors.length ?? 0,
             last_quarantined: captureTotals.quarantined,
+            next_run_at: computeNextCaptureRunAt({
+                captureEnabled: deps.config.capture.enabled,
+                intervalSeconds: deps.config.capture.interval_seconds,
+                startTime: deps.startTime,
+                now: Date.now(),
+            }),
         },
         feedback: { relay_enabled: relayEnabled },
+        update: computeUpdateProjection(dataDir, build.version),
+    };
+}
+/**
+ * Project the version-check snapshot to the three fields the renderer
+ * needs. A missing snapshot, a failed probe, or an up-to-date install
+ * all return `available: false` — the renderer prints nothing in those
+ * cases, so an unreachable npm registry can never make Rift look broken.
+ *
+ * Exported for tests.
+ */
+export function computeUpdateProjection(dataDir, installedVersion) {
+    const snapshot = readVersionCheck(dataDir);
+    if (!snapshot || snapshot.latest_beta === null) {
+        return {
+            available: false,
+            installed: installedVersion,
+            latest_beta: snapshot?.latest_beta ?? null,
+            checked_at: snapshot?.checked_at ?? null,
+        };
+    }
+    // Use the installedVersion from the live build, not the snapshot, so a
+    // post-update daemon restart immediately reports `available: false`
+    // even before the next probe writes a fresh snapshot.
+    const available = compareBetaVersions(installedVersion, snapshot.latest_beta) < 0;
+    return {
+        available,
+        installed: installedVersion,
+        latest_beta: snapshot.latest_beta,
+        checked_at: snapshot.checked_at,
+    };
+}
+/**
+ * Compute the next auto-capture tick.
+ *
+ * The daemon registers `setInterval(runCapture, intervalMs)` at startup
+ * (`src/main.ts`), so ticks land at `startTime + N * intervalMs` for
+ * N ≥ 1 (N = 0 is the eager startup call). We deliberately anchor to
+ * `startTime` rather than `last_run_at` because:
+ *   - `setInterval` does, so this matches what will actually fire.
+ *   - `last_run_at` lags by hundreds of ms (save-job wait), and could
+ *     be stale from a prior daemon process for the first interval after
+ *     a restart.
+ *
+ * Returns null when auto-capture is disabled in config.
+ *
+ * Exported for tests.
+ */
+export function computeNextCaptureRunAt(opts) {
+    if (!opts.captureEnabled)
+        return null;
+    if (opts.intervalSeconds <= 0)
+        return null;
+    const intervalMs = opts.intervalSeconds * 1000;
+    const elapsed = Math.max(0, opts.now - opts.startTime);
+    const ticksElapsed = Math.floor(elapsed / intervalMs);
+    return new Date(opts.startTime + (ticksElapsed + 1) * intervalMs).toISOString();
+}
+/**
+ * Reduce the embedding-events lane to the three voyage health fields the
+ * friend-status route needs.
+ *
+ * Exported for tests so we can verify the pipeline-filter and 24h-window
+ * logic without booting Fastify or stubbing the route layer.
+ */
+export function computeVoyageHealth(dataDir, now) {
+    let events;
+    try {
+        events = readEmbeddingEvents(dataDir);
+    }
+    catch {
+        events = [];
+    }
+    let lastSuccessTs = null;
+    let lastErrorTs = null;
+    let lastErrorReason = null;
+    const errorCutoff = now - VOYAGE_ERROR_LOOKBACK_MS;
+    for (const event of events) {
+        // The `voyage.*` projection must reflect Voyage health only. The lane
+        // itself is provider-agnostic so a future Ollama-only install reuses
+        // the same writer, but on a mixed cloud+local install an Ollama
+        // success would otherwise refresh `voyage.last_embed_at` and mask a
+        // Voyage outage. Filter at projection time, not write time.
+        if (event.provider !== "voyage")
+            continue;
+        if (event.outcome === "success") {
+            if (!lastSuccessTs || event.ts > lastSuccessTs) {
+                lastSuccessTs = event.ts;
+            }
+            continue;
+        }
+        // outcome === "error"
+        const eventTime = Date.parse(event.ts);
+        if (Number.isNaN(eventTime) || eventTime < errorCutoff)
+            continue;
+        if (!lastErrorTs || event.ts > lastErrorTs) {
+            lastErrorTs = event.ts;
+            lastErrorReason = event.error_class ?? "unknown";
+        }
+    }
+    return {
+        last_embed_at: lastSuccessTs,
+        last_error_at: lastErrorTs,
+        last_error_reason: lastErrorReason,
     };
 }
+/**
+ * Reduce the index-events lane to the three index health fields the
+ * friend-status route needs. Provider-agnostic and table-agnostic: an
+ * embed can succeed but the subsequent `table.add(...)` can fail, and
+ * `index.*` is what makes that visible. No 24h filter on `last_update_at`
+ * (a daemon that has not indexed in 7 days should still surface the
+ * stale timestamp); errors are filtered to the 24h window so old
+ * resolved incidents don't sit on the dashboard forever.
+ */
+export function computeIndexHealth(dataDir, now) {
+    let events;
+    try {
+        events = readIndexEvents(dataDir);
+    }
+    catch {
+        events = [];
+    }
+    let lastSuccessTs = null;
+    let lastErrorTs = null;
+    let lastErrorReason = null;
+    const errorCutoff = now - INDEX_ERROR_LOOKBACK_MS;
+    for (const event of events) {
+        if (event.outcome === "success") {
+            // Shadow-phase successes do NOT credit `last_update_at`: a row
+            // written to a shadow table is "prepared", not "searchable",
+            // until `commitAllSwaps` runs. If the swap rolls back, those
+            // rows stay invisible — so claiming a fresh index from them
+            // would lie. The post-commit "live" event is what credits the
+            // real update timestamp.
+            const phase = event.phase ?? "live";
+            if (phase !== "live")
+                continue;
+            if (!lastSuccessTs || event.ts > lastSuccessTs) {
+                lastSuccessTs = event.ts;
+            }
+            continue;
+        }
+        // Errors at any phase (including shadow) count toward
+        // `last_error_at` — a per-row LanceDB write failure during shadow
+        // population is a real failure regardless of the eventual swap.
+        const eventTime = Date.parse(event.ts);
+        if (Number.isNaN(eventTime) || eventTime < errorCutoff)
+            continue;
+        if (!lastErrorTs || event.ts > lastErrorTs) {
+            lastErrorTs = event.ts;
+            lastErrorReason = event.error_class ?? "unknown";
+        }
+    }
+    return {
+        last_update_at: lastSuccessTs,
+        last_error_at: lastErrorTs,
+        last_error_reason: lastErrorReason,
+    };
+}
+/**
+ * Reduce the inbox-keyed job set to the four fields the friend-status
+ * route needs. Pure over the queue's snapshot (no I/O), so tests can
+ * pass an in-memory `JobQueue` without booting Fastify.
+ *
+ * When the queue isn't wired up (deps.jobQueue undefined), this
+ * returns the empty / idle shape — the renderer treats it the same
+ * as "nothing dropped yet."
+ *
+ * Exported for tests.
+ */
+export function computeInboxHealth(queue, now) {
+    if (!queue) {
+        return {
+            last_import_at: null,
+            last_error_at: null,
+            last_error_reason: null,
+            pending: 0,
+        };
+    }
+    const jobs = queue.listByIdempotencyPrefix(INBOX_IDEMPOTENCY_PREFIX);
+    let lastImportTs = null;
+    let lastErrorTs = null;
+    let lastErrorReason = null;
+    let pending = 0;
+    const errorCutoff = now - INBOX_ERROR_LOOKBACK_MS;
+    for (const job of jobs) {
+        // Skip superseded jobs — the queue chains a retry by setting
+        // `retried_by` on the failed/completed parent and creating a fresh
+        // job with the same idempotency key. Counting both would let a
+        // long-resolved failure keep the "Inbox import errors" hint live
+        // for 24h after the retry already succeeded; the leaf is the only
+        // entry that reflects current state. (Same invariant the queue
+        // itself enforces in `findByIdempotencyKey`.)
+        if (job.retried_by !== undefined)
+            continue;
+        if (job.status === "queued" || job.status === "running") {
+            pending++;
+            continue;
+        }
+        if (job.status === "completed") {
+            if (!lastImportTs || job.updated_at > lastImportTs) {
+                lastImportTs = job.updated_at;
+            }
+            continue;
+        }
+        if (job.status === "failed") {
+            const eventTime = Date.parse(job.updated_at);
+            if (Number.isNaN(eventTime) || eventTime < errorCutoff)
+                continue;
+            if (!lastErrorTs || job.updated_at > lastErrorTs) {
+                lastErrorTs = job.updated_at;
+                lastErrorReason = classifyJobError(job);
+            }
+        }
+        // cancelled / interrupted: ignore — neither a successful import
+        // nor a real error the user can act on. A retry will be either
+        // queued (counted as pending) or completed/failed (counted above).
+    }
+    return {
+        last_import_at: lastImportTs,
+        last_error_at: lastErrorTs,
+        last_error_reason: lastErrorReason,
+        pending,
+    };
+}
+/**
+ * Best-effort short label for a failed inbox job's error. The queue
+ * stores the raw error message (`job.error`); we collapse it into a
+ * compact class keyword by substring match against the parser errors
+ * we know about, then fall back to a truncated form of the original
+ * message. Lower-cased for stability under capitalization drift.
+ *
+ * Exported for tests.
+ */
+export function classifyJobError(job) {
+    const raw = (job.error ?? "").trim();
+    if (!raw)
+        return "unknown";
+    const lower = raw.toLowerCase();
+    if (lower.includes("zip slip") || lower.includes("path traversal")) {
+        return "unsafe_archive";
+    }
+    if (lower.includes("too large") || lower.includes("max size")) {
+        return "size_limit";
+    }
+    if (lower.includes("unsupported source"))
+        return "unsupported_source";
+    if (lower.includes("no conversations"))
+        return "empty_export";
+    if (lower.includes("invalid json") || lower.includes("unexpected token")) {
+        return "invalid_json";
+    }
+    // ADM-ZIP throws strings like "ADM-ZIP: Invalid or unsupported zip
+    // format" when adm-zip can't open the archive at all (corrupt header,
+    // truncated CD). Distinct from `unsafe_archive` (security-blocked) —
+    // this is "the ZIP itself is broken before we can even look inside."
+    if (lower.includes("adm-zip") || lower.includes("invalid or unsupported zip")) {
+        return "invalid_archive";
+    }
+    if (lower.includes("parser"))
+        return "parser_error";
+    // Fallback: first ≤40 chars of the raw message, single-lined.
+    const snippet = raw.replace(/\s+/g, " ").slice(0, 40);
+    return snippet || "unknown";
+}
 export function registerFriendStatusRoute(server, deps) {
     server.get("/status/friend", async (_request, reply) => {
         return reply.send(buildFriendStatusPayload(deps));

package/dist/src/server/routes/friend-status.js.map

@@ -1 +1 @@
-{"version":3,"file":"friend-status.js","sourceRoot":"","sources":["../../../../src/server/routes/friend-status.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,yBAAyB,GAE1B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AA2D1E,MAAM,UAAU,wBAAwB,CACtC,IAAsB;IAEtB,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;IAEhD,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,yBAAyB,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,EAAE,CAAC;IAC3D,CAAC;IACD,MAAM,IAAI,GAAgC,OAAO,CAAC,QAAQ,CAAC;IAE3D,IAAI,aAAa,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IAC5D,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAC1D,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,aAAa,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC;YACpC,aAAa,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC;YACtC,aAAa,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,sBAAsB,CAAC,EAAE,CAAC;QACpE,IAAI,OAAO,IAAI,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,SAAS,GAAG,WAAW,CAAC,EAAE,CAAC;YACjE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;QAClC,CAAC;IACH,CAAC;IAED,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,YAAY,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,YAAY,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,OAAO;QACL,KAAK;QACL,MAAM,EAAE;YACN,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;YAChE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI;YAC7B,kBAAkB,EAChB,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;SACxD;QACD,MAAM,EAAE;YACN,aAAa,EAAE,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;YACtE,aAAa,EAAE,WAAW;SAC3B;QACD,KAAK,EAAE;YACL,iBAAiB,EAAE,IAAI,EAAE,SAAS,IAAI,IAAI;YAC1C,iBAAiB,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI;SACnD;QACD,OAAO,EAAE;YACP,WAAW,EAAE,IAAI,EAAE,SAAS,IAAI,IAAI;YACpC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;YACtC,UAAU,EAAE,aAAa,CAAC,KAAK;YAC/B,WAAW,EAAE,aAAa,CAAC,MAAM;YACjC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC;YACrC,gBAAgB,EAAE,aAAa,CAAC,WAAW;SAC5C;QACD,QAAQ,EAAE,EAAE,aAAa,EAAE,YAAY,EAAE;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,MAAuB,EACvB,IAAsB;IAEtB,MAAM,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE;QACrD,OAAO,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"friend-status.js","sourceRoot":"","sources":["../../../../src/server/routes/friend-status.ts"],"names":[],"mappings":"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"}

package/dist/src/server/routes/mcp-usage.d.ts

@@ -2,10 +2,10 @@
  * GET /stats/mcp-usage — unauthenticated MCP tool-call telemetry.
  *
  * SwiftBar pulls this on each tick. Returns per-window call counts +
- * a coarse `tokens_saved` estimate derived from a fixed per-tool table.
- * Mirrors the auth posture of `/health` and `/version` (no token
- * required) — the response carries only call counts and tool names,
- * never user content.
+ * `context_tokens_delivered_estimate` (≈ ceil(returned-text bytes / 4)
+ * over context-hit calls). Mirrors the auth posture of `/health` and
+ * `/version` (no token required) — the response carries only call
+ * counts and tool names, never user content.
  */
 import type { FastifyInstance } from "fastify";
 import type { ObservabilityDeps } from "../../observability/coverage.js";

package/dist/src/server/routes/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/server/routes/search.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAoFxD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,iBAAiB,GAAG,SAAS,EACxC,cAAc,CAAC,EAAE,iBAAiB,EAClC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,GAChC,IAAI,CA+LN"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/server/routes/search.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AA+FxD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,iBAAiB,GAAG,SAAS,EACxC,cAAc,CAAC,EAAE,iBAAiB,EAClC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,GAChC,IAAI,CA4TN"}

package/dist/src/server/routes/search.js

@@ -11,7 +11,7 @@ import { rerank } from "../../retrieval/reranker.js";
 import { lexicalSearchTables } from "../../retrieval/lexical.js";
 import { getTable, TABLE_NAMES } from "../../storage/tables.js";
 import { resolveCwdRoot, escapeLike } from "../../retrieval/cwd.js";
-import { buildCompactHit, buildCompactHitFromRow, fetchRawRowsForRanked, fetchRowByIdForTier, } from "../../retrieval/compact.js";
+import { buildCompactHit, buildCompactHitFromRow, fetchRawRowsForRanked, fetchRowByIdForTier, fetchRowsByIdAcrossTables, fetchRowsByIdInTables, tablesForTier, } from "../../retrieval/compact.js";
 const COLD_TIER_THRESHOLD = 0.4;
 const TIER_VALUES = ["hot", "cold", "digest", "document", "structured_doc"];
 /**
@@ -19,12 +19,20 @@ const TIER_VALUES = ["hot", "cold", "digest", "document", "structured_doc"];
  *
  * Two modes:
  * - Retrieval mode: `query` is required. Runs hybrid search + rerank.
- * - Expansion mode: `detail="full"` + `id` + `tier` — skips retrieval
- *   entirely and fetches the row by id from the table inferred from `tier`.
- *   This makes compact-hit `expand` pointers round-trippable from the
- *   payload alone, without the caller needing to re-run the search.
+ * - Exact-ID mode: `detail` of `"full"` or `"middle"` + `id` — skips
+ *   retrieval entirely and fetches the row by id. Trust contract: this
+ *   never silently falls back to ranked search. With `tier` (and optionally
+ *   `source_table`) the lookup is scoped to the backing table(s); without
+ *   `tier`, the route scans every supported table and returns either the
+ *   unique match, an explicit `id_not_found`, or an explicit `ambiguous_id`
+ *   error. `detail="middle"` returns the same exact-row response shape with
+ *   a bounded head+tail excerpt instead of the full body — preserves the
+ *   evidence bookends a fact-checker needs while bounding context spend.
  *
- * `query` becomes optional in expansion mode.
+ * `query` becomes optional in exact-ID mode. If both `query` and `id` are
+ * provided with a non-"summary" detail, the id wins — ranked retrieval is
+ * never run as a fallback. This is by design after the REX where a caller
+ * passed `query + id + detail="full"` and got a wrong-body response.
  */
 const SearchRequestSchema = z
     .object({
@@ -36,20 +44,20 @@ const SearchRequestSchema = z
     since: z.string().datetime().optional(),
     top_k: z.number().int().positive().default(10),
     cwd: z.string().optional(),
-    detail: z.enum(["summary", "full"]).default("summary"),
-    /** With detail="full", expand a single hit by id (bypasses ranking). */
+    detail: z.enum(["summary", "middle", "full"]).default("summary"),
+    /** With detail="middle"|"full", expand a single hit by id (bypasses ranking). */
     id: z.string().optional(),
-    /** Tier of the id being expanded. Required in expansion mode. */
+    /** Tier of the id being expanded. Optional — narrows the lookup. */
     tier: z.enum(TIER_VALUES).optional(),
     /**
      * Authoritative backing table for the id. When provided, disambiguates
      * rows that share an id across the cloud/local structured-doc tables.
-     * Optional — absent requests fall back to tier-based first-match lookup.
+     * Optional — absent requests scan every supported table.
      */
     source_table: z.enum(TABLE_NAMES).optional(),
 })
-    .refine((d) => !!d.query || (d.detail === "full" && !!d.id && !!d.tier), {
-    message: "Either `query` is required, or provide `id`+`tier`+`detail=\"full\"` for expansion.",
+    .refine((d) => !!d.query || ((d.detail === "full" || d.detail === "middle") && !!d.id), {
+    message: 'Either `query` is required, or provide `id` + `detail="full"` (or `detail="middle"`) for direct lookup.',
 })
     .refine((d) => {
     // If both tier and source_table are provided in expansion mode, the
@@ -81,21 +89,133 @@ export function registerSearchRoute(server, embedding, localEmbedding, sourceDir
         }
         const { query, scope, client, since, top_k, cwd, detail, id: expandId, tier: expandTier, source_table: expandSourceTable, } = parsed.data;
         const searchScope = scope;
-        // --- Expansion mode: direct id-based fetch, bypass retrieval/ranking ---
-        // Triggered when caller follows a compact hit's `expand` pointer
-        // verbatim: `{id, tier, source_table, detail: "full"}`. Guarantees the
-        // requested row is returned even if it would rank below `top_k` in search,
-        // and honors `source_table` to disambiguate cloud vs. local structured docs.
-        if (detail === "full" && expandId && expandTier) {
-            const fetched = await fetchRowByIdForTier(expandId, expandTier, expandSourceTable);
-            const hit = fetched
-                ? buildCompactHitFromRow(fetched.row, fetched.sourceTable, {
+        // --- Exact-ID mode: direct id-based fetch, never falls back to ranking ---
+        // Triggered whenever `detail="full"` + `id` are provided. The trust
+        // contract is strict: return the exact row, or fail loudly. Four sub-cases:
+        //   1. `tier` + `source_table` — direct fetch from that table. Powers the
+        //      round-trippable `expand` pointers carried by every compact hit
+        //      (which always include `source_table`).
+        //   2. `tier` without `source_table` — scan the tier's candidate tables;
+        //      the result must be unique. Multiple matches → 409 `ambiguous_id`
+        //      (matters for `document` / `structured_doc`, which map to both the
+        //      cloud and local structured-docs tables). Zero → 404 `id_not_found`.
+        //   3. `source_table` without `tier` — direct fetch from that table.
+        //   4. Neither `tier` nor `source_table` — scan every supported table.
+        //      Exactly one match returns the row; zero → 404 `id_not_found`;
+        //      multiple → 409 `ambiguous_id` with the candidate tables.
+        if ((detail === "full" || detail === "middle") && expandId) {
+            if (expandTier) {
+                // With an explicit `source_table`, the lookup is already scoped to
+                // one table — first-match is unambiguous. Without one, fall through
+                // to a multi-table scan so a tier that maps to multiple backing
+                // tables (document / structured_doc → cloud + local) gets the same
+                // ambiguity guarantee as the bare-id path. We never want to silently
+                // return the cloud row when a local row with the same id exists.
+                if (expandSourceTable) {
+                    const fetched = await fetchRowByIdForTier(expandId, expandTier, expandSourceTable);
+                    if (!fetched) {
+                        return reply.code(404).send({
+                            error: "id_not_found",
+                            id: expandId,
+                            tier: expandTier,
+                            source_table: expandSourceTable,
+                        });
+                    }
+                    const hit = buildCompactHitFromRow(fetched.row, fetched.sourceTable, {
+                        ...(query ? { query } : {}),
+                        expandRoute: "/search",
+                        detail,
+                    });
+                    return {
+                        results: [hit],
+                        degraded: false,
+                        cwd_matched: false,
+                        cwd_scope_applied_to: [],
+                    };
+                }
+                const tierTables = tablesForTier(expandTier);
+                const tierMatches = await fetchRowsByIdInTables(expandId, tierTables);
+                if (tierMatches.length === 0) {
+                    return reply.code(404).send({
+                        error: "id_not_found",
+                        id: expandId,
+                        tier: expandTier,
+                    });
+                }
+                if (tierMatches.length > 1) {
+                    return reply.code(409).send({
+                        error: "ambiguous_id",
+                        id: expandId,
+                        tier: expandTier,
+                        message: "Multiple rows share this id across this tier's backing tables. Pass `source_table` to disambiguate.",
+                        candidates: tierMatches.map((m) => ({ source_table: m.sourceTable })),
+                    });
+                }
+                const onlyTierMatch = tierMatches[0];
+                const hit = buildCompactHitFromRow(onlyTierMatch.row, onlyTierMatch.sourceTable, {
+                    ...(query ? { query } : {}),
+                    expandRoute: "/search",
+                    detail,
+                });
+                return {
+                    results: [hit],
+                    degraded: false,
+                    cwd_matched: false,
+                    cwd_scope_applied_to: [],
+                };
+            }
+            if (expandSourceTable) {
+                // Direct table fetch — no tier needed when caller already named the
+                // authoritative table.
+                const escaped = expandId.replace(/'/g, "''");
+                const rows = (await getTable(expandSourceTable)
+                    .query()
+                    .where(`id = '${escaped}'`)
+                    .limit(1)
+                    .toArray());
+                if (rows.length === 0) {
+                    return reply.code(404).send({
+                        error: "id_not_found",
+                        id: expandId,
+                        source_table: expandSourceTable,
+                    });
+                }
+                const hit = buildCompactHitFromRow(rows[0], expandSourceTable, {
                     ...(query ? { query } : {}),
                     expandRoute: "/search",
-                })
-                : null;
+                    detail,
+                });
+                return {
+                    results: [hit],
+                    degraded: false,
+                    cwd_matched: false,
+                    cwd_scope_applied_to: [],
+                };
+            }
+            // No tier, no source_table — scan every table. Must be uniquely-resolvable.
+            const matches = await fetchRowsByIdAcrossTables(expandId);
+            if (matches.length === 0) {
+                return reply.code(404).send({
+                    error: "id_not_found",
+                    id: expandId,
+                });
+            }
+            if (matches.length > 1) {
+                return reply.code(409).send({
+                    error: "ambiguous_id",
+                    id: expandId,
+                    message: "Multiple rows share this id across tables. Pass `source_table` (or `tier`) to disambiguate.",
+                    candidates: matches.map((m) => ({ source_table: m.sourceTable })),
+                });
+            }
+            const only = matches[0];
+            const hit = buildCompactHitFromRow(only.row, only.sourceTable, {
+                ...(query ? { query } : {}),
+                expandRoute: "/search",
+                detail,
+            });
             return {
-                results: hit ? [hit] : [],
+                results: [hit],
                 degraded: false,
                 cwd_matched: false,
                 cwd_scope_applied_to: [],