@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/capsule-lifecycle.js

@@ -0,0 +1,292 @@
+// capsule-lifecycle.ts — typed CRUD over the `capsules` table plus its FK-driven cascade.
+//
+// Invariants:
+//   * Every write runs inside `BEGIN`/`COMMIT` so partial state never lands on disk.
+//   * createCapsule rejects duplicate ids via the PRIMARY KEY — raised as KnowledgeStoreError.
+//   * Reads compose `sourceIds` from the live `capsule_sources` table — the capsule row
+//     does NOT denormalise the source list, so the reverse FK is the single truth.
+//   * deleteCapsule relies on the schema's ON DELETE CASCADE chain (#265). Removing the
+//     CASCADE clause from any dependent table will either throw an FK violation (when
+//     foreign_keys=ON catches a leftover) or leave orphan rows the cascade test catches.
+import { DELETE_CAPSULE_SQL, isSafeStorageReference, isSafeDisplaySummary, } from "@oscharko-dev/keiko-contracts";
+import { KnowledgeNotFoundError, KnowledgeStoreError } from "./errors.js";
+const INSERT_CAPSULE_SQL = [
+    "INSERT INTO capsules (",
+    "  id, display_name, description, tags_json, source_routing_instructions, always_query,",
+    "  retrieval_effort, output_mode, answer_grounding_policy,",
+    "  embedding_model_provider, embedding_model_id, embedding_model_revision,",
+    "  vector_dimensions, vector_metric, lifecycle_state, storage_reference,",
+    "  created_at, updated_at",
+    ") VALUES (",
+    "  :id, :display_name, :description, :tags_json, :source_routing_instructions, :always_query,",
+    "  :retrieval_effort, :output_mode, :answer_grounding_policy,",
+    "  :embedding_model_provider, :embedding_model_id, :embedding_model_revision,",
+    "  :vector_dimensions, :vector_metric, :lifecycle_state, :storage_reference,",
+    "  :created_at, :updated_at",
+    ")",
+].join(" ");
+const SELECT_CAPSULE_BY_ID_SQL = "SELECT * FROM capsules WHERE id = :id";
+const SELECT_ALL_CAPSULES_SQL = "SELECT * FROM capsules ORDER BY created_at ASC, id ASC";
+const SELECT_SOURCE_IDS_FOR_CAPSULE_SQL = "SELECT id FROM capsule_sources WHERE capsule_id = :c ORDER BY created_at ASC, id ASC";
+const UPDATE_STATE_SQL = "UPDATE capsules SET lifecycle_state = :state, updated_at = :now WHERE id = :id";
+const SELECT_AFFECTED_CAPSULE_SETS_SQL = "SELECT set_id FROM capsule_set_members WHERE capsule_id = :c ORDER BY set_id ASC";
+const DELETE_VERIFICATION_TABLES = [
+    "capsule_sources",
+    "capsule_set_members",
+    "documents",
+    "document_texts",
+    "document_text_windows",
+    "extraction_checkpoints",
+    "pages",
+    "sections",
+    "parsed_units",
+    "chunks",
+    "vectors",
+    "parser_diagnostics",
+    "indexing_jobs",
+];
+function jsonOrEmpty(value) {
+    return JSON.stringify(value);
+}
+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 assertSafeCreateCapsuleInput(input) {
+    assertSafeDisplayField("displayName", input.displayName);
+    assertSafeOptionalDisplayField("description", input.description);
+    assertSafeOptionalDisplayField("sourceRoutingInstructions", input.sourceRoutingInstructions);
+    for (const tag of input.tags) {
+        assertSafeDisplayField("tag", tag);
+    }
+    if (!isSafeStorageReference(input.storageReference)) {
+        throw new KnowledgeStoreError("storageReference must be a safe relative path");
+    }
+}
+function listSourceIdsFor(store, capsuleId) {
+    const rows = store._internal.db.prepare(SELECT_SOURCE_IDS_FOR_CAPSULE_SQL).all({ c: capsuleId });
+    return rows.map((row) => row.id);
+}
+function buildEmbeddingIdentity(row) {
+    const base = {
+        provider: row.embedding_model_provider,
+        modelId: row.embedding_model_id,
+        vectorDimensions: row.vector_dimensions,
+        vectorMetric: row.vector_metric,
+    };
+    if (row.embedding_model_revision === null)
+        return base;
+    return { ...base, modelRevision: row.embedding_model_revision };
+}
+function rowToCapsule(row, sourceIds) {
+    const base = {
+        id: row.id,
+        displayName: row.display_name,
+        tags: parseTags(row.tags_json),
+        sourceIds,
+        retrievalEffort: row.retrieval_effort,
+        outputMode: row.output_mode,
+        answerGroundingPolicy: row.answer_grounding_policy,
+        embeddingModelIdentity: buildEmbeddingIdentity(row),
+        lifecycleState: row.lifecycle_state,
+        storageReference: row.storage_reference,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+    return withOptionalCapsuleFields(base, row);
+}
+function withOptionalCapsuleFields(base, row) {
+    // exactOptionalPropertyTypes requires us to OMIT absent optionals rather than set them
+    // to undefined. Spread the optionals only when they are present in the row.
+    let result = base;
+    if (row.description !== null) {
+        result = { ...result, description: row.description };
+    }
+    if (row.source_routing_instructions !== null) {
+        result = { ...result, sourceRoutingInstructions: row.source_routing_instructions };
+    }
+    if (row.always_query === 1) {
+        result = { ...result, alwaysQuery: true };
+    }
+    else if (row.always_query === 0) {
+        // alwaysQuery defaults to undefined when stored as 0; we mirror "no" as omitted.
+    }
+    return result;
+}
+export function createCapsule(store, input, auditSink) {
+    assertSafeCreateCapsuleInput(input);
+    const now = store._internal.now();
+    const params = {
+        id: input.id,
+        display_name: input.displayName,
+        description: input.description ?? null,
+        tags_json: jsonOrEmpty(input.tags),
+        source_routing_instructions: input.sourceRoutingInstructions ?? null,
+        always_query: input.alwaysQuery === true ? 1 : 0,
+        retrieval_effort: input.retrievalEffort,
+        output_mode: input.outputMode,
+        answer_grounding_policy: input.answerGroundingPolicy,
+        embedding_model_provider: input.embeddingModelIdentity.provider,
+        embedding_model_id: input.embeddingModelIdentity.modelId,
+        embedding_model_revision: input.embeddingModelIdentity.modelRevision ?? null,
+        vector_dimensions: input.embeddingModelIdentity.vectorDimensions,
+        vector_metric: input.embeddingModelIdentity.vectorMetric,
+        lifecycle_state: input.lifecycleState,
+        storage_reference: input.storageReference,
+        created_at: now,
+        updated_at: now,
+    };
+    const db = store._internal.db;
+    db.exec("BEGIN");
+    try {
+        db.prepare(INSERT_CAPSULE_SQL).run(params);
+        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("capsule already exists", { cause: error });
+        }
+        throw new KnowledgeStoreError("failed to create capsule", { cause: error });
+    }
+    const capsule = getCapsule(store, input.id);
+    if (capsule === undefined) {
+        // Defensive: a successful INSERT must be readable. This branch indicates a serious
+        // store-level inconsistency (e.g. concurrent DELETE) and the caller cannot continue
+        // safely with a synthesised value.
+        throw new KnowledgeStoreError(`createCapsule: insert succeeded but row not found for ${String(input.id)}`);
+    }
+    auditSink?.emit({ kind: "capsule-created", capsuleId: capsule.id, occurredAt: now });
+    return capsule;
+}
+export function getCapsule(store, id) {
+    const row = store._internal.db.prepare(SELECT_CAPSULE_BY_ID_SQL).get({ id });
+    if (row === undefined)
+        return undefined;
+    const sourceIds = listSourceIdsFor(store, id);
+    return rowToCapsule(row, sourceIds);
+}
+export function listCapsules(store) {
+    const rows = store._internal.db.prepare(SELECT_ALL_CAPSULES_SQL).all();
+    return rows.map((row) => {
+        const typed = row;
+        const sourceIds = listSourceIdsFor(store, typed.id);
+        return rowToCapsule(typed, sourceIds);
+    });
+}
+export function updateCapsuleState(store, id, state) {
+    const db = store._internal.db;
+    const now = store._internal.now();
+    db.exec("BEGIN");
+    try {
+        const result = db.prepare(UPDATE_STATE_SQL).run({ state, now, id });
+        if (Number(result.changes) === 0) {
+            db.exec("ROLLBACK");
+            throw new KnowledgeNotFoundError(`Capsule not found: ${String(id)}`);
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        if (!(error instanceof KnowledgeNotFoundError)) {
+            db.exec("ROLLBACK");
+        }
+        throw error;
+    }
+    const capsule = getCapsule(store, id);
+    if (capsule === undefined) {
+        throw new KnowledgeNotFoundError(`Capsule not found after update: ${String(id)}`);
+    }
+    return capsule;
+}
+// Slice 4 (#189): update a capsule's display name / description. The SET clause is built only
+// from the columns present in the patch; column fragments are fixed literals (no user input),
+// so values stay fully parameterised. Metadata persistence is a separate schema migration and is
+// intentionally NOT handled here.
+export function updateCapsuleDetails(store, id, patch) {
+    const assignments = [];
+    const params = { id, now: store._internal.now() };
+    if (patch.displayName !== undefined) {
+        assertSafeDisplayField("displayName", patch.displayName);
+        assignments.push("display_name = :displayName");
+        params.displayName = patch.displayName;
+    }
+    if (patch.description !== undefined) {
+        assertSafeOptionalDisplayField("description", patch.description);
+        assignments.push("description = :description");
+        params.description = patch.description;
+    }
+    if (assignments.length === 0) {
+        throw new KnowledgeStoreError("updateCapsuleDetails requires at least one field to change.");
+    }
+    const sql = `UPDATE capsules SET ${assignments.join(", ")}, updated_at = :now WHERE id = :id`;
+    const db = store._internal.db;
+    db.exec("BEGIN");
+    try {
+        const result = db.prepare(sql).run(params);
+        if (Number(result.changes) === 0) {
+            db.exec("ROLLBACK");
+            throw new KnowledgeNotFoundError(`Capsule not found: ${String(id)}`);
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        if (!(error instanceof KnowledgeNotFoundError)) {
+            db.exec("ROLLBACK");
+        }
+        throw error;
+    }
+    const capsule = getCapsule(store, id);
+    if (capsule === undefined) {
+        throw new KnowledgeNotFoundError(`Capsule not found after update: ${String(id)}`);
+    }
+    return capsule;
+}
+export function deleteCapsule(store, id, auditSink) {
+    const db = store._internal.db;
+    const occurredAt = store._internal.now();
+    const affectedCapsuleSetIds = db
+        .prepare(SELECT_AFFECTED_CAPSULE_SETS_SQL)
+        .all({ c: id })
+        .map((row) => row.set_id);
+    db.exec("BEGIN");
+    try {
+        const result = db.prepare(DELETE_CAPSULE_SQL).run({ capsule_id: id });
+        if (Number(result.changes) === 0) {
+            db.exec("ROLLBACK");
+            throw new KnowledgeNotFoundError(`Capsule not found: ${String(id)}`);
+        }
+        verifyDeleteCleanup(db, id);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        if (!(error instanceof KnowledgeNotFoundError)) {
+            db.exec("ROLLBACK");
+        }
+        throw error;
+    }
+    auditSink?.emit({ kind: "capsule-deleted", capsuleId: id, occurredAt });
+    return { capsuleId: id, affectedCapsuleSetIds, cleanupVerified: true };
+}
+function verifyDeleteCleanup(db, capsuleId) {
+    for (const table of DELETE_VERIFICATION_TABLES) {
+        const row = db
+            .prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE capsule_id = :c`)
+            .get({ c: capsuleId });
+        if (row.n !== 0) {
+            throw new KnowledgeStoreError(`capsule delete left residual rows in ${table} for ${String(capsuleId)}`);
+        }
+    }
+}

package/dist/capsule-set-lifecycle.d.ts

@@ -0,0 +1,15 @@
+import { type CapsuleSet, type CapsuleSetId, type KnowledgeCapsuleId } from "@oscharko-dev/keiko-contracts";
+import type { KnowledgeStore } from "./store.js";
+export interface CreateCapsuleSetInput {
+    readonly id: CapsuleSetId;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly capsuleIds: readonly KnowledgeCapsuleId[];
+}
+export declare function createCapsuleSetWithinTxn(store: KnowledgeStore, input: CreateCapsuleSetInput, now: number): void;
+export declare function createCapsuleSet(store: KnowledgeStore, input: CreateCapsuleSetInput): CapsuleSet;
+export declare function getCapsuleSet(store: KnowledgeStore, id: CapsuleSetId): CapsuleSet | undefined;
+export declare function listCapsuleSets(store: KnowledgeStore): readonly CapsuleSet[];
+export declare function deleteCapsuleSet(store: KnowledgeStore, id: CapsuleSetId): void;
+//# sourceMappingURL=capsule-set-lifecycle.d.ts.map

package/dist/capsule-set-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule-set-lifecycle.d.ts","sourceRoot":"","sources":["../src/capsule-set-lifecycle.ts"],"names":[],"mappings":"AAYA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,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,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAwFD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,qBAAqB,EAC5B,GAAG,EAAE,MAAM,GACV,IAAI,CAuBN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,qBAAqB,GAAG,UAAU,CAsBhG;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS,CAQ7F;AAOD,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,UAAU,EAAE,CAc5E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,YAAY,GAAG,IAAI,CAiB9E"}

package/dist/capsule-set-lifecycle.js

@@ -0,0 +1,158 @@
+// capsule-set-lifecycle.ts — CapsuleSets are LOGICAL compositions: they hold capsule IDs
+// only, never vectors/chunks/documents (Foundry-IQ "no global pool" invariant).
+//
+// The #265 schema declares `capsule_set_members(set_id, capsule_id, ordinal, composed_at)`
+// but does NOT declare a top-level `capsule_sets` table; #265 explicitly defers the set's
+// metadata storage to consumers because the contract layer only knows the membership
+// relation. We persist the metadata (display name, description, tags) as a single row in
+// the existing `schema_meta` key-value table under key `capsule_set:<id>`, with the JSON
+// payload `{displayName, description?, tags, composedAt}`. Members live in their declared
+// table. Deleting a capsule cascades to the membership row via the FK from #265; this
+// module does not need to chase it.
+import { isSafeDisplaySummary, } from "@oscharko-dev/keiko-contracts";
+import { KnowledgeNotFoundError, KnowledgeStoreError } from "./errors.js";
+const META_PREFIX = "capsule_set:";
+function metaKey(id) {
+    return `${META_PREFIX}${String(id)}`;
+}
+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 parseMeta(value, id) {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new KnowledgeStoreError(`Corrupt schema_meta payload for ${String(id)}.`);
+    }
+    const obj = parsed;
+    const displayName = obj.displayName;
+    const description = obj.description;
+    const tags = obj.tags;
+    const composedAt = obj.composedAt;
+    if (typeof displayName !== "string") {
+        throw new KnowledgeStoreError(`schema_meta payload missing displayName for ${String(id)}.`);
+    }
+    if (typeof composedAt !== "number") {
+        throw new KnowledgeStoreError(`schema_meta payload missing composedAt for ${String(id)}.`);
+    }
+    return {
+        displayName,
+        description: typeof description === "string" ? description : null,
+        tags: Array.isArray(tags) ? tags.filter((t) => typeof t === "string") : [],
+        composedAt,
+    };
+}
+function readMembers(store, setId) {
+    const rows = store._internal.db
+        .prepare("SELECT capsule_id, ordinal FROM capsule_set_members WHERE set_id = :s ORDER BY ordinal ASC")
+        .all({ s: setId });
+    return rows.map((row) => row.capsule_id);
+}
+function metaToCapsuleSet(id, payload, capsuleIds) {
+    const base = {
+        id,
+        displayName: payload.displayName,
+        tags: payload.tags,
+        capsuleIds,
+        composedAt: payload.composedAt,
+    };
+    return payload.description === null ? base : { ...base, description: payload.description };
+}
+// Inserts the schema_meta row and all member rows WITHOUT bracketing a BEGIN/COMMIT.
+// Must be called from within an already-open transaction. Used by createCapsuleSet (which
+// wraps it in its own transaction) and by runComposeTransaction (which needs to combine the
+// set creation and audit writes in one atomic outer transaction).
+export function createCapsuleSetWithinTxn(store, input, now) {
+    assertSafeDisplayField("displayName", input.displayName);
+    assertSafeOptionalDisplayField("description", input.description);
+    for (const tag of input.tags) {
+        assertSafeDisplayField("tag", tag);
+    }
+    const db = store._internal.db;
+    const payload = {
+        displayName: input.displayName,
+        description: input.description ?? null,
+        tags: input.tags,
+        composedAt: now,
+    };
+    db.prepare("INSERT INTO schema_meta (key, value) VALUES (:k, :v)").run({
+        k: metaKey(input.id),
+        v: JSON.stringify(payload),
+    });
+    const insertMember = db.prepare("INSERT INTO capsule_set_members (set_id, capsule_id, ordinal, composed_at) VALUES (:s, :c, :o, :now)");
+    input.capsuleIds.forEach((capsuleId, index) => {
+        insertMember.run({ s: input.id, c: capsuleId, o: index, now });
+    });
+}
+export function createCapsuleSet(store, input) {
+    const db = store._internal.db;
+    const now = store._internal.now();
+    db.exec("BEGIN");
+    try {
+        createCapsuleSetWithinTxn(store, input, now);
+        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("capsule set already exists", { cause: error });
+        }
+        throw new KnowledgeStoreError("failed to create capsule set", { cause: error });
+    }
+    const fetched = getCapsuleSet(store, input.id);
+    if (fetched === undefined) {
+        throw new KnowledgeStoreError(`createCapsuleSet: insert succeeded but row not found for ${String(input.id)}`);
+    }
+    return fetched;
+}
+export function getCapsuleSet(store, id) {
+    const row = store._internal.db
+        .prepare("SELECT value FROM schema_meta WHERE key = :k")
+        .get({ k: metaKey(id) });
+    if (row === undefined)
+        return undefined;
+    const payload = parseMeta(row.value, id);
+    const members = readMembers(store, id);
+    return metaToCapsuleSet(id, payload, members);
+}
+export function listCapsuleSets(store) {
+    // Fetch (key, value) in one query so we avoid a getCapsuleSet re-query per row (N+1).
+    // Members still need a per-set query because capsule_set_members is a separate table.
+    const rows = store._internal.db
+        .prepare("SELECT key, value FROM schema_meta WHERE key LIKE :prefix")
+        .all({ prefix: `${META_PREFIX}%` });
+    const sets = rows.map((row) => {
+        const { key, value } = row;
+        const id = key.slice(META_PREFIX.length);
+        const payload = parseMeta(value, id);
+        const capsuleIds = readMembers(store, id);
+        return metaToCapsuleSet(id, payload, capsuleIds);
+    });
+    return sets.slice().sort((a, b) => a.composedAt - b.composedAt);
+}
+export function deleteCapsuleSet(store, id) {
+    const db = store._internal.db;
+    db.exec("BEGIN");
+    try {
+        const result = db.prepare("DELETE FROM schema_meta WHERE key = :k").run({ k: metaKey(id) });
+        if (Number(result.changes) === 0) {
+            db.exec("ROLLBACK");
+            throw new KnowledgeNotFoundError(`Capsule set not found: ${String(id)}`);
+        }
+        db.prepare("DELETE FROM capsule_set_members WHERE set_id = :s").run({ s: id });
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        if (!(error instanceof KnowledgeNotFoundError)) {
+            db.exec("ROLLBACK");
+        }
+        throw error;
+    }
+}

package/dist/chunking/chunker-persist.d.ts

@@ -0,0 +1,36 @@
+import type { ChunkId, DocumentId, KnowledgeCapsuleId, KnowledgeSourceId } from "@oscharko-dev/keiko-contracts";
+import type { DatabaseSync } from "node:sqlite";
+export interface ChunkInsertRow {
+    readonly id: ChunkId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly parsedUnitId: string;
+    readonly orderIndex: number;
+    readonly tokenCount: number;
+    readonly safeExcerptHash: string;
+    readonly chunkingStrategyVersion: string;
+    readonly characterStart: number;
+    readonly characterEnd: number;
+}
+export declare function insertChunkRow(db: DatabaseSync, row: ChunkInsertRow): void;
+export declare function deleteChunksForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): void;
+export declare function countChunksForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): number;
+export declare function hasStaleChunksForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId, chunkingStrategyVersion?: string): boolean;
+export declare function selectDocumentSourceId(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): KnowledgeSourceId | undefined;
+export interface ParsedUnitRow {
+    readonly id: string;
+    readonly kind: string;
+    readonly page_number: number | null;
+    readonly page_label: string | null;
+    readonly section_path_json: string | null;
+    readonly json_pointer: string | null;
+    readonly table_name: string | null;
+    readonly row_index: number | null;
+    readonly heading_path_json: string | null;
+    readonly unsupported_reason: string | null;
+    readonly character_start: number | null;
+    readonly character_end: number | null;
+}
+export declare function selectParsedUnitsForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): readonly ParsedUnitRow[];
+//# sourceMappingURL=chunker-persist.d.ts.map

package/dist/chunking/chunker-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker-persist.d.ts","sourceRoot":"","sources":["../../src/chunking/chunker-persist.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAqChD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IAIzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CAc1E;AAED,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,IAAI,CAEN;AAMD,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,MAAM,CAKR;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,EACtB,uBAAuB,GAAE,MAAsC,GAC9D,OAAO,CAOT;AAMD,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,iBAAiB,GAAG,SAAS,CAK/B;AAKD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,SAAS,aAAa,EAAE,CAK1B"}

package/dist/chunking/chunker-persist.js

@@ -0,0 +1,74 @@
+// Prepared-statement helpers for the `chunks` table (Epic #189, Issue #195). Every helper
+// wraps a single statement so the runner can compose them inside a transaction in
+// `chunker-runner.ts`. The runner is the only module that issues transactions for chunks —
+// mirrors the `discovery/persist.ts` boundary convention so a per-document failure rolls
+// back exactly the rows from that document.
+import { DEFAULT_CHUNKING_STRATEGY_KEY } from "./types.js";
+const INSERT_CHUNK_SQL = [
+    "INSERT INTO chunks (",
+    "  id, capsule_id, source_id, document_id, parsed_unit_id,",
+    "  order_index, token_count, safe_excerpt_hash, chunking_strategy_version,",
+    "  character_start, character_end",
+    ") VALUES (",
+    "  :id, :capsule_id, :source_id, :document_id, :parsed_unit_id,",
+    "  :order_index, :token_count, :safe_excerpt_hash, :chunking_strategy_version,",
+    "  :character_start, :character_end",
+    ")",
+].join(" ");
+const DELETE_CHUNKS_FOR_DOCUMENT_SQL = "DELETE FROM chunks WHERE capsule_id = :c AND document_id = :d";
+const COUNT_CHUNKS_FOR_DOCUMENT_SQL = "SELECT COUNT(*) AS n FROM chunks WHERE capsule_id = :c AND document_id = :d";
+const COUNT_STALE_CHUNKS_FOR_DOCUMENT_SQL = [
+    "SELECT COUNT(*) AS n FROM chunks",
+    "WHERE capsule_id = :c AND document_id = :d",
+    "  AND (chunking_strategy_version IS NULL OR chunking_strategy_version <> :v)",
+].join(" ");
+const SELECT_PARSED_UNITS_FOR_DOCUMENT_SQL = [
+    "SELECT id, kind, page_number, page_label, section_path_json,",
+    "  json_pointer, table_name, row_index, heading_path_json,",
+    "  unsupported_reason, character_start, character_end",
+    "FROM parsed_units",
+    "WHERE capsule_id = :c AND document_id = :d",
+    "ORDER BY rowid ASC",
+].join(" ");
+export function insertChunkRow(db, row) {
+    db.prepare(INSERT_CHUNK_SQL).run({
+        id: String(row.id),
+        capsule_id: String(row.capsuleId),
+        source_id: String(row.sourceId),
+        document_id: String(row.documentId),
+        parsed_unit_id: row.parsedUnitId,
+        order_index: row.orderIndex,
+        token_count: row.tokenCount,
+        safe_excerpt_hash: row.safeExcerptHash,
+        chunking_strategy_version: row.chunkingStrategyVersion,
+        character_start: row.characterStart,
+        character_end: row.characterEnd,
+    });
+}
+export function deleteChunksForDocument(db, capsuleId, documentId) {
+    db.prepare(DELETE_CHUNKS_FOR_DOCUMENT_SQL).run({ c: capsuleId, d: documentId });
+}
+export function countChunksForDocument(db, capsuleId, documentId) {
+    const row = db.prepare(COUNT_CHUNKS_FOR_DOCUMENT_SQL).get({ c: capsuleId, d: documentId });
+    return typeof row?.n === "number" ? row.n : 0;
+}
+export function hasStaleChunksForDocument(db, capsuleId, documentId, chunkingStrategyVersion = DEFAULT_CHUNKING_STRATEGY_KEY) {
+    const row = db.prepare(COUNT_STALE_CHUNKS_FOR_DOCUMENT_SQL).get({
+        c: capsuleId,
+        d: documentId,
+        v: chunkingStrategyVersion,
+    });
+    return (row?.n ?? 0) > 0;
+}
+export function selectDocumentSourceId(db, capsuleId, documentId) {
+    const row = db
+        .prepare("SELECT source_id FROM documents WHERE capsule_id = :c AND id = :d")
+        .get({ c: capsuleId, d: documentId });
+    return row === undefined ? undefined : row.source_id;
+}
+export function selectParsedUnitsForDocument(db, capsuleId, documentId) {
+    const rows = db
+        .prepare(SELECT_PARSED_UNITS_FOR_DOCUMENT_SQL)
+        .all({ c: capsuleId, d: documentId });
+    return rows;
+}

package/dist/chunking/chunker-runner.d.ts

@@ -0,0 +1,9 @@
+import type { ChunkId, DocumentId, ParsedUnit } from "@oscharko-dev/keiko-contracts";
+import { type ParsedUnitRow } from "./chunker-persist.js";
+import type { KnowledgeStore } from "../store.js";
+import type { StoreContentCipher } from "../store-content-cipher.js";
+import type { ChunkDocumentParams, ChunkDocumentResult, ChunkingOptions } from "./types.js";
+export declare function rowToParsedUnit(row: ParsedUnitRow, documentId: DocumentId, cipher: StoreContentCipher): ParsedUnit;
+export declare function composeChunkId(documentId: DocumentId, parsedUnitRowId: string, orderIndex: number): ChunkId;
+export declare function chunkDocument(store: KnowledgeStore, params: ChunkDocumentParams, options?: ChunkingOptions): ChunkDocumentResult;
+//# sourceMappingURL=chunker-runner.d.ts.map

package/dist/chunking/chunker-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker-runner.d.ts","sourceRoot":"","sources":["../../src/chunking/chunker-runner.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EAGV,UAAU,EACX,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAsG5F,wBAAgB,eAAe,CAC7B,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,kBAAkB,GACzB,UAAU,CAqBZ;AAcD,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,EACtB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACjB,OAAO,CAET;AAoHD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,mBAAmB,EAC3B,OAAO,CAAC,EAAE,eAAe,GACxB,mBAAmB,CAkCrB"}