@omgbase/core 0.1.0

package/dist/src/search/embeddings.js

@@ -0,0 +1,263 @@
+import { sha256 } from "../core/hash.js";
+export class SemanticUnavailable extends Error {
+    code = "semantic_unavailable";
+}
+// Context prefix (05 §6): "{doc title} · {path} · {heading chain} · {type}\n{text}".
+export function contextPrefix(input) {
+    const chain = input.headingChain.join(" › ");
+    return `${input.docTitle} · ${input.path} · ${chain} · ${input.blockType}`;
+}
+export function embedInput(ctx, blockText) {
+    return `${ctx}\n${blockText}`;
+}
+export function ctxHashHex(ctx) {
+    return sha256(ctx).toString("hex");
+}
+// Default cache-miss chunk size for process(). Embedding is done in bounded
+// batches so a single request never grows unbounded — a large all-at-once
+// request can exceed the provider's per-request limits (stdio line size, HTTP
+// body cap) and fail silently. Callers may override via opts.batchSize; the
+// value only affects request chunking, never whether work happens.
+const DEFAULT_EMBED_BATCH = 32;
+// Rows < minTokens roll into their section aggregate rather than embedding
+// alone (05 §6). We surface this as a filter the caller applies.
+export function shouldEmbed(text, minTokens = 24) {
+    return text.trim().split(/\s+/).filter(Boolean).length >= minTokens;
+}
+// Coarse token estimate for budget decisions and pool weighting. We don't have
+// the provider's tokenizer (it's out-of-process), so approximate: word-piece
+// tokenizers emit slightly MORE tokens than whitespace words (subword splits,
+// punctuation), so scale words up by ~1.3 to stay on the safe side of the
+// budget rather than under-counting and letting a doc silently truncate.
+export function estimateTokens(text) {
+    const words = text.trim().split(/\s+/).filter(Boolean).length;
+    return Math.ceil(words * 1.3);
+}
+// Default whole-doc token budget when the provider doesn't report its own
+// maxInputTokens and config doesn't override. Deliberately conservative: beyond
+// a model's real input limit the input is truncated, at which point pooling the
+// block vectors represents the whole document better than an embedding of only
+// its first N tokens. Callers should prefer the provider's actual limit.
+export const DEFAULT_DOC_TOKEN_BUDGET = 512;
+// Tokens reserved for the doc-embedding header line so the budget check leaves
+// room for it (the header is prepended to the body — see buildDocEmbedTasks).
+const DOC_HEADER_MARGIN_TOKENS = 16;
+export class EmbeddingWorker {
+    store;
+    provider;
+    constructor(store, provider) {
+        this.store = store;
+        this.provider = provider;
+    }
+    get available() {
+        return this.provider !== null;
+    }
+    cacheKey(contentHashHex, ctxHex) {
+        return [Buffer.from(contentHashHex, "hex"), Buffer.from(ctxHex, "hex"), this.provider.model];
+    }
+    /** Look up a cached vector; null if absent (stale/missing). */
+    getCached(contentHashHex, ctx) {
+        if (!this.provider)
+            return null;
+        const ctxHex = ctxHashHex(ctx);
+        const row = this.store.db
+            .prepare("SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?")
+            .get(...this.cacheKey(contentHashHex, ctxHex));
+        if (!row)
+            return null;
+        return new Float32Array(row.vec.buffer, row.vec.byteOffset, row.vec.byteLength / 4);
+    }
+    /**
+     * Embed a batch (skipping cache hits) and persist. Throws if no provider.
+     * Cache misses are embedded in chunks of `batchSize` (default:
+     * DEFAULT_EMBED_BATCH); `onProgress` fires after each chunk is persisted so
+     * callers can show live progress on a long drain.
+     */
+    async process(tasks, opts = {}) {
+        if (!this.provider)
+            throw new SemanticUnavailable("no embedding provider configured");
+        const misses = [];
+        let cached = 0;
+        for (const t of tasks) {
+            if (this.getCached(t.contentHashHex, t.ctx))
+                cached++;
+            else
+                misses.push(t);
+        }
+        const insert = this.store.db.prepare("INSERT OR REPLACE INTO embeddings (content_hash, ctx_hash, model, dim, vec) VALUES (?, ?, ?, ?, ?)");
+        const batchSize = opts.batchSize && opts.batchSize > 0 ? opts.batchSize : DEFAULT_EMBED_BATCH;
+        let embedded = 0;
+        for (let start = 0; start < misses.length; start += batchSize) {
+            const chunk = misses.slice(start, start + batchSize);
+            const vectors = await this.provider.embed(chunk.map((t) => embedInput(t.ctx, t.text)));
+            this.store.write(() => {
+                chunk.forEach((t, i) => {
+                    const v = Float32Array.from(vectors[i]);
+                    insert.run(Buffer.from(t.contentHashHex, "hex"), Buffer.from(ctxHashHex(t.ctx), "hex"), this.provider.model, this.provider.dim, Buffer.from(v.buffer));
+                });
+            });
+            embedded += chunk.length;
+            opts.onProgress?.({ embedded, total: misses.length });
+        }
+        return { embedded, cached };
+    }
+    /** Embed a bare query string (no context prefix, 05 §6). */
+    async embedQuery(query) {
+        if (!this.provider)
+            throw new SemanticUnavailable("no embedding provider configured");
+        const [v] = await this.provider.embed([query]);
+        return Float32Array.from(v);
+    }
+    // ---- doc-grain embeddings (doc semantic retrieval) ------------------------
+    docTokenBudget() {
+        const provider = this.provider;
+        const budget = provider.maxInputTokens ?? DEFAULT_DOC_TOKEN_BUDGET;
+        return Math.max(1, budget - DOC_HEADER_MARGIN_TOKENS);
+    }
+    /** The freshness key for a doc task: sha256 of the whole-doc embed input. */
+    docInputHash(input) {
+        return sha256(input);
+    }
+    /** Look up a cached doc vector; null if absent or stale (input changed). */
+    getCachedDoc(docId, input) {
+        if (!this.provider)
+            return null;
+        const row = this.store.db
+            .prepare("SELECT input_hash, method, vec FROM doc_embeddings WHERE doc_id = ? AND model = ?")
+            .get(docId, this.provider.model);
+        if (!row)
+            return null;
+        if (!row.input_hash.equals(this.docInputHash(input)))
+            return null; // stale
+        return {
+            vec: new Float32Array(row.vec.buffer, row.vec.byteOffset, row.vec.byteLength / 4),
+            method: row.method,
+        };
+    }
+    /** Doc ids whose current input has no fresh cached vector — the doc queue. */
+    staleDocs(tasks) {
+        return tasks.filter((t) => !this.getCachedDoc(t.docId, t.input)).map((t) => t.docId);
+    }
+    /**
+     * Compute one vector per document and persist. Whole-doc path (primary):
+     * embed the doc's input directly. Pooled fallback: only when the input
+     * exceeds the provider's token budget, pool the doc's already-cached block
+     * vectors (token-weighted mean, L2-normalized) — zero embedding calls. Skips
+     * docs whose fresh vector is already cached. Throws if no provider.
+     */
+    async processDocs(tasks, opts = {}) {
+        if (!this.provider)
+            throw new SemanticUnavailable("no embedding provider configured");
+        const budget = this.docTokenBudget();
+        const misses = [];
+        let cached = 0;
+        for (const t of tasks) {
+            if (this.getCachedDoc(t.docId, t.input))
+                cached++;
+            else
+                misses.push(t);
+        }
+        // Split misses by strategy: within budget ⇒ whole-doc embed; over budget ⇒
+        // pooled fallback (no provider call).
+        const whole = misses.filter((t) => estimateTokens(t.input) <= budget);
+        const pooledTasks = misses.filter((t) => estimateTokens(t.input) > budget);
+        const insert = this.store.db.prepare("INSERT OR REPLACE INTO doc_embeddings (doc_id, model, input_hash, method, dim, vec) VALUES (?, ?, ?, ?, ?, ?)");
+        let embedded = 0;
+        let pooled = 0;
+        const batchSize = opts.batchSize && opts.batchSize > 0 ? opts.batchSize : DEFAULT_EMBED_BATCH;
+        for (let start = 0; start < whole.length; start += batchSize) {
+            const chunk = whole.slice(start, start + batchSize);
+            const vectors = await this.provider.embed(chunk.map((t) => t.input));
+            this.store.write(() => {
+                chunk.forEach((t, i) => {
+                    const v = Float32Array.from(vectors[i]);
+                    insert.run(t.docId, this.provider.model, this.docInputHash(t.input), "whole", this.provider.dim, Buffer.from(v.buffer));
+                });
+            });
+            embedded += chunk.length;
+            opts.onProgress?.({ embedded, total: whole.length });
+        }
+        // Pooled fallback: reuse block vectors already in the embeddings cache.
+        if (pooledTasks.length > 0) {
+            this.store.write(() => {
+                for (const t of pooledTasks) {
+                    const v = this.poolBlockVectors(t.blocks);
+                    if (!v)
+                        continue; // no cached block vectors yet — leave it queued
+                    insert.run(t.docId, this.provider.model, this.docInputHash(t.input), "pooled", this.provider.dim, Buffer.from(v.buffer));
+                    pooled++;
+                }
+            });
+        }
+        return { embedded, cached, pooled };
+    }
+    /**
+     * Token-weighted mean of a document's cached block vectors, L2-normalized.
+     * Pool = Σ(wᵢ·vᵢ)/Σ(wᵢ) with wᵢ = block token count, then normalized (pooling
+     * breaks unit norm; downstream cosine assumes unit vectors). Returns null when
+     * no referenced block has a cached vector yet.
+     */
+    poolBlockVectors(refs) {
+        const dim = this.provider.dim;
+        const acc = new Float64Array(dim);
+        let weightSum = 0;
+        for (const ref of refs) {
+            const v = this.getCached(ref.contentHashHex, ref.ctx);
+            if (!v)
+                continue;
+            const w = ref.tokens > 0 ? ref.tokens : 1;
+            const n = Math.min(dim, v.length);
+            for (let i = 0; i < n; i++)
+                acc[i] += w * v[i];
+            weightSum += w;
+        }
+        if (weightSum === 0)
+            return null;
+        let norm = 0;
+        for (let i = 0; i < dim; i++) {
+            acc[i] /= weightSum;
+            norm += acc[i] * acc[i];
+        }
+        norm = Math.sqrt(norm);
+        const out = new Float32Array(dim);
+        if (norm === 0)
+            return out; // all-zero pool (degenerate) — return zeros
+        for (let i = 0; i < dim; i++)
+            out[i] = acc[i] / norm;
+        return out;
+    }
+    /**
+     * Staleness: a heading rename changes descendants' context prefixes, so their
+     * cached vectors (keyed by the OLD ctx_hash) no longer match the current
+     * context. This returns the block ids in a doc whose current ctx has no cached
+     * vector — i.e. stale/pending — for the worker queue.
+     */
+    staleBlocks(tasks) {
+        return tasks.filter((t) => shouldEmbed(t.text) && !this.getCached(t.contentHashHex, t.ctx)).map((t) => t.blockId);
+    }
+    /**
+     * Vectors left behind by a previous model. The cache and both search paths key
+     * on model name, so after switching models the old model's rows are dead
+     * weight: never read, never overwritten (the new model writes under its own
+     * key). Reports how many block + doc vectors belong to a model OTHER than the
+     * current provider's, so callers can offer to reclaim the space.
+     */
+    foreignVectorCount() {
+        if (!this.provider)
+            return { blocks: 0, docs: 0 };
+        const blocks = this.store.db.prepare("SELECT count(*) c FROM embeddings WHERE model != ?").get(this.provider.model).c;
+        const docs = this.store.db.prepare("SELECT count(*) c FROM doc_embeddings WHERE model != ?").get(this.provider.model).c;
+        return { blocks, docs };
+    }
+    /** Delete every cached vector not produced by the current model. */
+    pruneForeignVectors() {
+        if (!this.provider)
+            return { blocks: 0, docs: 0 };
+        const model = this.provider.model;
+        return this.store.write((db) => ({
+            blocks: db.prepare("DELETE FROM embeddings WHERE model != ?").run(model).changes,
+            docs: db.prepare("DELETE FROM doc_embeddings WHERE model != ?").run(model).changes,
+        }));
+    }
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/src/search/external.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingProvider } from "./embeddings.js";
+import type { EmbeddingSettings } from "./provider.js";
+export interface ExternalProvider {
+    provider: EmbeddingProvider;
+    /** Release resources (kill a spawned process; no-op for HTTP). */
+    close(): Promise<void>;
+}
+/**
+ * Build an embedding provider from repo settings by connecting to an external
+ * command (stdio) or endpoint (HTTP). Throws on misconfiguration or handshake
+ * failure. Callers must call close() when done.
+ */
+export declare function createExternalProvider(settings: EmbeddingSettings): Promise<ExternalProvider | null>;

package/dist/src/search/external.js

@@ -0,0 +1,177 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+const isUrl = (s) => /^https?:\/\//i.test(s.trim());
+/**
+ * Build an embedding provider from repo settings by connecting to an external
+ * command (stdio) or endpoint (HTTP). Throws on misconfiguration or handshake
+ * failure. Callers must call close() when done.
+ */
+export async function createExternalProvider(settings) {
+    if (!settings.provider)
+        return null;
+    return isUrl(settings.provider) ? connectHttp(settings) : connectStdio(settings);
+}
+// ---- HTTP -------------------------------------------------------------------
+async function connectHttp(settings) {
+    const url = settings.provider;
+    let model = settings.model ?? "http";
+    let dim = settings.dim ?? 0;
+    let maxInputTokens = settings.maxInputTokens;
+    try {
+        const res = await fetch(url, { method: "GET" });
+        if (res.ok) {
+            const meta = (await res.json());
+            if (meta.model)
+                model = meta.model;
+            if (typeof meta.dim === "number")
+                dim = meta.dim;
+            if (typeof meta.maxInputTokens === "number")
+                maxInputTokens = meta.maxInputTokens;
+        }
+    }
+    catch {
+        // Metadata is best-effort; embed() failures below are the real signal.
+    }
+    const provider = {
+        model,
+        dim,
+        ...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ texts, model }),
+            });
+            if (!res.ok)
+                throw new Error(`embedding endpoint ${url} returned ${res.status}`);
+            const body = (await res.json());
+            if (!body.vectors)
+                throw new Error(`embedding endpoint ${url} returned no "vectors"`);
+            return body.vectors;
+        },
+    };
+    return { provider, close: async () => { } };
+}
+// ---- stdio ------------------------------------------------------------------
+async function connectStdio(settings) {
+    const parts = settings.provider.trim().split(/\s+/);
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    // stderr is PIPED (not inherited) and forwarded manually. Inheriting would give
+    // the child a duplicate of our own stderr fd; when our process is itself the
+    // child of a synchronous spawn (execFileSync/spawnSync, as the CLI tests use),
+    // that captured pipe only reaches EOF once every holder closes it — so a
+    // lingering embedder would keep the grandparent's execFileSync blocked forever
+    // even after we exit. A private pipe we own severs that coupling.
+    let child;
+    try {
+        child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+    }
+    catch (err) {
+        throw new Error(`embedding command '${settings.provider}' failed to spawn: ${err.message}`);
+    }
+    child.stderr.pipe(process.stderr);
+    // Don't let a still-running embedder keep our own event loop alive on exit.
+    child.unref();
+    const rl = createInterface({ input: child.stdout });
+    const lines = lineQueue(rl);
+    const spawnFailed = new Promise((_, reject) => {
+        child.once("error", (err) => reject(new Error(`embedding command '${cmd}' failed to spawn: ${err.message}`)));
+        child.once("exit", (code) => reject(new Error(`embedding command '${cmd}' exited early (code ${code ?? "?"})`)));
+    });
+    // The race consumers below observe this rejection; guard the reference itself
+    // so that a benign post-close `exit` doesn't surface as an unhandled rejection.
+    spawnFailed.catch(() => { });
+    // Handshake: first stdout line carries model + dim (+ optional maxInputTokens).
+    const handshakeRaw = await Promise.race([lines.next(), spawnFailed]);
+    let model = settings.model ?? "stdio";
+    let dim = settings.dim ?? 0;
+    let maxInputTokens = settings.maxInputTokens;
+    try {
+        const meta = JSON.parse(handshakeRaw);
+        if (meta.model)
+            model = meta.model;
+        if (typeof meta.dim === "number")
+            dim = meta.dim;
+        if (typeof meta.maxInputTokens === "number")
+            maxInputTokens = meta.maxInputTokens;
+    }
+    catch {
+        throw new Error(`embedding command '${cmd}' sent an invalid handshake line: ${handshakeRaw.slice(0, 120)}`);
+    }
+    let nextId = 1;
+    const provider = {
+        model,
+        dim,
+        ...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            const id = nextId++;
+            child.stdin.write(JSON.stringify({ id, texts }) + "\n");
+            // Read lines until the matching id arrives (tolerate interleaved ids).
+            for (;;) {
+                const raw = await Promise.race([lines.next(), spawnFailed]);
+                const resp = JSON.parse(raw);
+                if (resp.error)
+                    throw new Error(`embedder error: ${resp.error}`);
+                if (resp.id === id) {
+                    if (!resp.vectors)
+                        throw new Error("embedder response missing vectors");
+                    return resp.vectors;
+                }
+            }
+        },
+    };
+    const close = async () => {
+        rl.close();
+        child.stderr.unpipe(process.stderr);
+        try {
+            child.stdin.end();
+        }
+        catch { /* already closed */ }
+        if (child.exitCode !== null || child.signalCode !== null)
+            return; // already gone
+        // Reap the child before returning: SIGTERM, wait briefly, then SIGKILL. This
+        // keeps a wedged provider from outliving us and holding pipes open.
+        await new Promise((resolve) => {
+            const t = setTimeout(() => { try {
+                child.kill("SIGKILL");
+            }
+            catch { /* gone */ } resolve(); }, 2000);
+            child.once("exit", () => { clearTimeout(t); resolve(); });
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                clearTimeout(t);
+                resolve();
+            }
+        });
+    };
+    return { provider, close };
+}
+// A pull-based async line reader over a readline Interface: next() resolves with
+// the next line, buffering lines that arrive before they're requested.
+function lineQueue(rl) {
+    const buffered = [];
+    const waiters = [];
+    rl.on("line", (line) => {
+        const w = waiters.shift();
+        if (w)
+            w(line);
+        else
+            buffered.push(line);
+    });
+    return {
+        next() {
+            const b = buffered.shift();
+            if (b !== undefined)
+                return Promise.resolve(b);
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+    };
+}
+//# sourceMappingURL=external.js.map

package/dist/src/search/fts-query.d.ts

@@ -0,0 +1 @@
+export declare function sanitizeFtsQuery(input: string): string;

package/dist/src/search/fts-query.js

@@ -0,0 +1,64 @@
+// Sanitize a user-supplied search string into a safe FTS5 MATCH expression.
+//
+// FTS5 MATCH has its own query grammar: bareword operators (AND/OR/NOT/NEAR),
+// prefix `*`, column filters `:`, grouping `()`, and assorted punctuation. A
+// raw string like "guides/onboarding" is parsed as syntax and errors with
+// `fts5: syntax error near "/"`. Agents and humans expect a search box, not a
+// query DSL, so we compile their input down to a grammar-free form:
+//
+//   - text inside double quotes stays a phrase (adjacent-token match);
+//   - every other run of characters becomes one double-quoted token.
+//
+// Quoting each token makes FTS5 treat inner punctuation as token separators
+// (the unicode61 tokenizer already strips non-alphanumerics), so `/`, `-`, `:`
+// and friends can never reach the query parser. Space-separated tokens keep
+// FTS5's implicit-AND semantics; a trailing `*` on a bareword is preserved as a
+// prefix match. Returns "" when the input carries no searchable token, so
+// callers can skip the MATCH entirely rather than emit an empty-query error.
+function hasWordChar(s) {
+    return /[\p{L}\p{N}]/u.test(s);
+}
+// Wrap one raw token as a quoted FTS5 string, doubling embedded quotes.
+function quoteToken(token) {
+    return `"${token.replace(/"/g, '""')}"`;
+}
+export function sanitizeFtsQuery(input) {
+    const out = [];
+    let i = 0;
+    const n = input.length;
+    while (i < n) {
+        const c = input[i];
+        // Skip whitespace between tokens.
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        // A user-supplied phrase: capture until the closing quote (or end).
+        if (c === '"') {
+            i++;
+            let phrase = "";
+            while (i < n && input[i] !== '"') {
+                phrase += input[i];
+                i++;
+            }
+            if (i < n)
+                i++; // consume closing quote
+            if (hasWordChar(phrase))
+                out.push(quoteToken(phrase));
+            continue;
+        }
+        // A bareword: read until whitespace or a quote.
+        let word = "";
+        while (i < n && !/\s/.test(input[i]) && input[i] !== '"') {
+            word += input[i];
+            i++;
+        }
+        // Preserve a trailing `*` as an FTS5 prefix match on the quoted token.
+        const prefix = word.endsWith("*");
+        const core = prefix ? word.slice(0, -1) : word;
+        if (hasWordChar(core))
+            out.push(quoteToken(core) + (prefix ? "*" : ""));
+    }
+    return out.join(" ");
+}
+//# sourceMappingURL=fts-query.js.map

package/dist/src/search/provider.d.ts

@@ -0,0 +1,17 @@
+export interface EmbeddingSettings {
+    /** Package name to import, e.g. "@omgbase/embedder". Absent ⇒ no provider. */
+    provider?: string;
+    /** Optional model id passed through to the provider factory. */
+    model?: string;
+    /** Optional dimension override passed through to the provider factory. */
+    dim?: number;
+    /**
+     * Optional max input length (tokens) the provider's model accepts before it
+     * truncates. Sets the doc-embedding whole-doc vs pooled-fallback threshold; a
+     * provider that reports it in its handshake overrides this. Absent everywhere
+     * ⇒ the worker's conservative default budget applies.
+     */
+    maxInputTokens?: number;
+}
+/** Read the embedding.* block out of a repo's parsed settings JSON. */
+export declare function embeddingSettings(settings: Record<string, unknown>): EmbeddingSettings;

package/dist/src/search/provider.js

@@ -0,0 +1,13 @@
+// Provider configuration (05 §6). The embedding provider is a plugin named in
+// repo settings (embedding.provider = a package that exports
+// `createProvider(opts?) => EmbeddingProvider`). The dynamic import itself lives
+// in the application (the CLI), not here, so it resolves against the app's
+// dependency tree and core carries no ML dependency. @omgbase/embedder is the
+// default local implementation; a remote HTTP provider is the same contract
+// behind a different package name — nothing privileges local vs. remote.
+/** Read the embedding.* block out of a repo's parsed settings JSON. */
+export function embeddingSettings(settings) {
+    const e = settings.embedding;
+    return e && typeof e === "object" ? e : {};
+}
+//# sourceMappingURL=provider.js.map

package/dist/src/search/resolve.d.ts

@@ -0,0 +1,18 @@
+import type { Store } from "../core/store/store.js";
+export interface ResolveHit {
+    id: string;
+    locator: string;
+    preview: string;
+    evidence: unknown;
+}
+export interface ResolveInput {
+    repoId: string;
+    query: string;
+    vector?: {
+        model: string;
+        vec: Float32Array;
+    };
+    limit?: number;
+}
+/** resolve: ranked candidates for the thing the caller means. */
+export declare function resolve(store: Store, input: ResolveInput): ResolveHit[];

package/dist/src/search/resolve.js

@@ -0,0 +1,23 @@
+import { hybridSearch } from "./rrf.js";
+function locatorFor(store, blockId) {
+    const row = store.db.prepare("SELECT d.path AS path, b.ordinal AS ordinal, b.type AS type FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ?").get(blockId);
+    if (!row)
+        return blockId;
+    return `${row.path}#${row.type}[${row.ordinal}]`;
+}
+function previewFor(store, blockId, words = 12) {
+    const row = store.db.prepare("SELECT text FROM blocks WHERE block_id = ?").get(blockId);
+    if (!row)
+        return "";
+    const w = row.text.split(/\s+/).filter(Boolean);
+    return w.length <= words ? w.join(" ") : w.slice(0, words).join(" ") + "…";
+}
+/** resolve: ranked candidates for the thing the caller means. */
+export function resolve(store, input) {
+    const hi = { repoId: input.repoId, text: input.query, limit: input.limit ?? 10 };
+    if (input.vector)
+        hi.vector = input.vector;
+    const hits = hybridSearch(store, hi);
+    return hits.map((h) => ({ id: h.blockId, locator: locatorFor(store, h.blockId), preview: previewFor(store, h.blockId), evidence: h.evidence }));
+}
+//# sourceMappingURL=resolve.js.map

package/dist/src/search/rrf.d.ts

@@ -0,0 +1,36 @@
+import type { Store } from "../core/store/store.js";
+export interface Boosts {
+    title?: number;
+    heading?: number;
+    path?: number;
+    layer?: number;
+    recency?: number;
+}
+export interface HybridHit {
+    blockId: string;
+    docId: string;
+    path: string;
+    score: number;
+    evidence: {
+        ftsRank?: number;
+        vectorRank?: number;
+        cosine?: number;
+        rrf: number;
+        boosts: Boosts;
+    };
+}
+export interface HybridInput {
+    repoId: string;
+    /** FTS query string (optional). */
+    text?: string;
+    /** query vector + model for the vector ranker (optional). */
+    vector?: {
+        model: string;
+        vec: Float32Array;
+    };
+    /** raw terms for boost matching (title/heading/path). */
+    terms?: string[];
+    limit?: number;
+}
+/** Hybrid search: RRF-fuse FTS + vector rankings, then multiplicative boosts. */
+export declare function hybridSearch(store: Store, input: HybridInput): HybridHit[];