ocr-provenance-mcp 1.0.0

package/dist/services/search/query-expander.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Query Expander for Legal/Medical Domain + Corpus-Driven Expansion
+ *
+ * Expands search queries with domain-specific synonyms and corpus cluster top terms.
+ * When enabled, the query "injury" also searches for "wound", "trauma", etc.
+ * With a database connection, also expands from cluster top_terms_json for
+ * corpus-specific vocabulary.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module services/search/query-expander
+ */
+import type { DatabaseService } from '../storage/database/index.js';
+/**
+ * Sanitize a single term for safe inclusion in an FTS5 OR-joined query.
+ *
+ * 1. Strips all FTS5 metacharacters
+ * 2. Returns empty string if the cleaned term is an FTS5 operator (AND/OR/NOT)
+ *    to prevent accidental operator injection from corpus/table data
+ *
+ * @param term - Raw term from corpus clusters, table columns, or synonyms
+ * @returns Sanitized term safe for FTS5, or empty string if term should be skipped
+ */
+export declare function sanitizeFTS5Term(term: string): string;
+/**
+ * Get matching table column names from provenance processing_params.
+ * Searches for column headers that contain any of the query words.
+ *
+ * @param db - DatabaseService instance
+ * @param queryWords - Lowercased query words to match against column names
+ * @returns Array of matching column name terms
+ */
+export declare function getTableColumnExpansionTerms(db: DatabaseService, queryWords: string[]): string[];
+/**
+ * Query cluster top terms from the database for corpus-specific expansion.
+ *
+ * For each query word, checks if it appears in any cluster's top_terms_json
+ * (clusters with coherence_score > 0.3). Returns other terms from matching
+ * clusters as expansion candidates (max 3 per cluster match).
+ *
+ * @param db - DatabaseService instance
+ * @param queryWords - Lowercased query words to match against cluster terms
+ * @returns Map of query word -> corpus expansion terms
+ */
+export declare function getCorpusExpansionTerms(db: DatabaseService, queryWords: string[]): Record<string, string[]>;
+/**
+ * Get detailed expansion information for a query.
+ * Shows which words were expanded and what synonyms were found.
+ * When a database is provided, also includes corpus-driven expansion from cluster top terms.
+ *
+ * @param query - Original search query
+ * @param db - Optional DatabaseService for corpus-driven expansion
+ * @param isTableQuery - Whether the query targets table content
+ * @returns Expansion details: original query, new expanded terms, synonym map, corpus terms
+ */
+export declare function getExpandedTerms(query: string, db?: DatabaseService, isTableQuery?: boolean): {
+    original: string;
+    expanded: string[];
+    synonyms_found: Record<string, string[]>;
+    corpus_terms?: Record<string, string[]>;
+    table_column_terms?: string[];
+};
+/**
+ * Expand query using static synonyms and optional corpus cluster terms.
+ * When isTableQuery is true, also expands with matching table column names.
+ *
+ * @param query - Original search query
+ * @param db - Optional DatabaseService for corpus-driven expansion
+ * @param isTableQuery - Whether the query targets table content
+ * @returns OR-joined expanded query string
+ */
+export declare function expandQuery(query: string, db?: DatabaseService, isTableQuery?: boolean): string;
+//# sourceMappingURL=query-expander.d.ts.map

package/dist/services/search/query-expander.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-expander.d.ts","sourceRoot":"","sources":["../../../src/services/search/query-expander.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAQpE;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AA8BD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CA8CV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAgD1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,EAAE,CAAC,EAAE,eAAe,EACpB,YAAY,CAAC,EAAE,OAAO,GACrB;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B,CAuCA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,eAAe,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CA0D/F"}

package/dist/services/search/query-expander.js

@@ -0,0 +1,281 @@
+/**
+ * Query Expander for Legal/Medical Domain + Corpus-Driven Expansion
+ *
+ * Expands search queries with domain-specific synonyms and corpus cluster top terms.
+ * When enabled, the query "injury" also searches for "wound", "trauma", etc.
+ * With a database connection, also expands from cluster top_terms_json for
+ * corpus-specific vocabulary.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module services/search/query-expander
+ */
+/** FTS5 metacharacters that must be stripped from expansion terms */
+const FTS5_METACHAR_RE = /['"()*:^~+{}[\]\\;@<>#!$%&|,./`?-]/g;
+/** FTS5 boolean operators that corrupt query semantics if used as literal terms */
+const FTS5_OPERATOR_WORDS = new Set(['AND', 'OR', 'NOT']);
+/**
+ * Sanitize a single term for safe inclusion in an FTS5 OR-joined query.
+ *
+ * 1. Strips all FTS5 metacharacters
+ * 2. Returns empty string if the cleaned term is an FTS5 operator (AND/OR/NOT)
+ *    to prevent accidental operator injection from corpus/table data
+ *
+ * @param term - Raw term from corpus clusters, table columns, or synonyms
+ * @returns Sanitized term safe for FTS5, or empty string if term should be skipped
+ */
+export function sanitizeFTS5Term(term) {
+    const cleaned = term.replace(FTS5_METACHAR_RE, '').trim();
+    if (cleaned.length === 0)
+        return '';
+    if (FTS5_OPERATOR_WORDS.has(cleaned.toUpperCase()))
+        return '';
+    return cleaned;
+}
+const SYNONYM_MAP = {
+    // Legal terms
+    injury: ['wound', 'trauma', 'harm', 'damage'],
+    accident: ['collision', 'crash', 'incident', 'wreck'],
+    plaintiff: ['claimant', 'complainant', 'petitioner'],
+    defendant: ['respondent', 'accused'],
+    contract: ['agreement', 'covenant', 'pact'],
+    negligence: ['carelessness', 'recklessness', 'fault'],
+    damages: ['compensation', 'restitution', 'remedy'],
+    testimony: ['deposition', 'declaration', 'statement', 'affidavit'],
+    evidence: ['exhibit', 'proof', 'documentation'],
+    settlement: ['resolution', 'compromise', 'accord'],
+    // Medical terms
+    fracture: ['break', 'crack', 'rupture'],
+    surgery: ['operation', 'procedure', 'intervention'],
+    diagnosis: ['assessment', 'evaluation', 'finding'],
+    medication: ['drug', 'prescription', 'pharmaceutical', 'medicine'],
+    chronic: ['persistent', 'ongoing', 'long-term', 'recurring'],
+    pain: ['discomfort', 'ache', 'soreness', 'agony'],
+    treatment: ['therapy', 'care', 'intervention', 'management'],
+};
+/** Max corpus expansion terms per cluster match */
+const MAX_CORPUS_TERMS_PER_CLUSTER = 3;
+/** Max table column terms to add per query */
+const MAX_TABLE_COLUMN_TERMS = 5;
+/**
+ * Get matching table column names from provenance processing_params.
+ * Searches for column headers that contain any of the query words.
+ *
+ * @param db - DatabaseService instance
+ * @param queryWords - Lowercased query words to match against column names
+ * @returns Array of matching column name terms
+ */
+export function getTableColumnExpansionTerms(db, queryWords) {
+    const terms = [];
+    try {
+        const conn = db.getConnection();
+        const rows = conn.prepare("SELECT DISTINCT processing_params FROM provenance WHERE processing_params LIKE '%table_columns%' LIMIT 500").all();
+        const allColumns = new Set();
+        for (const row of rows) {
+            try {
+                const params = JSON.parse(row.processing_params);
+                const cols = params.table_columns;
+                if (Array.isArray(cols)) {
+                    for (const col of cols) {
+                        if (typeof col === 'string' && col.length > 0) {
+                            allColumns.add(col);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`[query-expander] Failed to parse table_columns from processing_params: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // Find columns matching any query word
+        for (const col of allColumns) {
+            const colLower = col.toLowerCase();
+            for (const word of queryWords) {
+                if (colLower.includes(word) || word.includes(colLower)) {
+                    // Add individual words from the column name, sanitized for FTS5 safety
+                    const colWords = col.split(/\s+/)
+                        .map(w => sanitizeFTS5Term(w))
+                        .filter(w => w.length > 2);
+                    terms.push(...colWords);
+                    break;
+                }
+            }
+            if (terms.length >= MAX_TABLE_COLUMN_TERMS)
+                break;
+        }
+    }
+    catch (error) {
+        console.error(`[QueryExpander] Failed to query table column terms: ${String(error)}`);
+    }
+    return [...new Set(terms)].slice(0, MAX_TABLE_COLUMN_TERMS);
+}
+/**
+ * Query cluster top terms from the database for corpus-specific expansion.
+ *
+ * For each query word, checks if it appears in any cluster's top_terms_json
+ * (clusters with coherence_score > 0.3). Returns other terms from matching
+ * clusters as expansion candidates (max 3 per cluster match).
+ *
+ * @param db - DatabaseService instance
+ * @param queryWords - Lowercased query words to match against cluster terms
+ * @returns Map of query word -> corpus expansion terms
+ */
+export function getCorpusExpansionTerms(db, queryWords) {
+    const corpusTerms = {};
+    try {
+        const conn = db.getConnection();
+        const rows = conn
+            .prepare('SELECT top_terms_json FROM clusters WHERE top_terms_json IS NOT NULL AND coherence_score > 0.3 LIMIT 200')
+            .all();
+        if (rows.length === 0)
+            return corpusTerms;
+        // Parse all cluster top terms
+        const clusterTermSets = [];
+        for (const row of rows) {
+            try {
+                const terms = JSON.parse(row.top_terms_json);
+                if (Array.isArray(terms) && terms.length > 0) {
+                    clusterTermSets.push(terms.map((t) => String(t).toLowerCase()));
+                }
+            }
+            catch (error) {
+                console.error(`[query-expander] Failed to parse cluster top_terms_json: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        // For each query word, find matching clusters and extract expansion terms
+        for (const word of queryWords) {
+            const expansions = [];
+            for (const clusterTerms of clusterTermSets) {
+                if (clusterTerms.includes(word)) {
+                    // Add other terms from this cluster as expansions (max 3)
+                    const otherTerms = clusterTerms
+                        .filter((t) => t !== word && !queryWords.includes(t))
+                        .slice(0, MAX_CORPUS_TERMS_PER_CLUSTER);
+                    expansions.push(...otherTerms);
+                }
+            }
+            if (expansions.length > 0) {
+                // Deduplicate
+                corpusTerms[word] = [...new Set(expansions)];
+            }
+        }
+    }
+    catch (error) {
+        console.error(`[QueryExpander] Failed to query corpus expansion terms: ${String(error)}`);
+    }
+    return corpusTerms;
+}
+/**
+ * Get detailed expansion information for a query.
+ * Shows which words were expanded and what synonyms were found.
+ * When a database is provided, also includes corpus-driven expansion from cluster top terms.
+ *
+ * @param query - Original search query
+ * @param db - Optional DatabaseService for corpus-driven expansion
+ * @param isTableQuery - Whether the query targets table content
+ * @returns Expansion details: original query, new expanded terms, synonym map, corpus terms
+ */
+export function getExpandedTerms(query, db, isTableQuery) {
+    const words = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    const synonymsFound = {};
+    const expanded = [];
+    for (const word of words) {
+        const synonyms = SYNONYM_MAP[word];
+        if (synonyms) {
+            synonymsFound[word] = synonyms;
+            expanded.push(...synonyms);
+        }
+    }
+    // Corpus-driven expansion from cluster top terms
+    let corpusTerms;
+    if (db) {
+        corpusTerms = getCorpusExpansionTerms(db, words);
+        for (const terms of Object.values(corpusTerms)) {
+            expanded.push(...terms);
+        }
+    }
+    // Table column expansion
+    let tableColumnTerms;
+    if (isTableQuery && db) {
+        tableColumnTerms = getTableColumnExpansionTerms(db, words);
+        expanded.push(...tableColumnTerms);
+    }
+    return {
+        original: query,
+        expanded,
+        synonyms_found: synonymsFound,
+        ...(corpusTerms && Object.keys(corpusTerms).length > 0 ? { corpus_terms: corpusTerms } : {}),
+        ...(tableColumnTerms && tableColumnTerms.length > 0 ? { table_column_terms: tableColumnTerms } : {}),
+    };
+}
+/**
+ * Expand query using static synonyms and optional corpus cluster terms.
+ * When isTableQuery is true, also expands with matching table column names.
+ *
+ * @param query - Original search query
+ * @param db - Optional DatabaseService for corpus-driven expansion
+ * @param isTableQuery - Whether the query targets table content
+ * @returns OR-joined expanded query string
+ */
+export function expandQuery(query, db, isTableQuery) {
+    const words = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+    // Sanitize every term (including original query words) before adding to the set.
+    // This ensures the final OR-joined string is a valid FTS5 expression with no
+    // metacharacters or accidental operator words from any source.
+    const expanded = new Set();
+    for (const w of words) {
+        const safe = sanitizeFTS5Term(w);
+        if (safe.length > 0)
+            expanded.add(safe);
+    }
+    for (const word of words) {
+        const synonyms = SYNONYM_MAP[word];
+        if (synonyms) {
+            for (const syn of synonyms) {
+                const safe = sanitizeFTS5Term(syn);
+                if (safe.length > 0)
+                    expanded.add(safe);
+            }
+        }
+    }
+    // Corpus-driven expansion from cluster top terms.
+    // Corpus terms may be multi-word (e.g. "patient records") -- split into
+    // individual words so each becomes a separate OR operand.
+    if (db) {
+        const corpusTerms = getCorpusExpansionTerms(db, words);
+        for (const terms of Object.values(corpusTerms)) {
+            for (const term of terms) {
+                for (const part of term.split(/\s+/)) {
+                    const safe = sanitizeFTS5Term(part);
+                    if (safe.length > 0)
+                        expanded.add(safe);
+                }
+            }
+        }
+    }
+    // Table column expansion for table-related queries
+    if (isTableQuery && db) {
+        const tableTerms = getTableColumnExpansionTerms(db, words);
+        for (const term of tableTerms) {
+            for (const part of term.toLowerCase().split(/\s+/)) {
+                const safe = sanitizeFTS5Term(part);
+                if (safe.length > 0)
+                    expanded.add(safe);
+            }
+        }
+    }
+    const terms = [...expanded];
+    if (terms.length > 20) {
+        // Cap expanded terms to prevent query dilution
+        // Keep the first 20 terms (original words come first, then synonyms, then corpus terms)
+        return terms.slice(0, 20).join(' OR ');
+    }
+    return terms.join(' OR ');
+}
+//# sourceMappingURL=query-expander.js.map

package/dist/services/search/query-expander.js.map

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

package/dist/services/search/reranker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Local Cross-Encoder Search Re-ranker
+ *
+ * Re-ranks search results using a local cross-encoder model (ms-marco-MiniLM-L-12-v2)
+ * via the Python reranker worker. NO Gemini/cloud dependency.
+ *
+ * If the local model is not available (sentence-transformers not installed, model not
+ * downloaded, Python error), returns results as-is with a console.error() warning.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module services/search/reranker
+ */
+/**
+ * Re-rank search results using a local cross-encoder model.
+ *
+ * Takes the top results (max 20), sends them to the local Python cross-encoder
+ * for relevance scoring, and returns sorted results.
+ *
+ * If the local model is unavailable, returns the original results in their existing
+ * order with reasoning indicating no reranking was performed.
+ *
+ * @param query - The original search query
+ * @param results - Search results with original_text field
+ * @param maxResults - Maximum results to return after re-ranking (default: 10)
+ * @returns Re-ranked results with scores and reasoning
+ */
+export declare function rerankResults(query: string, results: Array<{
+    original_text: string;
+    [key: string]: unknown;
+}>, maxResults?: number): Promise<Array<{
+    original_index: number;
+    relevance_score: number;
+    reasoning: string;
+}>>;
+/**
+ * Build a re-rank prompt string (legacy helper, used only by unit tests).
+ *
+ * @param query - Search query
+ * @param excerpts - Array of text excerpts
+ * @returns Formatted prompt string
+ */
+export declare function buildRerankPrompt(query: string, excerpts: string[]): string;
+//# sourceMappingURL=reranker.d.ts.map

package/dist/services/search/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/services/search/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,KAAK,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC,EACjE,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,KAAK,CAAC;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CA8DxF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,CAaR"}

package/dist/services/search/reranker.js

@@ -0,0 +1,101 @@
+/**
+ * Local Cross-Encoder Search Re-ranker
+ *
+ * Re-ranks search results using a local cross-encoder model (ms-marco-MiniLM-L-12-v2)
+ * via the Python reranker worker. NO Gemini/cloud dependency.
+ *
+ * If the local model is not available (sentence-transformers not installed, model not
+ * downloaded, Python error), returns results as-is with a console.error() warning.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module services/search/reranker
+ */
+import { localRerank } from './local-reranker.js';
+/**
+ * Re-rank search results using a local cross-encoder model.
+ *
+ * Takes the top results (max 20), sends them to the local Python cross-encoder
+ * for relevance scoring, and returns sorted results.
+ *
+ * If the local model is unavailable, returns the original results in their existing
+ * order with reasoning indicating no reranking was performed.
+ *
+ * @param query - The original search query
+ * @param results - Search results with original_text field
+ * @param maxResults - Maximum results to return after re-ranking (default: 10)
+ * @returns Re-ranked results with scores and reasoning
+ */
+export async function rerankResults(query, results, maxResults = 10) {
+    if (results.length === 0)
+        return [];
+    // Take top results to re-rank (max 20 to stay within token limits)
+    const toRerank = results.slice(0, Math.min(results.length, 20));
+    // Build passages for the local reranker
+    const passages = toRerank.map((r, i) => {
+        let originalScore = 0;
+        if (typeof r.bm25_score === 'number') {
+            originalScore = r.bm25_score;
+        }
+        else if (typeof r.score === 'number') {
+            originalScore = r.score;
+        }
+        return { index: i, text: String(r.original_text), original_score: originalScore };
+    });
+    const localResults = await localRerank(query, passages);
+    if (localResults === null) {
+        // Local model not available - return results as-is in original order
+        console.error('[reranker] Local cross-encoder unavailable. Returning results without reranking. ' +
+            'Install sentence-transformers for local reranking: pip install sentence-transformers');
+        return toRerank
+            .slice(0, maxResults)
+            .map((_, i) => ({
+            original_index: i,
+            relevance_score: 0,
+            reasoning: 'local cross-encoder unavailable, original order preserved',
+        }));
+    }
+    // Filter to valid indices only
+    const validResults = localResults.filter((r) => r.index >= 0 && r.index < toRerank.length);
+    if (validResults.length === 0 && toRerank.length > 0) {
+        console.error(`[reranker] Cross-encoder returned 0 valid results from ${toRerank.length} inputs. ` +
+            'Returning results without reranking.');
+        return toRerank
+            .slice(0, maxResults)
+            .map((_, i) => ({
+            original_index: i,
+            relevance_score: 0,
+            reasoning: 'cross-encoder returned no valid results, original order preserved',
+        }));
+    }
+    // Sort by relevance score descending, take maxResults
+    return validResults
+        .sort((a, b) => b.relevance_score - a.relevance_score)
+        .slice(0, maxResults)
+        .map((r) => ({
+        original_index: r.index,
+        relevance_score: r.relevance_score,
+        reasoning: `cross-encoder score: ${r.relevance_score.toFixed(4)}`,
+    }));
+}
+/**
+ * Build a re-rank prompt string (legacy helper, used only by unit tests).
+ *
+ * @param query - Search query
+ * @param excerpts - Array of text excerpts
+ * @returns Formatted prompt string
+ */
+export function buildRerankPrompt(query, excerpts) {
+    const formattedExcerpts = excerpts
+        .map((text, i) => `[${i}] ${text.slice(0, 500)}`)
+        .join('\n\n');
+    return `You are a legal document search relevance expert. Given a search query and a list of document excerpts, score each excerpt's relevance to the query on a scale of 0-10.
+
+Query: "${query}"
+
+Excerpts:
+${formattedExcerpts}
+
+Score each excerpt's relevance to the query. Return a JSON object with a "rankings" array containing objects with "index" (number), "relevance_score" (0-10), and "reasoning" (string).`;
+}
+//# sourceMappingURL=reranker.js.map

package/dist/services/search/reranker.js.map

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

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

@@ -0,0 +1,113 @@
+/**
+ * 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 type Database from 'better-sqlite3';
+export interface CreateAnnotationParams {
+    document_id: string;
+    user_id?: string | null;
+    chunk_id?: string | null;
+    page_number?: number | null;
+    annotation_type: string;
+    content: string;
+    parent_id?: string | null;
+}
+export interface AnnotationRow {
+    id: string;
+    document_id: string;
+    user_id: string | null;
+    chunk_id: string | null;
+    page_number: number | null;
+    annotation_type: string;
+    content: string;
+    status: string;
+    parent_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ListAnnotationsOptions {
+    document_id: string;
+    annotation_type?: string;
+    status?: string;
+    user_id?: string;
+    page_number?: number;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * 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 declare function createAnnotation(conn: Database.Database, params: CreateAnnotationParams): AnnotationRow;
+/**
+ * Get an annotation by ID.
+ *
+ * @param conn - Database connection
+ * @param id - Annotation ID
+ * @returns The annotation row or null if not found
+ */
+export declare function getAnnotation(conn: Database.Database, id: string): AnnotationRow | 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 declare function getAnnotationWithThread(conn: Database.Database, id: string): {
+    annotation: AnnotationRow;
+    replies: AnnotationRow[];
+} | null;
+/**
+ * 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 declare function listAnnotations(conn: Database.Database, opts: ListAnnotationsOptions): {
+    annotations: AnnotationRow[];
+    total: number;
+};
+/**
+ * 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 declare function updateAnnotation(conn: Database.Database, id: string, updates: {
+    content?: string;
+    status?: string;
+}): AnnotationRow;
+/**
+ * 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 declare function deleteAnnotation(conn: Database.Database, id: string): void;
+/**
+ * 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 declare function getAnnotationSummary(conn: Database.Database, documentId: string): Record<string, unknown>;
+//# sourceMappingURL=annotation-operations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-operations.d.ts","sourceRoot":"","sources":["../../../../src/services/storage/database/annotation-operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAO3C,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,sBAAsB,GAAG,aAAa,CA2CvG;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAEvF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,EAAE,EAAE,MAAM,GACT;IAAE,UAAU,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,GAAG,IAAI,CAShE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,IAAI,EAAE,sBAAsB,GAC3B;IAAE,WAAW,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAmCjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,aAAa,CAsBf;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAM1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BzB"}