@amoree-code/ocean 0.0.0-stage → 1.1.0

package/node_modules/@ocean/brain/dist/brain/brain-service.js

@@ -0,0 +1,320 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { scopeVisible, visibleScopes, } from "@ocean/core/domain/brain/record-scope.js";
+import { BRAIN_INDEX_SCHEMA_VERSION, } from "@ocean/core/domain/ports/brain-index-port.js";
+import { oceanRoot, resolveStorePath, resolveWithin, STORE_DIR, storeRelativeToRoot, } from "@ocean/core/shared/paths.js";
+import { normalizeForSearch, normalizeRecord } from "./brain-markdown.js";
+import { brainIndexPath, computeCorpusHash, reindexBrain, } from "./brain-reindex.js";
+// A v1 index has no scope column, so it cannot answer a scoped query: say how to fix it
+// rather than return unfiltered hits.
+export class BrainIndexStaleError extends Error {
+}
+function assertScoped(reader) {
+    if (reader.meta.schemaVersion !== BRAIN_INDEX_SCHEMA_VERSION)
+        throw new BrainIndexStaleError(`brain index schema ${reader.meta.schemaVersion} predates record scopes — run \`ocean memory reindex\``);
+}
+const RRF_K = 60;
+function snippetOf(text, maxLen = 240) {
+    const trimmed = text.trim().replace(/\s+/g, " ");
+    return trimmed.length > maxLen ? `${trimmed.slice(0, maxLen - 1)}…` : trimmed;
+}
+export async function brainSearch(options) {
+    const root = options.root ?? oceanRoot();
+    const limit = Math.max(1, Math.min(20, options.limit ?? 8));
+    const indexFile = brainIndexPath(root);
+    let exists = true;
+    try {
+        await stat(indexFile);
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists) {
+        throw new Error("brain index not built — run ocean memory reindex");
+    }
+    const reader = options.indexPort.openIndexReadOnly(indexFile);
+    try {
+        if (options.scope)
+            assertScoped(reader);
+        const scopes = options.scope
+            ? visibleScopes(options.scope.project)
+            : undefined;
+        const normalizedQuery = normalizeForSearch(options.query);
+        const ftsHits = reader.ftsQuery(normalizedQuery, limit * 4, scopes);
+        let vecHits = [];
+        let vectorStatus = "unavailable: index built without an embedder";
+        if (reader.hasVectors && options.embedder) {
+            try {
+                const [embedding] = await options.embedder.embed([normalizedQuery]);
+                // KNN cannot filter by scope before k, so a scoped query oversamples: other projects'
+                // chunks would otherwise fill the top hits and the backstop below would drop them all.
+                vecHits = reader.vecQuery(embedding, options.scope ? limit * 16 : limit * 4);
+                vectorStatus = "ok";
+            }
+            catch (error) {
+                vectorStatus = `unavailable: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        else if (reader.hasVectors && !options.embedder) {
+            vectorStatus = "unavailable: no embedder supplied to this query";
+        }
+        // Reciprocal rank fusion: rank position (1-based), not raw score, so bm25 and cosine
+        // distance — on incompatible scales — combine without one dominating by magnitude.
+        const fused = new Map();
+        ftsHits.forEach((hit, index) => {
+            const entry = fused.get(hit.chunkId) ?? {
+                docId: hit.docId,
+                score: 0,
+                fts: false,
+                vec: false,
+            };
+            entry.score += 1 / (RRF_K + index + 1);
+            entry.fts = true;
+            fused.set(hit.chunkId, entry);
+        });
+        vecHits.forEach((hit, index) => {
+            const entry = fused.get(hit.chunkId) ?? {
+                docId: hit.docId,
+                score: 0,
+                fts: false,
+                vec: false,
+            };
+            entry.score += 1 / (RRF_K + index + 1);
+            entry.vec = true;
+            fused.set(hit.chunkId, entry);
+        });
+        const byDoc = new Map();
+        for (const [chunkId, entry] of fused) {
+            const existing = byDoc.get(entry.docId);
+            if (!existing || entry.score > existing.score) {
+                byDoc.set(entry.docId, {
+                    chunkId,
+                    score: entry.score,
+                    fts: entry.fts,
+                    vec: entry.vec,
+                });
+            }
+        }
+        const ranked = [...byDoc.entries()]
+            .map(([docId, entry]) => ({ docId, ...entry }))
+            .sort((a, b) => b.score - a.score || a.docId - b.docId);
+        const results = [];
+        for (const item of ranked) {
+            const doc = reader.getDoc(item.docId);
+            if (!doc)
+                continue;
+            if (options.pathPrefix &&
+                !String(doc.path).startsWith(options.pathPrefix))
+                continue;
+            if (options.types?.length && !options.types.includes(String(doc.type)))
+                continue;
+            // Backstop for hits the SQL filter never saw (vector hits are not scope-filtered).
+            if (options.scope &&
+                !scopeVisible(String(doc.scope), options.scope.project))
+                continue;
+            const chunk = reader.getChunk(item.chunkId);
+            results.push({
+                id: String(doc.id),
+                path: String(doc.path),
+                file: storeRelativeToRoot(String(doc.path), root),
+                updated: doc.updated ?? null,
+                title: String(doc.title),
+                summary: String(doc.summary),
+                type: String(doc.type),
+                scope: String(doc.scope ?? "global"),
+                confidence: String(doc.confidence),
+                lastConfirmedAt: doc.last_confirmed_at ?? null,
+                heading: chunk ? (chunk.heading ?? null) : null,
+                snippet: chunk ? snippetOf(String(chunk.text)) : "",
+                score: Math.round(item.score * 1_000_000) / 1_000_000,
+                matchedBy: item.fts && item.vec ? "both" : item.vec ? "vector" : "fts",
+            });
+            if (results.length >= limit)
+                break;
+        }
+        const stale = reader.meta.corpusHash !== (await computeCorpusHash(root));
+        return {
+            mode: reader.hasVectors && options.embedder && vectorStatus === "ok"
+                ? "hybrid"
+                : "fts",
+            stale,
+            vector: vectorStatus,
+            results,
+        };
+    }
+    finally {
+        reader.close();
+    }
+}
+// Always reads the markdown FILE, never the index row — the index can be stale or (in a
+// test) deliberately tampered with, and brain_read must never surface a lie about what's on
+// disk. The index is used only to resolve id -> path.
+export async function brainRead(options) {
+    const root = options.root ?? oceanRoot();
+    const maxBytes = Math.max(512, Math.min(16_000, options.maxBytes ?? 8_000));
+    const indexFile = brainIndexPath(root);
+    const reader = options.indexPort.openIndexReadOnly(indexFile);
+    let docRow;
+    try {
+        // Clients also cite a search result's path without its extension.
+        const candidates = options.idOrPath.endsWith(".md")
+            ? [options.idOrPath]
+            : [options.idOrPath, `${options.idOrPath}.md`];
+        for (const candidate of candidates) {
+            docRow = reader.getDocByIdOrPath(candidate);
+            if (!docRow) {
+                const storePath = indexedStorePath(candidate, root);
+                if (storePath)
+                    docRow = reader.getDocByIdOrPath(storePath);
+            }
+            if (docRow)
+                break;
+        }
+    }
+    finally {
+        reader.close();
+    }
+    if (!docRow)
+        throw new Error(`no brain record found for '${options.idOrPath}'`);
+    // The index is only ever used above to resolve id/path -> the store-relative path. Every
+    // field returned below is re-derived from the file's own bytes on disk (normalizeRecord),
+    // never from the (possibly stale or tampered) index row — this is what makes brain_read
+    // safe to trust even when the index itself cannot be.
+    const relativePath = String(docRow.path);
+    const filePath = resolveStorePath(root, relativePath);
+    const raw = await readFile(filePath, "utf8");
+    const { record, body } = normalizeRecord(relativePath, raw);
+    const truncated = Buffer.byteLength(body, "utf8") > maxBytes;
+    const slicedBody = truncated
+        ? Buffer.from(body).subarray(0, maxBytes).toString("utf8")
+        : body;
+    return {
+        id: record.id,
+        path: relativePath,
+        title: record.title,
+        summary: record.summary,
+        tags: record.tags,
+        type: record.type,
+        scope: record.scope,
+        confidence: record.confidence,
+        created: record.created,
+        updated: record.updated,
+        lastConfirmedAt: record.lastConfirmedAt,
+        body: slicedBody,
+        truncated,
+    };
+}
+export async function brainNeighbors(options) {
+    const root = options.root ?? oceanRoot();
+    const depth = options.depth ?? 1;
+    const direction = options.direction ?? "both";
+    const limit = Math.max(1, Math.min(50, options.limit ?? 20));
+    const indexFile = brainIndexPath(root);
+    const reader = options.indexPort.openIndexReadOnly(indexFile);
+    try {
+        if (options.scope)
+            assertScoped(reader);
+        const visible = (doc) => !options.scope || scopeVisible(String(doc.scope), options.scope.project);
+        const start = reader.getDocByIdOrPath(options.idOrPath);
+        if (!start || !visible(start))
+            throw new Error(`no brain record found for '${options.idOrPath}'`);
+        const visited = new Set([Number(start.doc_id)]);
+        const neighbors = [];
+        let frontier = [Number(start.doc_id)];
+        for (let level = 0; level < depth && neighbors.length < limit; level += 1) {
+            const next = [];
+            for (const docId of frontier) {
+                const directions = direction === "both" ? ["out", "in"] : [direction];
+                for (const dir of directions) {
+                    for (const link of reader.linksFor(docId, dir)) {
+                        const targetId = dir === "out" ? link.targetDocId : link.sourceDocId;
+                        if (targetId === null ||
+                            targetId === undefined ||
+                            visited.has(targetId))
+                            continue;
+                        visited.add(targetId);
+                        const doc = reader.getDoc(targetId);
+                        if (!doc || !visible(doc))
+                            continue;
+                        neighbors.push({
+                            id: String(doc.id),
+                            path: String(doc.path),
+                            title: String(doc.title),
+                            via: dir,
+                        });
+                        next.push(targetId);
+                        if (neighbors.length >= limit)
+                            break;
+                    }
+                    if (neighbors.length >= limit)
+                        break;
+                }
+                if (neighbors.length >= limit)
+                    break;
+            }
+            frontier = next;
+        }
+        return { neighbors };
+    }
+    finally {
+        reader.close();
+    }
+}
+// Whether the index is missing or older than the files it was built from, and whether it holds
+// vectors — what an automatic rebuild needs to decide (T-307).
+export async function brainIndexState(options) {
+    const root = options.root ?? oceanRoot();
+    const indexFile = brainIndexPath(root);
+    if (!(await ensureIndexBuilt(root)))
+        return { stale: true, hasVectors: false };
+    const reader = options.indexPort.openIndexReadOnly(indexFile);
+    try {
+        return {
+            stale: reader.meta.corpusHash !== (await computeCorpusHash(root)),
+            hasVectors: reader.hasVectors,
+        };
+    }
+    finally {
+        reader.close();
+    }
+}
+export async function ensureIndexBuilt(root = oceanRoot()) {
+    try {
+        await stat(brainIndexPath(root));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { reindexBrain };
+export function relativeStorePath(file, root = oceanRoot()) {
+    for (const [store, dir] of Object.entries(STORE_DIR)) {
+        const relative = path.relative(resolveWithin(root, dir), file);
+        if (!relative.startsWith("..") && !path.isAbsolute(relative))
+            return `${store}/${relative.split(path.sep).join("/")}`;
+    }
+    return path.relative(root, file).split(path.sep).join("/");
+}
+function indexedStorePath(input, root) {
+    let relative = input.replaceAll("\\", "/");
+    if (path.isAbsolute(input)) {
+        relative = path.relative(root, input).split(path.sep).join("/");
+        if (relative === ".." ||
+            relative.startsWith("../") ||
+            path.isAbsolute(relative))
+            return undefined;
+    }
+    if (relative.startsWith("02-personal/"))
+        return `memory/${relative.slice("02-personal/".length)}`;
+    if (relative.startsWith("05-knowledge/"))
+        return `knowledge/${relative.slice("05-knowledge/".length)}`;
+    const projectMemory = relative.match(/^04-projects\/([^/]+)\/memory\/(.+)$/);
+    if (projectMemory)
+        return `project/${projectMemory[1]}/${projectMemory[2]}`;
+    const projectDocs = relative.match(/^04-projects\/([^/]+)\/docs\/(.+)$/);
+    if (projectDocs)
+        return `project-docs/${projectDocs[1]}/${projectDocs[2]}`;
+    return undefined;
+}
+//# sourceMappingURL=brain-service.js.map

package/node_modules/@ocean/brain/dist/capture/inbox-sync.js

@@ -0,0 +1,22 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { INBOX_DIR, oceanPath } from "@ocean/core/shared/paths.js";
+const marker = "## Capture candidates (generated)";
+export async function syncCaptureInbox(store) {
+    const file = oceanPath(INBOX_DIR, "INBOX.md");
+    let current;
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch {
+        return;
+    }
+    const base = current.split(marker)[0].trimEnd();
+    const items = store.listCaptureItems("new");
+    const generated = items.length === 0
+        ? `${marker}\n\n_No new capture candidates._`
+        : `${marker}\n\n${items.map((item) => `- [${item.captureId}] ${item.content.replace(/\s+/g, " ").trim()} _(session ${item.sessionId})_`).join("\n")}`;
+    const next = `${base}\n\n${generated}\n`;
+    if (next !== current)
+        await writeFile(file, next, "utf8");
+}
+//# sourceMappingURL=inbox-sync.js.map

package/node_modules/@ocean/brain/dist/evidence/verification-report.js

@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+import { evidenceSchema, } from "@ocean/core/domain/evidence/evidence.js";
+export function buildVerificationReport(records) {
+    const evidence = records.map((record) => evidenceSchema.parse(record));
+    const proven = evidence.filter((record) => record.result === "proven");
+    const notProven = evidence.filter((record) => record.result === "not_proven");
+    const limitations = evidence.filter((record) => record.result === "limitation");
+    const fingerprint = createHash("sha256")
+        .update(JSON.stringify({ proven, notProven, limitations }))
+        .digest("hex");
+    return { proven, notProven, limitations, fingerprint };
+}
+//# sourceMappingURL=verification-report.js.map

package/node_modules/@ocean/brain/dist/infrastructure/brain/brain-index.js

@@ -0,0 +1,285 @@
+import { rename, rm } from "node:fs/promises";
+import { DatabaseSync } from "node:sqlite";
+import { BRAIN_INDEX_SCHEMA_VERSION, } from "@ocean/core/domain/ports/brain-index-port.js";
+import * as sqliteVec from "sqlite-vec";
+function createSchema(db, withVectors, dims) {
+    db.exec(`
+    CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+    CREATE TABLE docs (
+      doc_id INTEGER PRIMARY KEY,
+      id TEXT NOT NULL UNIQUE,
+      path TEXT NOT NULL UNIQUE,
+      title TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      tags_json TEXT NOT NULL,
+      type TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      confidence TEXT NOT NULL,
+      created TEXT,
+      updated TEXT,
+      last_confirmed_at TEXT,
+      content_hash TEXT NOT NULL,
+      bytes INTEGER NOT NULL,
+      conformance_json TEXT NOT NULL
+    );
+    CREATE TABLE chunks (
+      chunk_id INTEGER PRIMARY KEY,
+      doc_id INTEGER NOT NULL REFERENCES docs(doc_id),
+      ordinal INTEGER NOT NULL,
+      heading TEXT,
+      text TEXT NOT NULL
+    );
+    CREATE VIRTUAL TABLE chunks_fts USING fts5(
+      title, heading, body,
+      tokenize = "unicode61 remove_diacritics 2",
+      content = ""
+    );
+    CREATE TABLE links (
+      source_doc_id INTEGER NOT NULL REFERENCES docs(doc_id),
+      target_raw TEXT NOT NULL,
+      target_doc_id INTEGER,
+      PRIMARY KEY (source_doc_id, target_raw)
+    );
+    CREATE INDEX links_target_doc_id ON links(target_doc_id);
+    CREATE INDEX chunks_doc_id ON chunks(doc_id);
+  `);
+    if (withVectors) {
+        db.exec(`CREATE VIRTUAL TABLE chunks_vec USING vec0(embedding float[${dims}] distance_metric=cosine);`);
+    }
+}
+// Inserts sorted-by-path (docs already arrive sorted from the caller) in one transaction so
+// rowids — and therefore FTS/vec0 rowids — are deterministic across an identical rebuild.
+async function populate(db, docs, links, options) {
+    const insertDoc = db.prepare(`
+    INSERT INTO docs (id, path, title, summary, tags_json, type, scope, confidence, created, updated,
+      last_confirmed_at, content_hash, bytes, conformance_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const insertChunk = db.prepare(`
+    INSERT INTO chunks (doc_id, ordinal, heading, text) VALUES (?, ?, ?, ?)
+  `);
+    const insertFts = db.prepare(`
+    INSERT INTO chunks_fts (rowid, title, heading, body) VALUES (?, ?, ?, ?)
+  `);
+    // A document can legitimately link to the same target twice (e.g. two separate mentions
+    // of [[MEMORY.md]]); the second is a no-op, not a conflict — the same (source, target_raw)
+    // pair carries no extra information the second time.
+    const insertLink = db.prepare(`
+    INSERT OR IGNORE INTO links (source_doc_id, target_raw, target_doc_id) VALUES (?, ?, ?)
+  `);
+    const pathToDocId = new Map();
+    const chunkEmbedInputs = [];
+    db.exec("BEGIN");
+    try {
+        for (const doc of docs) {
+            insertDoc.run(doc.id, doc.path, doc.title, doc.summary, JSON.stringify(doc.tags), doc.type, doc.scope, doc.confidence, doc.created, doc.updated, doc.lastConfirmedAt, doc.contentHash, doc.bytes, JSON.stringify(doc.conformance));
+            const docIdRow = db.prepare("SELECT last_insert_rowid() AS id").get();
+            const docId = Number(docIdRow.id);
+            pathToDocId.set(doc.path, docId);
+            for (const chunk of doc.chunks) {
+                insertChunk.run(docId, chunk.ordinal, chunk.heading, chunk.text);
+                const chunkIdRow = db
+                    .prepare("SELECT last_insert_rowid() AS id")
+                    .get();
+                const chunkId = Number(chunkIdRow.id);
+                insertFts.run(chunkId, doc.title.toLowerCase(), (chunk.heading ?? "").toLowerCase(), chunk.normalizedText);
+                if (options.embedder)
+                    chunkEmbedInputs.push({
+                        chunkId: BigInt(chunkId),
+                        text: chunk.normalizedText,
+                    });
+            }
+        }
+        for (const link of links) {
+            const sourceDocId = pathToDocId.get(link.sourcePath);
+            if (sourceDocId === undefined)
+                continue;
+            const targetDocId = link.targetPath
+                ? (pathToDocId.get(link.targetPath) ?? null)
+                : null;
+            insertLink.run(sourceDocId, link.targetRaw, targetDocId);
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    if (options.embedder && chunkEmbedInputs.length > 0) {
+        const embeddings = await options.embedder.embed(chunkEmbedInputs.map((item) => item.text));
+        const insertVec = db.prepare("INSERT INTO chunks_vec (rowid, embedding) VALUES (?, ?)");
+        db.exec("BEGIN");
+        try {
+            chunkEmbedInputs.forEach((item, index) => {
+                insertVec.run(item.chunkId, embeddings[index]);
+            });
+            db.exec("COMMIT");
+        }
+        catch (error) {
+            db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)").run("schema_version", BRAIN_INDEX_SCHEMA_VERSION);
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)").run("embedder", options.embedder?.model ?? "");
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)").run("dims", String(options.embedder?.dimensions ?? 0));
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)").run("corpus_hash", options.corpusHash);
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?)").run("built_at", new Date().toISOString());
+}
+// Builds a brand-new index file at `outFile` from scratch: writes into a sibling temp file
+// and renames atomically into place, so a reader never observes a half-built index and a
+// crash mid-build never corrupts whatever index was there before.
+export async function buildIndex(docs, links, outFile, options) {
+    const temp = `${outFile}.tmp-${process.pid}-${Date.now()}`;
+    await rm(temp, { force: true });
+    const db = new DatabaseSync(temp, { allowExtension: true });
+    try {
+        if (options.embedder)
+            sqliteVec.load(db);
+        createSchema(db, Boolean(options.embedder), options.embedder?.dimensions ?? 0);
+        await populate(db, docs, links, options);
+    }
+    finally {
+        db.close();
+    }
+    await rename(temp, outFile);
+}
+function loadVectorExtension(db) {
+    try {
+        sqliteVec.load(db);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class BrainIndexReader {
+    db;
+    meta;
+    hasVectors;
+    constructor(file) {
+        this.db = new DatabaseSync(file, { readOnly: true, allowExtension: true });
+        this.db.exec("PRAGMA query_only = ON;");
+        const rows = this.db.prepare("SELECT key, value FROM meta").all();
+        const map = Object.fromEntries(rows.map((row) => [row.key, row.value]));
+        this.meta = {
+            schemaVersion: map.schema_version ?? "",
+            embedder: map.embedder ?? "",
+            dims: Number(map.dims ?? 0),
+            corpusHash: map.corpus_hash ?? "",
+            builtAt: map.built_at ?? "",
+        };
+        // sqlite-vec ships one prebuilt per platform; where none installed, search stays full-text.
+        this.hasVectors = this.meta.dims > 0 && loadVectorExtension(this.db);
+    }
+    ftsQuery(normalizedQuery, limit, scopes) {
+        // Tokens are matched as quoted prefixes (`"token"*`), ANDed together (FTS5's default):
+        // exact-token phrase matching is too strict for agglutinative languages like Sorani,
+        // where a query word is frequently a prefix of the inflected form actually stored.
+        const words = normalizedQuery
+            .split(/[^\p{L}\p{N}_-]+/u)
+            .map((token) => token.trim())
+            .filter(Boolean);
+        const quote = (token) => `"${token.replace(/"/g, '""')}"*`;
+        if (words.length === 0)
+            return [];
+        // Filtered in SQL, before LIMIT, so another project's records cannot crowd out the hits.
+        const scopeFilter = scopes
+            ? ` AND c.doc_id IN (SELECT doc_id FROM docs WHERE scope IN (${scopes.map(() => "?").join(",")}))`
+            : "";
+        const run = (match, max) => {
+            try {
+                return this.db
+                    .prepare(`
+            SELECT c.chunk_id AS chunkId, c.doc_id AS docId, bm25(chunks_fts) AS rank
+            FROM chunks_fts JOIN chunks c ON c.chunk_id = chunks_fts.rowid
+            WHERE chunks_fts MATCH ?${scopeFilter}
+            ORDER BY rank LIMIT ?
+          `)
+                    .all(match, ...(scopes ?? []), max);
+            }
+            catch {
+                return [];
+            }
+        };
+        const all = run(words.map(quote).join(" "), limit);
+        if (all.length >= limit)
+            return all;
+        // A question rarely shares every word with its answer (T-296 eval: natural questions found
+        // nothing). Fill up with any-word matches, bm25-ranked so rarer shared words weigh more;
+        // one-letter prefixes would match everything and are left out.
+        const anyWord = words.filter((word) => word.length > 1);
+        if (anyWord.length < 2)
+            return all;
+        const seen = new Set(all.map((hit) => hit.chunkId));
+        return [
+            ...all,
+            ...run(anyWord.map(quote).join(" OR "), limit).filter((hit) => !seen.has(hit.chunkId)),
+        ].slice(0, limit);
+    }
+    vecQuery(embedding, limit) {
+        if (!this.hasVectors)
+            return [];
+        const rows = this.db
+            .prepare(`
+        SELECT v.rowid AS chunkId, c.doc_id AS docId, v.distance AS distance
+        FROM chunks_vec v JOIN chunks c ON c.chunk_id = v.rowid
+        WHERE v.embedding MATCH ? AND k = ?
+        ORDER BY v.distance
+      `)
+            .all(embedding, limit);
+        return rows;
+    }
+    getDoc(docId) {
+        return this.db.prepare("SELECT * FROM docs WHERE doc_id = ?").get(docId);
+    }
+    getDocByIdOrPath(idOrPath) {
+        return this.db
+            .prepare("SELECT * FROM docs WHERE id = ? OR path = ?")
+            .get(idOrPath, idOrPath);
+    }
+    getChunk(chunkId) {
+        return this.db
+            .prepare("SELECT * FROM chunks WHERE chunk_id = ?")
+            .get(chunkId);
+    }
+    linksFor(docId, direction) {
+        const rows = (direction === "out"
+            ? this.db
+                .prepare("SELECT * FROM links WHERE source_doc_id = ?")
+                .all(docId)
+            : this.db
+                .prepare("SELECT * FROM links WHERE target_doc_id = ?")
+                .all(docId));
+        return rows.map((row) => ({
+            sourceDocId: row.source_doc_id,
+            targetDocId: row.target_doc_id,
+            targetRaw: row.target_raw,
+        }));
+    }
+    // Canonical, ordered dump of every row (minus built_at, which changes on every rebuild by
+    // design) — used by the round-trip test to prove reindex is deterministic.
+    dump() {
+        const meta = this.db
+            .prepare("SELECT key, value FROM meta WHERE key != 'built_at' ORDER BY key")
+            .all();
+        const docs = this.db.prepare("SELECT * FROM docs ORDER BY doc_id").all();
+        const chunks = this.db
+            .prepare("SELECT * FROM chunks ORDER BY chunk_id")
+            .all();
+        const links = this.db
+            .prepare("SELECT * FROM links ORDER BY source_doc_id, target_raw")
+            .all();
+        return { meta, docs, chunks, links };
+    }
+    close() {
+        this.db.close();
+    }
+}
+export function openIndexReadOnly(file) {
+    return new BrainIndexReader(file);
+}
+// The concrete brain-index driver, as the BrainIndexPort — wired into application code only
+// through composition/runtime.ts.
+export const brainIndexPort = { buildIndex, openIndexReadOnly };
+//# sourceMappingURL=brain-index.js.map