ocr-provenance-mcp 1.0.0

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

@@ -0,0 +1,151 @@
+/**
+ * User and Audit Log Operations for DatabaseService
+ *
+ * Provides CRUD operations for users and audit_log tables.
+ * Users represent identity for multi-user collaboration.
+ * Audit log tracks user actions for compliance and accountability.
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module database/user-operations
+ */
+// ═══════════════════════════════════════════════════════════════════════════════
+// USER CRUD
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Create a new user.
+ * ID is auto-generated by SQLite (lower(hex(randomblob(16)))).
+ *
+ * @returns The created user record
+ * @throws Error if external_id already exists (UNIQUE constraint)
+ */
+export function createUser(db, params) {
+    const now = new Date().toISOString();
+    try {
+        const stmt = db.prepare(`
+      INSERT INTO users (display_name, external_id, email, role, metadata_json, last_active_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+        const result = stmt.run(params.display_name, params.external_id ?? null, params.email ?? null, params.role ?? 'viewer', params.metadata_json ?? '{}', now);
+        // Retrieve the just-inserted user by rowid (safe under concurrent inserts)
+        const user = db
+            .prepare('SELECT * FROM users WHERE rowid = ?')
+            .get(result.lastInsertRowid);
+        if (!user) {
+            throw new Error('Failed to retrieve created user');
+        }
+        return user;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('UNIQUE constraint failed')) {
+            throw new Error(`User with external_id "${params.external_id}" already exists`);
+        }
+        throw error;
+    }
+}
+/**
+ * Get a user by internal ID
+ */
+export function getUser(db, userId) {
+    const row = db.prepare('SELECT * FROM users WHERE id = ?').get(userId);
+    return row ?? null;
+}
+/**
+ * Get a user by external ID
+ */
+export function getUserByExternalId(db, externalId) {
+    const row = db
+        .prepare('SELECT * FROM users WHERE external_id = ?')
+        .get(externalId);
+    return row ?? null;
+}
+/**
+ * Update the last_active_at timestamp for a user
+ */
+export function updateUserActivity(db, userId) {
+    const now = new Date().toISOString();
+    db.prepare('UPDATE users SET last_active_at = ? WHERE id = ?').run(now, userId);
+}
+/**
+ * List users with optional filters
+ */
+export function listUsers(db, options) {
+    const conditions = [];
+    const params = [];
+    if (options?.role) {
+        conditions.push('role = ?');
+        params.push(options.role);
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limit = options?.limit ?? 100;
+    const offset = options?.offset ?? 0;
+    params.push(limit, offset);
+    return db
+        .prepare(`SELECT * FROM users ${whereClause} ORDER BY created_at DESC LIMIT ? OFFSET ?`)
+        .all(...params);
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// AUDIT LOG
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Insert an entry into the audit log
+ */
+export function insertAuditLog(db, params) {
+    const result = db
+        .prepare(`INSERT INTO audit_log (user_id, session_id, action, entity_type, entity_id, details_json, ip_address)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(params.user_id, params.session_id, params.action, params.entity_type ?? null, params.entity_id ?? null, params.details_json ?? '{}', params.ip_address ?? null);
+    return Number(result.lastInsertRowid);
+}
+/**
+ * Query audit log with filters
+ *
+ * @returns Array of matching audit log entries, ordered by created_at DESC
+ */
+export function queryAuditLog(db, filters) {
+    const conditions = [];
+    const params = [];
+    if (filters.user_id) {
+        conditions.push('a.user_id = ?');
+        params.push(filters.user_id);
+    }
+    if (filters.action) {
+        conditions.push('a.action = ?');
+        params.push(filters.action);
+    }
+    if (filters.entity_type) {
+        conditions.push('a.entity_type = ?');
+        params.push(filters.entity_type);
+    }
+    if (filters.entity_id) {
+        conditions.push('a.entity_id = ?');
+        params.push(filters.entity_id);
+    }
+    if (filters.date_from) {
+        conditions.push('a.created_at >= ?');
+        params.push(filters.date_from);
+    }
+    if (filters.date_to) {
+        conditions.push('a.created_at <= ?');
+        params.push(filters.date_to);
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    // Get total count
+    const countRow = db
+        .prepare(`SELECT COUNT(*) as cnt FROM audit_log a ${whereClause}`)
+        .get(...params);
+    const total = countRow.cnt;
+    // Get paginated results with user display_name joined
+    const limit = filters.limit ?? 50;
+    const offset = filters.offset ?? 0;
+    const entries = db
+        .prepare(`SELECT a.*, u.display_name as user_display_name
+       FROM audit_log a
+       LEFT JOIN users u ON a.user_id = u.id
+       ${whereClause}
+       ORDER BY a.created_at DESC
+       LIMIT ? OFFSET ?`)
+        .all(...params, limit, offset);
+    return { entries, total };
+}
+//# sourceMappingURL=user-operations.js.map

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

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

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

@@ -0,0 +1,98 @@
+/**
+ * Workflow State Database Operations
+ *
+ * Provides operations for the workflow state machine that tracks document
+ * lifecycle states. Enforces valid state transitions to prevent invalid
+ * workflow progression.
+ *
+ * State machine:
+ *   '' -> draft -> submitted -> in_review -> approved -> executed -> archived
+ *                                         \-> changes_requested -> submitted
+ *                                         \-> rejected -> archived
+ *                             approved -> expired (auto, past due_date)
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module database/workflow-operations
+ */
+import type Database from 'better-sqlite3';
+export interface WorkflowStateRow {
+    id: string;
+    document_id: string;
+    state: string;
+    assigned_to: string | null;
+    assigned_by: string | null;
+    reason: string | null;
+    due_date: string | null;
+    completed_at: string | null;
+    created_at: string;
+    metadata_json: string | null;
+}
+export interface CreateWorkflowStateParams {
+    document_id: string;
+    state: string;
+    assigned_to?: string | null;
+    assigned_by?: string | null;
+    reason?: string | null;
+    due_date?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface WorkflowQueueFilters {
+    assigned_to?: string;
+    state?: string;
+    due_before?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Map of current state -> allowed next states.
+ * Empty string key represents "no existing state" (initial transition).
+ */
+export declare const VALID_TRANSITIONS: Record<string, string[]>;
+/**
+ * Get the most recent workflow state for a document.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @returns Latest workflow state row or null if no workflow history
+ */
+export declare function getLatestWorkflowState(conn: Database.Database, documentId: string): WorkflowStateRow | null;
+/**
+ * Create a new workflow state for a document.
+ *
+ * Enforces valid state transitions. If the document has no prior workflow
+ * state, only 'draft' is allowed. Otherwise the new state must be in the
+ * VALID_TRANSITIONS map for the current state.
+ *
+ * @param conn - Database connection
+ * @param params - Workflow state creation parameters
+ * @returns The created workflow state row
+ * @throws Error if document not found or transition is invalid
+ */
+export declare function createWorkflowState(conn: Database.Database, params: CreateWorkflowStateParams): WorkflowStateRow;
+/**
+ * List documents pending review with optional filters.
+ *
+ * Finds the latest workflow state per document and filters by the given
+ * criteria. Useful for building reviewer queues.
+ *
+ * @param conn - Database connection
+ * @param filters - Optional query filters
+ * @returns Paginated workflow states and total count
+ */
+export declare function listWorkflowQueue(conn: Database.Database, filters: WorkflowQueueFilters): {
+    items: WorkflowStateRow[];
+    total: number;
+};
+/**
+ * Get the full workflow history for a document.
+ *
+ * Returns all workflow state rows ordered by creation time (oldest first),
+ * showing the complete state progression.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @returns Array of workflow state rows
+ */
+export declare function getWorkflowHistory(conn: Database.Database, documentId: string): WorkflowStateRow[];
+//# sourceMappingURL=workflow-operations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-operations.d.ts","sourceRoot":"","sources":["../../../../src/services/storage/database/workflow-operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAO3C,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAStD,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,UAAU,EAAE,MAAM,GACjB,gBAAgB,GAAG,IAAI,CAIzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,MAAM,EAAE,yBAAyB,GAChC,gBAAgB,CA0ClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,OAAO,EAAE,oBAAoB,GAC5B;IAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAsD9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EACvB,UAAU,EAAE,MAAM,GACjB,gBAAgB,EAAE,CAIpB"}

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

@@ -0,0 +1,157 @@
+/**
+ * Workflow State Database Operations
+ *
+ * Provides operations for the workflow state machine that tracks document
+ * lifecycle states. Enforces valid state transitions to prevent invalid
+ * workflow progression.
+ *
+ * State machine:
+ *   '' -> draft -> submitted -> in_review -> approved -> executed -> archived
+ *                                         \-> changes_requested -> submitted
+ *                                         \-> rejected -> archived
+ *                             approved -> expired (auto, past due_date)
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module database/workflow-operations
+ */
+import { v4 as uuidv4 } from 'uuid';
+// =============================================================================
+// VALID STATE TRANSITIONS
+// =============================================================================
+/**
+ * Map of current state -> allowed next states.
+ * Empty string key represents "no existing state" (initial transition).
+ */
+export const VALID_TRANSITIONS = {
+    '': ['draft'],
+    'draft': ['submitted'],
+    'submitted': ['in_review'],
+    'in_review': ['approved', 'rejected', 'changes_requested'],
+    'changes_requested': ['submitted'],
+    'approved': ['executed', 'expired', 'archived'],
+    'rejected': ['archived'],
+    'executed': ['archived'],
+};
+// =============================================================================
+// WORKFLOW STATE OPERATIONS
+// =============================================================================
+/**
+ * Get the most recent workflow state for a document.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @returns Latest workflow state row or null if no workflow history
+ */
+export function getLatestWorkflowState(conn, documentId) {
+    return conn.prepare('SELECT * FROM workflow_states WHERE document_id = ? ORDER BY created_at DESC, rowid DESC LIMIT 1').get(documentId) ?? null;
+}
+/**
+ * Create a new workflow state for a document.
+ *
+ * Enforces valid state transitions. If the document has no prior workflow
+ * state, only 'draft' is allowed. Otherwise the new state must be in the
+ * VALID_TRANSITIONS map for the current state.
+ *
+ * @param conn - Database connection
+ * @param params - Workflow state creation parameters
+ * @returns The created workflow state row
+ * @throws Error if document not found or transition is invalid
+ */
+export function createWorkflowState(conn, params) {
+    // 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}`);
+    }
+    // Get current state to validate transition
+    const current = getLatestWorkflowState(conn, params.document_id);
+    const currentState = current?.state ?? '';
+    const allowed = VALID_TRANSITIONS[currentState];
+    if (!allowed || !allowed.includes(params.state)) {
+        const currentDisplay = currentState || '(none)';
+        const allowedDisplay = allowed ? allowed.join(', ') : '(none)';
+        throw new Error(`Invalid workflow transition: cannot move from "${currentDisplay}" to "${params.state}". ` +
+            `Allowed transitions from "${currentDisplay}": [${allowedDisplay}]`);
+    }
+    const id = uuidv4();
+    const now = new Date().toISOString();
+    const metadataJson = params.metadata ? JSON.stringify(params.metadata) : null;
+    conn.prepare(`
+    INSERT INTO workflow_states (id, document_id, state, assigned_to, assigned_by, reason, due_date, completed_at, created_at, metadata_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(id, params.document_id, params.state, params.assigned_to ?? null, params.assigned_by ?? null, params.reason ?? null, params.due_date ?? null, null, // completed_at set when reaching terminal states
+    now, metadataJson);
+    return conn.prepare('SELECT * FROM workflow_states WHERE id = ?').get(id);
+}
+/**
+ * List documents pending review with optional filters.
+ *
+ * Finds the latest workflow state per document and filters by the given
+ * criteria. Useful for building reviewer queues.
+ *
+ * @param conn - Database connection
+ * @param filters - Optional query filters
+ * @returns Paginated workflow states and total count
+ */
+export function listWorkflowQueue(conn, filters) {
+    // Use a CTE to get the latest state per document
+    const conditions = [];
+    const params = [];
+    if (filters.state) {
+        conditions.push('ws.state = ?');
+        params.push(filters.state);
+    }
+    if (filters.assigned_to) {
+        conditions.push('ws.assigned_to = ?');
+        params.push(filters.assigned_to);
+    }
+    if (filters.due_before) {
+        conditions.push('ws.due_date IS NOT NULL AND ws.due_date <= ?');
+        params.push(filters.due_before);
+    }
+    const whereClause = conditions.length > 0
+        ? `WHERE ${conditions.join(' AND ')}`
+        : '';
+    const limit = Math.min(filters.limit ?? 50, 200);
+    const offset = filters.offset ?? 0;
+    // Get latest state per document using MAX(rowid) which is strictly monotonic
+    // (avoids duplicates when multiple states share the same created_at timestamp)
+    const countSql = `
+    SELECT COUNT(*) as c FROM (
+      SELECT ws.* FROM workflow_states ws
+      INNER JOIN (
+        SELECT MAX(rowid) as max_rowid
+        FROM workflow_states GROUP BY document_id
+      ) latest ON ws.rowid = latest.max_rowid
+      ${whereClause}
+    )
+  `;
+    const totalRow = conn.prepare(countSql).get(...params);
+    const dataSql = `
+    SELECT ws.* FROM workflow_states ws
+    INNER JOIN (
+      SELECT MAX(rowid) as max_rowid
+      FROM workflow_states GROUP BY document_id
+    ) latest ON ws.rowid = latest.max_rowid
+    ${whereClause}
+    ORDER BY ws.due_date ASC NULLS LAST, ws.created_at DESC
+    LIMIT ? OFFSET ?
+  `;
+    const items = conn.prepare(dataSql).all(...params, limit, offset);
+    return { items, total: totalRow.c };
+}
+/**
+ * Get the full workflow history for a document.
+ *
+ * Returns all workflow state rows ordered by creation time (oldest first),
+ * showing the complete state progression.
+ *
+ * @param conn - Database connection
+ * @param documentId - Document ID
+ * @returns Array of workflow state rows
+ */
+export function getWorkflowHistory(conn, documentId) {
+    return conn.prepare('SELECT * FROM workflow_states WHERE document_id = ? ORDER BY created_at ASC').all(documentId);
+}
+//# sourceMappingURL=workflow-operations.js.map

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

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

package/dist/services/storage/database.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DatabaseService for OCR Provenance MCP System
+ *
+ * This file serves as a facade for backwards compatibility.
+ * All implementations have been modularized into src/services/storage/database/
+ *
+ * Provides all database operations for documents, OCR results, chunks,
+ * embeddings, and provenance records.
+ *
+ * Security: All SQL uses parameterized queries via db.prepare() (SEC-006)
+ * Performance: WAL mode, proper indexes, foreign key constraints
+ * Permissions: Database files created with mode 0o600 (SEC-003)
+ */
+export type { DatabaseInfo, DatabaseStats, ListDocumentsOptions } from './database/index.js';
+export { DatabaseErrorCode, DatabaseError, MigrationError, DatabaseService, } from './database/index.js';
+//# sourceMappingURL=database.d.ts.map

package/dist/services/storage/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/services/storage/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,qBAAqB,CAAC"}

package/dist/services/storage/database.js

@@ -0,0 +1,15 @@
+/**
+ * DatabaseService for OCR Provenance MCP System
+ *
+ * This file serves as a facade for backwards compatibility.
+ * All implementations have been modularized into src/services/storage/database/
+ *
+ * Provides all database operations for documents, OCR results, chunks,
+ * embeddings, and provenance records.
+ *
+ * Security: All SQL uses parameterized queries via db.prepare() (SEC-006)
+ * Performance: WAL mode, proper indexes, foreign key constraints
+ * Permissions: Database files created with mode 0o600 (SEC-003)
+ */
+export { DatabaseErrorCode, DatabaseError, MigrationError, DatabaseService, } from './database/index.js';
+//# sourceMappingURL=database.js.map

package/dist/services/storage/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../../src/services/storage/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,qBAAqB,CAAC"}

package/dist/services/storage/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Storage Service Module
+ *
+ * Provides database initialization, migrations, and storage operations
+ * for the OCR Provenance MCP System.
+ */
+export { initializeDatabase, checkSchemaVersion, migrateToLatest, getCurrentSchemaVersion, verifySchema, MigrationError, } from './migrations.js';
+export { DatabaseService, DatabaseError, DatabaseErrorCode, type DatabaseInfo, type DatabaseStats, type ListDocumentsOptions, } from './database.js';
+export { VectorService, VectorError, type VectorSearchResult, type VectorSearchOptions, } from './vector.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,YAAY,EACZ,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC"}

package/dist/services/storage/index.js

@@ -0,0 +1,10 @@
+/**
+ * Storage Service Module
+ *
+ * Provides database initialization, migrations, and storage operations
+ * for the OCR Provenance MCP System.
+ */
+export { initializeDatabase, checkSchemaVersion, migrateToLatest, getCurrentSchemaVersion, verifySchema, MigrationError, } from './migrations.js';
+export { DatabaseService, DatabaseError, DatabaseErrorCode, } from './database.js';
+export { VectorService, VectorError, } from './vector.js';
+//# sourceMappingURL=index.js.map

package/dist/services/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,YAAY,EACZ,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,eAAe,EACf,aAAa,EACb,iBAAiB,GAIlB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,WAAW,GAGZ,MAAM,aAAa,CAAC"}

package/dist/services/storage/migrations/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Database Schema Migrations for OCR Provenance MCP System
+ *
+ * This module handles SQLite schema initialization and migrations.
+ * Uses better-sqlite3 with sqlite-vec extension for vector storage.
+ *
+ * Security: All SQL uses parameterized queries via db.prepare()
+ * Performance: WAL mode, proper indexes, foreign key constraints
+ *
+ * @module migrations
+ */
+export { MigrationError } from './types.js';
+export { initializeDatabase, migrateToLatest, checkSchemaVersion, getCurrentSchemaVersion, } from './operations.js';
+export { configurePragmas } from './schema-helpers.js';
+export { verifySchema } from './verification.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/storage/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/storage/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/services/storage/migrations/index.js

@@ -0,0 +1,20 @@
+/**
+ * Database Schema Migrations for OCR Provenance MCP System
+ *
+ * This module handles SQLite schema initialization and migrations.
+ * Uses better-sqlite3 with sqlite-vec extension for vector storage.
+ *
+ * Security: All SQL uses parameterized queries via db.prepare()
+ * Performance: WAL mode, proper indexes, foreign key constraints
+ *
+ * @module migrations
+ */
+// Re-export types
+export { MigrationError } from './types.js';
+// Re-export main operations
+export { initializeDatabase, migrateToLatest, checkSchemaVersion, getCurrentSchemaVersion, } from './operations.js';
+// Re-export schema helpers needed by static-operations
+export { configurePragmas } from './schema-helpers.js';
+// Re-export verification
+export { verifySchema } from './verification.js';
+//# sourceMappingURL=index.js.map

package/dist/services/storage/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/services/storage/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,4BAA4B;AAC5B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,uDAAuD;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,yBAAyB;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/services/storage/migrations/operations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Database Migration Operations
+ *
+ * Contains the main migration functions: initializeDatabase, migrateToLatest,
+ * checkSchemaVersion, and getCurrentSchemaVersion.
+ *
+ * @module migrations/operations
+ */
+import type Database from 'better-sqlite3';
+/**
+ * Check the current schema version of the database
+ * @param db - Database instance
+ * @returns Current schema version, or 0 if not initialized
+ */
+export declare function checkSchemaVersion(db: Database.Database): number;
+/**
+ * Get the current schema version constant
+ * @returns The current schema version number
+ */
+export declare function getCurrentSchemaVersion(): number;
+/**
+ * Initialize the database with all tables, indexes, and configuration
+ *
+ * This function is idempotent - safe to call multiple times.
+ * Creates tables only if they don't exist.
+ *
+ * @param db - Database instance from better-sqlite3
+ * @throws MigrationError if any operation fails
+ */
+export declare function initializeDatabase(db: Database.Database): void;
+/**
+ * Migrate database to the latest schema version
+ *
+ * Checks current version and applies any necessary migrations.
+ *
+ * @param db - Database instance from better-sqlite3
+ * @throws MigrationError if migration fails
+ */
+export declare function migrateToLatest(db: Database.Database): void;
+//# sourceMappingURL=operations.d.ts.map

package/dist/services/storage/migrations/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../../src/services/storage/migrations/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAsP3C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAwBhE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAgC9D;AAizBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAsM3D"}