@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/retrieval/types.d.ts

@@ -0,0 +1,28 @@
+import type { CapsuleSetId, CitationReference, KnowledgeCapsuleId, RetrievalReference } from "@oscharko-dev/keiko-contracts";
+import { KnowledgeStoreError } from "../errors.js";
+export type RetrievalErrorCode = "EMBEDDING_ADAPTER_FAILED" | "INCOMPATIBLE_EMBEDDING_IDENTITY" | "CAPSULE_NOT_FOUND" | "INVALID_QUERY" | "STORE_READ_FAILED";
+export declare class RetrievalError extends KnowledgeStoreError {
+    readonly name: string;
+    readonly code: RetrievalErrorCode;
+    constructor(code: RetrievalErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface RetrievalQuery {
+    readonly capsuleSetId?: CapsuleSetId;
+    readonly capsuleId?: KnowledgeCapsuleId;
+    readonly text: string;
+    readonly topK?: number;
+    readonly minScore?: number;
+}
+export type RetrievalNoEvidenceReason = "no-scope" | "no-vectors" | "incompatible-embedding-identity" | "below-min-score" | "answer-grounding-rejected" | "no-evidence-stated" | "empty-query" | "embedding-failed";
+export interface RetrievalResult {
+    readonly references: readonly RetrievalReference[];
+    readonly noEvidence: boolean;
+    readonly reason?: RetrievalNoEvidenceReason;
+    readonly embeddingDegraded?: true;
+}
+export declare const DEFAULT_RETRIEVAL_TOP_K = 10;
+export declare const MAX_RETRIEVAL_TOP_K = 100;
+export type { CitationReference, RetrievalReference };
+//# sourceMappingURL=types.d.ts.map

package/dist/retrieval/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/retrieval/types.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,MAAM,kBAAkB,GAC1B,0BAA0B,GAC1B,iCAAiC,GACjC,mBAAmB,GACnB,eAAe,GACf,mBAAmB,CAAC;AAExB,qBAAa,cAAe,SAAQ,mBAAmB;IACrD,SAAyB,IAAI,EAAE,MAAM,CAAoB;IACzD,SAAgB,IAAI,EAAE,kBAAkB,CAAC;gBACtB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI5F;AAKD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAOD,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,YAAY,GACZ,iCAAiC,GACjC,iBAAiB,GACjB,2BAA2B,GAC3B,oBAAoB,GACpB,aAAa,GACb,kBAAkB,CAAC;AAEvB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;IAI5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;CACnC;AAMD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAI1C,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAGvC,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/retrieval/types.js

@@ -0,0 +1,33 @@
+// Type contracts for the retrieval layer (Epic #189, Issue #199). Retrieval is the
+// runtime side of the Local Knowledge Connector pipeline that #196 fed: a query string +
+// a `ComposedRetrievalScope` (#263) → a ranked list of `RetrievalReference` taken from the
+// `vectors` table, plus a `GroundedContextPack` derived from those references (citations
+// only, never raw text body unless the capsule's `outputMode === "raw"` — and even then
+// the body is sourced from the parsed-units row, not embedded vectors).
+//
+// `RetrievalResult` carries an explicit `noEvidence` boolean rather than overloading an
+// empty `references` array because the caller (#200 Conversation Center integration) needs
+// to discriminate "we scanned and found nothing" from "the answer-grounding policy refused
+// to release the references". A short, closed-enumeration `reason` string lets the UI map
+// the result to a precise message without re-deriving state.
+//
+// `RetrievalError` extends KnowledgeStoreError so callers that catch the parent class
+// still see the failure — same pattern as `IndexingError` in `../indexing/types.ts`.
+import { KnowledgeStoreError } from "../errors.js";
+export class RetrievalError extends KnowledgeStoreError {
+    name = "RetrievalError";
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+// ─── Defaults ────────────────────────────────────────────────────────────────
+// Match the scope's contract maxima for #200 the conversation-center surface: 10 is a
+// reasonable default that still fits in a small context budget for an LLM grounding
+// prompt and matches the "Top-K = 10" convention from sibling vector-store products.
+export const DEFAULT_RETRIEVAL_TOP_K = 10;
+// Hard cap on `topK`. A caller asking for more than this is clamped silently — we never
+// surface every vector in a large capsule because that breaks the "ranked top-K" contract
+// the answer-grounding policy depends on.
+export const MAX_RETRIEVAL_TOP_K = 100;

package/dist/section-path-hash.d.ts

@@ -0,0 +1,3 @@
+export declare function sectionPathHashFromJson(sectionPathJson: string): string;
+export declare function sectionPathHash(sectionPath: readonly string[]): string;
+//# sourceMappingURL=section-path-hash.d.ts.map

package/dist/section-path-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-path-hash.d.ts","sourceRoot":"","sources":["../src/section-path-hash.ts"],"names":[],"mappings":"AAIA,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEtE"}

package/dist/section-path-hash.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+const SECTION_PATH_HASH_PREFIX = "sha256:";
+export function sectionPathHashFromJson(sectionPathJson) {
+    const digest = createHash("sha256").update(sectionPathJson, "utf8").digest("base64url");
+    return `${SECTION_PATH_HASH_PREFIX}${digest}`;
+}
+export function sectionPathHash(sectionPath) {
+    return sectionPathHashFromJson(JSON.stringify(sectionPath));
+}

package/dist/source-lifecycle.d.ts

@@ -0,0 +1,14 @@
+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 {
+    readonly id: KnowledgeSourceId;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly scope: KnowledgeSourceScope;
+}
+export declare function addSourceToCapsule(store: KnowledgeStore, capsuleId: KnowledgeCapsuleId, input: AddCapsuleSourceInput, auditSink?: AuditEventSink): KnowledgeSource;
+export declare function listCapsuleSources(store: KnowledgeStore, capsuleId: KnowledgeCapsuleId): readonly KnowledgeSource[];
+export declare function removeSourceFromCapsule(store: KnowledgeStore, capsuleId: KnowledgeCapsuleId, sourceId: KnowledgeSourceId, auditSink?: AuditEventSink): void;
+//# sourceMappingURL=source-lifecycle.d.ts.map

package/dist/source-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"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,CAyBjB;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/dist/source-lifecycle.js

@@ -0,0 +1,155 @@
+// source-lifecycle.ts — typed CRUD over `capsule_sources`. Every read is capsule-scoped:
+// there is intentionally no `listAllSources(store)`. Deletion verifies the (capsuleId,
+// sourceId) tuple matches a row BEFORE issuing DELETE so a wrong-tuple call cannot succeed
+// 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 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) {
+    const parsed = JSON.parse(json);
+    if (!Array.isArray(parsed))
+        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) {
+        throw new KnowledgeStoreError(`Corrupt capsule_sources.scope_json (kind=${kind}).`);
+    }
+    // The contract validators in keiko-contracts shape these on write; we trust the row.
+    return { kind, ...parsed };
+}
+function rowToSource(row) {
+    const base = {
+        id: row.id,
+        displayName: row.display_name,
+        tags: parseTags(row.tags_json),
+        scope: parseScope(row.scope_kind, row.scope_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+    return row.description === null ? base : { ...base, description: row.description };
+}
+function scopeToJson(scope) {
+    // We persist only the fields beyond `kind` (kind lives in its own column). Build a
+    // plain object copy without `kind` rather than destructuring + discarding, which the
+    // lint config flags as an unused binding.
+    const copy = {};
+    for (const [key, value] of Object.entries(scope)) {
+        if (key === "kind")
+            continue;
+        copy[key] = value;
+    }
+    return JSON.stringify(copy);
+}
+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;
+    db.exec("BEGIN");
+    try {
+        db.prepare(INSERT_KNOWLEDGE_SOURCE_SQL).run(params);
+        db.prepare(INSERT_SQL).run({ ...params, capsule_id: capsuleId });
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        const msg = error instanceof Error ? error.message : String(error);
+        if (/UNIQUE|PRIMARY KEY/i.test(msg)) {
+            throw new KnowledgeStoreError("source already exists", { cause: error });
+        }
+        throw new KnowledgeStoreError("failed to add source", { cause: error });
+    }
+}
+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)}`);
+    }
+    const source = readSource(store, capsuleId, input.id);
+    auditSink?.emit({
+        kind: "source-added",
+        capsuleId,
+        sourceId: input.id,
+        occurredAt: now,
+    });
+    return source;
+}
+function readSource(store, capsuleId, sourceId) {
+    const row = store._internal.db
+        .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)}`);
+    }
+    return rowToSource(row);
+}
+export function listCapsuleSources(store, capsuleId) {
+    const rows = store._internal.db.prepare(SELECT_BY_CAPSULE_SQL).all({ c: capsuleId });
+    return rows.map((row) => rowToSource(row));
+}
+export function removeSourceFromCapsule(store, capsuleId, sourceId, auditSink) {
+    const db = store._internal.db;
+    const occurredAt = store._internal.now();
+    db.exec("BEGIN");
+    try {
+        // Verify the (capsule, source) tuple exists. Deleting on a non-matching tuple would
+        // silently succeed with 0 changes; we want the caller to learn about typos.
+        const probe = db.prepare(SELECT_BY_TUPLE_SQL).get({ c: capsuleId, s: sourceId });
+        if (probe === undefined) {
+            db.exec("ROLLBACK");
+            throw new KnowledgeNotFoundError(`Source not found for tuple capsule=${String(capsuleId)} source=${String(sourceId)}`);
+        }
+        db.prepare(DELETE_BY_TUPLE_SQL).run({ c: capsuleId, s: sourceId });
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        if (!(error instanceof KnowledgeNotFoundError)) {
+            db.exec("ROLLBACK");
+        }
+        throw error;
+    }
+    auditSink?.emit({ kind: "source-removed", capsuleId, sourceId, occurredAt });
+}

package/dist/source-routing-validation.d.ts

@@ -0,0 +1,11 @@
+import type { KnowledgeCapsule, KnowledgeSource, KnowledgeSourceScope } from "@oscharko-dev/keiko-contracts";
+export type SourceRoutingValidationCode = "always-query-without-sources" | "always-query-capsule-not-ready" | "always-query-source-list-mismatch" | "unknown-source-token" | "instructions-empty" | "include-globs-empty-array" | "exclude-globs-empty-array" | "duplicate-glob" | "glob-path-escape" | "absolute-glob" | "exclude-cancels-include";
+export declare class SourceRoutingValidationError extends Error {
+    readonly code: SourceRoutingValidationCode;
+    constructor(code: SourceRoutingValidationCode, message: string);
+}
+export declare function validateAlwaysQuery(capsule: KnowledgeCapsule, sources: readonly KnowledgeSource[]): void;
+export declare function validateRoutingInstructionsScope(instructions: string | undefined, sources: readonly KnowledgeSource[]): void;
+export declare function validateGlobPatterns(scope: KnowledgeSourceScope): void;
+export declare function validateSourceRoutingForCapsule(capsule: KnowledgeCapsule, sources: readonly KnowledgeSource[]): void;
+//# sourceMappingURL=source-routing-validation.d.ts.map

package/dist/source-routing-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-routing-validation.d.ts","sourceRoot":"","sources":["../src/source-routing-validation.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,MAAM,2BAA2B,GACnC,8BAA8B,GAC9B,gCAAgC,GAChC,mCAAmC,GACnC,sBAAsB,GACtB,oBAAoB,GACpB,2BAA2B,GAC3B,2BAA2B,GAC3B,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,yBAAyB,CAAC;AAE9B,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;gBAC/B,IAAI,EAAE,2BAA2B,EAAE,OAAO,EAAE,MAAM;CAK/D;AAYD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CAuBN;AAUD,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CAkBN;AAmBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAetE;AA2DD,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CAMN"}

package/dist/source-routing-validation.js

@@ -0,0 +1,140 @@
+// source-routing-validation.ts — pure validators for Knowledge Capsule source-routing
+// controls (Epic #189, Issue #263). Foundry-IQ "no global pool" rule is enforced at the
+// type system by every record carrying capsuleId+sourceId; this module catches the
+// **semantic** misconfigurations the type system cannot see:
+//
+//   * alwaysQuery=true on an empty or non-ready capsule (would query nothing or stale
+//     data on every conversation turn).
+//   * Routing instructions referencing source ids the capsule does not own.
+//   * Include/exclude globs that silently broaden retrieval (empty arrays, duplicates,
+//     `..` traversal, leading-slash absolute paths, or excludes that cancel includes).
+//
+// Pure module: no IO, no clock, no node:* imports. Safe to call from any layer.
+export class SourceRoutingValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SourceRoutingValidationError";
+        this.code = code;
+    }
+}
+function fail(code, message) {
+    throw new SourceRoutingValidationError(code, message);
+}
+// ─── alwaysQuery ───────────────────────────────────────────────────────────────
+// Truthy alwaysQuery means: include this capsule in every retrieval scope for the
+// current conversation by default. That makes a misconfiguration silently dangerous —
+// an empty or unindexed capsule would either return nothing every turn or expose
+// stale chunks. We refuse both states up front.
+export function validateAlwaysQuery(capsule, sources) {
+    if (capsule.alwaysQuery !== true)
+        return;
+    if (capsule.sourceIds.length === 0) {
+        fail("always-query-without-sources", `Capsule ${String(capsule.id)} has alwaysQuery=true but no sources.`);
+    }
+    if (capsule.lifecycleState !== "ready") {
+        fail("always-query-capsule-not-ready", `Capsule ${String(capsule.id)} cannot be alwaysQuery while lifecycleState=${capsule.lifecycleState}.`);
+    }
+    const ids = new Set(sources.map((s) => String(s.id)));
+    for (const declared of capsule.sourceIds) {
+        if (!ids.has(String(declared))) {
+            fail("always-query-source-list-mismatch", `Capsule ${String(capsule.id)} declares source ${String(declared)} but it is not in the supplied source list.`);
+        }
+    }
+}
+// ─── Routing instructions ─────────────────────────────────────────────────────
+// `sourceRoutingInstructions` is free-form prose, but a Foundry-IQ-style convention
+// uses `@source-id` tokens (e.g. "prefer @docs over @specs") to address specific
+// sources. The validator extracts those tokens and refuses any that do not resolve
+// to a source in this capsule. Instructions without tokens are accepted as-is.
+const SOURCE_TOKEN_RE = /@([A-Za-z0-9][A-Za-z0-9_.-]*)/g;
+export function validateRoutingInstructionsScope(instructions, sources) {
+    if (instructions === undefined)
+        return;
+    if (instructions.trim().length === 0) {
+        fail("instructions-empty", "sourceRoutingInstructions must be omitted entirely or contain non-whitespace content.");
+    }
+    const knownIds = new Set(sources.map((s) => String(s.id)));
+    const tokens = extractSourceTokens(instructions);
+    for (const token of tokens) {
+        if (!knownIds.has(token)) {
+            fail("unknown-source-token", `sourceRoutingInstructions references @${token} which is not a source in this capsule.`);
+        }
+    }
+}
+function extractSourceTokens(instructions) {
+    const out = [];
+    for (const match of instructions.matchAll(SOURCE_TOKEN_RE)) {
+        const captured = match[1];
+        if (captured !== undefined && captured.length > 0) {
+            out.push(captured);
+        }
+    }
+    return out;
+}
+// ─── Glob patterns ────────────────────────────────────────────────────────────
+// The contract's KnowledgeSourceScope only enforces TYPES on includeGlobs/excludeGlobs.
+// This validator enforces SEMANTICS: callers must omit the field instead of passing
+// an empty array, must not duplicate patterns, must not contain `..` or absolute
+// paths, and excludeGlobs must not byte-match an includeGlobs entry (cancelling it).
+export function validateGlobPatterns(scope) {
+    if (scope.kind === "files")
+        return;
+    validateGlobList(scope.includeGlobs, "include");
+    validateGlobList(scope.excludeGlobs, "exclude");
+    if (scope.includeGlobs !== undefined && scope.excludeGlobs !== undefined) {
+        const includeSet = new Set(scope.includeGlobs);
+        for (const pattern of scope.excludeGlobs) {
+            if (includeSet.has(pattern)) {
+                fail("exclude-cancels-include", `excludeGlobs entry "${pattern}" byte-matches an includeGlobs entry; the include is silently cancelled.`);
+            }
+        }
+    }
+}
+function validateGlobList(patterns, kind) {
+    if (patterns === undefined)
+        return;
+    if (patterns.length === 0) {
+        fail(kind === "include" ? "include-globs-empty-array" : "exclude-globs-empty-array", `${kind}Globs must be omitted, not supplied as an empty array.`);
+    }
+    const seen = new Set();
+    for (const pattern of patterns) {
+        assertGlobShape(pattern);
+        if (seen.has(pattern)) {
+            fail("duplicate-glob", `Duplicate ${kind} glob pattern "${pattern}".`);
+        }
+        seen.add(pattern);
+    }
+}
+function isWindowsDriveAbsolute(pattern) {
+    // Matches C:\ or C:/ — a single drive letter followed by colon and a separator.
+    return (pattern.length >= 3 &&
+        /[A-Za-z]/.test(pattern[0] ?? "") &&
+        pattern[1] === ":" &&
+        (pattern[2] === "/" || pattern[2] === "\\"));
+}
+function assertGlobShape(pattern) {
+    if (pattern.startsWith("/")) {
+        fail("absolute-glob", `Glob pattern "${pattern}" is absolute; patterns must be source-root-relative.`);
+    }
+    if (isWindowsDriveAbsolute(pattern) || pattern.startsWith("\\\\")) {
+        fail("absolute-glob", `Glob pattern "${pattern}" is an absolute Windows path; patterns must be source-root-relative.`);
+    }
+    // Reject any `..` segment. Split on EITHER separator so Windows-style backslash paths
+    // are also caught (e.g. "sub\..\other"). Match component-bounded so substrings like
+    // "abc..def" inside a filename are allowed; only path-segment traversal is refused.
+    const segments = pattern.split(/[/\\]/);
+    for (const segment of segments) {
+        if (segment === "..") {
+            fail("glob-path-escape", `Glob pattern "${pattern}" contains a parent-directory segment.`);
+        }
+    }
+}
+// ─── Composite ─────────────────────────────────────────────────────────────────
+export function validateSourceRoutingForCapsule(capsule, sources) {
+    validateAlwaysQuery(capsule, sources);
+    validateRoutingInstructionsScope(capsule.sourceRoutingInstructions, sources);
+    for (const src of sources) {
+        validateGlobPatterns(src.scope);
+    }
+}

package/dist/store-content-cipher.d.ts

@@ -0,0 +1,11 @@
+export interface StoreContentCipher {
+    readonly isEncrypted: boolean;
+    readonly sealText: (plaintext: string) => string;
+    readonly openText: (stored: string) => string;
+    readonly sealVector: (plaintext: Uint8Array) => Uint8Array;
+    readonly openVector: (stored: Uint8Array, plaintextByteLength: number) => Uint8Array;
+    readonly isSealed: (value: string) => boolean;
+}
+export declare const PLAINTEXT_CONTENT_CIPHER: StoreContentCipher;
+export declare function createEncryptedContentCipher(key: Uint8Array): StoreContentCipher;
+//# sourceMappingURL=store-content-cipher.d.ts.map

package/dist/store-content-cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-content-cipher.d.ts","sourceRoot":"","sources":["../src/store-content-cipher.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,kBAAkB;IAGjC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAI9B,QAAQ,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAI9C,QAAQ,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,UAAU,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,KAAK,UAAU,CAAC;IAIrF,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CAC/C;AAID,eAAO,MAAM,wBAAwB,EAAE,kBAOtC,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,UAAU,GAAG,kBAAkB,CA8ChF"}

package/dist/store-content-cipher.js

@@ -0,0 +1,67 @@
+// Store content cipher — the single crypto boundary for Local Knowledge encryption at rest
+// (Issue #1322, Epic #1319; ADR-0047). Resolves a 32-byte AES-256-GCM key once at store-open and
+// binds it into a `StoreContentCipher` that the row layer threads through every read/write of the
+// reconstructive content columns (document_texts.normalized_text,
+// document_text_windows.normalized_text, vectors.embedding, sections.section_path_json, and
+// parsed_units path JSON). The key NEVER appears in an error message, event, or persisted row; only
+// sealed envelopes touch SQLite.
+//
+// Mirrors keiko-memory-vault's MemoryContentCipher (ADR-0035): crypto knowledge lives only here, so
+// retrieval/parsing/UI layers stay crypto-free and just call seal*/open* at the column boundary.
+//
+// Plaintext mode binds the identity cipher (PLAINTEXT_CONTENT_CIPHER), so every call site is
+// byte-for-byte unchanged when no key provider is supplied. Encryption is therefore opt-in per
+// store-open: keiko-server injects a key provider for production stores; the in-package evaluation
+// harness and tests open plaintext stores unchanged.
+import { isSealed, openBytes, openString, sealBytes, sealString, } from "@oscharko-dev/keiko-security";
+import { KnowledgeStoreError } from "./errors.js";
+const KEY_BYTES = 32;
+// Identity cipher for plaintext stores. Every method is a no-op pass-through so a store opened
+// without a key provider behaves exactly as it did before encryption existed.
+export const PLAINTEXT_CONTENT_CIPHER = {
+    isEncrypted: false,
+    sealText: (plaintext) => plaintext,
+    openText: (stored) => stored,
+    sealVector: (plaintext) => plaintext,
+    openVector: (stored) => stored,
+    isSealed: () => false,
+};
+export function createEncryptedContentCipher(key) {
+    // Copy into a Buffer so the cipher owns its key material and a caller mutating the provider's array
+    // cannot retroactively change the key. Length is validated here (not deeper) so a misconfigured key
+    // provider fails at store-open with a clear, secret-free message.
+    const keyBuf = Buffer.from(key);
+    if (keyBuf.length !== KEY_BYTES) {
+        throw new KnowledgeStoreError("encrypted local-knowledge store key must be exactly 32 bytes");
+    }
+    return {
+        isEncrypted: true,
+        sealText: (plaintext) => sealString(keyBuf, plaintext),
+        openText: (stored) => {
+            if (!isSealed(stored)) {
+                throw new KnowledgeStoreError("encrypted Local Knowledge text content is not sealed at rest");
+            }
+            try {
+                return openString(keyBuf, stored);
+            }
+            catch (cause) {
+                throw new KnowledgeStoreError("cannot open encrypted Local Knowledge text content: wrong key or tampered content", { cause });
+            }
+        },
+        sealVector: (plaintext) => sealBytes(keyBuf, Buffer.from(plaintext)),
+        openVector: (stored, plaintextByteLength) => {
+            let opened;
+            try {
+                opened = openBytes(keyBuf, Buffer.from(stored));
+            }
+            catch (cause) {
+                throw new KnowledgeStoreError("cannot open encrypted Local Knowledge vector content: wrong key or tampered content", { cause });
+            }
+            if (opened.byteLength !== plaintextByteLength) {
+                throw new KnowledgeStoreError("encrypted Local Knowledge vector content length does not match vector_dimensions");
+            }
+            return opened;
+        },
+        isSealed,
+    };
+}

package/dist/store-content-encryption.d.ts

@@ -0,0 +1,12 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { StoreContentCipher } from "./store-content-cipher.js";
+export declare function applyStoreContentEncryption(db: DatabaseSync, cipher: StoreContentCipher): void;
+export declare const STORE_CONTENT_ENCRYPTION_TEST_CONSTANTS: {
+    readonly markerKey: "content_encryption";
+    readonly markerValue: "aes-256-gcm/v1";
+    readonly probeKey: "content_encryption_probe";
+    readonly probePlaintext: "keiko-local-knowledge-content-encryption-v1";
+    readonly scopeKey: "content_encryption_scope";
+    readonly scopeValue: "reconstructive-columns/v2";
+};
+//# sourceMappingURL=store-content-encryption.d.ts.map

package/dist/store-content-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-content-encryption.d.ts","sourceRoot":"","sources":["../src/store-content-encryption.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAiRpE,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CA0C9F;AAED,eAAO,MAAM,uCAAuC;;;;;;;CAO1C,CAAC"}