@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/evaluations/types.d.ts

@@ -0,0 +1,116 @@
+import type { CapsuleAnswerGroundingPolicy, ChunkId, DocumentId, EmbeddingModelIdentity, KnowledgeCapsuleId, KnowledgeSourceId, ParsedUnit } from "@oscharko-dev/keiko-contracts";
+import type { RetrievalNoEvidenceReason, RetrievalReference } from "../retrieval/types.js";
+export interface EvalChunkSpec {
+    readonly id: ChunkId;
+    readonly text: string;
+    readonly topic?: string;
+    readonly parsedUnitId?: string;
+}
+export type EvalParsedUnitWithoutDocId = 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 EvalParsedUnitSpec {
+    readonly id: string;
+    readonly unit: EvalParsedUnitWithoutDocId;
+}
+export interface EvalDocumentSpec {
+    readonly id: DocumentId;
+    readonly safeDisplayName: string;
+    readonly mediaType?: string;
+    readonly parserId?: string;
+    readonly parserVersion?: string;
+    readonly parsedUnits: readonly EvalParsedUnitSpec[];
+    readonly chunks: readonly EvalChunkSpec[];
+}
+export interface EvalSourceSpec {
+    readonly id: KnowledgeSourceId;
+    readonly documents: readonly EvalDocumentSpec[];
+}
+export interface EvalCapsuleSpec {
+    readonly id: KnowledgeCapsuleId;
+    readonly displayName: string;
+    readonly answerGroundingPolicy: CapsuleAnswerGroundingPolicy;
+    readonly embeddingModelIdentity: EmbeddingModelIdentity;
+    readonly sources: readonly EvalSourceSpec[];
+}
+export type EvalRetrievalScope = {
+    readonly kind: "capsule";
+    readonly capsuleId: KnowledgeCapsuleId;
+} | {
+    readonly kind: "capsule-set";
+    readonly capsuleSetId: string;
+    readonly capsuleIds: readonly KnowledgeCapsuleId[];
+};
+export interface RetrievalEvalQuery {
+    readonly id: string;
+    readonly text: string;
+    readonly topic?: string;
+    readonly scope: EvalRetrievalScope;
+    readonly expectedChunkIds?: readonly ChunkId[];
+    readonly expectedNoEvidence?: boolean;
+    readonly expectedNoEvidenceReason?: RetrievalNoEvidenceReason;
+    readonly topK?: number;
+    readonly contextBudgetTokens?: number;
+    readonly queryEmbeddingIdentity?: EmbeddingModelIdentity;
+}
+export interface RetrievalEvalFixture {
+    readonly id: string;
+    readonly description: string;
+    readonly capsules: readonly EvalCapsuleSpec[];
+    readonly queries: readonly RetrievalEvalQuery[];
+}
+export interface RetrievalEvalDimensionScores {
+    readonly recall: number;
+    readonly precision: number;
+    readonly meanReciprocalRank: number;
+    readonly ndcg: number;
+    readonly sourceIsolation: number;
+    readonly citationQuality: number;
+    readonly noEvidenceAccuracy: number;
+    readonly contextBudgetFit: number;
+    readonly latencyMs: number;
+}
+export interface ModelJudgedRetrievalEvalInput {
+    readonly fixtureId: string;
+    readonly queryId: string;
+    readonly queryText: string;
+    readonly references: readonly RetrievalReference[];
+    readonly noEvidence: boolean;
+    readonly reason?: RetrievalNoEvidenceReason;
+}
+export interface ModelJudgedRetrievalEvalScores {
+    readonly groundedness: number;
+    readonly faithfulness: number;
+}
+export interface ModelJudgedRetrievalEvalJudge {
+    readonly judge: (input: ModelJudgedRetrievalEvalInput) => Promise<ModelJudgedRetrievalEvalScores>;
+}
+export interface RetrievalEvalScorecard {
+    readonly fixtureId: string;
+    readonly runId: string;
+    readonly dimensions: RetrievalEvalDimensionScores;
+    readonly passed: boolean;
+    readonly modelJudged?: ModelJudgedRetrievalEvalScores;
+}
+export interface RetrievalEvalThresholds {
+    readonly recall: number;
+    readonly precision: number;
+    readonly meanReciprocalRank: number;
+    readonly ndcg: number;
+    readonly sourceIsolation: number;
+    readonly citationQuality: number;
+    readonly noEvidenceAccuracy: number;
+    readonly contextBudgetFit: number;
+}
+export declare const PASS_THRESHOLDS: RetrievalEvalThresholds;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/evaluations/types.ts"],"names":[],"mappings":"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"}

package/dist/evaluations/types.js

@@ -0,0 +1,27 @@
+// Type contracts for the retrieval evaluation harness (Epic #189, Issue #268). The
+// harness is OFFLINE only — it composes #199 retrieval through a scripted (deterministic)
+// embedding adapter so every scorecard is byte-identical across runs. That determinism is
+// load-bearing for the audit ledger (#10): a non-deterministic eval result would force
+// the manifest to encode timestamps or random salts and break the cross-machine equality
+// check that the verification matrix relies on.
+//
+// `RetrievalEvalFixture` is the executable contract a fixture must satisfy: enough capsule
+// + source + document + parsed-unit + chunk specs to materialise an in-memory store, plus
+// a list of queries with ground truth (`expectedChunkIds`) or an explicit no-evidence flag.
+//
+// `RetrievalEvalScorecard` is the immutable result the runner returns. The quality
+// dimensions are each in `[0, 1]`; latency is reported separately as a deterministic
+// synthetic-millisecond total unless the caller overrides `deps.now`. `passed` is the
+// conjunction of per-dimension thresholds in `PASS_THRESHOLDS` — exposing the constant
+// lets a UI display a "X met 5/6 thresholds" breakdown without re-implementing the
+// comparison.
+export const PASS_THRESHOLDS = Object.freeze({
+    recall: 0.9,
+    precision: 0.8,
+    meanReciprocalRank: 0.9,
+    ndcg: 0.9,
+    sourceIsolation: 1.0,
+    citationQuality: 0.9,
+    noEvidenceAccuracy: 1.0,
+    contextBudgetFit: 1.0,
+});

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { KEIKO_LOCAL_KNOWLEDGE_VERSION } from "./version.js";
+export { KnowledgeStoreError, KnowledgePathError, KnowledgeNotFoundError } from "./errors.js";
+export { resolveKnowledgeStorePath, type ResolveKnowledgeStorePathOptions } from "./store-paths.js";
+export { openKnowledgeStore, type KnowledgeStoreKeyProvider, type KnowledgeStoreKeyProviderContext, type KnowledgeStoreProtectionOptions, type KnowledgeStore, type OpenKnowledgeStoreOptions, } from "./store.js";
+export { createCapsule, deleteCapsule, getCapsule, listCapsules, updateCapsuleState, updateCapsuleDetails, type CapsuleDetailsPatch, type CreateCapsuleInput, } from "./capsule-lifecycle.js";
+export { addSourceToCapsule, listCapsuleSources, removeSourceFromCapsule, type AddCapsuleSourceInput, } from "./source-lifecycle.js";
+export { createCapsuleSet, deleteCapsuleSet, getCapsuleSet, listCapsuleSets, type CreateCapsuleSetInput, } from "./capsule-set-lifecycle.js";
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_NESTING_DEPTH, DEFAULT_MAX_OBJECTS, DEFAULT_MAX_UNITS, DEFAULT_TIMEOUT_MS, PARSER_ERROR_CODES, buildParserOptions, createDefaultParserRegistry, createParserRegistry, csvParser, docxParser, htmlParser, jsonParser, pdfParser, registerParser, resolveParser, textParser, unsupportedParser, xlsxParser, type AsyncParserAdapter, type ParserAdapter, type ParserCapability, type ParserErrorCode, type ParserOptions, type ParserRegistry, type ParserResolution, type ParserSelectionInput, } from "./parsers/index.js";
+export { createOcrPipelineParser, nullOcrAdapter, type OcrAdapter, type OcrPageResult, type OcrPipelineAdapter, } from "./parsers/ocr/index.js";
+export { extractBoundedDocumentText, type BoundedDocumentExtractionInput, type BoundedDocumentExtractionOptions, type BoundedDocumentExtractionOutcome, type BoundedDocumentExtractionResult, type BoundedDocumentFormat, } from "./bounded-document-extraction.js";
+export { DEFAULT_DISCOVERY_OPTIONS, discoverAndExtract, documentIdFor, extensionOf, extractDocument, mediaTypeFor, walkSource, type DiscoverAndExtractDeps, type DiscoverAndExtractParams, type DiscoveredFile, type DiscoveryError, type DiscoveryErrorCode, type DiscoveryOptions, type ExtractDocumentDeps, type ExtractDocumentParams, type ExtractionEvent, type ExtractionOutcome, type ExtractionResult, type WalkYield, } from "./discovery/index.js";
+export * from "./indexing/index.js";
+export * from "./retrieval/index.js";
+export * from "./evaluations/index.js";
+export * from "./conversation/index.js";
+export { readCitationExcerpt } from "./conversation/citation-excerpts.js";
+export * from "./privacy/index.js";
+export { addSourcesToCapsule, buildComposedRetrievalScope, composeCapsules, CompositionError, describeRetrievalScope, listCapsuleMembershipChanges, } from "./composition.js";
+export type { AddSourcesToCapsuleResult, CapsuleMembershipChange, CapsuleMembershipChangeKind, ComposedRetrievalScope, ComposeCapsulesOptions, CompositionErrorCode, RetrievalCapsuleSummary, RetrievalScopeDisclosure, RetrievalSourceSummary, } from "./composition.js";
+export { SourceRoutingValidationError, validateAlwaysQuery, validateGlobPatterns, validateRoutingInstructionsScope, validateSourceRoutingForCapsule, } from "./source-routing-validation.js";
+export type { SourceRoutingValidationCode } from "./source-routing-validation.js";
+export * as QualityIntelligenceHandoff from "./qualityIntelligence/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,41 @@
+// Public surface of @oscharko-dev/keiko-local-knowledge (Epic #189, Issues #193, #263, #266,
+// #194, #196, #199). Composes the #265 schema with a node:sqlite runtime, exposes typed
+// CRUD for capsules/sources/sets, the parser registry (#266), the discovery +
+// extraction bridge (#194), the indexing orchestrator (#196), and the retrieval
+// orchestrator (#199) that turns a `ComposedRetrievalScope` + query into a ranked list
+// of `RetrievalReference` + a `LocalKnowledgeGroundedContextPack`.
+//
+// The HTTP / UI wiring is OUT OF SCOPE for this package (lands in #200 Conversation
+// Center integration). ADR-0019 direction rule 3e allows this package to depend on
+// `@oscharko-dev/keiko-contracts`, `@oscharko-dev/keiko-workspace`, and
+// `@oscharko-dev/keiko-model-gateway` — the model-gateway dep was added at #196 so the
+// indexing + retrieval layers can call the OpenAI-compatible embeddings adapter
+// through the same boundary the rest of the codebase uses.
+export { KEIKO_LOCAL_KNOWLEDGE_VERSION } from "./version.js";
+export { KnowledgeStoreError, KnowledgePathError, KnowledgeNotFoundError } from "./errors.js";
+export { resolveKnowledgeStorePath } from "./store-paths.js";
+export { openKnowledgeStore, } from "./store.js";
+export { createCapsule, deleteCapsule, getCapsule, listCapsules, updateCapsuleState, updateCapsuleDetails, } from "./capsule-lifecycle.js";
+export { addSourceToCapsule, listCapsuleSources, removeSourceFromCapsule, } from "./source-lifecycle.js";
+export { createCapsuleSet, deleteCapsuleSet, getCapsuleSet, listCapsuleSets, } from "./capsule-set-lifecycle.js";
+export { DEFAULT_MAX_BYTES, DEFAULT_MAX_NESTING_DEPTH, DEFAULT_MAX_OBJECTS, DEFAULT_MAX_UNITS, DEFAULT_TIMEOUT_MS, PARSER_ERROR_CODES, buildParserOptions, createDefaultParserRegistry, createParserRegistry, csvParser, docxParser, htmlParser, jsonParser, pdfParser, registerParser, resolveParser, textParser, unsupportedParser, xlsxParser, } from "./parsers/index.js";
+// OCR adapter seam (Issue #202).
+export { createOcrPipelineParser, nullOcrAdapter, } from "./parsers/ocr/index.js";
+// Bounded request-local small-document text extraction for Repository Search (Issue #1285).
+// Reuses the shipped DOCX/XLSX/PDF parser adapters as a pure, byte-capped text projection.
+export { extractBoundedDocumentText, } from "./bounded-document-extraction.js";
+export { DEFAULT_DISCOVERY_OPTIONS, discoverAndExtract, documentIdFor, extensionOf, extractDocument, mediaTypeFor, walkSource, } from "./discovery/index.js";
+export * from "./indexing/index.js";
+export * from "./retrieval/index.js";
+export * from "./evaluations/index.js";
+export * from "./conversation/index.js";
+export { readCitationExcerpt } from "./conversation/citation-excerpts.js";
+export * from "./privacy/index.js";
+// Slice 4 (Issue #189) — non-destructive capsule-set composition exposed to the BFF.
+export { addSourcesToCapsule, buildComposedRetrievalScope, composeCapsules, CompositionError, describeRetrievalScope, listCapsuleMembershipChanges, } from "./composition.js";
+export { SourceRoutingValidationError, validateAlwaysQuery, validateGlobPatterns, validateRoutingInstructionsScope, validateSourceRoutingForCapsule, } from "./source-routing-validation.js";
+// ─── Quality Intelligence handoff (Issue #278) ─────────────────────────────────
+// Pure adapter that converts a local-knowledge RetrievalReference list into a list of
+// `QualityIntelligenceLocalKnowledgeCapsuleEnvelope` instances for QI ingestion. No
+// new retrieval logic; consumes only existing local-knowledge / contract types.
+export * as QualityIntelligenceHandoff from "./qualityIntelligence/index.js";

package/dist/indexing/bounded-indexing.d.ts

@@ -0,0 +1,41 @@
+import type { ChunkId, DocumentId, EmbeddingModelIdentity, IndexingJobError, KnowledgeCapsuleId, KnowledgeSourceId, LargeDocumentResourcePolicy } from "@oscharko-dev/keiko-contracts";
+import type { OpenAIEmbeddingAdapter } from "@oscharko-dev/keiko-model-gateway";
+import type { ChunkingOptions } from "../chunking/types.js";
+import type { KnowledgeStore } from "../store.js";
+export interface BoundedChunkParams {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+}
+export declare class BoundedIndexingCancelledError extends Error {
+    constructor(message?: string);
+}
+export declare class BoundedIndexingPolicyError extends Error {
+    readonly code = "RESOURCE_POLICY_EXCEEDED";
+    constructor(message: string);
+    toIndexingError(): IndexingJobError;
+}
+export declare function chunkDocumentBounded(store: KnowledgeStore, params: BoundedChunkParams, options: ChunkingOptions | undefined, signal: AbortSignal | undefined, policy?: LargeDocumentResourcePolicy): number;
+export interface BoundedEmbedDeps {
+    readonly store: KnowledgeStore;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly documentId: DocumentId;
+    readonly adapter: OpenAIEmbeddingAdapter;
+    readonly identity: EmbeddingModelIdentity;
+    readonly batchSize: number;
+    readonly concurrency: number;
+    readonly now: () => number;
+    readonly idSource: () => string;
+    readonly signal?: AbortSignal;
+    readonly policy?: LargeDocumentResourcePolicy;
+    readonly onBatch?: (cursor: number, lastChunkId: ChunkId) => void;
+}
+export interface BoundedEmbedResult {
+    readonly vectorCount: number;
+    readonly errors: readonly IndexingJobError[];
+    readonly lastChunkId: ChunkId | null;
+    readonly embeddedCursor: number;
+    readonly cancelled: boolean;
+}
+export declare function embedDocumentChunksBounded(deps: BoundedEmbedDeps): Promise<BoundedEmbedResult>;
+//# sourceMappingURL=bounded-indexing.d.ts.map

package/dist/indexing/bounded-indexing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-indexing.d.ts","sourceRoot":"","sources":["../../src/indexing/bounded-indexing.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,2BAA2B,EAE5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAQhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQ5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,qBAAa,6BAA8B,SAAQ,KAAK;gBACnC,OAAO,SAA+B;CAI1D;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAgB,IAAI,8BAA8B;gBAC/B,OAAO,EAAE,MAAM;IAK3B,eAAe,IAAI,gBAAgB;CAG3C;AA4FD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,eAAe,GAAG,SAAS,EACpC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,MAAM,CAAC,EAAE,2BAA2B,GACnC,MAAM,CA6BR;AAwCD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,2BAA2B,CAAC;IAG9C,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAqHD,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAmB7B"}

package/dist/indexing/bounded-indexing.js

@@ -0,0 +1,240 @@
+// Bounded chunking + embedding for progressively-extracted large documents (Epic #1160,
+// Issue #1286).
+//
+// The standard chunk/embed path loads the whole document text into a JS string and slices each
+// chunk from it. For a large document that defeats the bounded-memory guarantee. These helpers read
+// each parsed unit's / chunk's text back through the unified `readDocumentTextSpan` (SQLite SUBSTR
+// over the bounded document_text_windows rows), so peak memory stays O(window/batch) regardless of
+// document size. The chunk ids, offsets, token counts, and excerpt hashes are byte-identical to the
+// standard chunker, so the bounded path and the standard path produce the same retrievable index.
+import { chunkParsedUnit, chunkingStrategyKey, resolveChunkingOptions, } from "../chunking/chunker.js";
+import { composeChunkId, rowToParsedUnit } from "../chunking/chunker-runner.js";
+import { deleteChunksForDocument, insertChunkRow, selectParsedUnitsForDocument, } from "../chunking/chunker-persist.js";
+import { readDocumentTextSpan } from "../discovery/persist.js";
+import { embedChunkBatch } from "./embedding-batcher.js";
+export class BoundedIndexingCancelledError extends Error {
+    constructor(message = "bounded indexing cancelled") {
+        super(message);
+        this.name = "BoundedIndexingCancelledError";
+    }
+}
+export class BoundedIndexingPolicyError extends Error {
+    code = "RESOURCE_POLICY_EXCEEDED";
+    constructor(message) {
+        super(message);
+        this.name = "BoundedIndexingPolicyError";
+    }
+    toIndexingError() {
+        return { code: this.code, message: this.message };
+    }
+}
+function rebaseUnit(unit, length) {
+    if (unit.kind === "unsupported-media")
+        return unit;
+    return { ...unit, characterStart: 0, characterEnd: length };
+}
+function boundedMaxChunks(options, policy) {
+    return Math.min(resolveChunkingOptions(options).maxChunks, policy?.maxChunkCount ?? Number.POSITIVE_INFINITY);
+}
+function assertChunkingCanContinue(signal, orderIndex, maxChunks) {
+    if (signal?.aborted === true)
+        throw new BoundedIndexingCancelledError();
+    if (orderIndex >= maxChunks) {
+        throw new BoundedIndexingPolicyError("large-document chunk count exceeded the configured resource policy");
+    }
+}
+function assertChunkingHasRemainder(orderIndex, rowIndex, rowCount, maxChunks) {
+    if (orderIndex < maxChunks || rowIndex >= rowCount - 1)
+        return;
+    throw new BoundedIndexingPolicyError("large-document chunk count exceeded the configured resource policy");
+}
+// Chunks one parsed unit (read via SUBSTR, rebased to window-local offsets) and persists its chunks
+// with document-relative offsets. Returns the next order index.
+function chunkOneUnit(ctx, row, orderIndex) {
+    const { db, cipher, params } = ctx;
+    const start = row.character_start ?? 0;
+    const end = row.character_end ?? start;
+    const unitText = readDocumentTextSpan(db, cipher, params.capsuleId, params.documentId, start, end) ?? "";
+    const rebased = rebaseUnit(rowToParsedUnit(row, params.documentId, cipher), unitText.length);
+    const chunks = chunkParsedUnit(rebased, unitText, optionsWithBudget(ctx.options, ctx.maxChunks - orderIndex));
+    let next = orderIndex;
+    for (const chunk of chunks) {
+        insertChunkRow(db, {
+            id: composeChunkId(params.documentId, row.id, next),
+            capsuleId: params.capsuleId,
+            sourceId: params.sourceId,
+            documentId: params.documentId,
+            parsedUnitId: row.id,
+            orderIndex: next,
+            tokenCount: chunk.tokenCount,
+            safeExcerptHash: chunk.safeExcerptHash,
+            chunkingStrategyVersion: ctx.strategyKey,
+            characterStart: start + chunk.characterStart,
+            characterEnd: start + chunk.characterEnd,
+        });
+        next += 1;
+    }
+    return next;
+}
+// Bounded re-implementation of the chunker: reads each parsed unit's text via SUBSTR, chunks it with
+// window-relative offsets, then rebases the chunk offsets back to document-relative before persist,
+// so the rows are byte-identical to chunkDocument run over the full text. Returns the chunk count.
+export function chunkDocumentBounded(store, params, options, signal, policy) {
+    const db = store._internal.db;
+    const rows = selectParsedUnitsForDocument(db, params.capsuleId, params.documentId);
+    if (rows.length === 0)
+        return 0;
+    const ctx = {
+        db,
+        cipher: store._internal.contentCipher,
+        params,
+        options,
+        strategyKey: chunkingStrategyKey(options),
+        maxChunks: boundedMaxChunks(options, policy),
+    };
+    db.exec("BEGIN");
+    try {
+        deleteChunksForDocument(db, params.capsuleId, params.documentId);
+        let orderIndex = 0;
+        for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+            const row = rows[rowIndex];
+            if (row === undefined)
+                continue;
+            assertChunkingCanContinue(signal, orderIndex, ctx.maxChunks);
+            orderIndex = chunkOneUnit(ctx, row, orderIndex);
+            assertChunkingHasRemainder(orderIndex, rowIndex, rows.length, ctx.maxChunks);
+        }
+        db.exec("COMMIT");
+        return orderIndex;
+    }
+    catch (cause) {
+        db.exec("ROLLBACK");
+        throw cause;
+    }
+}
+function optionsWithBudget(options, budget) {
+    return { ...(options ?? {}), maxChunks: budget };
+}
+// Selects the next batch of chunks that do NOT yet have a vector. The missing-vector gate is the
+// resume mechanism: it self-heals across an interrupted embed, an externally deleted vector, and an
+// incompatible-checkpoint restart (which deletes vectors first), without trusting a fragile cursor.
+const SELECT_BOUNDED_CHUNKS_SQL = [
+    "SELECT c.id, c.source_id, c.order_index,",
+    "  COALESCE(c.character_start, pu.character_start) AS char_start,",
+    "  COALESCE(c.character_end, pu.character_end) AS char_end",
+    "FROM chunks AS c",
+    "JOIN parsed_units AS pu ON pu.capsule_id = c.capsule_id AND pu.id = c.parsed_unit_id",
+    "LEFT JOIN vectors AS v ON v.capsule_id = c.capsule_id AND v.chunk_id = c.id",
+    "WHERE c.capsule_id = :c AND c.document_id = :d AND v.id IS NULL",
+    "ORDER BY c.order_index ASC",
+    "LIMIT :limit",
+].join(" ");
+const COUNT_VECTORS_SQL = "SELECT COUNT(*) AS n FROM vectors WHERE capsule_id = :c AND document_id = :d";
+function embeddedChunkCount(db, deps) {
+    const row = db
+        .prepare(COUNT_VECTORS_SQL)
+        .get({ c: String(deps.capsuleId), d: String(deps.documentId) });
+    return row.n;
+}
+function nextBatch(db, deps) {
+    return db.prepare(SELECT_BOUNDED_CHUNKS_SQL).all({
+        c: String(deps.capsuleId),
+        d: String(deps.documentId),
+        limit: deps.batchSize,
+    });
+}
+function toChunkToEmbed(deps, row) {
+    const text = readDocumentTextSpan(deps.store._internal.db, deps.store._internal.contentCipher, deps.capsuleId, deps.documentId, row.char_start ?? 0, row.char_end ?? 0) ?? "";
+    return {
+        id: row.id,
+        capsuleId: deps.capsuleId,
+        sourceId: row.source_id,
+        documentId: deps.documentId,
+        text,
+    };
+}
+function embedOptions(deps) {
+    return {
+        adapter: deps.adapter,
+        store: deps.store,
+        pinnedIdentity: deps.identity,
+        concurrency: deps.concurrency,
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+        now: deps.now,
+        idSource: deps.idSource,
+    };
+}
+// Embeds one batch, updates the accumulator, and advances the durable checkpoint. Returns false to
+// stop the loop (the batch reported an error).
+async function embedOneBatch(db, deps, rows, acc) {
+    const batch = rows.map((row) => toChunkToEmbed(deps, row));
+    const result = await embedChunkBatch(batch, embedOptions(deps));
+    acc.vectorCount += result.vectors.length;
+    acc.errors.push(...result.errors);
+    const lastVector = result.vectors[result.vectors.length - 1];
+    if (lastVector !== undefined)
+        acc.lastChunkId = lastVector.chunkId;
+    if (acc.lastChunkId !== null)
+        deps.onBatch?.(embeddedChunkCount(db, deps), acc.lastChunkId);
+    return result.errors.length === 0;
+}
+function markCancelled(acc) {
+    acc.cancelled = true;
+}
+function appendBatchPolicyError(acc) {
+    acc.errors.push({
+        code: "RESOURCE_POLICY_EXCEEDED",
+        message: "large-document embedding batch count exceeded the configured resource policy",
+    });
+}
+function batchPolicyExceeded(deps, batchCount) {
+    return batchCount >= (deps.policy?.maxEmbeddingBatchCount ?? Number.POSITIVE_INFINITY);
+}
+function sawCancellationError(acc) {
+    return acc.errors.some((error) => error.code === "CANCELLED");
+}
+async function embedLoopStep(db, deps, acc, loop) {
+    if (deps.signal?.aborted === true) {
+        markCancelled(acc);
+        return "stop";
+    }
+    const rows = nextBatch(db, deps);
+    const firstRow = rows[0];
+    if (firstRow === undefined || firstRow.id === loop.previousFirstId)
+        return "stop";
+    if (batchPolicyExceeded(deps, loop.batchCount)) {
+        appendBatchPolicyError(acc);
+        return "stop";
+    }
+    loop.batchCount += 1;
+    loop.previousFirstId = firstRow.id;
+    if (await embedOneBatch(db, deps, rows, acc))
+        return "continue";
+    if (sawCancellationError(acc))
+        markCancelled(acc);
+    return "stop";
+}
+// Embeds a document's not-yet-embedded chunks in bounded batches, reading each chunk's text via
+// SUBSTR. Never materializes the whole document text or the whole chunk set, so peak memory stays
+// O(batch) regardless of document size. Resume falls out of the missing-vector gate.
+export async function embedDocumentChunksBounded(deps) {
+    const db = deps.store._internal.db;
+    const acc = {
+        vectorCount: 0,
+        errors: [],
+        lastChunkId: null,
+        cancelled: false,
+    };
+    const loop = { batchCount: 0 };
+    for (;;) {
+        if ((await embedLoopStep(db, deps, acc, loop)) === "stop")
+            break;
+    }
+    return {
+        vectorCount: acc.vectorCount,
+        errors: acc.errors,
+        lastChunkId: acc.lastChunkId,
+        embeddedCursor: embeddedChunkCount(db, deps),
+        cancelled: acc.cancelled,
+    };
+}

package/dist/indexing/checkpoint-persist.d.ts

@@ -0,0 +1,8 @@
+import type { ExtractionCheckpointRecord, KnowledgeCapsuleId } from "@oscharko-dev/keiko-contracts";
+import type { DocumentId } from "@oscharko-dev/keiko-contracts";
+import type { DatabaseSync } from "node:sqlite";
+export declare function upsertExtractionCheckpoint(db: DatabaseSync, checkpoint: ExtractionCheckpointRecord): void;
+export declare function selectExtractionCheckpoint(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): ExtractionCheckpointRecord | undefined;
+export declare function listExtractionCheckpoints(db: DatabaseSync, capsuleId: KnowledgeCapsuleId): readonly ExtractionCheckpointRecord[];
+export declare function deleteExtractionCheckpoint(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): void;
+//# sourceMappingURL=checkpoint-persist.d.ts.map

package/dist/indexing/checkpoint-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-persist.d.ts","sourceRoot":"","sources":["../../src/indexing/checkpoint-persist.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAGV,0BAA0B,EAE1B,kBAAkB,EAGnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAW,UAAU,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAgFhD,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,UAAU,EAAE,0BAA0B,GACrC,IAAI,CA0BN;AA+CD,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,0BAA0B,GAAG,SAAS,CAGxC;AAED,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,GAC5B,SAAS,0BAA0B,EAAE,CAGvC;AAED,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,IAAI,CAEN"}