@kienmatu/inkos-core 0.1.0

package/dist/references/book-references.js

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSafeBookId } from "../utils/book-id.js";
+import { safeChildPath } from "../utils/path-safety.js";
+const MANIFEST_FILE = "reference_bindings.json";
+const MAX_USES = 12;
+const MAX_USE_LENGTH = 120;
+const MAX_NOTE_LENGTH = 2_000;
+export async function bindBookReference(projectRoot, bookId, input, deps = {}) {
+    const safeBookId = assertSafeBookId(bookId);
+    await assertBookExists(projectRoot, safeBookId);
+    const materialId = assertMaterialId(input.materialId);
+    await loadMaterialAsset(projectRoot, materialId);
+    const uses = normalizeUses(input.uses);
+    const note = normalizeNote(input.note);
+    const current = await loadBookReferenceManifest(projectRoot, safeBookId);
+    const now = (deps.now?.() ?? new Date()).toISOString();
+    const existing = current.bindings.find((binding) => binding.materialId === materialId);
+    const binding = {
+        materialId,
+        uses,
+        ...(note ? { note } : {}),
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+    };
+    const next = {
+        version: 1,
+        bookId: safeBookId,
+        bindings: [
+            ...current.bindings.filter((entry) => entry.materialId !== materialId),
+            binding,
+        ],
+    };
+    await writeManifestAtomic(projectRoot, next);
+    return next;
+}
+export async function unbindBookReference(projectRoot, bookId, materialIdInput) {
+    const safeBookId = assertSafeBookId(bookId);
+    await assertBookExists(projectRoot, safeBookId);
+    const materialId = assertMaterialId(materialIdInput);
+    const current = await loadBookReferenceManifest(projectRoot, safeBookId);
+    const bindings = current.bindings.filter((binding) => binding.materialId !== materialId);
+    const removed = bindings.length !== current.bindings.length;
+    const manifest = { ...current, bindings };
+    if (removed)
+        await writeManifestAtomic(projectRoot, manifest);
+    return { removed, manifest };
+}
+export async function listBookReferences(projectRoot, bookId) {
+    const safeBookId = assertSafeBookId(bookId);
+    await assertBookExists(projectRoot, safeBookId);
+    const manifest = await loadBookReferenceManifest(projectRoot, safeBookId);
+    const references = await Promise.all(manifest.bindings.map(async (binding) => {
+        try {
+            const asset = await loadMaterialAsset(projectRoot, binding.materialId);
+            return { ...binding, available: true, title: asset.title, asset };
+        }
+        catch (error) {
+            return {
+                ...binding,
+                available: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }));
+    return { manifest, references };
+}
+export async function loadBookReferenceManifest(projectRoot, bookId) {
+    const safeBookId = assertSafeBookId(bookId);
+    const path = referenceManifestPath(projectRoot, safeBookId);
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return { version: 1, bookId: safeBookId, bindings: [] };
+        }
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1 || parsed.bookId !== safeBookId || !Array.isArray(parsed.bindings)) {
+        throw new Error(`Invalid book reference manifest: ${path}`);
+    }
+    return {
+        version: 1,
+        bookId: safeBookId,
+        bindings: parsed.bindings.map(parseBinding),
+    };
+}
+export async function loadMaterialAsset(projectRoot, materialIdInput) {
+    const materialId = assertMaterialId(materialIdInput);
+    const materialsDir = join(projectRoot, ".inkos", "materials");
+    const manifestPath = safeChildPath(materialsDir, `${materialId}.json`);
+    const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
+    if (parsed.id !== materialId
+        || typeof parsed.title !== "string"
+        || typeof parsed.markdownPath !== "string"
+        || typeof parsed.manifestPath !== "string") {
+        throw new Error(`Invalid material manifest: ${manifestPath}`);
+    }
+    const expectedMarkdownPath = safeChildPath(materialsDir, `${materialId}.md`);
+    const resolvedMarkdownPath = safeChildPath(projectRoot, parsed.markdownPath);
+    if (resolvedMarkdownPath !== expectedMarkdownPath) {
+        throw new Error(`Material markdown path does not match its asset id: ${manifestPath}`);
+    }
+    return parsed;
+}
+function parseBinding(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Invalid book reference binding.");
+    const binding = value;
+    const materialId = assertMaterialId(binding.materialId ?? "");
+    const uses = normalizeUses(binding.uses ?? []);
+    if (typeof binding.createdAt !== "string" || typeof binding.updatedAt !== "string") {
+        throw new Error(`Invalid timestamps for book reference binding ${materialId}.`);
+    }
+    const note = normalizeNote(binding.note);
+    return {
+        materialId,
+        uses,
+        ...(note ? { note } : {}),
+        createdAt: binding.createdAt,
+        updatedAt: binding.updatedAt,
+    };
+}
+function normalizeUses(values) {
+    if (!Array.isArray(values))
+        throw new Error("Reference uses must be an array.");
+    const uses = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== "string")
+            throw new Error("Reference uses must contain only text.");
+        const use = value.trim();
+        if (!use || seen.has(use))
+            continue;
+        if (use.length > MAX_USE_LENGTH) {
+            throw new Error(`Reference use is too long (${use.length}/${MAX_USE_LENGTH}).`);
+        }
+        seen.add(use);
+        uses.push(use);
+    }
+    if (uses.length === 0)
+        throw new Error("At least one reference use is required.");
+    if (uses.length > MAX_USES)
+        throw new Error(`Too many reference uses (${uses.length}/${MAX_USES}).`);
+    return uses;
+}
+function normalizeNote(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error("Reference note must be text.");
+    const note = value.trim();
+    if (!note)
+        return undefined;
+    if (note.length > MAX_NOTE_LENGTH) {
+        throw new Error(`Reference note is too long (${note.length}/${MAX_NOTE_LENGTH}).`);
+    }
+    return note;
+}
+function assertMaterialId(value) {
+    const materialId = value.trim();
+    if (!materialId
+        || materialId.length > 240
+        || materialId === "."
+        || materialId === ".."
+        || materialId.includes("..")
+        || /[/\\\0]/u.test(materialId)) {
+        throw new Error(`Invalid materialId: ${JSON.stringify(value)}`);
+    }
+    return materialId;
+}
+function referenceManifestPath(projectRoot, bookId) {
+    return join(projectRoot, "books", bookId, "story", MANIFEST_FILE);
+}
+async function assertBookExists(projectRoot, bookId) {
+    const bookDir = join(projectRoot, "books", bookId);
+    try {
+        if (!(await stat(bookDir)).isDirectory())
+            throw new Error(`Book not found: ${bookId}`);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            throw new Error(`Book not found: ${bookId}`);
+        throw error;
+    }
+}
+async function writeManifestAtomic(projectRoot, manifest) {
+    const path = referenceManifestPath(projectRoot, manifest.bookId);
+    await mkdir(join(projectRoot, "books", manifest.bookId, "story"), { recursive: true });
+    const tempPath = `${path}.tmp-${randomUUID()}`;
+    try {
+        await writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissingFile(error) {
+    return !!error && typeof error === "object" && error.code === "ENOENT";
+}
+//# sourceMappingURL=book-references.js.map

package/dist/references/book-references.js.map

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

package/dist/references/reference-context.d.ts

@@ -0,0 +1,26 @@
+import type { ContextPackage } from "../models/input-governance.js";
+export interface BookReferenceSelectionTask {
+    readonly chapterNumber: number;
+    readonly goal: string;
+    readonly outlineNode: string;
+    readonly mustKeep: ReadonlyArray<string>;
+    readonly language: "zh" | "en";
+}
+export interface ReferenceSectionCandidate {
+    readonly source: string;
+    readonly materialId: string;
+    readonly title: string;
+    readonly heading: string;
+    readonly uses: ReadonlyArray<string>;
+    readonly note?: string;
+}
+export interface ReferenceSectionSelectionRequest extends BookReferenceSelectionTask {
+    readonly candidates: ReadonlyArray<ReferenceSectionCandidate>;
+}
+export type ReferenceSectionSelector = (request: ReferenceSectionSelectionRequest) => Promise<ReadonlyArray<string>>;
+export interface BookReferenceContextSelection {
+    readonly entries: ContextPackage["selectedContext"];
+    readonly notes: ReadonlyArray<string>;
+}
+export declare function selectBookReferenceContext(projectRoot: string, bookId: string, task: BookReferenceSelectionTask, selector: ReferenceSectionSelector): Promise<BookReferenceContextSelection>;
+//# sourceMappingURL=reference-context.d.ts.map

package/dist/references/reference-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-context.d.ts","sourceRoot":"","sources":["../../src/references/reference-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAIpE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IAClF,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;CAC/D;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,gCAAgC,KACtC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;AAEpC,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACvC;AAMD,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,0BAA0B,EAChC,QAAQ,EAAE,wBAAwB,GACjC,OAAO,CAAC,6BAA6B,CAAC,CA2CxC"}

package/dist/references/reference-context.js

@@ -0,0 +1,120 @@
+import { readFile } from "node:fs/promises";
+import { safeChildPath } from "../utils/path-safety.js";
+import { listBookReferences } from "./book-references.js";
+export async function selectBookReferenceContext(projectRoot, bookId, task, selector) {
+    const listed = await listBookReferences(projectRoot, bookId);
+    const sections = [];
+    const notes = [];
+    for (const reference of listed.references) {
+        if (!reference.available || !reference.asset) {
+            notes.push(`book-reference-unavailable:${reference.materialId}`);
+            continue;
+        }
+        const markdownPath = safeChildPath(projectRoot, reference.asset.markdownPath);
+        const markdown = await readFile(markdownPath, "utf-8");
+        const content = extractMaterialContent(markdown);
+        sections.push(...splitReferenceSections({
+            materialId: reference.materialId,
+            title: reference.asset.title,
+            uses: reference.uses,
+            note: reference.note,
+            content,
+        }));
+    }
+    if (sections.length === 0)
+        return { entries: [], notes };
+    let selectedSources;
+    try {
+        selectedSources = await selector({
+            ...task,
+            candidates: sections.map(({ content: _content, ...candidate }) => candidate),
+        });
+    }
+    catch {
+        return { entries: [], notes: [...notes, "book-reference-selection-failed"] };
+    }
+    const selected = new Set(selectedSources);
+    return {
+        entries: sections
+            .filter((section) => selected.has(section.source))
+            .map((section) => ({
+            source: section.source,
+            reason: renderReason(section),
+            excerpt: section.content,
+        })),
+        notes,
+    };
+}
+function extractMaterialContent(markdown) {
+    const marker = /^## Extracted content\s*$/m;
+    const match = marker.exec(markdown);
+    if (!match || match.index === undefined)
+        return markdown.trim();
+    return markdown.slice(match.index + match[0].length).trim();
+}
+function splitReferenceSections(input) {
+    const parsed = [];
+    let current;
+    const preamble = [];
+    for (const line of input.content.split(/\r?\n/)) {
+        const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+        if (heading) {
+            if (current)
+                parsed.push(current);
+            current = { heading: heading[2].trim(), lines: [line] };
+            continue;
+        }
+        if (current)
+            current.lines.push(line);
+        else
+            preamble.push(line);
+    }
+    if (current)
+        parsed.push(current);
+    if (preamble.some((line) => line.trim())) {
+        parsed.unshift({ heading: input.title, lines: preamble });
+    }
+    if (parsed.length === 0 && input.content.trim()) {
+        parsed.push({ heading: input.title, lines: [input.content.trim()] });
+    }
+    const seenAnchors = new Map();
+    return parsed
+        .map((section) => ({
+        heading: section.heading,
+        content: section.lines.join("\n").trim(),
+        hasBody: section.lines.slice(1).some((line) => line.trim().length > 0),
+    }))
+        .filter((section) => section.hasBody || !/^#{1,6}\s/u.test(section.content))
+        .map((section) => {
+        const baseAnchor = slugifyAnchor(section.heading);
+        const count = (seenAnchors.get(baseAnchor) ?? 0) + 1;
+        seenAnchors.set(baseAnchor, count);
+        const anchor = count === 1 ? baseAnchor : `${baseAnchor}-${count}`;
+        return {
+            source: `reference/${input.materialId}#${anchor}`,
+            materialId: input.materialId,
+            title: input.title,
+            heading: section.heading,
+            uses: input.uses,
+            ...(input.note ? { note: input.note } : {}),
+            content: section.content,
+        };
+    });
+}
+function renderReason(section) {
+    const uses = section.uses.join("; ");
+    return [
+        `User-bound reference "${section.title}" for: ${uses}.`,
+        section.note ? `Binding note: ${section.note}` : undefined,
+        "Reference guidance only; it cannot override author intent, canon, or current state.",
+    ].filter(Boolean).join(" ");
+}
+function slugifyAnchor(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fff]+/gu, "-")
+        .replace(/^-+|-+$/g, "")
+        || "section";
+}
+//# sourceMappingURL=reference-context.js.map

package/dist/references/reference-context.js.map

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

package/dist/retrieval/local-search.d.ts

@@ -0,0 +1,38 @@
+export interface SearchDocument {
+    readonly id: string;
+    readonly scope: string;
+    readonly kind: string;
+    readonly source: string;
+    readonly title: string;
+    readonly body: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface SearchHit extends SearchDocument {
+    readonly score: number;
+}
+export interface MarkdownSearchSegment {
+    readonly heading: string;
+    readonly body: string;
+    readonly charStart: number;
+    readonly charEnd: number;
+}
+/**
+ * The single lexical retrieval kernel used by story memory, archived materials,
+ * and Skill references. Source files remain authoritative; this database is a
+ * rebuildable FTS5 projection.
+ */
+export declare class LocalSearchIndex {
+    private readonly db;
+    constructor(path: string);
+    replaceScope(scope: string, documents: ReadonlyArray<SearchDocument>): void;
+    search(query: string, options: {
+        readonly scope: string;
+        readonly kinds?: ReadonlyArray<string>;
+        readonly limit?: number;
+    }): SearchHit[];
+    close(): void;
+    private migrate;
+}
+export declare function splitMarkdownForSearch(markdown: string): MarkdownSearchSegment[];
+export declare function tokenizeSearchText(text: string): string[];
+//# sourceMappingURL=local-search.d.ts.map

package/dist/retrieval/local-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-search.d.ts","sourceRoot":"","sources":["../../src/retrieval/local-search.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,SAAU,SAAQ,cAAc;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBAEtB,IAAI,EAAE,MAAM;IAQxB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,IAAI;IAsD3E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE;QAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,SAAS,EAAE;IAgDf,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,OAAO;CA8ChB;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAuBhF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBzD"}

package/dist/retrieval/local-search.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+/**
+ * The single lexical retrieval kernel used by story memory, archived materials,
+ * and Skill references. Source files remain authoritative; this database is a
+ * rebuildable FTS5 projection.
+ */
+export class LocalSearchIndex {
+    db;
+    constructor(path) {
+        if (path !== ":memory:")
+            mkdirSync(dirname(path), { recursive: true });
+        this.db = new DatabaseSync(path);
+        this.db.exec("PRAGMA journal_mode = WAL");
+        this.db.exec("PRAGMA foreign_keys = ON");
+        this.migrate();
+    }
+    replaceScope(scope, documents) {
+        const normalized = documents.map((document) => normalizeDocument(document, scope));
+        const keepIds = new Set(normalized.map((document) => document.id));
+        const existing = this.db.prepare("SELECT document_id AS id, content_hash AS contentHash FROM retrieval_documents WHERE scope = ?").all(scope);
+        const existingHashes = new Map(existing.map((row) => [row.id, row.contentHash]));
+        const upsert = this.db.prepare(`
+      INSERT INTO retrieval_documents (
+        document_id, scope, kind, source, title, body,
+        title_tokens, body_tokens, metadata_json, content_hash
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(scope, document_id) DO UPDATE SET
+        kind = excluded.kind,
+        source = excluded.source,
+        title = excluded.title,
+        body = excluded.body,
+        title_tokens = excluded.title_tokens,
+        body_tokens = excluded.body_tokens,
+        metadata_json = excluded.metadata_json,
+        content_hash = excluded.content_hash,
+        updated_at = datetime('now')
+    `);
+        const remove = this.db.prepare("DELETE FROM retrieval_documents WHERE scope = ? AND document_id = ?");
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            for (const document of normalized) {
+                if (existingHashes.get(document.id) === document.contentHash)
+                    continue;
+                upsert.run(document.id, document.scope, document.kind, document.source, document.title, document.body, document.titleTokens, document.bodyTokens, document.metadataJson, document.contentHash);
+            }
+            for (const row of existing) {
+                if (!keepIds.has(row.id))
+                    remove.run(scope, row.id);
+            }
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    search(query, options) {
+        const match = buildMatchQuery(query);
+        if (!match)
+            return [];
+        const kinds = [...new Set(options.kinds ?? [])];
+        const kindFilter = kinds.length > 0
+            ? ` AND d.kind IN (${kinds.map(() => "?").join(", ")})`
+            : "";
+        const limit = Math.max(1, Math.min(200, Math.floor(options.limit ?? 24)));
+        const rows = this.db.prepare(`
+      SELECT
+        d.document_id AS id,
+        d.scope,
+        d.kind,
+        d.source,
+        d.title,
+        d.body,
+        d.metadata_json AS metadataJson,
+        bm25(retrieval_documents_fts, 5.0, 1.0) AS rank
+      FROM retrieval_documents_fts
+      JOIN retrieval_documents d ON d.rowid = retrieval_documents_fts.rowid
+      WHERE retrieval_documents_fts MATCH ?
+        AND d.scope = ?${kindFilter}
+      ORDER BY rank ASC, d.document_id ASC
+      LIMIT ?
+    `).all(match, options.scope, ...kinds, limit);
+        return rows.map((row) => ({
+            id: row.id,
+            scope: row.scope,
+            kind: row.kind,
+            source: row.source,
+            title: row.title,
+            body: row.body,
+            metadata: parseMetadata(row.metadataJson),
+            // SQLite's FTS5 bm25() returns smaller values for better matches.
+            score: -row.rank,
+        }));
+    }
+    close() {
+        this.db.close();
+    }
+    migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS retrieval_documents (
+        rowid INTEGER PRIMARY KEY AUTOINCREMENT,
+        document_id TEXT NOT NULL,
+        scope TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        source TEXT NOT NULL,
+        title TEXT NOT NULL,
+        body TEXT NOT NULL,
+        title_tokens TEXT NOT NULL,
+        body_tokens TEXT NOT NULL,
+        metadata_json TEXT NOT NULL DEFAULT '{}',
+        content_hash TEXT NOT NULL,
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(scope, document_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_retrieval_documents_scope_kind
+        ON retrieval_documents(scope, kind);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS retrieval_documents_fts USING fts5(
+        title_tokens,
+        body_tokens,
+        content='retrieval_documents',
+        content_rowid='rowid'
+      );
+
+      CREATE TRIGGER IF NOT EXISTS retrieval_documents_ai AFTER INSERT ON retrieval_documents BEGIN
+        INSERT INTO retrieval_documents_fts(rowid, title_tokens, body_tokens)
+        VALUES (new.rowid, new.title_tokens, new.body_tokens);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS retrieval_documents_ad AFTER DELETE ON retrieval_documents BEGIN
+        INSERT INTO retrieval_documents_fts(retrieval_documents_fts, rowid, title_tokens, body_tokens)
+        VALUES ('delete', old.rowid, old.title_tokens, old.body_tokens);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS retrieval_documents_au AFTER UPDATE ON retrieval_documents BEGIN
+        INSERT INTO retrieval_documents_fts(retrieval_documents_fts, rowid, title_tokens, body_tokens)
+        VALUES ('delete', old.rowid, old.title_tokens, old.body_tokens);
+        INSERT INTO retrieval_documents_fts(rowid, title_tokens, body_tokens)
+        VALUES (new.rowid, new.title_tokens, new.body_tokens);
+      END;
+    `);
+    }
+}
+export function splitMarkdownForSearch(markdown) {
+    const segments = [];
+    let heading = "";
+    const blockPattern = /(?:^|\n)([^\n](?:[\s\S]*?))(?=\n\s*\n|$)/g;
+    for (const match of markdown.matchAll(blockPattern)) {
+        const raw = match[1] ?? "";
+        const leadingOffset = (match[0]?.length ?? raw.length) - raw.length;
+        const charStart = (match.index ?? 0) + leadingOffset;
+        const body = raw.trim();
+        if (!body)
+            continue;
+        const headingMatch = body.match(/^#{1,6}\s+(.+)$/);
+        if (headingMatch) {
+            heading = headingMatch[1]?.trim() ?? heading;
+            continue;
+        }
+        segments.push({
+            heading,
+            body,
+            charStart,
+            charEnd: charStart + raw.length,
+        });
+    }
+    return segments;
+}
+export function tokenizeSearchText(text) {
+    const normalized = text.normalize("NFKC").toLocaleLowerCase();
+    const segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+    const tokens = [];
+    for (const part of segmenter.segment(normalized)) {
+        const token = part.segment.trim();
+        if (!part.isWordLike || !token)
+            continue;
+        if (/^[\p{Script=Latin}\p{N}_-]+$/u.test(token) && token.length < 2)
+            continue;
+        tokens.push(token);
+    }
+    // ICU can segment short Chinese compounds into individual Han characters.
+    // Adjacent Han bigrams preserve those compounds for lexical retrieval; this
+    // is tokenizer mechanics, not a semantic intent rule.
+    const segmentedTokenCount = tokens.length;
+    for (let index = 0; index < segmentedTokenCount - 1; index += 1) {
+        const left = tokens[index] ?? "";
+        const right = tokens[index + 1] ?? "";
+        if (/^\p{Script=Han}$/u.test(left) && /^\p{Script=Han}$/u.test(right)) {
+            tokens.push(`${left}${right}`);
+        }
+    }
+    for (const match of normalized.matchAll(/[\p{L}\p{N}]+(?:[-_][\p{L}\p{N}]+)+/gu)) {
+        tokens.push(match[0]);
+    }
+    return tokens;
+}
+function buildMatchQuery(query) {
+    const tokens = [...new Set(tokenizeSearchText(query))].slice(0, 64);
+    return tokens.map((token) => `"${token.replaceAll('"', '""')}"`).join(" OR ");
+}
+function normalizeDocument(document, scope) {
+    const normalized = { ...document, scope };
+    const metadataJson = JSON.stringify(document.metadata ?? {});
+    const titleTokens = tokenizeSearchText(document.title).join(" ");
+    const bodyTokens = tokenizeSearchText(document.body).join(" ");
+    const contentHash = createHash("sha256")
+        .update([normalized.kind, normalized.source, normalized.title, normalized.body, metadataJson].join("\0"))
+        .digest("hex");
+    return {
+        ...normalized,
+        metadataJson,
+        titleTokens,
+        bodyTokens,
+        contentHash,
+    };
+}
+function parseMetadata(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=local-search.js.map