@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/discovery/glob.d.ts

@@ -0,0 +1,10 @@
+interface CompiledGlob {
+    readonly source: string;
+    readonly regex: RegExp;
+}
+export declare function compileGlob(glob: string): CompiledGlob;
+export declare function matchesGlob(glob: CompiledGlob, relativePath: string): boolean;
+export declare function matchesAny(globs: readonly CompiledGlob[], relativePath: string, defaultWhenEmpty: boolean): boolean;
+export declare function compileGlobList(globs: readonly string[] | undefined): readonly CompiledGlob[];
+export type { CompiledGlob };
+//# sourceMappingURL=glob.d.ts.map

package/dist/discovery/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/discovery/glob.ts"],"names":[],"mappings":"AAYA,UAAU,YAAY;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAmCD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAKtD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAE7E;AAMD,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,OAAO,GACxB,OAAO,CAUT;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,YAAY,EAAE,CAK7F;AAED,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/discovery/glob.js

@@ -0,0 +1,72 @@
+// Minimal glob matcher for KnowledgeSourceScope include/exclude lists (Issue #194).
+//
+// We intentionally support ONLY the safe subset: `*` matches any sequence of characters
+// EXCEPT `/`; `**` matches any sequence including `/`; `?` matches any single non-`/`
+// character. All other characters are literal. Brace expansion and character classes are
+// NOT supported — adding them now would let a malformed glob slip past the path-safety
+// gate, and callers who really need them can keep multiple entries instead.
+//
+// Pure function — no FS access, no clock, no regex source built from the input character-
+// for-character (which would risk ReDoS); we compile a single anchored RegExp per glob
+// with linear-time alternation only.
+const SPECIAL_RE = /[.+^${}()|[\]\\]/g;
+// Build the regex source from the glob in a single pass so we never call `new RegExp` on
+// an attacker-controlled string without escaping first. `**/` is treated as "zero or more
+// path segments" (so `**/*.md` matches `foo.md` AND `a/b/foo.md`), matching the standard
+// tooling convention; a bare `**` (not followed by `/`) matches any sequence including `/`.
+function compileGlobSource(glob) {
+    let out = "^";
+    for (let i = 0; i < glob.length; i += 1) {
+        const ch = glob[i] ?? "";
+        if (ch === "*") {
+            if (glob[i + 1] === "*") {
+                if (glob[i + 2] === "/") {
+                    out += "(?:.*/)?";
+                    i += 2;
+                    continue;
+                }
+                out += ".*";
+                i += 1;
+                continue;
+            }
+            out += "[^/]*";
+            continue;
+        }
+        if (ch === "?") {
+            out += "[^/]";
+            continue;
+        }
+        out += ch.replace(SPECIAL_RE, "\\$&");
+    }
+    return `${out}$`;
+}
+export function compileGlob(glob) {
+    const source = compileGlobSource(glob);
+    // The compiled pattern has bounded alternation (`.*`, `[^/]*`, `[^/]`, literals only),
+    // so backtracking is linear in input length — safe against ReDoS even on hostile globs.
+    return { source, regex: new RegExp(source) };
+}
+export function matchesGlob(glob, relativePath) {
+    return glob.regex.test(relativePath);
+}
+// Convenience: returns `true` when `relativePath` matches AT LEAST ONE of `globs`.
+// An empty `globs` list returns `defaultWhenEmpty` — that distinguishes the two scopes:
+//   * includeGlobs: default to "match everything" when unset.
+//   * excludeGlobs: default to "match nothing" when unset.
+export function matchesAny(globs, relativePath, defaultWhenEmpty) {
+    if (globs.length === 0) {
+        return defaultWhenEmpty;
+    }
+    for (const glob of globs) {
+        if (matchesGlob(glob, relativePath)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function compileGlobList(globs) {
+    if (globs === undefined || globs.length === 0) {
+        return [];
+    }
+    return globs.map((glob) => compileGlob(glob));
+}

package/dist/discovery/index.d.ts

@@ -0,0 +1,6 @@
+export { DEFAULT_DISCOVERY_OPTIONS, documentIdFor, type DiscoveredFile, type DiscoveryError, type DiscoveryErrorCode, type DiscoveryOptions, type ExtractionEvent, type ExtractionOutcome, type ExtractionResult, } from "./types.js";
+export { walkSource, type WalkYield } from "./walk.js";
+export { extractDocument, type ExtractDocumentDeps, type ExtractDocumentParams, } from "./extract.js";
+export { discoverAndExtract, type DiscoverAndExtractDeps, type DiscoverAndExtractParams, } from "./discovery-runner.js";
+export { extensionOf, mediaTypeFor } from "./media-type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/discovery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,yBAAyB,EACzB,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EACL,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/discovery/index.js

@@ -0,0 +1,8 @@
+// Public surface of the discovery + extraction bridge (Epic #189, Issue #194). Consumers
+// import everything from `@oscharko-dev/keiko-local-knowledge`; this module is the single
+// re-export point so the package barrel stays a flat list of names.
+export { DEFAULT_DISCOVERY_OPTIONS, documentIdFor, } from "./types.js";
+export { walkSource } from "./walk.js";
+export { extractDocument, } from "./extract.js";
+export { discoverAndExtract, } from "./discovery-runner.js";
+export { extensionOf, mediaTypeFor } from "./media-type.js";

package/dist/discovery/media-type.d.ts

@@ -0,0 +1,4 @@
+export declare function extensionOf(relativePath: string): string;
+export declare function mediaTypeFor(extension: string): string;
+export declare function basenameOf(relativePath: string): string;
+//# sourceMappingURL=media-type.d.ts.map

package/dist/discovery/media-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-type.d.ts","sourceRoot":"","sources":["../../src/discovery/media-type.ts"],"names":[],"mappings":"AAgDA,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGvD"}

package/dist/discovery/media-type.js

@@ -0,0 +1,62 @@
+// Pure extension/media-type lookup table (Issue #194). The discovery layer must give the
+// parser registry a `(extension, mediaType)` hint without sniffing the bytes. This table
+// covers the formats supported by the shipped adapters; unknown extensions fall through to
+// the unsupported sentinel, which then sniffs magic bytes.
+//
+// The mapping is intentionally NOT exhaustive — it's the minimal set that lets the parser
+// registry route correctly. Adding a new entry is a one-line change.
+const MEDIA_TYPES = Object.freeze({
+    // text-like
+    txt: "text/plain",
+    md: "text/markdown",
+    markdown: "text/markdown",
+    rst: "text/x-rst",
+    log: "text/plain",
+    ts: "text/x-typescript",
+    tsx: "text/x-typescript",
+    js: "text/javascript",
+    jsx: "text/javascript",
+    mjs: "text/javascript",
+    cjs: "text/javascript",
+    py: "text/x-python",
+    go: "text/x-go",
+    rs: "text/x-rust",
+    java: "text/x-java",
+    yaml: "text/yaml",
+    yml: "text/yaml",
+    // json
+    json: "application/json",
+    jsonl: "application/x-ndjson",
+    ndjson: "application/x-ndjson",
+    // csv / tsv
+    csv: "text/csv",
+    tsv: "text/tab-separated-values",
+    // html
+    html: "text/html",
+    htm: "text/html",
+    xhtml: "application/xhtml+xml",
+    // unsupported binaries (the unsupported adapter still classifies these explicitly)
+    pdf: "application/pdf",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+});
+export function extensionOf(relativePath) {
+    const slash = relativePath.lastIndexOf("/");
+    const basename = slash === -1 ? relativePath : relativePath.slice(slash + 1);
+    const dot = basename.lastIndexOf(".");
+    if (dot <= 0 || dot === basename.length - 1) {
+        return "";
+    }
+    return basename.slice(dot + 1).toLowerCase();
+}
+export function mediaTypeFor(extension) {
+    return MEDIA_TYPES[extension] ?? "";
+}
+export function basenameOf(relativePath) {
+    const slash = relativePath.lastIndexOf("/");
+    return slash === -1 ? relativePath : relativePath.slice(slash + 1);
+}

package/dist/discovery/persist.d.ts

@@ -0,0 +1,63 @@
+import type { DocumentId, KnowledgeCapsuleId, KnowledgeSourceId, PageRecord, ParsedUnit, ParserDiagnostic, SectionRecord } from "@oscharko-dev/keiko-contracts";
+import type { DatabaseSync } from "node:sqlite";
+import type { StoreContentCipher } from "../store-content-cipher.js";
+export interface DocumentInsertRow {
+    readonly id: DocumentId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: string;
+    readonly documentPath: string;
+    readonly sizeBytes: number;
+    readonly mediaType: string;
+    readonly contentHash: string;
+    readonly parserId: string;
+    readonly parserVersion: string;
+    readonly lastExtractedAt: number;
+    readonly status: string;
+    readonly safeDisplayName: string;
+}
+export declare function insertDocumentRow(db: DatabaseSync, row: DocumentInsertRow): void;
+export declare function deleteDependentRows(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): void;
+export declare function insertDocumentTextRow(db: DatabaseSync, cipher: StoreContentCipher, capsuleId: KnowledgeCapsuleId, documentId: DocumentId, normalizedText: string): void;
+export declare function readDocumentTextRow(db: DatabaseSync, cipher: StoreContentCipher, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): string | undefined;
+export interface DocumentTextWindowInsertRow {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly documentId: DocumentId;
+    readonly windowIndex: number;
+    readonly characterStart: number;
+    readonly characterEnd: number;
+    readonly normalizedText: string;
+}
+export declare function insertDocumentTextWindowRow(db: DatabaseSync, cipher: StoreContentCipher, row: DocumentTextWindowInsertRow): void;
+export declare function deleteDocumentTextWindows(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): void;
+export declare function readDocumentTextSpan(db: DatabaseSync, cipher: StoreContentCipher, capsuleId: KnowledgeCapsuleId, documentId: DocumentId, charStart: number, charEnd: number): string | undefined;
+export interface PersistedSourceDocumentRow {
+    readonly id: DocumentId;
+    readonly document_path: string;
+}
+export declare function listPersistedDocumentsForSource(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, sourceId: KnowledgeSourceId): readonly PersistedSourceDocumentRow[];
+export declare function deleteDocumentRow(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): void;
+export declare function updateDocumentStatusRow(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId, status: DocumentInsertRow["status"]): void;
+export declare function insertPageRow(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, page: PageRecord): void;
+export declare function insertSectionRow(db: DatabaseSync, cipher: StoreContentCipher, capsuleId: KnowledgeCapsuleId, section: SectionRecord): void;
+export declare function insertParsedUnitRow(db: DatabaseSync, cipher: StoreContentCipher, capsuleId: KnowledgeCapsuleId, unitId: string, unit: ParsedUnit): void;
+export declare function insertDiagnosticRow(db: DatabaseSync, params: {
+    readonly id: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly diagnostic: ParserDiagnostic;
+    readonly createdAt: number;
+}): void;
+interface ExistingDocumentRow {
+    readonly content_hash: string;
+    readonly status: string;
+    readonly size_bytes: number;
+    readonly media_type: string;
+    readonly parser_id: string;
+    readonly parser_version: string;
+    readonly last_extracted_at: number;
+    readonly safe_display_name: string;
+    readonly document_path: string;
+    readonly source_id: string;
+}
+export declare function readExistingDocumentRow(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): ExistingDocumentRow | undefined;
+export {};
+//# sourceMappingURL=persist.d.ts.map

package/dist/discovery/persist.d.ts.map

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

package/dist/discovery/persist.js

@@ -0,0 +1,345 @@
+// SQLite persistence helpers for the discovery layer (Issue #194). Every helper here is a
+// prepared-statement wrapper around a single table; the transaction boundary lives in
+// extract.ts so a per-file failure rolls back exactly the rows from that file.
+//
+// All inserts use REPLACE semantics on the document row (PRIMARY KEY id), but the
+// dependent rows (pages, sections, parsed_units, parser_diagnostics) are deleted first via
+// the documents-cascade chain — see deleteDependentRows. That keeps a re-extract idempotent:
+// running extract twice on the same file leaves exactly one set of rows on disk.
+import { sectionPathHash } from "../section-path-hash.js";
+const INSERT_DOCUMENT_SQL = [
+    "INSERT OR REPLACE INTO documents (",
+    "  id, capsule_id, source_id, document_path, size_bytes, media_type,",
+    "  content_hash, parser_id, parser_version, last_extracted_at, status, safe_display_name",
+    ") VALUES (",
+    "  :id, :capsule_id, :source_id, :document_path, :size_bytes, :media_type,",
+    "  :content_hash, :parser_id, :parser_version, :last_extracted_at, :status, :safe_display_name",
+    ")",
+].join(" ");
+const INSERT_DOCUMENT_TEXT_SQL = [
+    "INSERT OR REPLACE INTO document_texts (",
+    "  capsule_id, document_id, normalized_text",
+    ") VALUES (",
+    "  :capsule_id, :document_id, :normalized_text",
+    ")",
+].join(" ");
+const INSERT_PAGE_SQL = [
+    "INSERT INTO pages (",
+    "  capsule_id, document_id, page_number, page_label, character_start, character_end,",
+    "  bbox_x, bbox_y, bbox_w, bbox_h",
+    ") VALUES (",
+    "  :capsule_id, :document_id, :page_number, :page_label, :character_start, :character_end,",
+    "  :bbox_x, :bbox_y, :bbox_w, :bbox_h",
+    ")",
+].join(" ");
+const INSERT_SECTION_SQL = [
+    "INSERT INTO sections (",
+    "  capsule_id, document_id, section_path_json, section_path_hash, character_start, character_end",
+    ") VALUES (",
+    "  :capsule_id, :document_id, :section_path_json, :section_path_hash, :character_start, :character_end",
+    ")",
+].join(" ");
+const INSERT_PARSED_UNIT_SQL = [
+    "INSERT INTO parsed_units (",
+    "  id, capsule_id, document_id, kind, page_number, page_label, section_path_json,",
+    "  json_pointer, table_name, row_index, heading_path_json, unsupported_reason,",
+    "  character_start, character_end",
+    ") VALUES (",
+    "  :id, :capsule_id, :document_id, :kind, :page_number, :page_label, :section_path_json,",
+    "  :json_pointer, :table_name, :row_index, :heading_path_json, :unsupported_reason,",
+    "  :character_start, :character_end",
+    ")",
+].join(" ");
+const INSERT_DIAGNOSTIC_SQL = [
+    "INSERT INTO parser_diagnostics (",
+    "  id, capsule_id, document_id, severity, code, message, page_number, created_at",
+    ") VALUES (",
+    "  :id, :capsule_id, :document_id, :severity, :code, :message, :page_number, :created_at",
+    ")",
+].join(" ");
+const DELETE_PAGES_SQL = "DELETE FROM pages WHERE capsule_id = :c AND document_id = :d";
+const DELETE_SECTIONS_SQL = "DELETE FROM sections WHERE capsule_id = :c AND document_id = :d";
+const DELETE_DOCUMENT_TEXT_SQL = "DELETE FROM document_texts WHERE capsule_id = :c AND document_id = :d";
+const DELETE_PARSED_UNITS_SQL = "DELETE FROM parsed_units WHERE capsule_id = :c AND document_id = :d";
+const DELETE_DIAGNOSTICS_SQL = "DELETE FROM parser_diagnostics WHERE capsule_id = :c AND document_id = :d";
+const SELECT_DOCUMENT_TEXT_SQL = "SELECT normalized_text FROM document_texts WHERE capsule_id = :c AND document_id = :d";
+// ─── Bounded large-document text windows (Epic #1160, Issue #1286) ─────────────
+const INSERT_DOCUMENT_TEXT_WINDOW_SQL = [
+    "INSERT OR REPLACE INTO document_text_windows (",
+    "  capsule_id, document_id, window_index, character_start, character_end, normalized_text",
+    ") VALUES (",
+    "  :capsule_id, :document_id, :window_index, :character_start, :character_end, :normalized_text",
+    ")",
+].join(" ");
+const DELETE_DOCUMENT_TEXT_WINDOWS_SQL = "DELETE FROM document_text_windows WHERE capsule_id = :c AND document_id = :d";
+const DELETE_EXTRACTION_CHECKPOINT_SQL = "DELETE FROM extraction_checkpoints WHERE capsule_id = :c AND document_id = :d";
+// SQLite SUBSTR is 1-indexed; a document-relative char offset `s` maps to SUBSTR position `s + 1`.
+const SELECT_DOCUMENT_TEXT_SPAN_SQL = "SELECT SUBSTR(normalized_text, :start + 1, :len) AS span FROM document_texts WHERE capsule_id = :c AND document_id = :d";
+const SELECT_DOCUMENT_TEXT_WINDOW_SPAN_SQL = [
+    "SELECT SUBSTR(normalized_text, :start - character_start + 1, :len) AS span",
+    "FROM document_text_windows",
+    "WHERE capsule_id = :c AND document_id = :d AND character_start <= :start AND character_end >= :end",
+    "ORDER BY window_index ASC LIMIT 1",
+].join(" ");
+// Encrypted-store span read: SQLite SUBSTR cannot slice a sealed envelope, so the encrypted path
+// fetches the one bounded window that contains the span (with its character_start), decrypts that
+// single window, and slices in JS. Returns the whole sealed window text so the caller decrypts once.
+const SELECT_DOCUMENT_TEXT_WINDOW_FULL_SQL = [
+    "SELECT normalized_text, character_start AS character_start",
+    "FROM document_text_windows",
+    "WHERE capsule_id = :c AND document_id = :d AND character_start <= :start AND character_end >= :end",
+    "ORDER BY window_index ASC LIMIT 1",
+].join(" ");
+const SELECT_DOCUMENTS_FOR_SOURCE_SQL = [
+    "SELECT id, document_path FROM documents",
+    "WHERE capsule_id = :c AND source_id = :s",
+    "ORDER BY document_path ASC",
+].join(" ");
+const DELETE_DOCUMENT_SQL = "DELETE FROM documents WHERE capsule_id = :c AND id = :d";
+const UPDATE_DOCUMENT_STATUS_SQL = "UPDATE documents SET status = :status WHERE capsule_id = :c AND id = :d";
+const statementsByDb = new WeakMap();
+function statements(db) {
+    const cached = statementsByDb.get(db);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const prepared = {
+        insertDocument: db.prepare(INSERT_DOCUMENT_SQL),
+        insertDocumentText: db.prepare(INSERT_DOCUMENT_TEXT_SQL),
+        insertPage: db.prepare(INSERT_PAGE_SQL),
+        insertSection: db.prepare(INSERT_SECTION_SQL),
+        insertParsedUnit: db.prepare(INSERT_PARSED_UNIT_SQL),
+        insertDiagnostic: db.prepare(INSERT_DIAGNOSTIC_SQL),
+        deletePages: db.prepare(DELETE_PAGES_SQL),
+        deleteSections: db.prepare(DELETE_SECTIONS_SQL),
+        deleteDocumentText: db.prepare(DELETE_DOCUMENT_TEXT_SQL),
+        deleteParsedUnits: db.prepare(DELETE_PARSED_UNITS_SQL),
+        deleteDiagnostics: db.prepare(DELETE_DIAGNOSTICS_SQL),
+        deleteDocument: db.prepare(DELETE_DOCUMENT_SQL),
+        selectDocumentText: db.prepare(SELECT_DOCUMENT_TEXT_SQL),
+        insertDocumentTextWindow: db.prepare(INSERT_DOCUMENT_TEXT_WINDOW_SQL),
+        deleteDocumentTextWindows: db.prepare(DELETE_DOCUMENT_TEXT_WINDOWS_SQL),
+        deleteExtractionCheckpoint: db.prepare(DELETE_EXTRACTION_CHECKPOINT_SQL),
+        selectDocumentTextSpan: db.prepare(SELECT_DOCUMENT_TEXT_SPAN_SQL),
+        selectDocumentTextWindowSpan: db.prepare(SELECT_DOCUMENT_TEXT_WINDOW_SPAN_SQL),
+        selectDocumentTextWindowFull: db.prepare(SELECT_DOCUMENT_TEXT_WINDOW_FULL_SQL),
+        selectDocumentsForSource: db.prepare(SELECT_DOCUMENTS_FOR_SOURCE_SQL),
+    };
+    statementsByDb.set(db, prepared);
+    return prepared;
+}
+export function insertDocumentRow(db, row) {
+    statements(db).insertDocument.run({
+        id: row.id,
+        capsule_id: row.capsuleId,
+        source_id: row.sourceId,
+        document_path: row.documentPath,
+        size_bytes: row.sizeBytes,
+        media_type: row.mediaType,
+        content_hash: row.contentHash,
+        parser_id: row.parserId,
+        parser_version: row.parserVersion,
+        last_extracted_at: row.lastExtractedAt,
+        status: row.status,
+        safe_display_name: row.safeDisplayName,
+    });
+}
+export function deleteDependentRows(db, capsuleId, documentId) {
+    const params = { c: capsuleId, d: documentId };
+    statements(db).deleteDocumentText.run(params);
+    statements(db).deleteDocumentTextWindows.run(params);
+    statements(db).deleteExtractionCheckpoint.run(params);
+    statements(db).deletePages.run(params);
+    statements(db).deleteSections.run(params);
+    statements(db).deleteParsedUnits.run(params);
+    statements(db).deleteDiagnostics.run(params);
+}
+export function insertDocumentTextRow(db, cipher, capsuleId, documentId, normalizedText) {
+    statements(db).insertDocumentText.run({
+        capsule_id: capsuleId,
+        document_id: documentId,
+        normalized_text: cipher.sealText(normalizedText),
+    });
+}
+export function readDocumentTextRow(db, cipher, capsuleId, documentId) {
+    const row = statements(db).selectDocumentText.get({
+        c: capsuleId,
+        d: documentId,
+    });
+    return row === undefined ? undefined : cipher.openText(row.normalized_text);
+}
+export function insertDocumentTextWindowRow(db, cipher, row) {
+    statements(db).insertDocumentTextWindow.run({
+        capsule_id: String(row.capsuleId),
+        document_id: String(row.documentId),
+        window_index: row.windowIndex,
+        character_start: row.characterStart,
+        character_end: row.characterEnd,
+        normalized_text: cipher.sealText(row.normalizedText),
+    });
+}
+export function deleteDocumentTextWindows(db, capsuleId, documentId) {
+    statements(db).deleteDocumentTextWindows.run({ c: capsuleId, d: documentId });
+}
+// Reads a bounded, document-relative character span without ever materializing the whole
+// document text. Resolves from `document_texts` when a small file stored a single row, otherwise
+// from the one `document_text_windows` row that contains the span (every chunk lies inside one
+// page → one window). Returns undefined when no text is stored for the document.
+//
+// Plaintext stores slice the span in SQLite via SUBSTR so the whole column never enters JS. Encrypted
+// stores cannot SUBSTR a sealed envelope, so they decrypt exactly one bounded unit — the small-document
+// row or the single window that contains the span — and slice in JS. The Issue #1286 memory bound holds
+// either way: a window is bounded and a document_texts row is only used for small documents.
+export function readDocumentTextSpan(db, cipher, capsuleId, documentId, charStart, charEnd) {
+    const start = Math.max(0, Math.floor(charStart));
+    const end = Math.max(start, Math.floor(charEnd));
+    const len = end - start;
+    const c = String(capsuleId);
+    const d = String(documentId);
+    if (!cipher.isEncrypted) {
+        const single = statements(db).selectDocumentTextSpan.get({ c, d, start, len });
+        if (single !== undefined) {
+            return single.span ?? "";
+        }
+        const windowed = statements(db).selectDocumentTextWindowSpan.get({ c, d, start, end, len });
+        return windowed === undefined ? undefined : (windowed.span ?? "");
+    }
+    const single = statements(db).selectDocumentText.get({ c, d });
+    if (single !== undefined) {
+        return cipher.openText(single.normalized_text).slice(start, start + len);
+    }
+    const windowed = statements(db).selectDocumentTextWindowFull.get({ c, d, start, end });
+    if (windowed === undefined) {
+        return undefined;
+    }
+    const offset = start - windowed.character_start;
+    return cipher.openText(windowed.normalized_text).slice(offset, offset + len);
+}
+export function listPersistedDocumentsForSource(db, capsuleId, sourceId) {
+    const rows = statements(db).selectDocumentsForSource.all({
+        c: capsuleId,
+        s: sourceId,
+    });
+    return rows;
+}
+export function deleteDocumentRow(db, capsuleId, documentId) {
+    deleteDependentRows(db, capsuleId, documentId);
+    statements(db).deleteDocument.run({ c: capsuleId, d: documentId });
+}
+export function updateDocumentStatusRow(db, capsuleId, documentId, status) {
+    db.prepare(UPDATE_DOCUMENT_STATUS_SQL).run({
+        status,
+        c: capsuleId,
+        d: documentId,
+    });
+}
+export function insertPageRow(db, capsuleId, page) {
+    statements(db).insertPage.run({
+        capsule_id: capsuleId,
+        document_id: page.documentId,
+        page_number: page.pageNumber,
+        page_label: page.pageLabel ?? null,
+        character_start: page.characterStart,
+        character_end: page.characterEnd,
+        bbox_x: page.boundingBox?.x ?? null,
+        bbox_y: page.boundingBox?.y ?? null,
+        bbox_w: page.boundingBox?.w ?? null,
+        bbox_h: page.boundingBox?.h ?? null,
+    });
+}
+export function insertSectionRow(db, cipher, capsuleId, section) {
+    const sectionPathJson = JSON.stringify(section.sectionPath);
+    statements(db).insertSection.run({
+        capsule_id: capsuleId,
+        document_id: section.documentId,
+        section_path_json: cipher.sealText(sectionPathJson),
+        section_path_hash: sectionPathHash(section.sectionPath),
+        character_start: section.characterStart,
+        character_end: section.characterEnd,
+    });
+}
+function parsedUnitParams(cipher, capsuleId, unitId, unit) {
+    const base = {
+        id: unitId,
+        capsule_id: String(capsuleId),
+        document_id: String(unit.documentId),
+        kind: unit.kind,
+        page_number: null,
+        page_label: null,
+        section_path_json: null,
+        json_pointer: null,
+        table_name: null,
+        row_index: null,
+        heading_path_json: null,
+        unsupported_reason: null,
+        character_start: null,
+        character_end: null,
+    };
+    return populateUnitFields(base, unit, cipher);
+}
+function populateUnitFields(base, unit, cipher) {
+    if (unit.kind === "page") {
+        return {
+            ...base,
+            page_number: unit.pageNumber,
+            page_label: unit.pageLabel ?? null,
+            character_start: unit.characterStart,
+            character_end: unit.characterEnd,
+        };
+    }
+    if (unit.kind === "section") {
+        return {
+            ...base,
+            section_path_json: cipher.sealText(JSON.stringify(unit.sectionPath)),
+            character_start: unit.characterStart,
+            character_end: unit.characterEnd,
+        };
+    }
+    if (unit.kind === "json-path") {
+        return {
+            ...base,
+            json_pointer: unit.jsonPointer,
+            character_start: unit.characterStart,
+            character_end: unit.characterEnd,
+        };
+    }
+    if (unit.kind === "csv-row") {
+        return {
+            ...base,
+            table_name: unit.tableName,
+            row_index: unit.rowIndex,
+            character_start: unit.characterStart,
+            character_end: unit.characterEnd,
+        };
+    }
+    if (unit.kind === "html-block") {
+        return {
+            ...base,
+            heading_path_json: unit.headingPath !== undefined ? cipher.sealText(JSON.stringify(unit.headingPath)) : null,
+            character_start: unit.characterStart,
+            character_end: unit.characterEnd,
+        };
+    }
+    return { ...base, unsupported_reason: unit.reason };
+}
+export function insertParsedUnitRow(db, cipher, capsuleId, unitId, unit) {
+    statements(db).insertParsedUnit.run(parsedUnitParams(cipher, capsuleId, unitId, unit));
+}
+export function insertDiagnosticRow(db, params) {
+    statements(db).insertDiagnostic.run({
+        id: params.id,
+        capsule_id: params.capsuleId,
+        document_id: params.diagnostic.documentId ?? null,
+        severity: params.diagnostic.severity,
+        code: params.diagnostic.code,
+        message: params.diagnostic.message,
+        page_number: params.diagnostic.pageNumber ?? null,
+        created_at: params.createdAt,
+    });
+}
+export function readExistingDocumentRow(db, capsuleId, documentId) {
+    const row = db
+        .prepare("SELECT * FROM documents WHERE capsule_id = :c AND id = :d")
+        .get({ c: capsuleId, d: documentId });
+    return row === undefined ? undefined : row;
+}

package/dist/discovery/test-support.d.ts

@@ -0,0 +1,16 @@
+import type { KnowledgeSourceScope } from "@oscharko-dev/keiko-contracts";
+import type { WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+export interface MemoryFsFile {
+    readonly relativePath: string;
+    readonly content: string | Uint8Array;
+    readonly realPathOverride?: string;
+    readonly hardLinkCount?: number;
+    readonly isSymbolicLink?: boolean;
+}
+export declare function memoryFs(root: string, files: readonly MemoryFsFile[]): WorkspaceFs;
+export declare function folderScope(rootPath: string, options?: {
+    readonly recursive?: boolean;
+    readonly includeGlobs?: readonly string[];
+    readonly excludeGlobs?: readonly string[];
+}): KnowledgeSourceScope;
+//# sourceMappingURL=test-support.d.ts.map

package/dist/discovery/test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-support.d.ts","sourceRoot":"","sources":["../../src/discovery/test-support.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAqB,WAAW,EAAiB,MAAM,+BAA+B,CAAC;AAmDnG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA4CD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,CA4ClF;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,GACL,oBAAoB,CAWtB"}