@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/store-content-encryption.js

@@ -0,0 +1,275 @@
+// Content-encryption lifecycle for the Local Knowledge capsule store (Issue #1322, Epic #1319;
+// ADR-0047 D4). Runs once at store-open, AFTER the schema migrations and BEFORE any content read.
+//
+// Case matrix (marker in schema_meta records that a store is encrypted):
+//
+//   marker present, opened WITH a key provider     → verify the sealed probe (fail-closed on a wrong
+//                                                     key / tampered probe), then proceed.
+//   marker present, opened WITHOUT a key provider   → throw: the store is encrypted, a key is required.
+//   marker absent,  probe present, WITHOUT a key    → throw: incomplete encrypted migration, a key is
+//                                                     required.
+//   marker absent,  probe present, WITH a key       → verify the existing probe before any mutation,
+//                                                     then finish the idempotent migration.
+//   marker absent,  probe absent,  opened WITHOUT a key → plaintext store opened plaintext: no-op.
+//   marker absent,  opened WITH a key provider      → forward migration: seal every plaintext content
+//                                                     row, write the probe, set the marker, then flush
+//                                                     plaintext from the WAL and freelist.
+//
+// The migration is crash-aware and idempotent: it verifies any existing probe before retrying, seals
+// only rows that do not authenticate with the current key, and sets the marker only after plaintext
+// has been checkpointed and vacuumed away.
+import { KnowledgeStoreError } from "./errors.js";
+import { sectionPathHashFromJson } from "./section-path-hash.js";
+const ENCRYPTION_MARKER_KEY = "content_encryption";
+const ENCRYPTION_MARKER_VALUE = "aes-256-gcm/v1";
+const ENCRYPTION_PROBE_KEY = "content_encryption_probe";
+const ENCRYPTION_SCOPE_KEY = "content_encryption_scope";
+const ENCRYPTION_SCOPE_VALUE = "reconstructive-columns/v2";
+// Fixed, non-secret sentinel. Sealed at migration time and re-opened on every encrypted open to prove
+// the resolved key matches the one the store was sealed with. Never carries customer content.
+const ENCRYPTION_PROBE_PLAINTEXT = "keiko-local-knowledge-content-encryption-v1";
+const BYTES_PER_FLOAT32 = 4;
+function readSchemaMeta(db, key) {
+    const row = db.prepare("SELECT value FROM schema_meta WHERE key = :k").get({ k: key });
+    return row?.value;
+}
+function writeSchemaMeta(db, key, value) {
+    db.prepare("INSERT OR REPLACE INTO schema_meta (key, value) VALUES (:k, :v)").run({
+        k: key,
+        v: value,
+    });
+}
+// Collects a table's rowids up front so the seal pass holds at most one row's content in memory at a
+// time, and never UPDATEs the table while a SELECT cursor over it is still open (SQLite does not
+// guarantee a consistent enumeration in that case). rowids are integers, so the collection is tiny
+// relative to the content it gates — the Issue #1286 bounded-memory invariant holds during migration.
+function collectRowIds(db, table) {
+    const ids = [];
+    for (const row of db.prepare(`SELECT rowid AS rowid FROM ${table}`).iterate()) {
+        ids.push(row.rowid);
+    }
+    return ids;
+}
+const LEGACY_TEXT_TARGETS = [
+    { table: "document_texts", column: "normalized_text" },
+    { table: "document_text_windows", column: "normalized_text" },
+];
+const PATH_TEXT_TARGETS = [
+    { table: "sections", column: "section_path_json" },
+    { table: "parsed_units", column: "section_path_json" },
+    { table: "parsed_units", column: "heading_path_json" },
+];
+const TEXT_TARGETS = [...LEGACY_TEXT_TARGETS, ...PATH_TEXT_TARGETS];
+function isAlreadySealed(cipher, value) {
+    if (!cipher.isSealed(value))
+        return false;
+    try {
+        cipher.openText(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function openMaybeSealedText(cipher, value) {
+    return cipher.isEncrypted && isAlreadySealed(cipher, value) ? cipher.openText(value) : value;
+}
+// Seals every TEXT content row that does not authenticate under the current key, one row at a time.
+// This intentionally does NOT trust the "kv1." prefix alone: a legacy plaintext value can literally
+// start with "kv1.", and must be sealed as plaintext instead of skipped.
+function sealTextColumn(db, target, cipher) {
+    const select = db.prepare(`SELECT ${target.column} AS value FROM ${target.table} WHERE rowid = :id`);
+    const update = db.prepare(`UPDATE ${target.table} SET ${target.column} = :t WHERE rowid = :id`);
+    for (const id of collectRowIds(db, target.table)) {
+        const row = select.get({ id });
+        const value = row?.value;
+        if (value === undefined || value === null || isAlreadySealed(cipher, value))
+            continue;
+        update.run({ t: cipher.sealText(value), id });
+    }
+}
+function ensureSectionPathHashes(db, cipher) {
+    const select = db.prepare("SELECT section_path_json, section_path_hash FROM sections WHERE rowid = :id");
+    const update = db.prepare("UPDATE sections SET section_path_hash = :h WHERE rowid = :id");
+    for (const id of collectRowIds(db, "sections")) {
+        const row = select.get({ id });
+        if (row === undefined)
+            continue;
+        const canonicalJson = openMaybeSealedText(cipher, row.section_path_json);
+        const hash = sectionPathHashFromJson(canonicalJson);
+        if (row.section_path_hash !== hash)
+            update.run({ h: hash, id });
+    }
+}
+function sealTextColumns(db, cipher) {
+    for (const target of TEXT_TARGETS) {
+        sealTextColumn(db, target, cipher);
+    }
+}
+function sealPathTextColumns(db, cipher) {
+    for (const target of PATH_TEXT_TARGETS) {
+        sealTextColumn(db, target, cipher);
+    }
+}
+function assertTextColumnSealed(db, target, cipher) {
+    const select = db.prepare(`SELECT ${target.column} AS value FROM ${target.table} WHERE rowid = :id`);
+    for (const id of collectRowIds(db, target.table)) {
+        const row = select.get({ id });
+        const value = row?.value;
+        if (value === undefined || value === null)
+            continue;
+        if (isAlreadySealed(cipher, value))
+            continue;
+        throw new KnowledgeStoreError(`encrypted Local Knowledge store contains unsealed ${target.table}.${target.column}`);
+    }
+}
+function assertLegacyTextColumnsSealed(db, cipher) {
+    for (const target of LEGACY_TEXT_TARGETS) {
+        assertTextColumnSealed(db, target, cipher);
+    }
+}
+function assertVectorOpens(row, cipher) {
+    const plaintextByteLength = row.vector_dimensions * BYTES_PER_FLOAT32;
+    try {
+        cipher.openVector(row.embedding, plaintextByteLength);
+    }
+    catch (cause) {
+        throw new KnowledgeStoreError("encrypted Local Knowledge vector row is neither plaintext nor a valid sealed envelope", { cause });
+    }
+}
+function sealVectorColumn(db, cipher) {
+    const select = db.prepare("SELECT embedding, vector_dimensions FROM vectors WHERE rowid = :id");
+    const update = db.prepare("UPDATE vectors SET embedding = :e WHERE rowid = :id");
+    for (const id of collectRowIds(db, "vectors")) {
+        const row = select.get({ id });
+        if (row === undefined)
+            continue;
+        if (row.embedding.byteLength === row.vector_dimensions * BYTES_PER_FLOAT32) {
+            update.run({ e: cipher.sealVector(row.embedding), id });
+            continue;
+        }
+        assertVectorOpens(row, cipher);
+    }
+}
+function assertVectorColumnSealed(db, cipher) {
+    const select = db.prepare("SELECT embedding, vector_dimensions FROM vectors WHERE rowid = :id");
+    for (const id of collectRowIds(db, "vectors")) {
+        const row = select.get({ id });
+        if (row !== undefined)
+            assertVectorOpens(row, cipher);
+    }
+}
+function sealReconstructiveContent(db, cipher) {
+    ensureSectionPathHashes(db, cipher);
+    sealTextColumns(db, cipher);
+    sealVectorColumn(db, cipher);
+}
+function flushPlaintextResidue(db) {
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    db.exec("VACUUM");
+}
+function migrateToEncrypted(db, cipher) {
+    // Phase 1 (transactional): seal every content row and write the sealed key-verification probe. The
+    // completion MARKER is deliberately NOT written here — see phase 2.
+    db.exec("BEGIN");
+    try {
+        sealReconstructiveContent(db, cipher);
+        writeSchemaMeta(db, ENCRYPTION_PROBE_KEY, cipher.sealText(ENCRYPTION_PROBE_PLAINTEXT));
+        db.exec("COMMIT");
+    }
+    catch (cause) {
+        db.exec("ROLLBACK");
+        throw new KnowledgeStoreError("failed to migrate Local Knowledge store content to encrypted storage", { cause });
+    }
+    // Phase 2: after the in-place UPDATEs, plaintext can linger in the WAL and on freed pages. Truncate
+    // the WAL and VACUUM so the rewritten file holds no plaintext extracted text, path labels, or
+    // vector bytes (ADR-0047 D4). These run outside the transaction; VACUUM cannot run inside one.
+    // Phase 3: mark the store encrypted ONLY after the file has been rewritten free of plaintext. If
+    // phase 2 throws (I/O error, disk full), the marker stays unset, this open fails closed, and the
+    // next open re-runs the idempotent migration instead of skipping it over a WAL that still holds
+    // plaintext. The seal sweep is a no-op on the already-sealed rows, so the retry only re-checkpoints
+    // and re-VACUUMs.
+    flushPlaintextResidue(db);
+    writeSchemaMeta(db, ENCRYPTION_MARKER_KEY, ENCRYPTION_MARKER_VALUE);
+    writeSchemaMeta(db, ENCRYPTION_SCOPE_KEY, ENCRYPTION_SCOPE_VALUE);
+}
+function upgradeEncryptedScope(db, cipher) {
+    db.exec("BEGIN");
+    try {
+        ensureSectionPathHashes(db, cipher);
+        assertLegacyTextColumnsSealed(db, cipher);
+        assertVectorColumnSealed(db, cipher);
+        sealPathTextColumns(db, cipher);
+        db.exec("COMMIT");
+    }
+    catch (cause) {
+        db.exec("ROLLBACK");
+        throw new KnowledgeStoreError("failed to upgrade Local Knowledge encrypted-content coverage", {
+            cause,
+        });
+    }
+    flushPlaintextResidue(db);
+    writeSchemaMeta(db, ENCRYPTION_SCOPE_KEY, ENCRYPTION_SCOPE_VALUE);
+}
+function verifyProbe(db, cipher) {
+    const probe = readSchemaMeta(db, ENCRYPTION_PROBE_KEY);
+    if (probe === undefined || !cipher.isSealed(probe)) {
+        throw new KnowledgeStoreError("encrypted Local Knowledge store is missing or has a malformed key-verification probe " +
+            "(corrupt store or incomplete migration)");
+    }
+    let opened;
+    try {
+        opened = cipher.openText(probe);
+    }
+    catch (cause) {
+        throw new KnowledgeStoreError("cannot open encrypted Local Knowledge store: wrong key or tampered content", { cause });
+    }
+    if (opened !== ENCRYPTION_PROBE_PLAINTEXT) {
+        throw new KnowledgeStoreError("cannot open encrypted Local Knowledge store: key-verification probe mismatch");
+    }
+}
+// Reconciles the store's on-disk encryption state with the resolved cipher. Called once from
+// openKnowledgeStore after migrations and before the handle is returned.
+export function applyStoreContentEncryption(db, cipher) {
+    const marker = readSchemaMeta(db, ENCRYPTION_MARKER_KEY);
+    const probe = readSchemaMeta(db, ENCRYPTION_PROBE_KEY);
+    const scope = readSchemaMeta(db, ENCRYPTION_SCOPE_KEY);
+    if (marker !== undefined) {
+        if (marker !== ENCRYPTION_MARKER_VALUE) {
+            throw new KnowledgeStoreError(`unsupported Local Knowledge content encryption marker: ${marker}`);
+        }
+        if (!cipher.isEncrypted) {
+            throw new KnowledgeStoreError("this Local Knowledge store is encrypted; a key provider is required to open it");
+        }
+        verifyProbe(db, cipher);
+        if (scope !== undefined && scope !== ENCRYPTION_SCOPE_VALUE) {
+            throw new KnowledgeStoreError(`unsupported Local Knowledge content encryption scope marker: ${scope}`);
+        }
+        if (scope !== ENCRYPTION_SCOPE_VALUE) {
+            upgradeEncryptedScope(db, cipher);
+        }
+        return;
+    }
+    if (probe !== undefined) {
+        if (!cipher.isEncrypted) {
+            throw new KnowledgeStoreError("this Local Knowledge store has an incomplete encrypted-content migration; " +
+                "a key provider is required to finish opening it");
+        }
+        verifyProbe(db, cipher);
+        migrateToEncrypted(db, cipher);
+        return;
+    }
+    if (!cipher.isEncrypted) {
+        ensureSectionPathHashes(db, cipher);
+        return;
+    }
+    migrateToEncrypted(db, cipher);
+}
+export const STORE_CONTENT_ENCRYPTION_TEST_CONSTANTS = {
+    markerKey: ENCRYPTION_MARKER_KEY,
+    markerValue: ENCRYPTION_MARKER_VALUE,
+    probeKey: ENCRYPTION_PROBE_KEY,
+    probePlaintext: ENCRYPTION_PROBE_PLAINTEXT,
+    scopeKey: ENCRYPTION_SCOPE_KEY,
+    scopeValue: ENCRYPTION_SCOPE_VALUE,
+};

package/dist/store-paths.d.ts

@@ -0,0 +1,6 @@
+export interface ResolveKnowledgeStorePathOptions {
+    readonly runtimeStateDir: string;
+    readonly namespace?: string;
+}
+export declare function resolveKnowledgeStorePath(opts: ResolveKnowledgeStorePathOptions): string;
+//# sourceMappingURL=store-paths.d.ts.map

package/dist/store-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-paths.d.ts","sourceRoot":"","sources":["../src/store-paths.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA0CD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,gCAAgC,GAAG,MAAM,CAcxF"}

package/dist/store-paths.js

@@ -0,0 +1,61 @@
+// Pure path arithmetic for the local-knowledge capsule store. Resolves the on-disk DB path
+// from a runtime-state directory + optional namespace, with hard fail-closed rules:
+//   * runtimeStateDir must be non-empty.
+//   * namespace (when provided) must be non-empty, must not contain NUL, must not start with
+//     `~`, must not be absolute, must not contain `..` segments, and must reduce to a single
+//     path segment (no slashes in either direction).
+//   * The resolved path is asserted to live inside `runtimeStateDir` — caller code that
+//     trusts a runtime-state root for path containment must never receive a value outside it.
+//
+// This module performs NO filesystem access (no `node:fs` import). The runtime opener in
+// store.ts owns directory creation and atomic operations.
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { KnowledgePathError } from "./errors.js";
+const DEFAULT_NAMESPACE = "default";
+const DB_FILE_NAME = "capsules.db";
+const SUBSYSTEM_DIR = "local-knowledge";
+function rejectInvalidNamespace(namespace) {
+    if (namespace.length === 0) {
+        throw new KnowledgePathError("namespace must not be empty when provided.");
+    }
+    if (namespace.includes("\0")) {
+        throw new KnowledgePathError("namespace must not contain NUL bytes.");
+    }
+    if (namespace.startsWith("~")) {
+        throw new KnowledgePathError("namespace must not start with `~`; resolve home directories at the caller.");
+    }
+    if (isAbsolute(namespace)) {
+        throw new KnowledgePathError("namespace must not be an absolute path.");
+    }
+    if (namespace.includes("/") || namespace.includes("\\")) {
+        throw new KnowledgePathError("namespace must be a single path segment.");
+    }
+    if (namespace === "." || namespace === "..") {
+        throw new KnowledgePathError("namespace must not be `.` or `..`.");
+    }
+}
+function assertContained(resolvedPath, base) {
+    // resolve() normalises away `.`/`..` segments. If the result is not a strict descendant of
+    // the resolved base, the input escaped the root via some path the prior segment-level
+    // rejections missed and we MUST fail closed.
+    const normalisedBase = resolve(base);
+    const normalisedPath = resolve(resolvedPath);
+    if (normalisedPath !== normalisedBase && !normalisedPath.startsWith(normalisedBase + sep)) {
+        throw new KnowledgePathError("Resolved knowledge-store path escaped its runtimeStateDir; refusing to open.");
+    }
+}
+export function resolveKnowledgeStorePath(opts) {
+    if (opts.runtimeStateDir.length === 0) {
+        throw new KnowledgePathError("runtimeStateDir must not be empty.");
+    }
+    if (opts.runtimeStateDir.includes("\0")) {
+        throw new KnowledgePathError("runtimeStateDir must not contain NUL bytes.");
+    }
+    const namespace = opts.namespace ?? DEFAULT_NAMESPACE;
+    if (opts.namespace !== undefined) {
+        rejectInvalidNamespace(namespace);
+    }
+    const candidate = join(opts.runtimeStateDir, SUBSYSTEM_DIR, namespace, DB_FILE_NAME);
+    assertContained(candidate, opts.runtimeStateDir);
+    return candidate;
+}

package/dist/store.d.ts

@@ -0,0 +1,30 @@
+import { DatabaseSync } from "node:sqlite";
+import { type StoreContentCipher } from "./store-content-cipher.js";
+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;
+    readonly _internal: {
+        readonly db: DatabaseSync;
+        readonly now: () => number;
+        readonly contentCipher: StoreContentCipher;
+    };
+}
+export declare const LK_STORE_BUSY_TIMEOUT_MS = 5000;
+export declare function openKnowledgeStore(opts: OpenKnowledgeStoreOptions): KnowledgeStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,2BAA2B,CAAC;AAGnC,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;QAI3B,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;KAC5C,CAAC;CACH;AAkBD,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AA8K9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,cAAc,CAoClF"}

package/dist/store.js

@@ -0,0 +1,219 @@
+// Capsule store runtime. Opens a node:sqlite database, sets durability/correctness pragmas
+// (WAL journal + NORMAL synchronous + foreign_keys), applies the #265 DDL via the migration
+// runner, and quarantines partial-write / wrong-schema files to `.corrupt.<iso>`.
+//
+// Foundry-IQ invariants enforced here:
+//   * PRAGMA foreign_keys=ON before any insert so capsule_id NOT NULL cascades and the
+//     composite (capsule_id, source/document/chunk) FKs cannot be silently bypassed.
+//   * Mirroring keiko-server's #62 pattern, a structurally corrupt file is renamed aside
+//     (preserving sidecars) rather than reformatted in place — operators recover the file
+//     by hand if it was actually data.
+//
+// Crash-safe write tradeoffs documented inline next to each PRAGMA call.
+import { chmodSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { KNOWLEDGE_CAPSULE_MIGRATIONS, KNOWLEDGE_CAPSULE_TABLES, KNOWLEDGE_CAPSULE_V1_TABLES, } from "@oscharko-dev/keiko-contracts";
+import { KnowledgeStoreError } from "./errors.js";
+import { createEncryptedContentCipher, PLAINTEXT_CONTENT_CIPHER, } from "./store-content-cipher.js";
+import { applyStoreContentEncryption } from "./store-content-encryption.js";
+function defaultClock() {
+    return Date.now();
+}
+// Concurrent writers (indexing write + grounded-ask audit INSERT) must wait for the writer
+// lock instead of failing immediately with SQLITE_BUSY → HTTP 500. 5_000ms matches the
+// keiko-server UI DB constant (packages/keiko-server/src/store/db.ts, issue #639) and is
+// the conservative default for the local single-writer desktop pattern.
+export const LK_STORE_BUSY_TIMEOUT_MS = 5_000;
+function applyDurabilityPragmas(db) {
+    // WAL: crash-safe single-writer; readers do not block the writer. Right tradeoff for
+    // the indexing+retrieval mix the local-knowledge layer will see.
+    db.exec("PRAGMA journal_mode = WAL");
+    // synchronous=NORMAL: fsyncs on commit boundaries but skips the fsync between WAL
+    // appends. Standard durability/latency choice for embedded apps where the user controls
+    // the host process; matches keiko-server's #62 store.
+    db.exec("PRAGMA synchronous = NORMAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec(`PRAGMA busy_timeout = ${String(LK_STORE_BUSY_TIMEOUT_MS)}`);
+}
+// Resolves the store-boundary content cipher from the protection options. Plaintext (identity cipher)
+// is the default: a store opened without a key provider behaves exactly as before. Encryption is
+// requested by `encrypted-key-provider` mode or by supplying a keyProvider; the provider's 32-byte key
+// (resolved for this dbPath + schema version) binds an AES-256-GCM cipher (ADR-0047 D1/D2).
+function resolveContentCipher(opts, schemaVersion) {
+    const protection = opts.protection;
+    if (protection === undefined)
+        return PLAINTEXT_CONTENT_CIPHER;
+    const encryptionRequested = protection.mode === "encrypted-key-provider" || protection.keyProvider !== undefined;
+    if (!encryptionRequested)
+        return PLAINTEXT_CONTENT_CIPHER;
+    const provider = protection.keyProvider;
+    if (provider === undefined) {
+        throw new KnowledgeStoreError("encrypted-key-provider protection requires a keyProvider to resolve the store key");
+    }
+    const key = provider.resolveKey({ dbPath: opts.dbPath, schemaVersion });
+    return createEncryptedContentCipher(key);
+}
+function currentUserVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    return typeof row?.user_version === "number" ? row.user_version : 0;
+}
+function setUserVersion(db, version) {
+    // user_version is not parameterisable. The value here is an integer constant from the
+    // contracts package's migration manifest, never caller input.
+    db.exec(`PRAGMA user_version = ${String(version)}`);
+}
+function runMigrations(db) {
+    const start = currentUserVersion(db);
+    const pending = KNOWLEDGE_CAPSULE_MIGRATIONS.filter((m) => m.version > start);
+    if (pending.length === 0)
+        return;
+    db.exec("BEGIN");
+    try {
+        for (const migration of pending) {
+            for (const statement of migration.up) {
+                db.exec(statement);
+            }
+            setUserVersion(db, migration.version);
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw new KnowledgeStoreError(`Failed to apply knowledge-capsule migration (start=${String(start)})`, { cause: error });
+    }
+}
+function listExistingTables(db) {
+    const rows = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all();
+    return rows.map((row) => row.name);
+}
+function hasAnyUserContent(db) {
+    // Non-empty sqlite_master OR non-zero user_version → the file is "in use" by something.
+    // Either means: don't silently overwrite; quarantine and start fresh.
+    const tables = listExistingTables(db);
+    const userTables = tables.filter((n) => !n.startsWith("sqlite_"));
+    if (userTables.length > 0)
+        return true;
+    return currentUserVersion(db) !== 0;
+}
+function expectedV1TablesPresent(db) {
+    // Only checks the v1 table set (pre-migration). Used before runMigrations so that a v1
+    // database with a valid pre-v2 schema is not quarantined as corrupt.
+    const present = new Set(listExistingTables(db));
+    for (const expected of KNOWLEDGE_CAPSULE_V1_TABLES) {
+        if (!present.has(expected))
+            return false;
+    }
+    return true;
+}
+function expectedTablesPresent(db) {
+    const present = new Set(listExistingTables(db));
+    for (const expected of KNOWLEDGE_CAPSULE_TABLES) {
+        if (!present.has(expected))
+            return false;
+    }
+    return true;
+}
+function quarantineFile(target) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    if (existsSync(target)) {
+        renameSync(target, `${target}.corrupt.${ts}`);
+    }
+    for (const sidecar of [`${target}-wal`, `${target}-shm`]) {
+        if (existsSync(sidecar)) {
+            renameSync(sidecar, `${sidecar}.corrupt.${ts}`);
+        }
+    }
+}
+function tryOpenAndMigrate(dbPath, onError) {
+    // Returns the opened, migrated handle on success; undefined when the file is unusable
+    // (open threw OR the post-migrate schema is missing expected tables OR the file held
+    // foreign content that we refuse to coexist with). Callers handle quarantine + retry.
+    let db;
+    try {
+        db = new DatabaseSync(dbPath);
+    }
+    catch {
+        // Cannot open at all (file missing permissions, OS error). Caller quarantines and retries.
+        return undefined;
+    }
+    try {
+        applyDurabilityPragmas(db);
+        if (hasAnyUserContent(db) && !expectedV1TablesPresent(db)) {
+            // Pre-existing foreign schema or a partial install missing even the v1 tables.
+            // Quarantine and retry. The v1 check is intentionally narrow: a v1 database that
+            // has not yet been migrated to v2 passes here, then runMigrations upgrades it.
+            db.close();
+            return undefined;
+        }
+        runMigrations(db);
+        if (!expectedTablesPresent(db)) {
+            db.close();
+            return undefined;
+        }
+        return db;
+    }
+    catch (cause) {
+        onError?.(cause);
+        try {
+            db.close();
+        }
+        catch {
+            // ignore close failure; outer caller will quarantine and retry
+        }
+        return undefined;
+    }
+}
+function ensureParentDir(dbPath) {
+    const dir = dirname(dbPath);
+    if (!existsSync(dir)) {
+        // 0o700: best-effort on POSIX; ignored on win32.
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    restrictPathPermissions(dir, 0o700);
+}
+function restrictPathPermissions(target, mode) {
+    if (process.platform === "win32" || !existsSync(target))
+        return;
+    chmodSync(target, mode);
+}
+function restrictStoreFilePermissions(dbPath) {
+    restrictPathPermissions(dbPath, 0o600);
+    restrictPathPermissions(`${dbPath}-wal`, 0o600);
+    restrictPathPermissions(`${dbPath}-shm`, 0o600);
+}
+export function openKnowledgeStore(opts) {
+    ensureParentDir(opts.dbPath);
+    let db = tryOpenAndMigrate(opts.dbPath);
+    let lastError;
+    if (db === undefined) {
+        quarantineFile(opts.dbPath);
+        db = tryOpenAndMigrate(opts.dbPath, (cause) => {
+            lastError = cause;
+        });
+    }
+    if (db === undefined) {
+        throw new KnowledgeStoreError(`Failed to open knowledge-capsule store at ${opts.dbPath} even after quarantine.`, lastError !== undefined ? { cause: lastError } : undefined);
+    }
+    // The cipher binds the key resolved for the migrated schema version. Reconcile the store's on-disk
+    // encryption state before the handle is usable: this seals a legacy plaintext store forward, or
+    // fails closed on a wrong key / missing provider for an already-encrypted store (ADR-0047 D4). A
+    // failure here closes the handle so a half-open store never leaks.
+    const contentCipher = resolveContentCipher(opts, currentUserVersion(db));
+    try {
+        applyStoreContentEncryption(db, contentCipher);
+    }
+    catch (cause) {
+        db.close();
+        throw cause;
+    }
+    restrictStoreFilePermissions(opts.dbPath);
+    const now = opts.clock ?? defaultClock;
+    const handle = db;
+    return {
+        close: () => {
+            handle.close();
+        },
+        _internal: { db: handle, now, contentCipher },
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,47 @@
+import type { ChunkId, DocumentId, EmbeddingModelIdentity, KnowledgeCapsuleId, KnowledgeSourceId, ParsedUnit } from "@oscharko-dev/keiko-contracts";
+import type { OpenAIEmbeddingAdapter, OpenAIEmbeddingOutcome, OpenAIEmbeddingRequest } from "@oscharko-dev/keiko-model-gateway";
+import type { ChunkingOptions } from "./chunking/types.js";
+import type { KnowledgeStore } from "./store.js";
+type ParsedUnitWithoutDocId = Omit<Extract<ParsedUnit, {
+    kind: "page";
+}>, "documentId"> | Omit<Extract<ParsedUnit, {
+    kind: "section";
+}>, "documentId"> | Omit<Extract<ParsedUnit, {
+    kind: "json-path";
+}>, "documentId"> | Omit<Extract<ParsedUnit, {
+    kind: "csv-row";
+}>, "documentId"> | Omit<Extract<ParsedUnit, {
+    kind: "html-block";
+}>, "documentId"> | Omit<Extract<ParsedUnit, {
+    kind: "unsupported-media";
+}>, "documentId">;
+export interface SeedVectorsOptions {
+    readonly capsuleId?: string;
+    readonly displayName?: string;
+    readonly sourceId?: string;
+    readonly documentId?: string;
+    readonly text?: string;
+    readonly unit?: ParsedUnitWithoutDocId;
+    readonly identity?: EmbeddingModelIdentity;
+    readonly contentHash?: string;
+    readonly safeDisplayName?: string;
+    readonly chunkingOptions?: ChunkingOptions;
+}
+export interface SeededVectors {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly chunkIds: readonly ChunkId[];
+    readonly vectorTexts: readonly string[];
+}
+export declare function deterministicVector(input: string, dimensions: number): Float32Array;
+export interface ScriptedAdapterOptions {
+    readonly responder?: (request: OpenAIEmbeddingRequest) => OpenAIEmbeddingOutcome;
+    readonly identity?: EmbeddingModelIdentity;
+    readonly endpoint?: string;
+    readonly apiKey?: string;
+}
+export declare function scriptedAdapter(options?: ScriptedAdapterOptions): OpenAIEmbeddingAdapter;
+export declare function seedCapsuleWithVectors(store: KnowledgeStore, options?: SeedVectorsOptions): Promise<SeededVectors>;
+export {};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACX,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AASjD,KAAK,sBAAsB,GACvB,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,YAAY,CAAC,GACzD,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EAAE,YAAY,CAAC,GAC5D,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,EAAE,YAAY,CAAC,GAC9D,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EAAE,YAAY,CAAC,GAC5D,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,EAAE,YAAY,CAAC,GAC/D,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,EAAE,YAAY,CAAC,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;CAC5C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAWnF;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,sBAAsB,CAAC;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,sBAAsB,CAkB5F;AAkLD,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,aAAa,CAAC,CAYxB"}