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

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

@@ -12,12 +12,57 @@
 // native dependency we have explicitly avoided in `@oscharko-dev/keiko-local-knowledge`.
 import { getCapsule } from "../capsule-lifecycle.js";
 import { RetrievalError } from "./types.js";
+const SEARCH_EXCERPT_MAX_CHARS = 1_600;
+const SEARCH_CONTEXT_BEFORE_CHARS = 420;
+const EXACT_TERM_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}._:/#-]{2,}/gu;
+const BROAD_QUERY_PATTERN = /\b(compare|comparez|summari[sz]e|overview|explain|describe|analyse|analyze|erkl[aä]re|ueberblick|überblick|vergleiche|zusammenfassung)\b/iu;
+const SEARCH_STOPWORDS = new Set([
+    "a",
+    "about",
+    "and",
+    "are",
+    "auf",
+    "aus",
+    "bei",
+    "das",
+    "der",
+    "die",
+    "ein",
+    "eine",
+    "einen",
+    "einer",
+    "eines",
+    "for",
+    "from",
+    "how",
+    "in",
+    "ist",
+    "mit",
+    "of",
+    "on",
+    "oder",
+    "sagen",
+    "steht",
+    "the",
+    "to",
+    "und",
+    "uber",
+    "ueber",
+    "über",
+    "von",
+    "was",
+    "what",
+    "wie",
+    "zu",
+    "zum",
+    "zur",
+]);
 // ─── Compose a scope object from either `ComposedRetrievalScope` or a single capsule ────
 export function toScopeInput(scope) {
     if ("capsuleId" in scope) {
         return { capsuleIds: [scope.capsuleId] };
     }
-    return { capsuleIds: scope.capsuleIds };
+    return { capsuleIds: scope.capsuleIds, sourceFilter: scope.sourceIds };
 }
 const SELECT_VECTORS_FOR_CAPSULE_SQL = [
     "SELECT chunk_id, capsule_id, source_id, document_id, embedding,",
@@ -25,10 +70,21 @@ const SELECT_VECTORS_FOR_CAPSULE_SQL = [
     "FROM vectors",
     "WHERE capsule_id = :c",
 ].join(" ");
-function readVectorsForCapsule(store, capsuleId) {
+function readVectorsForCapsule(store, capsuleId, sourceFilter) {
+    if (sourceFilter?.length === 0)
+        return [];
+    const params = { c: String(capsuleId) };
+    const sourceClause = sourceFilter === undefined
+        ? ""
+        : ` AND source_id IN (${sourceFilter.map((_, i) => `:s${String(i)}`).join(", ")})`;
+    if (sourceFilter !== undefined) {
+        for (let i = 0; i < sourceFilter.length; i += 1) {
+            params[`s${String(i)}`] = String(sourceFilter[i]);
+        }
+    }
     const rows = store._internal.db
-        .prepare(SELECT_VECTORS_FOR_CAPSULE_SQL)
-        .all({ c: String(capsuleId) });
+        .prepare(`${SELECT_VECTORS_FOR_CAPSULE_SQL}${sourceClause}`)
+        .all(params);
     return rows;
 }
 function readCitationRows(store, capsuleId, chunkIds) {
@@ -38,8 +94,24 @@ function readCitationRows(store, capsuleId, chunkIds) {
     const sql = [
         "SELECT c.id AS chunk_id, c.capsule_id, c.source_id, c.document_id,",
         "  d.safe_display_name AS safe_display_name,",
-        "  pu.page_number, pu.page_label, pu.section_path_json,",
-        "  pu.character_start, pu.character_end",
+        "  COALESCE(pu.page_number, (",
+        "    SELECT p.page_number FROM pages p",
+        "    WHERE p.capsule_id = c.capsule_id AND p.document_id = c.document_id",
+        "      AND p.character_start <= COALESCE(c.character_start, pu.character_start)",
+        "      AND p.character_end >= COALESCE(c.character_end, pu.character_end)",
+        "    ORDER BY p.page_number ASC LIMIT 1",
+        "  )) AS page_number,",
+        "  COALESCE(pu.page_label, (",
+        "    SELECT p.page_label FROM pages p",
+        "    WHERE p.capsule_id = c.capsule_id AND p.document_id = c.document_id",
+        "      AND p.character_start <= COALESCE(c.character_start, pu.character_start)",
+        "      AND p.character_end >= COALESCE(c.character_end, pu.character_end)",
+        "    ORDER BY p.page_number ASC LIMIT 1",
+        "  )) AS page_label,",
+        "  COALESCE(pu.section_path_json, pu.heading_path_json) AS section_path_json,",
+        "  pu.json_pointer, pu.table_name, pu.row_index,",
+        "  COALESCE(c.character_start, pu.character_start) AS character_start,",
+        "  COALESCE(c.character_end, pu.character_end) AS character_end",
         "FROM chunks c",
         "LEFT JOIN documents d ON d.capsule_id = c.capsule_id AND d.id = c.document_id",
         "LEFT JOIN parsed_units pu",
@@ -168,11 +240,14 @@ function rowToCitation(row) {
         ...(row.page_number !== null ? { pageNumber: row.page_number } : {}),
         ...(row.page_label !== null ? { pageLabel: row.page_label } : {}),
         ...(sectionPath !== undefined ? { sectionPath } : {}),
+        ...(row.json_pointer !== null ? { jsonPointer: row.json_pointer } : {}),
+        ...(row.table_name !== null ? { tableName: row.table_name } : {}),
+        ...(row.row_index !== null ? { rowIndex: row.row_index } : {}),
         ...(row.character_start !== null ? { characterStart: row.character_start } : {}),
         ...(row.character_end !== null ? { characterEnd: row.character_end } : {}),
     };
 }
-function scoreCapsuleVectors(rows, capsule, queryVector, topK, minScore) {
+function scoreCapsuleVectors(rows, capsule, queryVector, candidateLimit, minScore) {
     const metric = capsule.embeddingModelIdentity.vectorMetric;
     const scored = [];
     for (const row of rows) {
@@ -189,10 +264,12 @@ function scoreCapsuleVectors(rows, capsule, queryVector, topK, minScore) {
         scored.push({ chunkId: row.chunk_id, capsuleId: capsule.id, score });
     }
     scored.sort(scoreDesc);
-    return scored.slice(0, oversampleTopK(topK));
+    return scored.slice(0, candidateLimit);
 }
-function oversampleTopK(topK) {
-    return Math.max(topK, Math.min(topK * 3, topK + 12));
+function oversampleTopK(topK, profile) {
+    const multiplier = profile.strategy === "exact" ? 12 : profile.strategy === "broad" ? 10 : 8;
+    const cap = profile.strategy === "exact" ? topK + 96 : topK + 64;
+    return Math.max(topK, Math.min(topK * multiplier, cap));
 }
 function scoreDesc(a, b) {
     if (b.score !== a.score)
@@ -209,8 +286,8 @@ function emptyState() {
         embeddingFailed: false,
     };
 }
-async function processCapsule(store, embeddingAdapter, capsule, query, options, cache, state) {
-    const rows = readVectorsForCapsule(store, capsule.id);
+async function processCapsule(store, embeddingAdapter, capsule, sourceFilter, query, options, profile, cache, state) {
+    const rows = readVectorsForCapsule(store, capsule.id, sourceFilter);
     if (rows.length === 0)
         return;
     state.anyVectorSeen = true;
@@ -225,7 +302,7 @@ async function processCapsule(store, embeddingAdapter, capsule, query, options,
         return;
     }
     state.anyDimensionCompatible = true;
-    const candidates = scoreCapsuleVectors(rows, capsule, embedded.vector, options.topK, options.minScore);
+    const candidates = scoreCapsuleVectors(rows, capsule, embedded.vector, oversampleTopK(options.topK, profile), options.minScore);
     state.candidates.push(...candidates);
 }
 async function ensureQueryEmbedded(adapter, identity, query, signal, cache) {
@@ -239,7 +316,7 @@ async function ensureQueryEmbedded(adapter, identity, query, signal, cache) {
     cache.set(key, result);
     return result;
 }
-function selectTopCandidates(state, options) {
+function selectTopCandidates(state, options, profile) {
     if (!state.anyVectorSeen)
         return { ok: false, reason: "no-vectors" };
     if (state.embeddingFailed && state.candidates.length === 0) {
@@ -249,7 +326,7 @@ function selectTopCandidates(state, options) {
         return { ok: false, reason: "incompatible-embedding-identity" };
     }
     state.candidates.sort(scoreDesc);
-    const top = state.candidates.slice(0, oversampleTopK(options.topK));
+    const top = state.candidates.slice(0, oversampleTopK(options.topK, profile));
     if (top.length === 0)
         return { ok: false, reason: "below-min-score" };
     return { ok: true, top };
@@ -258,15 +335,22 @@ export async function searchVectorsForScope(store, embeddingAdapter, scope, quer
     const capsules = loadCapsules(store, scope.capsuleIds);
     if (capsules.length === 0)
         return { references: [], noEvidenceReason: "no-vectors" };
+    const profile = profileQuery(query, options.strategy);
     const cache = new Map();
     const state = emptyState();
     for (const capsule of capsules) {
-        await processCapsule(store, embeddingAdapter, capsule, query, options, cache, state);
+        await processCapsule(store, embeddingAdapter, capsule, sourceFilterForCapsule(scope.sourceFilter, capsule), query, options, profile, cache, state);
     }
-    const selection = selectTopCandidates(state, options);
+    const selection = selectTopCandidates(state, options, profile);
     if (!selection.ok)
         return { references: [], noEvidenceReason: selection.reason };
-    return { references: buildReferences(store, selection.top, query, options.topK) };
+    return { references: buildReferences(store, selection.top, query, options.topK, profile) };
+}
+function sourceFilterForCapsule(sourceFilter, capsule) {
+    if (sourceFilter === undefined)
+        return undefined;
+    const capsuleSourceIds = new Set(capsule.sourceIds.map(String));
+    return sourceFilter.filter((sourceId) => capsuleSourceIds.has(String(sourceId)));
 }
 function loadCapsules(store, ids) {
     const out = [];
@@ -277,7 +361,7 @@ function loadCapsules(store, ids) {
     }
     return out;
 }
-function buildReferences(store, candidates, query, limit) {
+function buildReferences(store, candidates, query, limit, profile) {
     // Group surviving candidates by capsule so we can issue one citation-read per capsule.
     const byCapsule = new Map();
     for (const candidate of candidates) {
@@ -312,45 +396,247 @@ function buildReferences(store, candidates, query, limit) {
         refs.push({
             chunkId: citation.chunkId,
             capsuleId: candidate.capsuleId,
-            score: candidate.score + lexicalMetadataBonus(query, citation),
+            score: candidate.score +
+                lexicalMetadataBonus(citation, profile) +
+                lexicalContentBonus(store, candidate.capsuleId, citation, profile),
             citation,
         });
     }
     refs.sort(referenceScoreDesc);
-    return refs.slice(0, limit);
+    return diversifyReferences(refs, limit, profile);
 }
 function referenceScoreDesc(a, b) {
     if (b.score !== a.score)
         return b.score - a.score;
     return String(a.chunkId).localeCompare(String(b.chunkId));
 }
-function lexicalMetadataBonus(query, citation) {
-    const queryTokens = tokenise(query);
-    if (queryTokens.length === 0)
+function diversifyReferences(references, limit, profile) {
+    if (references.length <= limit)
+        return references;
+    const remaining = [...references];
+    const selected = [];
+    while (remaining.length > 0 && selected.length < limit) {
+        const pick = pickNextReference(remaining, selected, profile);
+        selected.push(pick.reference);
+        remaining.splice(pick.index, 1);
+    }
+    selected.sort(referenceScoreDesc);
+    return selected;
+}
+function pickNextReference(remaining, selected, profile) {
+    let bestIndex = 0;
+    let best = withDiversityScore(remaining[0], selected, profile);
+    for (let i = 1; i < remaining.length; i += 1) {
+        const candidate = withDiversityScore(remaining[i], selected, profile);
+        if (referenceScoreDesc(candidate, best) < 0) {
+            best = candidate;
+            bestIndex = i;
+        }
+    }
+    return { reference: best, index: bestIndex };
+}
+function withDiversityScore(reference, selected, profile) {
+    if (reference === undefined)
+        throw new RetrievalError("STORE_READ_FAILED", "missing reference");
+    const penalty = diversityPenalty(reference, selected, profile);
+    if (penalty === 0)
+        return reference;
+    return { ...reference, score: reference.score - penalty };
+}
+function diversityPenalty(reference, selected, profile) {
+    let sameDocument = 0;
+    let sameSection = 0;
+    const sectionKey = referenceSectionKey(reference);
+    for (const prior of selected) {
+        if (String(prior.citation.documentId) === String(reference.citation.documentId)) {
+            sameDocument += 1;
+        }
+        if (sectionKey !== "" && sectionKey === referenceSectionKey(prior)) {
+            sameSection += 1;
+        }
+    }
+    return (sameDocument * profile.documentDiversityPenalty + sameSection * profile.sectionDiversityPenalty);
+}
+function referenceSectionKey(reference) {
+    const path = reference.citation.sectionPath?.join(">");
+    return path === undefined ? "" : `${String(reference.citation.documentId)}:${path}`;
+}
+function lexicalMetadataBonus(citation, profile) {
+    if (profile.tokens.length === 0)
         return 0;
     const haystack = tokenise([
         citation.safeDisplayName,
         citation.pageLabel,
         ...(citation.sectionPath ?? []),
+        citation.jsonPointer,
+        citation.tableName,
+        citation.rowIndex === undefined ? undefined : String(citation.rowIndex),
         String(citation.pageNumber ?? ""),
     ]
         .filter((value) => typeof value === "string" && value.length > 0)
         .join(" "));
     if (haystack.length === 0)
         return 0;
+    const haystackSet = new Set(haystack);
+    const hits = countTokenHits(profile.tokens, haystackSet);
+    if (hits === 0)
+        return 0;
+    return (hits / profile.tokens.length) * profile.metadataWeight;
+}
+function lexicalContentBonus(store, capsuleId, citation, profile) {
+    if (profile.tokens.length === 0)
+        return 0;
+    const excerpt = readCitationSearchExcerpt(store, capsuleId, citation, SEARCH_EXCERPT_MAX_CHARS, profile.contextBeforeChars);
+    if (excerpt.length === 0)
+        return 0;
+    const excerptTokens = tokenise(excerpt);
+    if (excerptTokens.length === 0)
+        return 0;
+    const normalisedExcerpt = normaliseForSearch(excerpt);
+    const tokenCoverage = countTokenHits(profile.tokens, new Set(excerptTokens)) / profile.tokens.length;
+    const phraseHits = countAdjacentPhraseHits(profile.tokens, normalisedExcerpt);
+    const exactHits = countExactTermHits(profile.exactTerms, normalisedExcerpt);
+    return (Math.min(0.24, tokenCoverage * profile.lexicalWeight) +
+        Math.min(0.16, phraseHits * profile.phraseWeight) +
+        Math.min(0.18, exactHits * 0.06));
+}
+function readCitationSearchExcerpt(store, capsuleId, citation, maxChars, beforeChars) {
+    const row = store._internal.db
+        .prepare("SELECT normalized_text FROM document_texts WHERE capsule_id = :capsule_id AND document_id = :document_id")
+        .get({
+        capsule_id: String(capsuleId),
+        document_id: String(citation.documentId),
+    });
+    const text = row?.normalized_text;
+    if (typeof text !== "string" || text.length === 0)
+        return "";
+    const focusStart = Math.max(0, Math.min(text.length, citation.characterStart ?? 0));
+    const focusEnd = Math.max(focusStart, Math.min(text.length, citation.characterEnd ?? focusStart + maxChars));
+    const start = Math.max(0, focusStart - beforeChars);
+    const afterBudget = Math.max(0, maxChars - (focusStart - start));
+    const end = Math.min(text.length, focusEnd + afterBudget);
+    return text.slice(start, end).trim();
+}
+function countTokenHits(tokens, haystack) {
     let hits = 0;
-    for (const token of queryTokens) {
-        if (haystack.includes(token)) {
+    for (const token of tokens) {
+        if (haystack.has(token))
             hits += 1;
-        }
     }
-    if (hits === 0)
-        return 0;
-    return hits / (queryTokens.length * 10);
+    return hits;
+}
+function countAdjacentPhraseHits(tokens, normalisedHaystack) {
+    let hits = 0;
+    for (let i = 0; i < tokens.length - 1; i += 1) {
+        const first = tokens[i];
+        const second = tokens[i + 1];
+        if (first === undefined || second === undefined)
+            continue;
+        if (normalisedHaystack.includes(`${first} ${second}`))
+            hits += 1;
+    }
+    return hits;
+}
+function countExactTermHits(terms, normalisedHaystack) {
+    let hits = 0;
+    for (const term of terms) {
+        if (normalisedHaystack.includes(term))
+            hits += 1;
+    }
+    return hits;
+}
+function profileQuery(query, requested) {
+    const tokens = uniqueTokens(tokenise(query));
+    const exactTerms = extractExactTerms(query);
+    const strategy = resolveQueryStrategy(query, tokens, exactTerms, requested);
+    if (strategy === "exact")
+        return exactQueryProfile(tokens, exactTerms);
+    if (strategy === "broad")
+        return broadQueryProfile(tokens, exactTerms);
+    return balancedQueryProfile(tokens, exactTerms);
+}
+function resolveQueryStrategy(query, tokens, exactTerms, requested) {
+    if (requested !== undefined && requested !== "auto")
+        return requested;
+    if (exactTerms.length > 0)
+        return "exact";
+    if (tokens.length >= 8 || BROAD_QUERY_PATTERN.test(query))
+        return "broad";
+    return "balanced";
+}
+function exactQueryProfile(tokens, exactTerms) {
+    return {
+        strategy: "exact",
+        tokens,
+        exactTerms,
+        lexicalWeight: 0.22,
+        phraseWeight: 0.06,
+        metadataWeight: 0.16,
+        contextBeforeChars: SEARCH_CONTEXT_BEFORE_CHARS * 2,
+        documentDiversityPenalty: 0.018,
+        sectionDiversityPenalty: 0.01,
+    };
+}
+function broadQueryProfile(tokens, exactTerms) {
+    return {
+        strategy: "broad",
+        tokens,
+        exactTerms,
+        lexicalWeight: 0.16,
+        phraseWeight: 0.04,
+        metadataWeight: 0.1,
+        contextBeforeChars: SEARCH_CONTEXT_BEFORE_CHARS,
+        documentDiversityPenalty: 0.085,
+        sectionDiversityPenalty: 0.035,
+    };
+}
+function balancedQueryProfile(tokens, exactTerms) {
+    return {
+        strategy: "balanced",
+        tokens,
+        exactTerms,
+        lexicalWeight: 0.18,
+        phraseWeight: 0.045,
+        metadataWeight: 0.12,
+        contextBeforeChars: SEARCH_CONTEXT_BEFORE_CHARS,
+        documentDiversityPenalty: 0.045,
+        sectionDiversityPenalty: 0.02,
+    };
+}
+function extractExactTerms(value) {
+    const out = [];
+    const matches = value.matchAll(EXACT_TERM_PATTERN);
+    for (const match of matches) {
+        const raw = match[0];
+        if (!isExactTerm(raw))
+            continue;
+        const term = normaliseForSearch(raw);
+        if (term.length > 0)
+            out.push(term);
+    }
+    return uniqueTokens(out);
+}
+function isExactTerm(value) {
+    if (/\d/u.test(value))
+        return true;
+    if (/[._:/#-]/u.test(value))
+        return true;
+    if (/[a-z][A-Z]/u.test(value))
+        return true;
+    return value.length >= 3 && value === value.toUpperCase() && /\p{L}/u.test(value);
+}
+function uniqueTokens(tokens) {
+    return [...new Set(tokens)];
 }
 function tokenise(value) {
+    return normaliseForSearch(value)
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((token) => token.length >= 2 && !SEARCH_STOPWORDS.has(token));
+}
+function normaliseForSearch(value) {
     return value
+        .normalize("NFKD")
+        .replace(/\p{Mark}+/gu, "")
         .toLowerCase()
-        .split(/[^a-z0-9]+/i)
-        .filter((token) => token.length >= 2);
+        .replace(/ß/gu, "ss");
 }

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/source-lifecycle.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeCapsuleId, KnowledgeSource, KnowledgeSourceId, KnowledgeSourceScope } from "@oscharko-dev/keiko-contracts";
+import { type KnowledgeCapsuleId, type KnowledgeSource, type KnowledgeSourceId, type KnowledgeSourceScope } from "@oscharko-dev/keiko-contracts";
 import type { AuditEventSink } from "./privacy/types.js";
 import type { KnowledgeStore } from "./store.js";
 export interface AddCapsuleSourceInput {

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/source-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-lifecycle.d.ts","sourceRoot":"","sources":["../src/source-lifecycle.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AA+DD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,KAAK,EAAE,qBAAqB,EAC5B,SAAS,CAAC,EAAE,cAAc,GACzB,eAAe,CAuCjB;AAkBD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,GAC5B,SAAS,eAAe,EAAE,CAG5B;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,CAAC,EAAE,cAAc,GACzB,IAAI,CAuBN"}
+{"version":3,"file":"source-lifecycle.d.ts","sourceRoot":"","sources":["../src/source-lifecycle.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAiID,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,KAAK,EAAE,qBAAqB,EAC5B,SAAS,CAAC,EAAE,cAAc,GACzB,eAAe,CAuBjB;AAoBD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,GAC5B,SAAS,eAAe,EAAE,CAG5B;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,CAAC,EAAE,cAAc,GACzB,IAAI,CAuBN"}

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/source-lifecycle.js

@@ -4,9 +4,11 @@
 // by chance (a plain DELETE with COUNT-on-changes still races with concurrent CASCADE
 // deletes of the parent capsule, but the verify+delete sequence is correct under WAL's
 // single-writer semantics).
+import { isSafeDisplaySummary, validateKnowledgeSourceScope, } from "@oscharko-dev/keiko-contracts";
 import { KnowledgeNotFoundError, KnowledgeStoreError } from "./errors.js";
 const INSERT_SQL = "INSERT INTO capsule_sources (id, capsule_id, display_name, description, tags_json, scope_kind, scope_json, created_at, updated_at) VALUES (:id, :capsule_id, :display_name, :description, :tags_json, :scope_kind, :scope_json, :created_at, :updated_at)";
-const SELECT_BY_CAPSULE_SQL = "SELECT * FROM capsule_sources WHERE capsule_id = :c ORDER BY created_at ASC, id ASC";
+const INSERT_KNOWLEDGE_SOURCE_SQL = "INSERT INTO knowledge_sources (id, display_name, description, tags_json, scope_kind, scope_json, created_at, updated_at) VALUES (:id, :display_name, :description, :tags_json, :scope_kind, :scope_json, :created_at, :updated_at) ON CONFLICT(id) DO UPDATE SET display_name = excluded.display_name, description = excluded.description, tags_json = excluded.tags_json, scope_kind = excluded.scope_kind, scope_json = excluded.scope_json, updated_at = excluded.updated_at";
+const SELECT_BY_CAPSULE_SQL = "SELECT ks.* FROM capsule_sources AS cs JOIN knowledge_sources AS ks ON ks.id = cs.id WHERE cs.capsule_id = :c ORDER BY cs.created_at ASC, cs.id ASC";
 const SELECT_BY_TUPLE_SQL = "SELECT id FROM capsule_sources WHERE capsule_id = :c AND id = :s";
 const DELETE_BY_TUPLE_SQL = "DELETE FROM capsule_sources WHERE capsule_id = :c AND id = :s";
 function parseTags(json) {
@@ -15,6 +17,22 @@ function parseTags(json) {
         return [];
     return parsed.filter((entry) => typeof entry === "string");
 }
+function assertSafeDisplayField(field, value) {
+    if (value.trim().length === 0 || !isSafeDisplaySummary(value)) {
+        throw new KnowledgeStoreError(`${field} must be a browser-safe non-empty string`);
+    }
+}
+function assertSafeOptionalDisplayField(field, value) {
+    if (value !== undefined && !isSafeDisplaySummary(value)) {
+        throw new KnowledgeStoreError(`${field} must be browser-safe when set`);
+    }
+}
+function assertSafeScope(scope) {
+    const result = validateKnowledgeSourceScope(scope);
+    if (result.ok)
+        return;
+    throw new KnowledgeStoreError(result.errors.join(" "));
+}
 function parseScope(kind, json) {
     const parsed = JSON.parse(json);
     if (typeof parsed !== "object" || parsed === null) {
@@ -46,22 +64,24 @@ function scopeToJson(scope) {
     }
     return JSON.stringify(copy);
 }
-export function addSourceToCapsule(store, capsuleId, input, auditSink) {
+function sourceParams(input, now) {
+    return {
+        id: input.id,
+        display_name: input.displayName,
+        description: input.description ?? null,
+        tags_json: JSON.stringify(input.tags),
+        scope_kind: input.scope.kind,
+        scope_json: scopeToJson(input.scope),
+        created_at: now,
+        updated_at: now,
+    };
+}
+function insertSourceLink(store, capsuleId, params) {
     const db = store._internal.db;
-    const now = store._internal.now();
     db.exec("BEGIN");
     try {
-        db.prepare(INSERT_SQL).run({
-            id: input.id,
-            capsule_id: capsuleId,
-            display_name: input.displayName,
-            description: input.description ?? null,
-            tags_json: JSON.stringify(input.tags),
-            scope_kind: input.scope.kind,
-            scope_json: scopeToJson(input.scope),
-            created_at: now,
-            updated_at: now,
-        });
+        db.prepare(INSERT_KNOWLEDGE_SOURCE_SQL).run(params);
+        db.prepare(INSERT_SQL).run({ ...params, capsule_id: capsuleId });
         db.exec("COMMIT");
     }
     catch (error) {
@@ -72,7 +92,17 @@ export function addSourceToCapsule(store, capsuleId, input, auditSink) {
         }
         throw new KnowledgeStoreError("failed to add source", { cause: error });
     }
-    const fetched = db.prepare(SELECT_BY_TUPLE_SQL).get({ c: capsuleId, s: input.id });
+}
+export function addSourceToCapsule(store, capsuleId, input, auditSink) {
+    assertSafeDisplayField("displayName", input.displayName);
+    assertSafeOptionalDisplayField("description", input.description);
+    for (const tag of input.tags) {
+        assertSafeDisplayField("tag", tag);
+    }
+    assertSafeScope(input.scope);
+    const now = store._internal.now();
+    insertSourceLink(store, capsuleId, sourceParams(input, now));
+    const fetched = store._internal.db.prepare(SELECT_BY_TUPLE_SQL).get({ c: capsuleId, s: input.id });
     if (fetched === undefined) {
         throw new KnowledgeStoreError(`addSourceToCapsule: insert succeeded but row not found for ${String(input.id)}`);
     }
@@ -87,7 +117,7 @@ export function addSourceToCapsule(store, capsuleId, input, auditSink) {
 }
 function readSource(store, capsuleId, sourceId) {
     const row = store._internal.db
-        .prepare("SELECT * FROM capsule_sources WHERE capsule_id = :c AND id = :s")
+        .prepare("SELECT ks.* FROM capsule_sources AS cs JOIN knowledge_sources AS ks ON ks.id = cs.id WHERE cs.capsule_id = :c AND cs.id = :s")
         .get({ c: capsuleId, s: sourceId });
     if (row === undefined) {
         throw new KnowledgeNotFoundError(`Source not found: capsule=${String(capsuleId)} source=${String(sourceId)}`);

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

@@ -2,6 +2,19 @@ import { DatabaseSync } from "node:sqlite";
 export interface OpenKnowledgeStoreOptions {
     readonly dbPath: string;
     readonly clock?: () => number;
+    readonly protection?: KnowledgeStoreProtectionOptions;
+}
+export interface KnowledgeStoreKeyProviderContext {
+    readonly dbPath: string;
+    readonly schemaVersion: number;
+}
+export interface KnowledgeStoreKeyProvider {
+    readonly providerId: string;
+    readonly resolveKey: (context: KnowledgeStoreKeyProviderContext) => Uint8Array;
+}
+export interface KnowledgeStoreProtectionOptions {
+    readonly mode?: "plaintext-local-file-permissions" | "encrypted-key-provider";
+    readonly keyProvider?: KnowledgeStoreKeyProvider;
 }
 export interface KnowledgeStore {
     readonly close: () => void;
@@ -10,5 +23,6 @@ export interface KnowledgeStore {
         readonly now: () => number;
     };
 }
+export declare const LK_STORE_BUSY_TIMEOUT_MS = 5000;
 export declare function openKnowledgeStore(opts: OpenKnowledgeStoreOptions): KnowledgeStore;
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAMD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;QAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;KAC5B,CAAC;CACH;AAmJD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,cAAc,CAwBlF"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,+BAA+B,CAAC;CACvD;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,gCAAgC,KAAK,UAAU,CAAC;CAChF;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,kCAAkC,GAAG,wBAAwB,CAAC;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE,yBAAyB,CAAC;CAClD;AAMD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;QAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;KAC5B,CAAC;CACH;AAkBD,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAkK9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,cAAc,CA0BlF"}