ocr-provenance-mcp 1.0.0

package/dist/services/storage/database/annotation-operations.js

@@ -0,0 +1,177 @@
+/**
+ * Annotation Database Operations
+ *
+ * CRUD operations for document annotations with threading support.
+ * Annotations can be attached to documents or specific chunks, with
+ * optional page numbers and threaded replies via parent_id.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module database/annotation-operations
+ */
+import { v4 as uuidv4 } from 'uuid';
+// ═══════════════════════════════════════════════════════════════════════════════
+// ANNOTATION CRUD
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Create a new annotation on a document or chunk.
+ *
+ * @param conn - Database connection
+ * @param params - Annotation creation parameters
+ * @returns The created annotation row
+ * @throws Error if document, chunk, or parent annotation not found
+ */
+export function createAnnotation(conn, params) {
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    // Validate document exists
+    const doc = conn.prepare('SELECT id FROM documents WHERE id = ?').get(params.document_id);
+    if (!doc) {
+        throw new Error(`Document not found: ${params.document_id}`);
+    }
+    // Validate chunk exists if provided
+    if (params.chunk_id) {
+        const chunk = conn.prepare('SELECT id FROM chunks WHERE id = ?').get(params.chunk_id);
+        if (!chunk) {
+            throw new Error(`Chunk not found: ${params.chunk_id}`);
+        }
+    }
+    // Validate parent exists if provided (for threaded replies)
+    if (params.parent_id) {
+        const parent = conn.prepare('SELECT id FROM annotations WHERE id = ?').get(params.parent_id);
+        if (!parent) {
+            throw new Error(`Parent annotation not found: ${params.parent_id}`);
+        }
+    }
+    conn.prepare(`
+    INSERT INTO annotations (id, document_id, user_id, chunk_id, page_number, annotation_type, content, status, parent_id, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 'open', ?, ?, ?)
+  `).run(id, params.document_id, params.user_id ?? null, params.chunk_id ?? null, params.page_number ?? null, params.annotation_type, params.content, params.parent_id ?? null, now, now);
+    return conn.prepare('SELECT * FROM annotations WHERE id = ?').get(id);
+}
+/**
+ * Get an annotation by ID.
+ *
+ * @param conn - Database connection
+ * @param id - Annotation ID
+ * @returns The annotation row or null if not found
+ */
+export function getAnnotation(conn, id) {
+    return conn.prepare('SELECT * FROM annotations WHERE id = ?').get(id) ?? null;
+}
+/**
+ * Get an annotation with its threaded replies.
+ *
+ * @param conn - Database connection
+ * @param id - Annotation ID
+ * @returns The annotation and its replies, or null if not found
+ */
+export function getAnnotationWithThread(conn, id) {
+    const annotation = getAnnotation(conn, id);
+    if (!annotation)
+        return null;
+    const replies = conn.prepare('SELECT * FROM annotations WHERE parent_id = ? ORDER BY created_at ASC').all(id);
+    return { annotation, replies };
+}
+/**
+ * List annotations for a document with optional filters.
+ *
+ * @param conn - Database connection
+ * @param opts - Filter and pagination options
+ * @returns Paginated annotations and total count
+ */
+export function listAnnotations(conn, opts) {
+    const conditions = ['document_id = ?'];
+    const params = [opts.document_id];
+    if (opts.annotation_type) {
+        conditions.push('annotation_type = ?');
+        params.push(opts.annotation_type);
+    }
+    if (opts.status) {
+        conditions.push('status = ?');
+        params.push(opts.status);
+    }
+    if (opts.user_id) {
+        conditions.push('user_id = ?');
+        params.push(opts.user_id);
+    }
+    if (opts.page_number !== undefined) {
+        conditions.push('page_number = ?');
+        params.push(opts.page_number);
+    }
+    const where = conditions.join(' AND ');
+    const totalRow = conn.prepare(`SELECT COUNT(*) as c FROM annotations WHERE ${where}`).get(...params);
+    const limit = Math.min(opts.limit ?? 50, 200);
+    const offset = opts.offset ?? 0;
+    const annotations = conn.prepare(`SELECT * FROM annotations WHERE ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`).all(...params, limit, offset);
+    return { annotations, total: totalRow.c };
+}
+/**
+ * Update an annotation's content and/or status.
+ *
+ * @param conn - Database connection
+ * @param id - Annotation ID
+ * @param updates - Fields to update (content and/or status)
+ * @returns The updated annotation row
+ * @throws Error if annotation not found
+ */
+export function updateAnnotation(conn, id, updates) {
+    const annotation = getAnnotation(conn, id);
+    if (!annotation) {
+        throw new Error(`Annotation not found: ${id}`);
+    }
+    const sets = ['updated_at = ?'];
+    const params = [new Date().toISOString()];
+    if (updates.content !== undefined) {
+        sets.push('content = ?');
+        params.push(updates.content);
+    }
+    if (updates.status !== undefined) {
+        sets.push('status = ?');
+        params.push(updates.status);
+    }
+    params.push(id);
+    conn.prepare(`UPDATE annotations SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+    return conn.prepare('SELECT * FROM annotations WHERE id = ?').get(id);
+}
+/**
+ * Delete an annotation by ID.
+ * Child annotations (replies) are cascade-deleted by the FK constraint.
+ *
+ * @param conn - Database connection
+ * @param id - Annotation ID
+ * @throws Error if annotation not found
+ */
+export function deleteAnnotation(conn, id) {
+    const annotation = getAnnotation(conn, id);
+    if (!annotation) {
+        throw new Error(`Annotation not found: ${id}`);
+    }
+    conn.prepare('DELETE FROM annotations WHERE id = ?').run(id);
+}
+/**
+ * Get annotation summary statistics for a document.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @returns Summary with counts by type, status, and totals
+ */
+export function getAnnotationSummary(conn, documentId) {
+    const byType = conn.prepare(`
+    SELECT annotation_type, status, COUNT(*) as count
+    FROM annotations WHERE document_id = ?
+    GROUP BY annotation_type, status
+  `).all(documentId);
+    const totalOpen = conn.prepare(`SELECT COUNT(*) as c FROM annotations WHERE document_id = ? AND status = 'open'`).get(documentId);
+    const totalResolved = conn.prepare(`SELECT COUNT(*) as c FROM annotations WHERE document_id = ? AND status = 'resolved'`).get(documentId);
+    const totalDismissed = conn.prepare(`SELECT COUNT(*) as c FROM annotations WHERE document_id = ? AND status = 'dismissed'`).get(documentId);
+    return {
+        document_id: documentId,
+        total_open: totalOpen.c,
+        total_resolved: totalResolved.c,
+        total_dismissed: totalDismissed.c,
+        total: totalOpen.c + totalResolved.c + totalDismissed.c,
+        by_type_and_status: byType,
+    };
+}
+//# sourceMappingURL=annotation-operations.js.map

package/dist/services/storage/database/annotation-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-operations.js","sourceRoot":"","sources":["../../../../src/services/storage/database/annotation-operations.ts"],"names":[],"mappings":"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"}

package/dist/services/storage/database/approval-operations.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Approval Chain Database Operations
+ *
+ * Provides operations for creating reusable approval chains and tracking
+ * per-document approval progress through multi-step review processes.
+ *
+ * An approval chain defines a sequence of steps (roles) that must approve
+ * a document. When applied to a document, individual approval_steps rows
+ * are created. Steps are processed in order - the next step becomes active
+ * only when the previous step is approved.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module database/approval-operations
+ */
+import type Database from 'better-sqlite3';
+export interface ApprovalChainRow {
+    id: string;
+    name: string;
+    description: string | null;
+    steps_json: string;
+    created_at: string;
+    created_by: string | null;
+}
+export interface ApprovalStepRow {
+    id: string;
+    document_id: string;
+    chain_id: string;
+    step_order: number;
+    required_role: string;
+    status: string;
+    decided_by: string | null;
+    decided_at: string | null;
+    reason: string | null;
+}
+export interface ApprovalChainStep {
+    role: string;
+    required_approvals?: number;
+    auto_advance?: boolean;
+}
+export interface CreateApprovalChainParams {
+    name: string;
+    description?: string | null;
+    steps: ApprovalChainStep[];
+    created_by?: string | null;
+}
+export interface ApprovalProgress {
+    chain_id: string;
+    chain_name: string;
+    document_id: string;
+    steps: ApprovalStepRow[];
+    total_steps: number;
+    completed_steps: number;
+    current_step: ApprovalStepRow | null;
+    is_complete: boolean;
+    is_rejected: boolean;
+}
+/**
+ * Create a reusable approval chain with ordered steps.
+ *
+ * @param conn - Database connection
+ * @param params - Chain creation parameters
+ * @returns The created approval chain row
+ * @throws Error if name is empty or no steps provided
+ */
+export declare function createApprovalChain(conn: Database.Database, params: CreateApprovalChainParams): ApprovalChainRow;
+/**
+ * Get an approval chain by ID.
+ *
+ * @param conn - Database connection
+ * @param chainId - Approval chain ID
+ * @returns The approval chain row or null
+ */
+export declare function getApprovalChain(conn: Database.Database, chainId: string): ApprovalChainRow | null;
+/**
+ * List all approval chains.
+ *
+ * @param conn - Database connection
+ * @returns Array of approval chain rows
+ */
+export declare function listApprovalChains(conn: Database.Database): ApprovalChainRow[];
+/**
+ * Apply an approval chain to a document, creating approval_steps rows.
+ *
+ * Creates one approval_steps row per step in the chain, all starting
+ * with 'pending' status. Steps are ordered by step_order.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID to apply the chain to
+ * @param chainId - Approval chain ID to apply
+ * @returns Array of created approval step rows
+ * @throws Error if document or chain not found, or chain already applied
+ */
+export declare function applyApprovalChain(conn: Database.Database, documentId: string, chainId: string): ApprovalStepRow[];
+/**
+ * Get the current (first pending) approval step for a document+chain.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @param chainId - Approval chain ID
+ * @returns The first pending step, or null if all steps are decided
+ */
+export declare function getCurrentApprovalStep(conn: Database.Database, documentId: string, chainId: string): ApprovalStepRow | null;
+/**
+ * Decide on an approval step (approve or reject).
+ *
+ * On approval: marks the step as 'approved' and returns it.
+ * On rejection: marks the step as 'rejected' and skips all subsequent
+ * pending steps (sets them to 'skipped').
+ *
+ * @param conn - Database connection
+ * @param stepId - Approval step ID to decide on
+ * @param decision - 'approved' or 'rejected'
+ * @param userId - User ID making the decision
+ * @param reason - Optional reason (required for rejection)
+ * @returns The updated approval step row
+ * @throws Error if step not found, not pending, or not the current step
+ */
+export declare function decideApprovalStep(conn: Database.Database, stepId: string, decision: 'approved' | 'rejected', userId: string, reason?: string | null): ApprovalStepRow;
+/**
+ * Get approval progress for a document and chain.
+ *
+ * Returns all steps with summary counts and the current pending step.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @param chainId - Approval chain ID
+ * @returns Approval progress with steps and summary
+ * @throws Error if chain not found or not applied to document
+ */
+export declare function getApprovalProgress(conn: Database.Database, documentId: string, chainId: string): ApprovalProgress;
+//# sourceMappingURL=approval-operations.d.ts.map

package/dist/services/storage/database/approval-operations.d.ts.map

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

package/dist/services/storage/database/approval-operations.js

@@ -0,0 +1,206 @@
+/**
+ * Approval Chain Database Operations
+ *
+ * Provides operations for creating reusable approval chains and tracking
+ * per-document approval progress through multi-step review processes.
+ *
+ * An approval chain defines a sequence of steps (roles) that must approve
+ * a document. When applied to a document, individual approval_steps rows
+ * are created. Steps are processed in order - the next step becomes active
+ * only when the previous step is approved.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module database/approval-operations
+ */
+import { v4 as uuidv4 } from 'uuid';
+// =============================================================================
+// APPROVAL CHAIN OPERATIONS
+// =============================================================================
+/**
+ * Create a reusable approval chain with ordered steps.
+ *
+ * @param conn - Database connection
+ * @param params - Chain creation parameters
+ * @returns The created approval chain row
+ * @throws Error if name is empty or no steps provided
+ */
+export function createApprovalChain(conn, params) {
+    if (!params.steps || params.steps.length === 0) {
+        throw new Error('Approval chain must have at least one step');
+    }
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    const stepsJson = JSON.stringify(params.steps);
+    conn.prepare(`
+    INSERT INTO approval_chains (id, name, description, steps_json, created_at, created_by)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, params.name, params.description ?? null, stepsJson, now, params.created_by ?? null);
+    return conn.prepare('SELECT * FROM approval_chains WHERE id = ?').get(id);
+}
+/**
+ * Get an approval chain by ID.
+ *
+ * @param conn - Database connection
+ * @param chainId - Approval chain ID
+ * @returns The approval chain row or null
+ */
+export function getApprovalChain(conn, chainId) {
+    return conn.prepare('SELECT * FROM approval_chains WHERE id = ?').get(chainId) ?? null;
+}
+/**
+ * List all approval chains.
+ *
+ * @param conn - Database connection
+ * @returns Array of approval chain rows
+ */
+export function listApprovalChains(conn) {
+    return conn.prepare('SELECT * FROM approval_chains ORDER BY created_at DESC').all();
+}
+/**
+ * Apply an approval chain to a document, creating approval_steps rows.
+ *
+ * Creates one approval_steps row per step in the chain, all starting
+ * with 'pending' status. Steps are ordered by step_order.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID to apply the chain to
+ * @param chainId - Approval chain ID to apply
+ * @returns Array of created approval step rows
+ * @throws Error if document or chain not found, or chain already applied
+ */
+export function applyApprovalChain(conn, documentId, chainId) {
+    // Validate document exists
+    const doc = conn.prepare('SELECT id FROM documents WHERE id = ?').get(documentId);
+    if (!doc) {
+        throw new Error(`Document not found: ${documentId}`);
+    }
+    // Validate chain exists
+    const chain = getApprovalChain(conn, chainId);
+    if (!chain) {
+        throw new Error(`Approval chain not found: ${chainId}`);
+    }
+    // Check if chain is already applied to this document
+    const existing = conn.prepare('SELECT id FROM approval_steps WHERE document_id = ? AND chain_id = ? LIMIT 1').get(documentId, chainId);
+    if (existing) {
+        throw new Error(`Approval chain "${chain.name}" is already applied to document ${documentId}`);
+    }
+    const steps = JSON.parse(chain.steps_json);
+    const createdSteps = [];
+    const insertStmt = conn.prepare(`
+    INSERT INTO approval_steps (id, document_id, chain_id, step_order, required_role, status, decided_by, decided_at, reason)
+    VALUES (?, ?, ?, ?, ?, 'pending', NULL, NULL, NULL)
+  `);
+    const getStmt = conn.prepare('SELECT * FROM approval_steps WHERE id = ?');
+    for (let i = 0; i < steps.length; i++) {
+        const stepId = uuidv4();
+        insertStmt.run(stepId, documentId, chainId, i + 1, steps[i].role);
+        createdSteps.push(getStmt.get(stepId));
+    }
+    return createdSteps;
+}
+/**
+ * Get the current (first pending) approval step for a document+chain.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @param chainId - Approval chain ID
+ * @returns The first pending step, or null if all steps are decided
+ */
+export function getCurrentApprovalStep(conn, documentId, chainId) {
+    return conn.prepare(`
+    SELECT * FROM approval_steps
+    WHERE document_id = ? AND chain_id = ? AND status = 'pending'
+    ORDER BY step_order ASC
+    LIMIT 1
+  `).get(documentId, chainId) ?? null;
+}
+/**
+ * Decide on an approval step (approve or reject).
+ *
+ * On approval: marks the step as 'approved' and returns it.
+ * On rejection: marks the step as 'rejected' and skips all subsequent
+ * pending steps (sets them to 'skipped').
+ *
+ * @param conn - Database connection
+ * @param stepId - Approval step ID to decide on
+ * @param decision - 'approved' or 'rejected'
+ * @param userId - User ID making the decision
+ * @param reason - Optional reason (required for rejection)
+ * @returns The updated approval step row
+ * @throws Error if step not found, not pending, or not the current step
+ */
+export function decideApprovalStep(conn, stepId, decision, userId, reason) {
+    const step = conn.prepare('SELECT * FROM approval_steps WHERE id = ?').get(stepId);
+    if (!step) {
+        throw new Error(`Approval step not found: ${stepId}`);
+    }
+    if (step.status !== 'pending') {
+        throw new Error(`Approval step ${stepId} is already "${step.status}" and cannot be decided`);
+    }
+    // Ensure this is the current step (lowest pending step_order for this doc+chain)
+    const currentStep = getCurrentApprovalStep(conn, step.document_id, step.chain_id);
+    if (!currentStep || currentStep.id !== stepId) {
+        throw new Error(`Step ${stepId} (order ${step.step_order}) is not the current step. ` +
+            `Steps must be decided in order.`);
+    }
+    if (decision === 'rejected' && !reason) {
+        throw new Error('Reason is required when rejecting an approval step');
+    }
+    const now = new Date().toISOString();
+    // Update the step
+    conn.prepare(`
+    UPDATE approval_steps SET status = ?, decided_by = ?, decided_at = ?, reason = ?
+    WHERE id = ?
+  `).run(decision, userId, now, reason ?? null, stepId);
+    // On rejection, skip all subsequent pending steps
+    if (decision === 'rejected') {
+        conn.prepare(`
+      UPDATE approval_steps
+      SET status = 'skipped', decided_at = ?, reason = 'Skipped due to rejection at step ' || ?
+      WHERE document_id = ? AND chain_id = ? AND step_order > ? AND status = 'pending'
+    `).run(now, step.step_order, step.document_id, step.chain_id, step.step_order);
+    }
+    return conn.prepare('SELECT * FROM approval_steps WHERE id = ?').get(stepId);
+}
+/**
+ * Get approval progress for a document and chain.
+ *
+ * Returns all steps with summary counts and the current pending step.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @param chainId - Approval chain ID
+ * @returns Approval progress with steps and summary
+ * @throws Error if chain not found or not applied to document
+ */
+export function getApprovalProgress(conn, documentId, chainId) {
+    const chain = getApprovalChain(conn, chainId);
+    if (!chain) {
+        throw new Error(`Approval chain not found: ${chainId}`);
+    }
+    const steps = conn.prepare(`
+    SELECT * FROM approval_steps
+    WHERE document_id = ? AND chain_id = ?
+    ORDER BY step_order ASC
+  `).all(documentId, chainId);
+    if (steps.length === 0) {
+        throw new Error(`Approval chain "${chain.name}" has not been applied to document ${documentId}`);
+    }
+    const completedSteps = steps.filter((s) => s.status === 'approved' || s.status === 'rejected' || s.status === 'skipped').length;
+    const currentStep = steps.find((s) => s.status === 'pending') ?? null;
+    const isRejected = steps.some((s) => s.status === 'rejected');
+    const isComplete = currentStep === null;
+    return {
+        chain_id: chainId,
+        chain_name: chain.name,
+        document_id: documentId,
+        steps,
+        total_steps: steps.length,
+        completed_steps: completedSteps,
+        current_step: currentStep,
+        is_complete: isComplete,
+        is_rejected: isRejected,
+    };
+}
+//# sourceMappingURL=approval-operations.js.map

package/dist/services/storage/database/approval-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-operations.js","sourceRoot":"","sources":["../../../../src/services/storage/database/approval-operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAoDpC,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAuB,EACvB,MAAiC;IAEjC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE/C,IAAI,CAAC,OAAO,CAAC;;;GAGZ,CAAC,CAAC,GAAG,CACJ,EAAE,EACF,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,WAAW,IAAI,IAAI,EAC1B,SAAS,EACT,GAAG,EACH,MAAM,CAAC,UAAU,IAAI,IAAI,CAC1B,CAAC;IAEF,OAAO,IAAI,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,CAAC,EAAE,CAAqB,CAAC;AAChG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAuB,EACvB,OAAe;IAEf,OAAQ,IAAI,CAAC,OAAO,CAClB,4CAA4C,CAC7C,CAAC,GAAG,CAAC,OAAO,CAAsB,IAAI,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAuB;IACxD,OAAO,IAAI,CAAC,OAAO,CACjB,wDAAwD,CACzD,CAAC,GAAG,EAAwB,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAuB,EACvB,UAAkB,EAClB,OAAe;IAEf,2BAA2B;IAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,uCAAuC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAClF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,uBAAuB,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,wBAAwB;IACxB,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,qDAAqD;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAC3B,8EAA8E,CAC/E,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3B,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mBAAmB,KAAK,CAAC,IAAI,oCAAoC,UAAU,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAwB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAChE,MAAM,YAAY,GAAsB,EAAE,CAAC;IAE3C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;;;GAG/B,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAC;IAE1E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;QACxB,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClE,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAoB,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAuB,EACvB,UAAkB,EAClB,OAAe;IAEf,OAAQ,IAAI,CAAC,OAAO,CAAC;;;;;GAKpB,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAqB,IAAI,IAAI,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAuB,EACvB,MAAc,EACd,QAAiC,EACjC,MAAc,EACd,MAAsB;IAEtB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CACvB,2CAA2C,CAC5C,CAAC,GAAG,CAAC,MAAM,CAAgC,CAAC;IAE7C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,gBAAgB,IAAI,CAAC,MAAM,yBAAyB,CAC5E,CAAC;IACJ,CAAC;IAED,iFAAiF;IACjF,MAAM,WAAW,GAAG,sBAAsB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClF,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,QAAQ,MAAM,WAAW,IAAI,CAAC,UAAU,6BAA6B;YACrE,iCAAiC,CAClC,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,kBAAkB;IAClB,IAAI,CAAC,OAAO,CAAC;;;GAGZ,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,IAAI,IAAI,EAAE,MAAM,CAAC,CAAC;IAEtD,kDAAkD;IAClD,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC;;;;KAIZ,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACjF,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CACjB,2CAA2C,CAC5C,CAAC,GAAG,CAAC,MAAM,CAAoB,CAAC;AACnC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAuB,EACvB,UAAkB,EAClB,OAAe;IAEf,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;;;;GAI1B,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAsB,CAAC;IAEjD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,mBAAmB,KAAK,CAAC,IAAI,sCAAsC,UAAU,EAAE,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,CACpF,CAAC,MAAM,CAAC;IAET,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,IAAI,IAAI,CAAC;IACtE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,WAAW,KAAK,IAAI,CAAC;IAExC,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,UAAU,EAAE,KAAK,CAAC,IAAI;QACtB,WAAW,EAAE,UAAU;QACvB,KAAK;QACL,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,eAAe,EAAE,cAAc;QAC/B,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,UAAU;QACvB,WAAW,EAAE,UAAU;KACxB,CAAC;AACJ,CAAC"}

package/dist/services/storage/database/chunk-operations.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Chunk operations for DatabaseService
+ *
+ * Handles all CRUD operations for text chunks including
+ * batch inserts, embedding status updates, filtered queries,
+ * and neighbor lookups.
+ */
+import Database from 'better-sqlite3';
+import { Chunk } from '../../../models/chunk.js';
+/**
+ * Filter options for getChunksFiltered
+ */
+export interface ChunkFilterOptions {
+    section_path_filter?: string;
+    heading_filter?: string;
+    content_type_filter?: string[];
+    min_quality_score?: number;
+    embedding_status?: 'pending' | 'complete' | 'failed';
+    is_atomic?: boolean;
+    page_range?: {
+        min_page?: number;
+        max_page?: number;
+    };
+    limit?: number;
+    offset?: number;
+    include_text?: boolean;
+}
+/**
+ * Insert a chunk
+ *
+ * @param db - Database connection
+ * @param chunk - Chunk data (created_at, embedding_status, embedded_at will be generated)
+ * @param updateMetadataCounts - Callback to update metadata counts
+ * @returns string - The chunk ID
+ */
+export declare function insertChunk(db: Database.Database, chunk: Omit<Chunk, 'created_at' | 'embedding_status' | 'embedded_at'>, updateMetadataCounts: () => void): string;
+/**
+ * Insert multiple chunks in a batch transaction
+ *
+ * @param db - Database connection
+ * @param chunks - Array of chunk data
+ * @param updateMetadataCounts - Callback to update metadata counts
+ * @param transaction - Transaction wrapper function
+ * @returns string[] - Array of chunk IDs
+ */
+export declare function insertChunks(db: Database.Database, chunks: Omit<Chunk, 'created_at' | 'embedding_status' | 'embedded_at'>[], updateMetadataCounts: () => void, transaction: <T>(fn: () => T) => T): string[];
+/**
+ * Get a chunk by ID
+ *
+ * @param db - Database connection
+ * @param id - Chunk ID
+ * @returns Chunk | null - The chunk or null if not found
+ */
+export declare function getChunk(db: Database.Database, id: string): Chunk | null;
+/**
+ * Check if a document has any chunks (M-9: avoids loading all chunk rows)
+ *
+ * @param db - Database connection
+ * @param documentId - Document ID
+ * @returns boolean - true if document has at least one chunk
+ */
+export declare function hasChunksByDocumentId(db: Database.Database, documentId: string): boolean;
+/**
+ * Get all chunks for a document
+ *
+ * @param db - Database connection
+ * @param documentId - Document ID
+ * @returns Chunk[] - Array of chunks ordered by chunk_index
+ */
+export declare function getChunksByDocumentId(db: Database.Database, documentId: string, options?: {
+    limit?: number;
+    offset?: number;
+}): Chunk[];
+/**
+ * Get all chunks for an OCR result
+ *
+ * @param db - Database connection
+ * @param ocrResultId - OCR result ID
+ * @returns Chunk[] - Array of chunks ordered by chunk_index
+ */
+export declare function getChunksByOCRResultId(db: Database.Database, ocrResultId: string, options?: {
+    limit?: number;
+    offset?: number;
+}): Chunk[];
+/**
+ * Get chunks pending embedding generation
+ *
+ * @param db - Database connection
+ * @param limit - Optional maximum number of chunks to return
+ * @returns Chunk[] - Array of pending chunks
+ */
+export declare function getPendingEmbeddingChunks(db: Database.Database, limit?: number): Chunk[];
+/**
+ * Update chunk embedding status
+ *
+ * @param db - Database connection
+ * @param id - Chunk ID
+ * @param status - New embedding status
+ * @param embeddedAt - Optional ISO 8601 timestamp when embedded
+ * @param updateMetadataModified - Callback to update metadata modified timestamp
+ */
+export declare function updateChunkEmbeddingStatus(db: Database.Database, id: string, status: 'pending' | 'complete' | 'failed', embeddedAt: string | undefined, updateMetadataModified: () => void): void;
+/**
+ * Get chunks for a document with dynamic filtering.
+ *
+ * Builds a parameterized WHERE clause from the provided filters.
+ * For content_type_filter, uses LIKE matching against the JSON-encoded
+ * content_types column (e.g., content_types LIKE '%table%').
+ *
+ * @param db - Database connection
+ * @param documentId - Document ID to filter by
+ * @param filters - Filter options
+ * @returns Object with chunks array and total count
+ */
+export declare function getChunksFiltered(db: Database.Database, documentId: string, filters: ChunkFilterOptions): {
+    chunks: Chunk[];
+    total: number;
+};
+/**
+ * Get neighboring chunks around a given chunk index for context building.
+ *
+ * Returns chunks with chunk_index in range [chunkIndex - count, chunkIndex + count],
+ * ordered by chunk_index.
+ *
+ * @param db - Database connection
+ * @param documentId - Document ID
+ * @param chunkIndex - Center chunk index
+ * @param count - Number of neighbors on each side
+ * @returns Chunk[] - Array of neighboring chunks (including center)
+ */
+export declare function getChunkNeighbors(db: Database.Database, documentId: string, chunkIndex: number, count: number): Chunk[];
+//# sourceMappingURL=chunk-operations.d.ts.map