onadit 0.0.1 → 1.0.0

package/dist/src/retrieval/git-state.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Six-state classification, ordered by precedence in the partitioner:
+ *
+ *   deleted    — git knew about the file but it's gone from disk now.
+ *                Strongest discount signal: the asker cannot read it.
+ *   untracked  — file exists on disk but git doesn't know about it.
+ *                The v1 generalization of v0's LAUNCH.md hack: a doc
+ *                that's not under version control is not canonical
+ *                project state.
+ *   modified   — tracked, but worktree differs from HEAD/index. Treated
+ *                as live: the operator is actively editing it.
+ *   newer_on_disk
+ *              — tracked, unmodified vs HEAD, but the worktree mtime
+ *                is newer than the indexed_at timestamp. Means: the
+ *                LanceDB row is stale relative to the file. Still live,
+ *                but the retrieved snippet may lag.
+ *   tracked    — tracked, unmodified, index in sync. Canonical.
+ *   unknown    — couldn't determine (path outside repo, git
+ *                unavailable, etc). Partitioner falls back to v0
+ *                path-pattern heuristics.
+ */
+export type GitState = "tracked" | "untracked" | "modified" | "deleted" | "newer_on_disk" | "unknown";
+export interface GitStateInput {
+    sourcePath: string;
+    /** ISO timestamp of when the row was indexed. Used for `newer_on_disk`. */
+    indexedAt?: string | undefined;
+}
+export interface ProbeOptions {
+    /**
+     * Any directory inside the git repo whose state we want to probe.
+     * Need NOT be the repo root — `probeGitStates` resolves the actual
+     * top-level via `git rev-parse --show-toplevel` and classifies all
+     * paths against that root. This matters because MCP `cwd` is the
+     * agent's working directory, often a subdirectory (e.g. `src/` or
+     * `tests/`); without top-level resolution, root-level docs like
+     * `PROJECT_STATE.md` would fall outside `projectRoot` and get
+     * labeled `"unknown"`, defeating the v1 signal.
+     */
+    projectRoot: string;
+}
+/**
+ * Probe git state for a batch of source paths. Returns a Map keyed by
+ * the input `sourcePath` strings (verbatim — caller can do direct
+ * Map.get with the same string it passed in).
+ *
+ * Behavior contract:
+ *   - Empty input → empty map.
+ *   - Git unavailable / not a repo → every path mapped to "unknown".
+ *   - Path not under the resolved git top-level → "unknown" for that path.
+ *   - Otherwise classified per {@link GitState} precedence.
+ */
+export declare function probeGitStates(inputs: readonly GitStateInput[], opts: ProbeOptions): Map<string, GitState>;
+/**
+ * Resolve the git top-level for `cwd` via `git rev-parse --show-toplevel`,
+ * so callers can locate repo-root files (PROJECT_STATE.md, TODO.md) even when
+ * the agent's cwd is a subdirectory (the same problem {@link probeGitStates}
+ * solves for path classification). Returns the resolved absolute repo root, or
+ * the resolved `cwd` when git is unavailable / `cwd` is not a repo — a safe
+ * fallback that simply looks in `cwd`.
+ */
+export declare function resolveRepoRoot(cwd: string): string;
+//# sourceMappingURL=git-state.d.ts.map

package/dist/src/retrieval/git-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-state.d.ts","sourceRoot":"","sources":["../../../src/retrieval/git-state.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,WAAW,GACX,UAAU,GACV,SAAS,GACT,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,YAAY,GACjB,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CA+BvB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQnD"}

package/dist/src/retrieval/git-state.js

@@ -0,0 +1,192 @@
+/**
+ * Current Truth Mode v1 — git-state probe for file-backed evidence.
+ *
+ * Given a batch of (source_path, indexed_at) inputs and a project root,
+ * classifies each path into one of six git states. The classifier is
+ * the load-bearing signal that v0's path-pattern hack
+ * (hard-coding `LAUNCH.md` into the snapshot list) was a stand-in for:
+ * "this file isn't tracked in git, so it can't be canonical state."
+ *
+ * Design choices:
+ *
+ *   - One git invocation pair per call, regardless of input size
+ *     (`git status --porcelain=v1 -uall` + `git ls-files`), so cost
+ *     scales with repo size, not with the number of evidence cards.
+ *   - Synchronous `execFileSync` — buildContextPack is already
+ *     latency-tolerant (sub-second budget), git status on this repo
+ *     comes back in single-digit ms, and the alternative (async +
+ *     plumb through 4 await sites) buys nothing here.
+ *   - Paths outside `projectRoot` return `"unknown"` rather than
+ *     probing their own repos. v1 is single-repo scoped; cross-repo
+ *     awareness (e.g. /Users/clement/clients/*) is a v2 question.
+ *   - If git or the repo is unavailable, every input returns
+ *     `"unknown"` and the partitioner falls back to v0 behavior. We
+ *     never throw — git-state is an advisory signal, not a contract.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+/**
+ * Probe git state for a batch of source paths. Returns a Map keyed by
+ * the input `sourcePath` strings (verbatim — caller can do direct
+ * Map.get with the same string it passed in).
+ *
+ * Behavior contract:
+ *   - Empty input → empty map.
+ *   - Git unavailable / not a repo → every path mapped to "unknown".
+ *   - Path not under the resolved git top-level → "unknown" for that path.
+ *   - Otherwise classified per {@link GitState} precedence.
+ */
+export function probeGitStates(inputs, opts) {
+    const out = new Map();
+    if (inputs.length === 0)
+        return out;
+    const cwd = path.resolve(opts.projectRoot);
+    // Resolve the actual repo top-level. `opts.projectRoot` is the
+    // agent's cwd, which may sit deep inside the repo — without this
+    // resolution, root-level docs would be misclassified as "unknown"
+    // because they're not lexically under `cwd`.
+    let root;
+    let statusByRel;
+    let trackedSet;
+    try {
+        root = path.resolve(runGit(cwd, ["rev-parse", "--show-toplevel"]).trim());
+        if (!root)
+            throw new Error("empty toplevel");
+        statusByRel = parsePorcelain(runGit(root, ["status", "--porcelain=v1", "-uall"]));
+        trackedSet = new Set(runGit(root, ["ls-files"])
+            .split("\n")
+            .filter(Boolean));
+    }
+    catch {
+        for (const input of inputs)
+            out.set(input.sourcePath, "unknown");
+        return out;
+    }
+    for (const input of inputs) {
+        out.set(input.sourcePath, classifyOne(input, root, statusByRel, trackedSet));
+    }
+    return out;
+}
+/**
+ * Resolve the git top-level for `cwd` via `git rev-parse --show-toplevel`,
+ * so callers can locate repo-root files (PROJECT_STATE.md, TODO.md) even when
+ * the agent's cwd is a subdirectory (the same problem {@link probeGitStates}
+ * solves for path classification). Returns the resolved absolute repo root, or
+ * the resolved `cwd` when git is unavailable / `cwd` is not a repo — a safe
+ * fallback that simply looks in `cwd`.
+ */
+export function resolveRepoRoot(cwd) {
+    const base = path.resolve(cwd);
+    try {
+        const top = runGit(base, ["rev-parse", "--show-toplevel"]).trim();
+        return top ? path.resolve(top) : base;
+    }
+    catch {
+        return base;
+    }
+}
+function runGit(cwd, args) {
+    return execFileSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 16 * 1024 * 1024,
+    });
+}
+function classifyOne(input, root, statusByRel, trackedSet) {
+    // `git rev-parse --show-toplevel` returns a realpath'd path on macOS
+    // (the system /var → /private/var symlink in tmpdir is the obvious
+    // example, but the same divergence can happen with any symlinked
+    // ancestor). Resolve symlinks on the input side too so the
+    // startsWith / relative comparison doesn't reject a legitimate
+    // path just because of a symlinked prefix. realpath fails on a
+    // non-existent path — for deleted files, fall back to realpath'ing
+    // the parent dir (which still exists) and re-attaching the basename
+    // so the path lands under the canonical root.
+    const raw = path.resolve(input.sourcePath);
+    const abs = realpathSafe(raw);
+    if (abs !== root && !abs.startsWith(root + path.sep))
+        return "unknown";
+    const rel = path.relative(root, abs);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return "unknown";
+    const status = statusByRel.get(rel);
+    if (status !== undefined) {
+        if (status === "??")
+            return "untracked";
+        // Porcelain status is two chars: [index][worktree]. A "D" in either
+        // slot means deleted; we surface that as the strongest signal.
+        if (status[0] === "D" || status[1] === "D")
+            return "deleted";
+        return "modified";
+    }
+    if (!trackedSet.has(rel))
+        return "unknown";
+    // Tracked + clean in git. The worktree file should exist; if it
+    // doesn't, git's status output should have caught it — but be
+    // defensive in case of races (e.g., user just rm'd the file between
+    // the two git calls).
+    if (!existsSync(abs))
+        return "deleted";
+    if (input.indexedAt) {
+        const indexedMs = Date.parse(input.indexedAt);
+        if (!Number.isNaN(indexedMs)) {
+            try {
+                const mtimeMs = statSync(abs).mtimeMs;
+                // 1s grace to absorb filesystem mtime quantization and the
+                // small lag between indexer write and row's indexed_at stamp.
+                if (mtimeMs > indexedMs + 1000)
+                    return "newer_on_disk";
+            }
+            catch {
+                // ignore — fall through to "tracked"
+            }
+        }
+    }
+    return "tracked";
+}
+/**
+ * Parse `git status --porcelain=v1` output into rel-path → 2-char status code.
+ *
+ * Each line looks like `XY path` where X is index status and Y is
+ * worktree status (e.g. ` M`, `D `, `??`). Renames look like
+ * `R  old -> new`; v1 returns the new path so the asker's source_path
+ * (which is the current name on disk) matches.
+ */
+/**
+ * realpath that survives a missing file. Falls back to realpath'ing
+ * the parent directory and re-attaching the basename — covers the
+ * "tracked + deleted from worktree" classification path, where the
+ * file is gone but we still need its canonical path to land under
+ * the repo root.
+ */
+function realpathSafe(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        const dir = path.dirname(p);
+        const base = path.basename(p);
+        try {
+            return path.join(realpathSync(dir), base);
+        }
+        catch {
+            return p;
+        }
+    }
+}
+function parsePorcelain(out) {
+    const map = new Map();
+    for (const line of out.split("\n")) {
+        if (line.length < 4)
+            continue;
+        const code = line.slice(0, 2);
+        const rest = line.slice(3);
+        // Rename / copy: "old -> new" — index by the new (current) name.
+        const arrow = rest.indexOf(" -> ");
+        const p = arrow >= 0 ? rest.slice(arrow + 4) : rest;
+        map.set(p, code);
+    }
+    return map;
+}
+//# sourceMappingURL=git-state.js.map

package/dist/src/retrieval/git-state.js.map

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

package/dist/src/retrieval/group-by-parent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Post-rerank collapse of chunk siblings.
+ *
+ * When a long document/conversation is indexed as multiple chunk rows, several
+ * chunks of the SAME source can rank in the deep pool and would otherwise flood
+ * top-k. This pass keeps the best-scoring chunk per parent as the representative
+ * and drops the siblings, recording how many rows the parent contributed so the
+ * UI can render "+N more sections".
+ *
+ * Flag-off / legacy safety: collapse is driven ENTIRELY by `parentKeyOf`, which
+ * returns `null` for any row without an explicit chunk marker (see
+ * `parentKeyForRow` in `../ingestion/chunk-meta.ts`). Rows that merely share a
+ * `source_path` or `idempotency_key` get `null` and are never grouped — so with
+ * `RIFT_CHUNKING` off (no marked rows exist) this is provably a no-op.
+ *
+ * Input is assumed score-descending (reranker output), so the first row seen for
+ * a parent is its best; overall order is otherwise preserved.
+ */
+import type { RankedResult } from "./reranker.js";
+/**
+ * Composite key that preserves table identity. The SAME row id can exist in two
+ * source tables (notably `structured_docs` vs `structured_docs_local`, but also
+ * hot/cold conversation tiers), so any map keyed by bare `id` would collide and
+ * could silently merge a cloud row with a local one — the exact cross-table
+ * collapse the table-namespaced parent key is meant to prevent. Always key
+ * parent-key lookups, sibling counts, AND raw-row maps by `(source_table, id)`.
+ */
+export declare function rankedKey(r: Pick<RankedResult, "source_table" | "id">): string;
+export interface GroupByParentResult {
+    /** Collapsed list: best chunk per parent, siblings removed, order preserved. */
+    ranked: RankedResult[];
+    /** {@link rankedKey} of the representative → number of rows in its parent
+     *  group (≥ 2 only when grouped). Keyed by `(source_table, id)`, NOT bare id,
+     *  so a cross-table id clash can never misattribute a sibling count. */
+    siblingCountById: Map<string, number>;
+}
+export declare function groupByParent(ranked: RankedResult[], parentKeyOf: (r: RankedResult) => string | null): GroupByParentResult;
+//# sourceMappingURL=group-by-parent.d.ts.map

package/dist/src/retrieval/group-by-parent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by-parent.d.ts","sourceRoot":"","sources":["../../../src/retrieval/group-by-parent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC,GAAG,MAAM,CAK9E;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;4EAEwE;IACxE,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,YAAY,EAAE,EACtB,WAAW,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,MAAM,GAAG,IAAI,GAC9C,mBAAmB,CAyBrB"}

package/dist/src/retrieval/group-by-parent.js

@@ -0,0 +1,40 @@
+/**
+ * Composite key that preserves table identity. The SAME row id can exist in two
+ * source tables (notably `structured_docs` vs `structured_docs_local`, but also
+ * hot/cold conversation tiers), so any map keyed by bare `id` would collide and
+ * could silently merge a cloud row with a local one — the exact cross-table
+ * collapse the table-namespaced parent key is meant to prevent. Always key
+ * parent-key lookups, sibling counts, AND raw-row maps by `(source_table, id)`.
+ */
+export function rankedKey(r) {
+    // Space separator: a TableName is a fixed [a-z_] enum and a row id is
+    // charset-guarded ([A-Za-z0-9_:.-]) — neither can contain a space, so the
+    // join is unambiguous. Plain printable text, never a literal control byte.
+    return `${r.source_table} ${r.id}`;
+}
+export function groupByParent(ranked, parentKeyOf) {
+    const kept = [];
+    const siblingCountById = new Map();
+    // parent key → representative result (the first/best row for that parent)
+    const repByKey = new Map();
+    for (const r of ranked) {
+        const key = parentKeyOf(r);
+        if (key === null) {
+            kept.push(r); // unmarked row: its own singleton, never collapsed
+            continue;
+        }
+        const rep = repByKey.get(key);
+        if (rep === undefined) {
+            repByKey.set(key, r);
+            siblingCountById.set(rankedKey(r), 1);
+            kept.push(r);
+        }
+        else {
+            // A lower-ranked sibling of an already-kept parent — drop, bump count.
+            const repKey = rankedKey(rep);
+            siblingCountById.set(repKey, (siblingCountById.get(repKey) ?? 1) + 1);
+        }
+    }
+    return { ranked: kept, siblingCountById };
+}
+//# sourceMappingURL=group-by-parent.js.map

package/dist/src/retrieval/group-by-parent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-by-parent.js","sourceRoot":"","sources":["../../../src/retrieval/group-by-parent.ts"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,CAA4C;IACpE,sEAAsE;IACtE,0EAA0E;IAC1E,2EAA2E;IAC3E,OAAO,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;AACrC,CAAC;AAWD,MAAM,UAAU,aAAa,CAC3B,MAAsB,EACtB,WAA+C;IAE/C,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACnD,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEjD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,mDAAmD;YACjE,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACrB,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;YAC9B,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;AAC5C,CAAC"}

package/dist/src/retrieval/hybrid.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Hybrid retrieval: union vector + lexical candidate sets.
+ *
+ * Deduplicates by id, preserves source-path info to know whether
+ * a result came from vector, lexical, or both.
+ */
+import type { EmbeddingProvider } from "../providers/types.js";
+import type { SearchOptions } from "./vector.js";
+import type { TableName } from "../storage/tables.js";
+export type RetrievalMethod = "vector" | "lexical" | "hybrid";
+export interface HybridResult {
+    id: string;
+    content: string;
+    /** Raw similarity score from vector search (0-1), used by reranker as S_sim. */
+    raw_sim: number;
+    /** Raw BM25 score from lexical search (unnormalized). */
+    raw_bm25: number;
+    source_table: TableName;
+    retrieval_method: RetrievalMethod;
+    indexed_at?: string;
+    quality?: string;
+}
+export interface HybridOptions extends SearchOptions {
+    /** When true, skip vector search entirely (degraded mode). */
+    skipVector?: boolean;
+    /**
+     * Longest time to wait for the query embedding before answering with
+     * keyword results alone. Defaults to {@link EMBED_WAIT_MS}.
+     */
+    embedWaitMs?: number;
+}
+/**
+ * Interactive wait for a query embedding. Fresh Voyage embeds measured
+ * p50 225 ms, p95 241 ms, max 352 ms (n=40, 2026-09-24); cached ones are
+ * disk reads. 1.5 s leaves normal fresh queries untouched and only cuts off
+ * retry/backoff storms, which otherwise hold a search for 10 s or more. At
+ * the deadline the query's request is aborted (HTTP call and retry sleeps),
+ * unless another caller still waits on the same text — a save sharing it
+ * keeps it alive.
+ */
+export declare const EMBED_WAIT_MS = 1500;
+export declare class EmbeddingWaitExceeded extends Error {
+    readonly waitMs: number;
+    constructor(waitMs: number);
+}
+/**
+ * Wrap a provider so `embed` rejects after `waitMs` and cancels the request
+ * it abandoned. A caller's own signal still applies.
+ */
+export declare function boundedEmbedding(embedding: EmbeddingProvider, waitMs: number): EmbeddingProvider;
+/**
+ * Share one embedding per distinct text across the searches of a single
+ * request (the context pack runs a conversation lane and a document lane).
+ * The shared request is cancelled only when every lane waiting on it gave up.
+ */
+export declare function sharedEmbedding(embedding: EmbeddingProvider): EmbeddingProvider;
+/**
+ * Run hybrid retrieval: vector + lexical, deduplicate, tag retrieval method.
+ *
+ * Does NOT rerank — returns raw candidates for the reranker.
+ * Fetches more candidates than top_k to give the reranker headroom.
+ * Vector and keyword retrieval run concurrently; if the query embedding is
+ * slow or fails, keyword results still return, flagged `degraded` with a
+ * reason that says semantic retrieval did not run (a partial search, not
+ * proof that nothing relevant exists).
+ *
+ * With no embedding provider (no key: search by meaning is off), only the
+ * keyword lane runs. That is the intended no-key mode, so it is not degraded.
+ */
+export declare function hybridSearch(query: string, embedding: EmbeddingProvider | undefined, options: HybridOptions): Promise<{
+    candidates: HybridResult[];
+    degraded: boolean;
+    degraded_reason?: string;
+}>;
+//# sourceMappingURL=hybrid.d.ts.map

package/dist/src/retrieval/hybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.d.ts","sourceRoot":"","sources":["../../../src/retrieval/hybrid.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,KAAK,EAAgB,aAAa,EAAkB,MAAM,aAAa,CAAC;AAG/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,CAAC;IACxB,gBAAgB,EAAE,eAAe,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,OAAQ,CAAC;AAEnC,qBAAa,qBAAsB,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAgBhG;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,iBAAiB,GAAG,iBAAiB,CAsB/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,GAAG,SAAS,EACxC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,UAAU,EAAE,YAAY,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6EtF"}

package/dist/src/retrieval/hybrid.js

@@ -0,0 +1,151 @@
+import { joinShared } from "../providers/shared-request.js";
+import { vectorSearch } from "./vector.js";
+import { lexicalSearch } from "./lexical.js";
+/**
+ * Interactive wait for a query embedding. Fresh Voyage embeds measured
+ * p50 225 ms, p95 241 ms, max 352 ms (n=40, 2026-09-24); cached ones are
+ * disk reads. 1.5 s leaves normal fresh queries untouched and only cuts off
+ * retry/backoff storms, which otherwise hold a search for 10 s or more. At
+ * the deadline the query's request is aborted (HTTP call and retry sleeps),
+ * unless another caller still waits on the same text — a save sharing it
+ * keeps it alive.
+ */
+export const EMBED_WAIT_MS = 1_500;
+export class EmbeddingWaitExceeded extends Error {
+    waitMs;
+    constructor(waitMs) {
+        super(`query embedding exceeded ${waitMs} ms`);
+        this.waitMs = waitMs;
+        this.name = "EmbeddingWaitExceeded";
+    }
+}
+/**
+ * Wrap a provider so `embed` rejects after `waitMs` and cancels the request
+ * it abandoned. A caller's own signal still applies.
+ */
+export function boundedEmbedding(embedding, waitMs) {
+    return {
+        name: embedding.name,
+        model: embedding.model,
+        embedBatch: (texts) => embedding.embedBatch(texts),
+        embed: (text, opts = {}) => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new EmbeddingWaitExceeded(waitMs)), waitMs);
+            const signal = opts.signal ? AbortSignal.any([opts.signal, controller.signal]) : controller.signal;
+            // Race too: a provider that ignores the signal must not hold the query.
+            const deadline = new Promise((_, reject) => {
+                signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+            });
+            return Promise.race([embedding.embed(text, { signal }), deadline]).finally(() => clearTimeout(timer));
+        },
+    };
+}
+/**
+ * Share one embedding per distinct text across the searches of a single
+ * request (the context pack runs a conversation lane and a document lane).
+ * The shared request is cancelled only when every lane waiting on it gave up.
+ */
+export function sharedEmbedding(embedding) {
+    const done = new Map();
+    const pending = new Map();
+    return {
+        name: embedding.name,
+        model: embedding.model,
+        embedBatch: (texts) => embedding.embedBatch(texts),
+        embed: (text, opts = {}) => {
+            const hit = done.get(text);
+            if (hit)
+                return Promise.resolve(hit);
+            return joinShared(pending, text, (signal) => embedding.embed(text, { signal }).then((v) => {
+                done.set(text, v);
+                return v;
+            }), opts.signal);
+        },
+    };
+}
+/**
+ * Run hybrid retrieval: vector + lexical, deduplicate, tag retrieval method.
+ *
+ * Does NOT rerank — returns raw candidates for the reranker.
+ * Fetches more candidates than top_k to give the reranker headroom.
+ * Vector and keyword retrieval run concurrently; if the query embedding is
+ * slow or fails, keyword results still return, flagged `degraded` with a
+ * reason that says semantic retrieval did not run (a partial search, not
+ * proof that nothing relevant exists).
+ *
+ * With no embedding provider (no key: search by meaning is off), only the
+ * keyword lane runs. That is the intended no-key mode, so it is not degraded.
+ */
+export async function hybridSearch(query, embedding, options) {
+    // Fetch 3x top_k from each path to give reranker headroom
+    const fetchK = Math.max(options.top_k * 3, 30);
+    let degraded = false;
+    let degradedReason;
+    const vectorP = options.skipVector || !embedding
+        ? Promise.resolve([])
+        : vectorSearch(query, boundedEmbedding(embedding, options.embedWaitMs ?? EMBED_WAIT_MS), {
+            ...options,
+            top_k: fetchK,
+        }).then((r) => r.results, (err) => {
+            degraded = true;
+            degradedReason =
+                err instanceof EmbeddingWaitExceeded
+                    ? `partial search: semantic retrieval skipped (${err.message}); keyword results only`
+                    : `vector search failed: ${err instanceof Error ? err.message : String(err)}`;
+            return [];
+        });
+    if (options.skipVector) {
+        degraded = true;
+        degradedReason = "vector search skipped (embedding unavailable)";
+    }
+    const [vectorResults, lexicalResults] = await Promise.all([
+        vectorP,
+        lexicalSearch(query, { ...options, top_k: fetchK }),
+    ]);
+    // Build lookup maps for tagging retrieval method and carrying BM25 scores
+    const vectorIds = new Set(vectorResults.map((r) => r.id));
+    const lexicalById = new Map(lexicalResults.map((r) => [r.id, r]));
+    // Merge and deduplicate — vector results take priority for raw_sim
+    const merged = new Map();
+    for (const r of vectorResults) {
+        const lexMatch = lexicalById.get(r.id);
+        const entry = {
+            id: r.id,
+            content: r.content,
+            raw_sim: r.score,
+            raw_bm25: lexMatch?.score ?? 0,
+            source_table: r.source_table,
+            retrieval_method: lexMatch ? "hybrid" : "vector",
+        };
+        if (r.indexed_at)
+            entry.indexed_at = r.indexed_at;
+        if (r.quality)
+            entry.quality = r.quality;
+        merged.set(r.id, entry);
+    }
+    for (const r of lexicalResults) {
+        if (!merged.has(r.id)) {
+            const entry = {
+                id: r.id,
+                content: r.content,
+                raw_sim: 0,
+                raw_bm25: r.score,
+                source_table: r.source_table,
+                retrieval_method: vectorIds.has(r.id) ? "hybrid" : "lexical",
+            };
+            if (r.indexed_at)
+                entry.indexed_at = r.indexed_at;
+            if (r.quality)
+                entry.quality = r.quality;
+            merged.set(r.id, entry);
+        }
+    }
+    const result = {
+        candidates: Array.from(merged.values()),
+        degraded,
+    };
+    if (degradedReason)
+        result.degraded_reason = degradedReason;
+    return result;
+}
+//# sourceMappingURL=hybrid.js.map

package/dist/src/retrieval/hybrid.js.map

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

package/dist/src/retrieval/lexical.d.ts

@@ -0,0 +1,33 @@
+import type { TableName } from "../storage/tables.js";
+import type { SearchScope, SearchOptions, SearchResult } from "./vector.js";
+export interface LexicalSearchOptions extends SearchOptions {
+    /**
+     * Scan fallback only: maximum rows to read per table. Unset = every
+     * matching row. Tests use it; retrieval must not, or it drops evidence.
+     */
+    scanLimit?: number;
+    /** Additional WHERE clauses appended to the query (for metadata filters). */
+    extraClauses?: string[];
+}
+/**
+ * Run BM25 lexical search across tables for a text query.
+ * Returns results sorted by BM25 score descending, limited to top_k.
+ */
+export declare function lexicalSearch(query: string, options: LexicalSearchOptions): Promise<SearchResult[]>;
+/** Forget cached index readiness (tests, and after maintenance in-process). */
+export declare function resetLexicalIndexCache(): void;
+/**
+ * Tokenize text into lowercase terms.
+ * Unicode-aware: keeps accented characters (é, ç, à, ü, etc.) intact
+ * so that French and other Latin-script languages are searchable.
+ * Preserves proper nouns as additional tokens (uppercase sequences, camelCase).
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Run BM25 lexical search against specific tables (for cold-tier fallback).
+ */
+export declare function lexicalSearchTables(query: string, tables: TableName[], options: Pick<SearchOptions, "top_k" | "since" | "client" | "sourcePathPrefix"> & {
+    scope?: SearchScope;
+    extraClauses?: string[];
+}): Promise<SearchResult[]>;
+//# sourceMappingURL=lexical.d.ts.map

package/dist/src/retrieval/lexical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical.d.ts","sourceRoot":"","sources":["../../../src/retrieval/lexical.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY5E,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAwCD,+EAA+E;AAC/E,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAoOD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAsB/C;AA8DD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,kBAAkB,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,WAAW,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACjI,OAAO,CAAC,YAAY,EAAE,CAAC,CAqBzB"}