@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/indexing/types.d.ts

@@ -0,0 +1,156 @@
+import type { ChunkId, DocumentId, EmbeddingModelIdentity, ExtractionCapabilityAvailability, IndexingJobError, KnowledgeCapsuleId, KnowledgeSourceId, LargeDocumentResourcePolicy, VectorRecord } from "@oscharko-dev/keiko-contracts";
+import type { OpenAIEmbeddingAdapter } from "@oscharko-dev/keiko-model-gateway";
+import type { WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+import type { ChunkingOptions } from "../chunking/index.js";
+import type { DiscoveryOptions } from "../discovery/index.js";
+import { KnowledgeStoreError } from "../errors.js";
+import type { ParserRegistry, ProgressiveExtractor } from "../parsers/index.js";
+import type { AuditEventSink } from "../privacy/index.js";
+import type { KnowledgeStore } from "../store.js";
+export declare const DEFAULT_INDEXING_BATCH_SIZE = 64;
+export declare const DEFAULT_INDEXING_CONCURRENCY = 4;
+export type IndexingErrorCode = "INCOMPATIBLE_EMBEDDING_IDENTITY" | "EMBEDDING_ADAPTER_FAILED" | "DISCOVERY_FAILED" | "CHUNKING_FAILED" | "CANCELLED" | "CAPSULE_NOT_FOUND" | "INVALID_OPTIONS" | "PERSISTENCE_FAILED";
+export declare class IndexingError extends KnowledgeStoreError {
+    readonly name: string;
+    readonly code: IndexingErrorCode;
+    constructor(code: IndexingErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface IndexingOptions {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceIds?: readonly KnowledgeSourceId[];
+    readonly parserRegistry: ParserRegistry;
+    readonly workspaceFs: WorkspaceFs;
+    readonly embeddingAdapter: OpenAIEmbeddingAdapter;
+    readonly store: KnowledgeStore;
+    readonly signal?: AbortSignal;
+    readonly progress?: (event: IndexingEvent) => void;
+    readonly auditSink?: AuditEventSink;
+    readonly force?: boolean;
+    readonly batchSize?: number;
+    readonly concurrency?: number;
+    readonly chunkingOptions?: ChunkingOptions;
+    readonly discoveryOptions?: DiscoveryOptions;
+    readonly now?: () => number;
+    readonly idSource?: () => string;
+    readonly largeDocumentPolicy?: LargeDocumentResourcePolicy;
+    readonly progressiveExtractors?: readonly ProgressiveExtractor[];
+    readonly extractionCapabilities?: ExtractionCapabilityAvailability;
+    readonly resume?: boolean;
+}
+export interface IndexingJobStartedEvent {
+    readonly kind: "job-started";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceIds: readonly KnowledgeSourceId[];
+    readonly startedAt: number;
+}
+export interface IndexingDocumentDiscoveredEvent {
+    readonly kind: "document-discovered";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+}
+export interface IndexingDocumentExtractedEvent {
+    readonly kind: "document-extracted";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly relativePath: string;
+}
+export interface IndexingDocumentChunkedEvent {
+    readonly kind: "document-chunked";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly chunkCount: number;
+}
+export interface IndexingDocumentEmbeddedEvent {
+    readonly kind: "document-embedded";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly vectorCount: number;
+    readonly resumeToken: ChunkId;
+}
+export interface IndexingDocumentSkippedEvent {
+    readonly kind: "document-skipped";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly reason: "unchanged" | "already-embedded" | "unsupported";
+}
+export interface IndexingDocumentFailedEvent {
+    readonly kind: "document-failed";
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId?: DocumentId;
+    readonly relativePath?: string;
+    readonly error: IndexingJobError;
+}
+export interface IndexingJobCompletedEvent {
+    readonly kind: "job-completed";
+    readonly jobId: string;
+    readonly result: IndexingResult;
+}
+export interface IndexingJobCancelledEvent {
+    readonly kind: "job-cancelled";
+    readonly jobId: string;
+    readonly result: IndexingResult;
+}
+export interface IndexingJobFailedEvent {
+    readonly kind: "job-failed";
+    readonly jobId: string;
+    readonly error: IndexingJobError;
+    readonly result: IndexingResult;
+}
+export type IndexingEvent = IndexingJobStartedEvent | IndexingDocumentDiscoveredEvent | IndexingDocumentExtractedEvent | IndexingDocumentChunkedEvent | IndexingDocumentEmbeddedEvent | IndexingDocumentSkippedEvent | IndexingDocumentFailedEvent | IndexingJobCompletedEvent | IndexingJobCancelledEvent | IndexingJobFailedEvent;
+export interface IndexingResult {
+    readonly jobId: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly status: "succeeded" | "failed" | "cancelled";
+    readonly totalDocuments: number;
+    readonly processedDocuments: number;
+    readonly failedDocuments: number;
+    readonly skippedDocuments: number;
+    readonly vectorsPersisted: number;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly lastError?: IndexingJobError;
+    readonly embeddingIdentity?: EmbeddingModelIdentity;
+}
+export interface ChunkToEmbed {
+    readonly id: ChunkId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly text: string;
+}
+export interface EmbedRetryOptions {
+    readonly maxRetries: number;
+    readonly baseDelayMs: number;
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export interface EmbedBatchOptions {
+    readonly adapter: OpenAIEmbeddingAdapter;
+    readonly store: KnowledgeStore;
+    readonly pinnedIdentity: EmbeddingModelIdentity;
+    readonly concurrency: number;
+    readonly signal?: AbortSignal;
+    readonly now: () => number;
+    readonly idSource: () => string;
+    readonly retry?: EmbedRetryOptions;
+}
+export interface EmbedBatchResult {
+    readonly vectors: readonly VectorRecord[];
+    readonly errors: readonly IndexingJobError[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/indexing/types.js

@@ -0,0 +1,30 @@
+// Type contracts for the indexing orchestrator (Epic #189, Issue #196). The orchestrator
+// composes #194 discovery, #195 chunking, and #192 embedding capability into a single
+// streaming pipeline that produces `vectors` rows for a capsule. Every state change emits
+// one `IndexingEvent`; consumers (UI surfaces, evidence ledger, CLI) read the event stream
+// rather than polling the database.
+//
+// The progress channel is an event union (not a number) so a consumer can branch on the
+// `kind` discriminant and surface domain-specific UI per state — matching the pattern the
+// discovery layer (#194) and the verification orchestrator (#7) already use elsewhere in
+// the codebase.
+import { KnowledgeStoreError } from "../errors.js";
+// ─── Defaults (declared up-front so callers can reason about behaviour) ──────
+// Hard caps tracked in the orchestrator. The contract scope (#196) requires:
+//   * batch size cap = 64 chunks per embedding flush
+//   * concurrent in-flight batches ≤ 4
+// Lower defaults are not exposed because they bias toward "more requests, smaller batches"
+// which costs more roundtrips without saving memory in our pipeline.
+export const DEFAULT_INDEXING_BATCH_SIZE = 64;
+export const DEFAULT_INDEXING_CONCURRENCY = 4;
+// Distinct from KnowledgeStoreError so a test asserting "indexing failed" cannot
+// accidentally accept any other store error. Extends KnowledgeStoreError so callers that
+// catch the parent class still see the failure.
+export class IndexingError extends KnowledgeStoreError {
+    name = "IndexingError";
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { ChunkId, DocumentId, EmbeddingModelIdentity, KnowledgeCapsuleId, KnowledgeSourceId, VectorId, VectorRecord } from "@oscharko-dev/keiko-contracts";
+import type { DatabaseSync } from "node:sqlite";
+import type { StoreContentCipher } from "../store-content-cipher.js";
+export interface ChunkRow {
+    readonly id: string;
+    readonly capsule_id: string;
+    readonly source_id: string;
+    readonly document_id: string;
+    readonly parsed_unit_id: string;
+    readonly order_index: number;
+    readonly token_count: number;
+    readonly safe_excerpt_hash: string;
+}
+export interface VectorInsertRow {
+    readonly id: VectorId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly chunkId: ChunkId;
+    readonly embedding: Uint8Array;
+    readonly identity: EmbeddingModelIdentity;
+    readonly storageReference: string;
+    readonly createdAt: number;
+}
+export declare function insertVectorRow(db: DatabaseSync, cipher: StoreContentCipher, row: VectorInsertRow): void;
+export declare function deleteVectorsForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): void;
+export declare function deleteVectorsForCapsule(db: DatabaseSync, capsuleId: KnowledgeCapsuleId): void;
+export declare function countVectorsForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): number;
+export declare function countVectorsForCapsule(db: DatabaseSync, capsuleId: KnowledgeCapsuleId): number;
+export declare function selectChunksForDocument(db: DatabaseSync, capsuleId: KnowledgeCapsuleId, documentId: DocumentId): readonly ChunkRow[];
+export declare function composeVectorRecord(row: VectorInsertRow): VectorRecord;
+//# sourceMappingURL=vector-persist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vector-persist.d.ts","sourceRoot":"","sources":["../../src/indexing/vector-persist.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAyCrE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAaD,wBAAgB,eAAe,CAC7B,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,EAAE,eAAe,GACnB,IAAI,CAmBN;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,IAAI,CAEN;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAE7F;AAMD,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,MAAM,CAKR;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAK9F;AAED,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,UAAU,GACrB,SAAS,QAAQ,EAAE,CAGrB;AAID,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,CAYtE"}

package/dist/indexing/vector-persist.js

@@ -0,0 +1,105 @@
+// Prepared-statement helpers for the `vectors` table (Epic #189, Issue #196). Every helper
+// wraps a single statement so the orchestrator can compose them at the boundaries of its
+// per-document work. The orchestrator is the only module that writes `vectors` rows.
+//
+// Vector ids are deterministic on `chunkId` (`vec:<chunkId>`): the chunks table already
+// owns a UNIQUE (capsule_id, id) constraint, so the same chunk being re-embedded twice in
+// a force run produces a byte-identical row id — the audit ledger's row-equality assertions
+// (#10) hold across re-indexes.
+//
+// The composite FK `vectors(capsule_id, chunk_id) → chunks(capsule_id, id)` is enforced by
+// SQLite — the orchestrator never bypasses it. If an upstream bug projects a chunk to a
+// wrong capsule, the INSERT raises rather than silently splitting tenants.
+import { KnowledgeStoreError } from "../errors.js";
+const INSERT_VECTOR_SQL = [
+    "INSERT INTO vectors (",
+    "  id, capsule_id, source_id, document_id, chunk_id,",
+    "  embedding, embedding_model_provider, embedding_model_id, embedding_model_revision,",
+    "  vector_dimensions, vector_metric, storage_reference, created_at",
+    ") VALUES (",
+    "  :id, :capsule_id, :source_id, :document_id, :chunk_id,",
+    "  :embedding, :provider, :model_id, :revision,",
+    "  :dimensions, :metric, :storage_reference, :created_at",
+    ")",
+    "ON CONFLICT(id) DO UPDATE SET",
+    "  embedding = excluded.embedding,",
+    "  embedding_model_provider = excluded.embedding_model_provider,",
+    "  embedding_model_id = excluded.embedding_model_id,",
+    "  embedding_model_revision = excluded.embedding_model_revision,",
+    "  vector_dimensions = excluded.vector_dimensions,",
+    "  vector_metric = excluded.vector_metric,",
+    "  storage_reference = excluded.storage_reference,",
+    "  created_at = excluded.created_at",
+].join(" ");
+const DELETE_VECTORS_FOR_DOCUMENT_SQL = "DELETE FROM vectors WHERE capsule_id = :c AND document_id = :d";
+const DELETE_VECTORS_FOR_CAPSULE_SQL = "DELETE FROM vectors WHERE capsule_id = :c";
+const COUNT_VECTORS_FOR_DOCUMENT_SQL = "SELECT COUNT(*) AS n FROM vectors WHERE capsule_id = :c AND document_id = :d";
+const COUNT_VECTORS_FOR_CAPSULE_SQL = "SELECT COUNT(*) AS n FROM vectors WHERE capsule_id = :c";
+const SELECT_CHUNKS_FOR_DOCUMENT_SQL = [
+    "SELECT id, capsule_id, source_id, document_id, parsed_unit_id, order_index, token_count,",
+    "  safe_excerpt_hash",
+    "FROM chunks",
+    "WHERE capsule_id = :c AND document_id = :d",
+    "ORDER BY order_index ASC",
+].join(" ");
+function assertEmbeddingShape(row) {
+    const expectedByteLength = row.identity.vectorDimensions * Float32Array.BYTES_PER_ELEMENT;
+    if (row.embedding.byteLength !== expectedByteLength) {
+        throw new KnowledgeStoreError(`vector ${String(row.id)} for capsule=${String(row.capsuleId)} ` +
+            `chunk=${String(row.chunkId)} has blob length ${String(row.embedding.byteLength)} ` +
+            `but identity.vectorDimensions=${String(row.identity.vectorDimensions)}`);
+    }
+}
+export function insertVectorRow(db, cipher, row) {
+    // Validate the PLAINTEXT shape (dimensions * 4 bytes) before sealing, so the identity check stays
+    // meaningful; the embedding is content (ADR-0047) and is sealed before it touches the BLOB column.
+    assertEmbeddingShape(row);
+    db.prepare(INSERT_VECTOR_SQL).run({
+        id: String(row.id),
+        capsule_id: String(row.capsuleId),
+        source_id: String(row.sourceId),
+        document_id: String(row.documentId),
+        chunk_id: String(row.chunkId),
+        embedding: cipher.sealVector(row.embedding),
+        provider: row.identity.provider,
+        model_id: row.identity.modelId,
+        revision: row.identity.modelRevision ?? null,
+        dimensions: row.identity.vectorDimensions,
+        metric: row.identity.vectorMetric,
+        storage_reference: row.storageReference,
+        created_at: row.createdAt,
+    });
+}
+export function deleteVectorsForDocument(db, capsuleId, documentId) {
+    db.prepare(DELETE_VECTORS_FOR_DOCUMENT_SQL).run({ c: capsuleId, d: documentId });
+}
+export function deleteVectorsForCapsule(db, capsuleId) {
+    db.prepare(DELETE_VECTORS_FOR_CAPSULE_SQL).run({ c: capsuleId });
+}
+export function countVectorsForDocument(db, capsuleId, documentId) {
+    const row = db.prepare(COUNT_VECTORS_FOR_DOCUMENT_SQL).get({ c: capsuleId, d: documentId });
+    return typeof row?.n === "number" ? row.n : 0;
+}
+export function countVectorsForCapsule(db, capsuleId) {
+    const row = db.prepare(COUNT_VECTORS_FOR_CAPSULE_SQL).get({ c: capsuleId });
+    return typeof row?.n === "number" ? row.n : 0;
+}
+export function selectChunksForDocument(db, capsuleId, documentId) {
+    const rows = db.prepare(SELECT_CHUNKS_FOR_DOCUMENT_SQL).all({ c: capsuleId, d: documentId });
+    return rows;
+}
+// VectorRecord composition is consolidated here so the batcher and any future replay tool
+// share the exact shape that gets persisted into `vectors`.
+export function composeVectorRecord(row) {
+    return {
+        id: row.id,
+        chunkId: row.chunkId,
+        capsuleId: row.capsuleId,
+        sourceId: row.sourceId,
+        documentId: row.documentId,
+        embeddingIdentity: row.identity,
+        vectorDimensions: row.identity.vectorDimensions,
+        storageReference: row.storageReference,
+        createdAt: row.createdAt,
+    };
+}

package/dist/parsers/_internal.d.ts

@@ -0,0 +1,20 @@
+import type { DocumentId, ParsedUnit, ParserDiagnostic, ParserIdentity, ParserResult } from "@oscharko-dev/keiko-contracts";
+import type { ParserCapability, ParserErrorCode, ParserOptions } from "./types.js";
+export declare function emptyResult(capability: ParserCapability, documentId: DocumentId, options: ParserOptions, diagnostics?: readonly ParserDiagnostic[], units?: readonly ParsedUnit[]): ParserResult;
+export declare function parserIdentity(capability: ParserCapability): ParserIdentity;
+export declare function diagnostic(code: ParserErrorCode, message: string, documentId: DocumentId, severity?: ParserDiagnostic["severity"]): ParserDiagnostic;
+export interface LimitCheck {
+    readonly stop: boolean;
+    readonly code?: ParserErrorCode;
+    readonly message?: string;
+}
+export declare function shouldStop(startedAt: number, options: ParserOptions, emittedUnits: number): LimitCheck;
+export declare function oversizeDiagnostic(documentId: DocumentId, byteLength: number, maxBytes: number): ParserDiagnostic;
+export declare function objectLimitDiagnostic(documentId: DocumentId, maxObjectsPerDocument: number): ParserDiagnostic;
+export interface DecodedText {
+    readonly text: string;
+    readonly bomBytes: number;
+}
+export declare function decodeXmlEntities(value: string): string;
+export declare function decodeUtf8(bytes: Uint8Array): DecodedText;
+//# sourceMappingURL=_internal.d.ts.map

package/dist/parsers/_internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_internal.d.ts","sourceRoot":"","sources":["../../src/parsers/_internal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,YAAY,EACb,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnF,wBAAgB,WAAW,CACzB,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,aAAa,EACtB,WAAW,GAAE,SAAS,gBAAgB,EAAO,EAC7C,KAAK,GAAE,SAAS,UAAU,EAAO,GAChC,YAAY,CAUd;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,gBAAgB,GAAG,cAAc,CAQ3E;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,QAAQ,GAAE,gBAAgB,CAAC,UAAU,CAAU,GAC9C,gBAAgB,CAElB;AAID,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,GACnB,UAAU,CAmBZ;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAOlB;AAED,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,qBAAqB,EAAE,MAAM,GAC5B,gBAAgB,CAOlB;AAMD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAkDD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWvD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CASzD"}

package/dist/parsers/_internal.js

@@ -0,0 +1,122 @@
+// Shared helpers for the parser adapters (Epic #189, Issue #266). NOT exported from the
+// package barrel — kept internal so the adapter surface stays minimal.
+export function emptyResult(capability, documentId, options, diagnostics = [], units = []) {
+    return {
+        documentId,
+        parser: parserIdentity(capability),
+        pages: [],
+        sections: [],
+        units,
+        diagnostics,
+        extractedAt: options.now(),
+    };
+}
+export function parserIdentity(capability) {
+    return capability.dependencyVersions === undefined
+        ? { parserId: capability.parserId, parserVersion: capability.parserVersion }
+        : {
+            parserId: capability.parserId,
+            parserVersion: capability.parserVersion,
+            dependencyVersions: capability.dependencyVersions,
+        };
+}
+export function diagnostic(code, message, documentId, severity = "info") {
+    return { severity, code, message, documentId };
+}
+export function shouldStop(startedAt, options, emittedUnits) {
+    if (options.signal?.aborted === true) {
+        return { stop: true, code: "PARSER_CANCELLED", message: "caller aborted parser" };
+    }
+    if (options.now() - startedAt > options.timeoutMs) {
+        return {
+            stop: true,
+            code: "PARSER_TIMEOUT",
+            message: `exceeded ${String(options.timeoutMs)}ms deadline`,
+        };
+    }
+    if (emittedUnits >= options.maxUnitsPerDocument) {
+        return {
+            stop: true,
+            code: "UNIT_LIMIT_REACHED",
+            message: `reached maxUnitsPerDocument=${String(options.maxUnitsPerDocument)}`,
+        };
+    }
+    return { stop: false };
+}
+export function oversizeDiagnostic(documentId, byteLength, maxBytes) {
+    return diagnostic("OVERSIZED_FILE", `input size ${String(byteLength)} exceeds maxBytes=${String(maxBytes)}`, documentId, "info");
+}
+export function objectLimitDiagnostic(documentId, maxObjectsPerDocument) {
+    return diagnostic("OBJECT_LIMIT_REACHED", `reached maxObjectsPerDocument=${String(maxObjectsPerDocument)}`, documentId, "error");
+}
+// GRD-012: detect UTF-16 LE/BE by BOM (common Windows .txt/.csv/.json exports) and re-decode
+// with the matching codec. Without this they decode as UTF-8 mojibake (every other byte a NUL /
+// replacement char) and are silently chunked/embedded as garbage. UTF-32 LE (FF FE 00 00) is
+// explicitly excluded so it is not mis-read as UTF-16 LE.
+function utf16CodecForBom(bytes) {
+    if (bytes.byteLength < 2)
+        return undefined;
+    const b0 = bytes[0];
+    const b1 = bytes[1];
+    if (b0 === 0xfe && b1 === 0xff)
+        return "utf-16be";
+    if (b0 !== 0xff || b1 !== 0xfe)
+        return undefined;
+    // FF FE is UTF-16 LE — unless it is the UTF-32 LE BOM (FF FE 00 00), which is not handled here.
+    const isUtf32Le = bytes.byteLength >= 4 && bytes[2] === 0x00 && bytes[3] === 0x00;
+    return isUtf32Le ? undefined : "utf-16le";
+}
+function decodeUtf16(bytes) {
+    const codec = utf16CodecForBom(bytes);
+    if (codec === undefined)
+        return undefined;
+    const text = new TextDecoder(codec, { fatal: false }).decode(bytes);
+    // The 2-byte UTF-16 BOM is normally consumed by TextDecoder; strip defensively so a leading
+    // U+FEFF never survives into offsets. bomBytes is the consumed BOM byte length (2).
+    const stripped = text.length > 0 && text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    return { text: stripped, bomBytes: 2 };
+}
+// GRD-027: decode an XML numeric character reference body (the part between `&#` and `;`),
+// e.g. "8217" (decimal) or "xE9" / "x2019" (hex). Returns undefined for malformed or
+// out-of-range references (incl. surrogates) so the caller leaves the literal text intact —
+// String.fromCodePoint throws on those, which must never crash the parser.
+// Valid Unicode scalar value: in range and not a lone surrogate (String.fromCodePoint throws
+// on surrogates / out-of-range).
+function isValidScalarCodePoint(cp) {
+    if (!Number.isInteger(cp) || cp < 0 || cp > 0x10ffff)
+        return false;
+    return cp < 0xd800 || cp > 0xdfff;
+}
+function decodeNumericCharacterReference(body) {
+    const isHex = body.startsWith("x") || body.startsWith("X");
+    const digits = isHex ? body.slice(1) : body;
+    if (digits.length === 0)
+        return undefined;
+    if (!(isHex ? /^[0-9a-fA-F]+$/ : /^[0-9]+$/).test(digits))
+        return undefined;
+    const codePoint = Number.parseInt(digits, isHex ? 16 : 10);
+    return isValidScalarCodePoint(codePoint) ? String.fromCodePoint(codePoint) : undefined;
+}
+// Shared OOXML/HTML entity decoder for docx/xlsx text runs. Decodes numeric references first
+// (decimal `&#8217;` and hex `&#xE9;` — smart quotes, accents), then the five named refs, with
+// `&amp;` LAST so an escaped ampersand (`&amp;#65;`) is not re-interpreted as a numeric ref.
+export function decodeXmlEntities(value) {
+    const withNumeric = value.replace(/&#(x?[0-9a-fA-F]+);/g, (match, body) => decodeNumericCharacterReference(body) ?? match);
+    return withNumeric
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&apos;", "'")
+        .replaceAll("&amp;", "&");
+}
+export function decodeUtf8(bytes) {
+    const utf16 = decodeUtf16(bytes);
+    if (utf16 !== undefined)
+        return utf16;
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    const raw = decoder.decode(bytes);
+    if (raw.length > 0 && raw.charCodeAt(0) === 0xfeff) {
+        return { text: raw.slice(1), bomBytes: 3 };
+    }
+    return { text: raw, bomBytes: 0 };
+}

package/dist/parsers/csv-parser.d.ts

@@ -0,0 +1,3 @@
+import type { ParserAdapter } from "./types.js";
+export declare const csvParser: ParserAdapter;
+//# sourceMappingURL=csv-parser.d.ts.map

package/dist/parsers/csv-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/csv-parser.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAuC,MAAM,YAAY,CAAC;AAiMrF,eAAO,MAAM,SAAS,EAAE,aA8BtB,CAAC"}