@oscharko-dev/keiko 0.2.0-beta.4 → 0.2.0-beta.6

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/parsers/xlsx-parser.js

@@ -0,0 +1,425 @@
+import { Buffer } from "node:buffer";
+import yauzl from "yauzl";
+import { decodeXmlEntities, diagnostic, emptyResult, objectLimitDiagnostic, oversizeDiagnostic, shouldStop, } from "./_internal.js";
+const PARSER_ID = "xlsx";
+const PARSER_VERSION = "1";
+const DEPENDENCY_VERSIONS = Object.freeze([
+    Object.freeze({ packageName: "yauzl", version: "3.4.0" }),
+]);
+const XLSX_MEDIA = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+const MAX_XML_INFLATED_BYTES = 32 * 1024 * 1024;
+const MAX_XML_INFLATE_RATIO = 100;
+const SHEET_ENTRY_PREFIX = "xl/worksheets/";
+function isXlsx(input) {
+    const ext = input.extension.toLowerCase();
+    const media = input.mediaType.toLowerCase();
+    return ext === "xlsx" || media === XLSX_MEDIA;
+}
+function cancelled(capability, input, options) {
+    return emptyResult(capability, input.documentId, options, [
+        diagnostic("PARSER_CANCELLED", "caller aborted parser", input.documentId, "info"),
+    ]);
+}
+function syncFallback(capability) {
+    return (input, options) => emptyResult(capability, input.documentId, options, [
+        diagnostic("UNSUPPORTED_FORMAT", "xlsx parser requires async caller; use parseAsync via discovery", input.documentId, "info"),
+    ], [{ kind: "unsupported-media", documentId: input.documentId, reason: "xlsx-async-required" }]);
+}
+function toError(error, fallback) {
+    return error instanceof Error ? error : new Error(fallback);
+}
+function closeZipQuietly(zip) {
+    try {
+        zip.close();
+    }
+    catch {
+        // Close failures are non-fatal during parser cleanup.
+    }
+}
+function openZip(bytes) {
+    return new Promise((resolve, reject) => {
+        yauzl.fromBuffer(Buffer.from(bytes), { lazyEntries: true, decodeStrings: true }, (error, zip) => {
+            if (error !== null) {
+                reject(toError(error, "failed to open xlsx zip"));
+                return;
+            }
+            resolve(zip);
+        });
+    });
+}
+function maxInflatedEntryBytes(maxInputBytes) {
+    const inputCap = Math.max(1, Math.floor(maxInputBytes));
+    return Math.min(MAX_XML_INFLATED_BYTES, inputCap * 10);
+}
+function isRelevantEntry(name) {
+    return (name === "xl/workbook.xml" ||
+        name === "xl/_rels/workbook.xml.rels" ||
+        name === "xl/sharedStrings.xml" ||
+        (name.startsWith(SHEET_ENTRY_PREFIX) && name.endsWith(".xml")));
+}
+function assertEntryWithinLimits(entry, maxInflatedBytes) {
+    if (entry.uncompressedSize > maxInflatedBytes) {
+        throw new Error("xlsx xml inflated size exceeds parser limit");
+    }
+    if (entry.compressedSize > 0 &&
+        entry.uncompressedSize / entry.compressedSize > MAX_XML_INFLATE_RATIO) {
+        throw new Error("xlsx xml compression ratio exceeds parser limit");
+    }
+}
+function destroyStream(readStream, error) {
+    const destroy = readStream.destroy;
+    if (typeof destroy === "function") {
+        destroy.call(readStream, error);
+    }
+}
+function readEntryText(zip, entry, maxInflatedBytes) {
+    assertEntryWithinLimits(entry, maxInflatedBytes);
+    return new Promise((resolve, reject) => {
+        zip.openReadStream(entry, (error, stream) => {
+            if (error !== null) {
+                reject(toError(error, "failed to open xlsx entry stream"));
+                return;
+            }
+            const readStream = stream;
+            const chunks = [];
+            let inflatedBytes = 0;
+            let settled = false;
+            const rejectOnce = (streamError) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(streamError);
+                destroyStream(readStream, streamError);
+            };
+            readStream.on("data", (chunk) => {
+                if (settled)
+                    return;
+                inflatedBytes += chunk.byteLength;
+                if (inflatedBytes > maxInflatedBytes) {
+                    rejectOnce(new Error("xlsx xml inflated stream exceeds parser limit"));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            readStream.on("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            });
+            readStream.on("error", (streamError) => {
+                rejectOnce(streamError);
+            });
+        });
+    });
+}
+function removeZipEntryListeners(zip, listeners) {
+    zip.removeListener("entry", listeners.onEntry);
+    zip.removeListener("end", listeners.onEnd);
+    zip.removeListener("error", listeners.onError);
+}
+function readRelevantEntries(zip, maxInflatedBytes) {
+    return new Promise((resolve, reject) => {
+        const entries = [];
+        let settled = false;
+        const resolveOnce = () => {
+            if (settled)
+                return;
+            settled = true;
+            removeZipEntryListeners(zip, { onEntry, onEnd, onError });
+            resolve(entries);
+        };
+        const rejectOnce = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            removeZipEntryListeners(zip, { onEntry, onEnd, onError });
+            reject(error);
+        };
+        const onEnd = () => {
+            resolveOnce();
+        };
+        const onError = (error) => {
+            rejectOnce(toError(error, "failed to read xlsx zip"));
+        };
+        const handleEntry = async (entry) => {
+            if (!isRelevantEntry(entry.fileName)) {
+                zip.readEntry();
+                return;
+            }
+            try {
+                const xml = await readEntryText(zip, entry, maxInflatedBytes);
+                entries.push({ name: entry.fileName, xml });
+                zip.readEntry();
+            }
+            catch (error) {
+                rejectOnce(toError(error, "failed to read xlsx entry"));
+            }
+        };
+        const onEntry = (entry) => {
+            void handleEntry(entry);
+        };
+        zip.on("entry", onEntry);
+        zip.on("end", onEnd);
+        zip.on("error", onError);
+        zip.readEntry();
+    });
+}
+// GRD-027: delegate to the shared decoder so cell text resolves numeric character references
+// (smart quotes, accents) instead of surfacing literal `’`.
+function decodeXml(value) {
+    return decodeXmlEntities(value);
+}
+function attribute(tag, name) {
+    const pattern = new RegExp(`(?:^|\\s)${name}="([^"]*)"`, "u");
+    const match = pattern.exec(tag);
+    return match?.[1] === undefined ? undefined : decodeXml(match[1]);
+}
+function xmlTextContent(value) {
+    let out = "";
+    let inTag = false;
+    for (const char of value) {
+        if (char === "<") {
+            inTag = true;
+            continue;
+        }
+        if (inTag) {
+            if (char === ">")
+                inTag = false;
+            continue;
+        }
+        out += char;
+    }
+    return decodeXml(out);
+}
+function parseSharedStrings(xml, input, options) {
+    const strings = [];
+    const diagnostics = [];
+    const startedAt = options.now();
+    const itemPattern = /<si\b[\s\S]*?<\/si>/gi;
+    let match;
+    while ((match = itemPattern.exec(xml)) !== null) {
+        const limit = shouldStop(startedAt, options, strings.length);
+        if (limit.stop && limit.code !== undefined && limit.message !== undefined) {
+            diagnostics.push(diagnostic(limit.code, limit.message, input.documentId, "info"));
+            break;
+        }
+        if (strings.length >= options.maxObjectsPerDocument) {
+            diagnostics.push(objectLimitDiagnostic(input.documentId, options.maxObjectsPerDocument));
+            break;
+        }
+        const itemXml = match[0];
+        const parts = [...itemXml.matchAll(/<t\b[^>]*>([\s\S]*?)<\/t>/gi)].map((part) => decodeXml(part[1] ?? ""));
+        strings.push(parts.length > 0 ? parts.join("") : xmlTextContent(itemXml));
+    }
+    return { strings, diagnostics };
+}
+function parseRelationships(xml) {
+    const rels = new Map();
+    for (const match of xml.matchAll(/<Relationship\b[^>]*>/gi)) {
+        const tag = match[0];
+        const id = attribute(tag, "Id");
+        const target = attribute(tag, "Target");
+        if (id === undefined || target === undefined)
+            continue;
+        rels.set(id, target.startsWith("/") ? target.slice(1) : `xl/${target.replace(/^\.\//u, "")}`);
+    }
+    return rels;
+}
+function parseWorkbookSheets(workbookXml, relsXml, worksheetEntries) {
+    const rels = relsXml === undefined ? new Map() : parseRelationships(relsXml);
+    const sheets = [];
+    if (workbookXml !== undefined) {
+        for (const match of workbookXml.matchAll(/<sheet\b[^>]*>/gi)) {
+            const tag = match[0];
+            const name = attribute(tag, "name") ?? "Sheet";
+            const relId = attribute(tag, "r:id");
+            const entryName = relId === undefined ? undefined : rels.get(relId);
+            if (entryName !== undefined)
+                sheets.push({ name, entryName });
+        }
+    }
+    if (sheets.length > 0)
+        return sheets;
+    return worksheetEntries
+        .map((entry, index) => ({ name: `Sheet${String(index + 1)}`, entryName: entry.name }))
+        .sort((a, b) => a.entryName.localeCompare(b.entryName));
+}
+function columnName(ref, fallbackIndex) {
+    if (ref !== undefined) {
+        const match = /^([A-Z]+)/iu.exec(ref);
+        if (match?.[1] !== undefined)
+            return match[1].toUpperCase();
+    }
+    let n = fallbackIndex + 1;
+    let out = "";
+    while (n > 0) {
+        const rem = (n - 1) % 26;
+        out = String.fromCharCode(65 + rem) + out;
+        n = Math.floor((n - 1) / 26);
+    }
+    return out;
+}
+function rowNumber(rowTag, fallback) {
+    const raw = attribute(rowTag, "r");
+    if (raw === undefined)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function inlineStringValue(cellXml) {
+    const inline = /<is\b[\s\S]*?<\/is>/iu.exec(cellXml)?.[0];
+    if (inline === undefined)
+        return "";
+    return [...inline.matchAll(/<t\b[^>]*>([\s\S]*?)<\/t>/gi)]
+        .map((part) => decodeXml(part[1] ?? ""))
+        .join("");
+}
+function rawCellValue(type, raw, sharedStrings) {
+    const decoded = decodeXml(raw);
+    if (type !== "s")
+        return decoded;
+    const index = Number.parseInt(decoded, 10);
+    return Number.isFinite(index) ? (sharedStrings[index] ?? "") : "";
+}
+function formulaCellValue(cellXml) {
+    const formula = /<f\b[^>]*>([\s\S]*?)<\/f>/iu.exec(cellXml)?.[1];
+    return formula === undefined ? "" : `=${decodeXml(formula)}`;
+}
+function cellValue(cellXml, sharedStrings) {
+    const tag = /^<c\b[^>]*>/iu.exec(cellXml)?.[0] ?? "";
+    const type = attribute(tag, "t");
+    if (type === "inlineStr")
+        return inlineStringValue(cellXml);
+    const raw = /<v\b[^>]*>([\s\S]*?)<\/v>/iu.exec(cellXml)?.[1];
+    if (raw !== undefined)
+        return rawCellValue(type, raw, sharedStrings);
+    return formulaCellValue(cellXml);
+}
+function projectSheetRows(sheetName, xml, sharedStrings) {
+    const rows = [];
+    let fallbackRow = 1;
+    for (const rowMatch of xml.matchAll(/<row\b[^>]*>[\s\S]*?<\/row>/gi)) {
+        const rowXml = rowMatch[0];
+        const rowTag = /^<row\b[^>]*>/iu.exec(rowXml)?.[0] ?? "";
+        const number = rowNumber(rowTag, fallbackRow);
+        fallbackRow = number + 1;
+        const cells = [];
+        let fallbackCol = 0;
+        for (const cellMatch of rowXml.matchAll(/<c\b[^>]*>[\s\S]*?<\/c>/gi)) {
+            const cellXml = cellMatch[0];
+            const cellTag = /^<c\b[^>]*>/iu.exec(cellXml)?.[0] ?? "";
+            const value = cellValue(cellXml, sharedStrings).trim();
+            if (value.length === 0) {
+                fallbackCol += 1;
+                continue;
+            }
+            cells.push({ column: columnName(attribute(cellTag, "r"), fallbackCol), value });
+            fallbackCol += 1;
+        }
+        if (cells.length === 0)
+            continue;
+        rows.push({
+            sheetName,
+            rowNumber: number,
+            text: `${sheetName}!${String(number)}: ${cells
+                .map((cell) => `${cell.column}=${cell.value}`)
+                .join(" | ")}\n`,
+        });
+    }
+    return rows;
+}
+function emitUnits(rows, input, options) {
+    const units = [];
+    const diagnostics = [];
+    const parts = [];
+    let offset = 0;
+    const startedAt = options.now();
+    for (const row of rows) {
+        const limit = shouldStop(startedAt, options, units.length);
+        if (limit.stop && limit.code !== undefined && limit.message !== undefined) {
+            diagnostics.push(diagnostic(limit.code, limit.message, input.documentId, "info"));
+            break;
+        }
+        const start = offset;
+        parts.push(row.text);
+        offset += row.text.length;
+        units.push({
+            kind: "csv-row",
+            documentId: input.documentId,
+            tableName: row.sheetName,
+            rowIndex: Math.max(0, row.rowNumber - 1),
+            characterStart: start,
+            characterEnd: offset,
+        });
+    }
+    return { units, diagnostics, normalizedText: parts.join("") };
+}
+function parseWorkbook(entries, input, options) {
+    const byName = new Map(entries.map((entry) => [entry.name, entry.xml]));
+    const shared = byName.get("xl/sharedStrings.xml");
+    const sharedResult = shared === undefined
+        ? { strings: [], diagnostics: [] }
+        : parseSharedStrings(shared, input, options);
+    if (sharedResult.diagnostics.some((entry) => entry.severity === "error")) {
+        return emptyResult(xlsxParser.capability, input.documentId, options, sharedResult.diagnostics);
+    }
+    const worksheetEntries = entries.filter((entry) => entry.name.startsWith(SHEET_ENTRY_PREFIX));
+    const workbookSheets = parseWorkbookSheets(byName.get("xl/workbook.xml"), byName.get("xl/_rels/workbook.xml.rels"), worksheetEntries);
+    const rows = [];
+    for (const sheet of workbookSheets) {
+        const xml = byName.get(sheet.entryName);
+        if (xml === undefined)
+            continue;
+        rows.push(...projectSheetRows(sheet.name, xml, sharedResult.strings));
+        if (rows.length > options.maxObjectsPerDocument) {
+            return emptyResult(xlsxParser.capability, input.documentId, options, [
+                objectLimitDiagnostic(input.documentId, options.maxObjectsPerDocument),
+            ]);
+        }
+    }
+    const emitted = emitUnits(rows, input, options);
+    return {
+        ...emptyResult(xlsxParser.capability, input.documentId, options, [...sharedResult.diagnostics, ...emitted.diagnostics], emitted.units),
+        normalizedText: emitted.normalizedText,
+    };
+}
+export const xlsxParser = Object.freeze({
+    capability: Object.freeze({
+        parserId: PARSER_ID,
+        parserVersion: PARSER_VERSION,
+        dependencyVersions: DEPENDENCY_VERSIONS,
+        matches: (input) => isXlsx(input),
+    }),
+    parse: syncFallback({
+        parserId: PARSER_ID,
+        parserVersion: PARSER_VERSION,
+        dependencyVersions: DEPENDENCY_VERSIONS,
+        matches: (input) => isXlsx(input),
+    }),
+    parseAsync: async (input, options) => {
+        if (input.bytes.byteLength > options.maxBytes) {
+            return emptyResult(xlsxParser.capability, input.documentId, options, [
+                oversizeDiagnostic(input.documentId, input.bytes.byteLength, options.maxBytes),
+            ]);
+        }
+        if (options.signal?.aborted === true) {
+            return cancelled(xlsxParser.capability, input, options);
+        }
+        try {
+            const zip = await openZip(input.bytes);
+            try {
+                const entries = await readRelevantEntries(zip, maxInflatedEntryBytes(options.maxBytes));
+                return parseWorkbook(entries, input, options);
+            }
+            finally {
+                closeZipQuietly(zip);
+            }
+        }
+        catch {
+            return emptyResult(xlsxParser.capability, input.documentId, options, [
+                diagnostic("MALFORMED_INPUT", "xlsx parser rejected malformed or unsupported workbook", input.documentId, "error"),
+            ]);
+        }
+    },
+});

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/privacy/retention-applier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retention-applier.d.ts","sourceRoot":"","sources":["../../src/privacy/retention-applier.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,+BAA+B,CAAC;AAG3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AA8D/F,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,cAAc,GACzB,oBAAoB,CA4CtB"}
+{"version":3,"file":"retention-applier.d.ts","sourceRoot":"","sources":["../../src/privacy/retention-applier.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,+BAA+B,CAAC;AAG3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAiE/F,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,cAAc,GACzB,oBAAoB,CA4CtB"}

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/qualityIntelligence/capsuleCorpus.d.ts

@@ -4,12 +4,17 @@ export interface CapsuleDocumentText {
     readonly documentId: string;
     readonly text: string;
 }
+export interface ListCapsuleDocumentTextsOptions {
+    /** Maximum number of documents to return (SQL LIMIT). Defaults to 10 000. */
+    readonly maxDocuments?: number;
+}
 /**
- * Returns the full normalized text for every indexed document in a capsule, ordered by
- * document_id for deterministic output. Documents with empty text are skipped. Sync — reads the
- * node:sqlite handle directly like the capsule-lifecycle queries.
+ * Returns the full normalized text for up to `maxDocuments` indexed documents in a
+ * capsule, ordered by document_id for deterministic output. Documents with empty text
+ * are skipped. Sync — reads the node:sqlite handle directly like the capsule-lifecycle
+ * queries.
  */
-export declare function listCapsuleDocumentTexts(store: KnowledgeStore, capsuleId: string | KnowledgeCapsuleId): readonly CapsuleDocumentText[];
+export declare function listCapsuleDocumentTexts(store: KnowledgeStore, capsuleId: string | KnowledgeCapsuleId, options?: ListCapsuleDocumentTextsOptions): readonly CapsuleDocumentText[];
 /**
  * Returns the full corpus text for every member capsule of a capsule-set, concatenated in
  * membership order (ordinal). Each member's documents stay ordered by document_id. An unknown

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/qualityIntelligence/capsuleCorpus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capsuleCorpus.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/capsuleCorpus.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAKD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,GAAG,kBAAkB,GACrC,SAAS,mBAAmB,EAAE,CAWhC;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,GAAG,YAAY,GAClC,SAAS,mBAAmB,EAAE,CAUhC"}
+{"version":3,"file":"capsuleCorpus.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/capsuleCorpus.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,+BAA+B;IAC9C,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,GAAG,kBAAkB,EACtC,OAAO,GAAE,+BAAoC,GAC5C,SAAS,mBAAmB,EAAE,CAchC;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,GAAG,YAAY,GAClC,SAAS,mBAAmB,EAAE,CAUhC"}

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/qualityIntelligence/capsuleCorpus.js

@@ -8,14 +8,19 @@
 // SYNC: keiko-local-knowledge uses node:sqlite (synchronous API) throughout; this function
 // follows the same pattern used in capsule-lifecycle.ts (_internal.db.prepare().all()).
 import { getCapsuleSet } from "../capsule-set-lifecycle.js";
-const SELECT_DOCUMENT_TEXTS_SQL = "SELECT document_id, normalized_text FROM document_texts WHERE capsule_id = ? ORDER BY document_id";
+// Safe default: caps the in-process document load to prevent unbounded memory
+// consumption on large capsules. Callers may override with a smaller value.
+const DEFAULT_MAX_DOCUMENTS = 10_000;
 /**
- * Returns the full normalized text for every indexed document in a capsule, ordered by
- * document_id for deterministic output. Documents with empty text are skipped. Sync — reads the
- * node:sqlite handle directly like the capsule-lifecycle queries.
+ * Returns the full normalized text for up to `maxDocuments` indexed documents in a
+ * capsule, ordered by document_id for deterministic output. Documents with empty text
+ * are skipped. Sync — reads the node:sqlite handle directly like the capsule-lifecycle
+ * queries.
  */
-export function listCapsuleDocumentTexts(store, capsuleId) {
-    const rows = store._internal.db.prepare(SELECT_DOCUMENT_TEXTS_SQL).all(String(capsuleId));
+export function listCapsuleDocumentTexts(store, capsuleId, options = {}) {
+    const limit = options.maxDocuments ?? DEFAULT_MAX_DOCUMENTS;
+    const sql = "SELECT document_id, normalized_text FROM document_texts WHERE capsule_id = ? ORDER BY document_id LIMIT ?";
+    const rows = store._internal.db.prepare(sql).all(String(capsuleId), limit);
     const result = [];
     for (const row of rows) {
         const documentId = row.document_id;

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/retrieval/retrieval-runner.js

@@ -130,13 +130,26 @@ function finaliseWithGrounding(search, policy) {
         };
     }
     if (search.references.length === 0) {
+        // Surface the policy-specific reason ('no-evidence-stated') ONLY when the search actually ran
+        // over indexed content and nothing cleared the bar ('below-min-score'). For hard pre-search
+        // misses ('no-vectors' = nothing indexed, 'embedding-failed', 'empty-query',
+        // 'incompatible-embedding-identity') the search-layer reason is the actionable one and MUST be
+        // preserved — collapsing those into 'no-evidence-stated' would destroy exactly the distinction
+        // this fix is meant to expose: 'nothing indexed' vs 'searched, found nothing relevant'.
+        const reason = decision.reason === "no-evidence-stated" && search.noEvidenceReason === "below-min-score"
+            ? "no-evidence-stated"
+            : search.noEvidenceReason;
         return {
             references: [],
             noEvidence: true,
-            ...(search.noEvidenceReason !== undefined ? { reason: search.noEvidenceReason } : {}),
+            ...(reason !== undefined ? { reason } : {}),
         };
     }
-    return { references: search.references, noEvidence: false };
+    return {
+        references: search.references,
+        noEvidence: false,
+        ...(search.embeddingDegraded === true ? { embeddingDegraded: true } : {}),
+    };
 }
 function clampTopK(input) {
     if (input === undefined)

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/retrieval/scoped-vector-search.d.ts

@@ -18,6 +18,7 @@ export declare function toScopeInput(scope: ComposedRetrievalScope | {
 export interface SearchOutcome {
     readonly references: readonly RetrievalReference[];
     readonly noEvidenceReason?: "no-vectors" | "incompatible-embedding-identity" | "below-min-score" | "embedding-failed";
+    readonly embeddingDegraded?: true;
 }
 export declare function searchVectorsForScope(store: KnowledgeStore, embeddingAdapter: OpenAIEmbeddingAdapter, scope: RetrievalScopeInput, query: string, options: SearchOptions): Promise<SearchOutcome>;
 //# sourceMappingURL=scoped-vector-search.d.ts.map

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/retrieval/scoped-vector-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scoped-vector-search.d.ts","sourceRoot":"","sources":["../../src/retrieval/scoped-vector-search.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAKV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAGhF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAyDlD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;CAC7D;AAeD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,sBAAsB,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,GACzE,mBAAmB,CAKrB;AA0TD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAGnD,QAAQ,CAAC,gBAAgB,CAAC,EACtB,YAAY,GACZ,iCAAiC,GACjC,iBAAiB,GACjB,kBAAkB,CAAC;CACxB;AA8GD,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,cAAc,EACrB,gBAAgB,EAAE,sBAAsB,EACxC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,aAAa,CAAC,CAuBxB"}
+{"version":3,"file":"scoped-vector-search.d.ts","sourceRoot":"","sources":["../../src/retrieval/scoped-vector-search.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAKV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAGhF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA4DlD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;CAC7D;AAgBD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,sBAAsB,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,GACzE,mBAAmB,CAKrB;AA+iBD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAGnD,QAAQ,CAAC,gBAAgB,CAAC,EACtB,YAAY,GACZ,iCAAiC,GACjC,iBAAiB,GACjB,kBAAkB,CAAC;IAIvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;CACnC;AA+GD,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,cAAc,EACrB,gBAAgB,EAAE,sBAAsB,EACxC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,aAAa,CAAC,CAsCxB"}