ocr-provenance-mcp 1.0.0

package/dist/services/provenance/chain-hash.js.map

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

package/dist/services/provenance/exporter.d.ts

@@ -0,0 +1,202 @@
+/**
+ * ProvenanceExporter - Export provenance records in JSON, W3C PROV-JSON, and CSV
+ *
+ * Constitution Compliance:
+ * - CP-001: Complete provenance chain for every data item
+ * - CP-003: SHA-256 content hashing
+ * - CP-005: Full reproducibility via processing params
+ *
+ * FAIL FAST: All errors throw immediately with detailed error info
+ * NO MOCKS: Tests use real DatabaseService
+ */
+import { DatabaseService } from '../storage/database/index.js';
+import { ProvenanceTracker } from './tracker.js';
+import { ProvenanceRecord } from '../../models/provenance.js';
+export type ExportScope = 'document' | 'database' | 'all';
+export type ExportFormat = 'json' | 'w3c-prov' | 'csv';
+/**
+ * W3C PROV-JSON Document structure
+ * Reference: https://www.w3.org/submissions/prov-json/
+ */
+interface PROVDocument {
+    prefix: Record<string, string>;
+    entity: Record<string, Record<string, unknown>>;
+    activity: Record<string, Record<string, unknown>>;
+    agent: Record<string, Record<string, unknown>>;
+    wasDerivedFrom: Record<string, Record<string, unknown>>;
+    wasGeneratedBy: Record<string, Record<string, unknown>>;
+    wasAttributedTo: Record<string, Record<string, unknown>>;
+}
+/** Result of JSON export */
+interface JSONExportResult {
+    format: 'json';
+    scope: ExportScope;
+    document_id?: string;
+    exported_at: string;
+    record_count: number;
+    records: ProvenanceRecord[];
+}
+/** Result of W3C PROV-JSON export */
+interface W3CPROVExportResult {
+    format: 'w3c-prov';
+    scope: ExportScope;
+    document_id?: string;
+    exported_at: string;
+    entity_count: number;
+    activity_count: number;
+    agent_count: number;
+    prov_document: PROVDocument;
+}
+/** Result of CSV export */
+interface CSVExportResult {
+    format: 'csv';
+    scope: ExportScope;
+    document_id?: string;
+    exported_at: string;
+    record_count: number;
+    csv_content: string;
+}
+/** Result of file export */
+interface FileExportResult {
+    success: boolean;
+    format: ExportFormat;
+    output_path: string;
+    bytes_written: number;
+    record_count: number;
+}
+/** Error codes for exporter operations - extends ProvenanceErrorCode */
+export declare const ExporterErrorCode: {
+    readonly INVALID_SCOPE: "INVALID_EXPORT_SCOPE";
+    readonly INVALID_FORMAT: "INVALID_EXPORT_FORMAT";
+    readonly FILE_WRITE_ERROR: "FILE_WRITE_ERROR";
+    readonly DOCUMENT_REQUIRED: "DOCUMENT_ID_REQUIRED_FOR_SCOPE";
+    readonly NOT_FOUND: "PROVENANCE_NOT_FOUND";
+    readonly CHAIN_BROKEN: "PROVENANCE_CHAIN_BROKEN";
+    readonly ROOT_NOT_FOUND: "ROOT_DOCUMENT_NOT_FOUND";
+    readonly INVALID_TYPE: "INVALID_PROVENANCE_TYPE";
+    readonly INVALID_PARAMS: "INVALID_PROVENANCE_PARAMS";
+};
+type ExporterErrorCodeType = (typeof ExporterErrorCode)[keyof typeof ExporterErrorCode];
+/**
+ * ExporterError - Typed error for export operations
+ * FAIL FAST: Always throw with detailed error information
+ */
+export declare class ExporterError extends Error {
+    readonly code: ExporterErrorCodeType;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: ExporterErrorCodeType, details?: Record<string, unknown> | undefined);
+}
+/**
+ * ProvenanceExporter - Export provenance records in multiple formats
+ *
+ * Supports:
+ * - JSON: Internal JSON format with full ProvenanceRecord data
+ * - W3C PROV-JSON: Standard W3C PROV-JSON format for interoperability
+ * - CSV: Tabular format for spreadsheet/analysis tools
+ *
+ * Scopes:
+ * - document: Export all records for a specific root document
+ * - database/all: Export all records in the database
+ */
+export declare class ProvenanceExporter {
+    private readonly tracker;
+    private readonly rawDb;
+    private static readonly PROV_PREFIX;
+    private static readonly OCR_PREFIX;
+    private static readonly OCRP_PREFIX;
+    constructor(db: DatabaseService, tracker: ProvenanceTracker);
+    /**
+     * Export provenance records as internal JSON format
+     *
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns JSONExportResult with full ProvenanceRecord array
+     * @throws ExporterError if scope invalid or documentId missing when required
+     */
+    exportJSON(scope: ExportScope, documentId?: string): Promise<JSONExportResult>;
+    /**
+     * Export provenance records as W3C PROV-JSON format
+     *
+     * Reference: https://www.w3.org/submissions/prov-json/
+     *
+     * Mapping:
+     * - ProvenanceRecord -> prov:Entity
+     * - Processing operation -> prov:Activity (non-DOCUMENT types)
+     * - Processor -> prov:Agent
+     * - source_id relationship -> wasDerivedFrom
+     * - Processing creates record -> wasGeneratedBy
+     * - Processor attribution -> wasAttributedTo
+     *
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns W3CPROVExportResult with PROV-JSON document
+     * @throws ExporterError if scope invalid or documentId missing when required
+     */
+    exportW3CPROV(scope: ExportScope, documentId?: string): Promise<W3CPROVExportResult>;
+    /**
+     * Export provenance records as CSV format
+     *
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns CSVExportResult with CSV content string
+     * @throws ExporterError if scope invalid or documentId missing when required
+     */
+    exportCSV(scope: ExportScope, documentId?: string): Promise<CSVExportResult>;
+    /**
+     * Export provenance records to a file
+     *
+     * Creates parent directories if they don't exist.
+     *
+     * @param outputPath - Absolute path to output file
+     * @param format - 'json', 'w3c-prov', or 'csv'
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns FileExportResult with bytes written and path
+     * @throws ExporterError if format invalid, scope invalid, or write fails
+     */
+    exportToFile(outputPath: string, format: ExportFormat, scope: ExportScope, documentId?: string): Promise<FileExportResult>;
+    /**
+     * Validate scope and documentId
+     * @throws ExporterError if invalid
+     */
+    private validateScope;
+    /**
+     * Get provenance records for the given scope
+     * Note: validateScope() must be called before this to ensure documentId is present when needed
+     */
+    private getRecordsForScope;
+    /**
+     * Get all provenance records from database
+     * Ordered by chain_depth ASC, created_at ASC
+     */
+    private getAllProvenance;
+    /**
+     * Transform provenance records to W3C PROV-JSON format
+     *
+     * Mapping rules:
+     * - Each ProvenanceRecord becomes an entity: ocr:<type>-<id>
+     * - Non-DOCUMENT types create an activity: ocr:activity-<id>
+     * - Unique agents per processor name
+     * - wasDerivedFrom links entities with source_id
+     * - wasGeneratedBy links entities to their activities
+     * - wasAttributedTo links all entities to their processor agents
+     */
+    private transformToPROVJSON;
+    /**
+     * Sanitize processor name for use as agent ID
+     * Only allows alphanumeric and hyphens
+     */
+    private sanitizeAgentId;
+    /**
+     * Transform provenance records to CSV format
+     */
+    private transformToCSV;
+    /**
+     * Escape a value for CSV
+     * - Wrap in quotes if contains comma, quote, or newline
+     * - Escape quotes by doubling them
+     */
+    private escapeCSV;
+}
+export {};
+//# sourceMappingURL=exporter.d.ts.map

package/dist/services/provenance/exporter.d.ts.map

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

package/dist/services/provenance/exporter.js

@@ -0,0 +1,457 @@
+/**
+ * ProvenanceExporter - Export provenance records in JSON, W3C PROV-JSON, and CSV
+ *
+ * Constitution Compliance:
+ * - CP-001: Complete provenance chain for every data item
+ * - CP-003: SHA-256 content hashing
+ * - CP-005: Full reproducibility via processing params
+ *
+ * FAIL FAST: All errors throw immediately with detailed error info
+ * NO MOCKS: Tests use real DatabaseService
+ */
+import { writeFile } from 'fs/promises';
+import { existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { ProvenanceErrorCode } from './tracker.js';
+import { ProvenanceType } from '../../models/provenance.js';
+import { rowToProvenance } from '../storage/database/converters.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// ERROR HANDLING - FAIL FAST
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Error codes for exporter operations - extends ProvenanceErrorCode */
+export const ExporterErrorCode = {
+    ...ProvenanceErrorCode,
+    INVALID_SCOPE: 'INVALID_EXPORT_SCOPE',
+    INVALID_FORMAT: 'INVALID_EXPORT_FORMAT',
+    FILE_WRITE_ERROR: 'FILE_WRITE_ERROR',
+    DOCUMENT_REQUIRED: 'DOCUMENT_ID_REQUIRED_FOR_SCOPE',
+};
+/**
+ * ExporterError - Typed error for export operations
+ * FAIL FAST: Always throw with detailed error information
+ */
+export class ExporterError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ExporterError';
+        Object.setPrototypeOf(this, ExporterError.prototype);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN CLASS
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * ProvenanceExporter - Export provenance records in multiple formats
+ *
+ * Supports:
+ * - JSON: Internal JSON format with full ProvenanceRecord data
+ * - W3C PROV-JSON: Standard W3C PROV-JSON format for interoperability
+ * - CSV: Tabular format for spreadsheet/analysis tools
+ *
+ * Scopes:
+ * - document: Export all records for a specific root document
+ * - database/all: Export all records in the database
+ */
+export class ProvenanceExporter {
+    tracker;
+    rawDb;
+    static PROV_PREFIX = 'http://www.w3.org/ns/prov#';
+    static OCR_PREFIX = 'http://ocr-provenance.local/ns#';
+    static OCRP_PREFIX = 'http://ocr-provenance.local/prov#';
+    constructor(db, tracker) {
+        this.tracker = tracker;
+        this.rawDb = db.getConnection();
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PUBLIC API
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Export provenance records as internal JSON format
+     *
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns JSONExportResult with full ProvenanceRecord array
+     * @throws ExporterError if scope invalid or documentId missing when required
+     */
+    async exportJSON(scope, documentId) {
+        this.validateScope(scope, documentId);
+        const records = this.getRecordsForScope(scope, documentId);
+        return {
+            format: 'json',
+            scope,
+            document_id: documentId,
+            exported_at: new Date().toISOString(),
+            record_count: records.length,
+            records,
+        };
+    }
+    /**
+     * Export provenance records as W3C PROV-JSON format
+     *
+     * Reference: https://www.w3.org/submissions/prov-json/
+     *
+     * Mapping:
+     * - ProvenanceRecord -> prov:Entity
+     * - Processing operation -> prov:Activity (non-DOCUMENT types)
+     * - Processor -> prov:Agent
+     * - source_id relationship -> wasDerivedFrom
+     * - Processing creates record -> wasGeneratedBy
+     * - Processor attribution -> wasAttributedTo
+     *
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns W3CPROVExportResult with PROV-JSON document
+     * @throws ExporterError if scope invalid or documentId missing when required
+     */
+    async exportW3CPROV(scope, documentId) {
+        this.validateScope(scope, documentId);
+        const records = this.getRecordsForScope(scope, documentId);
+        const provDoc = this.transformToPROVJSON(records);
+        return {
+            format: 'w3c-prov',
+            scope,
+            document_id: documentId,
+            exported_at: new Date().toISOString(),
+            entity_count: Object.keys(provDoc.entity).length,
+            activity_count: Object.keys(provDoc.activity).length,
+            agent_count: Object.keys(provDoc.agent).length,
+            prov_document: provDoc,
+        };
+    }
+    /**
+     * Export provenance records as CSV format
+     *
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns CSVExportResult with CSV content string
+     * @throws ExporterError if scope invalid or documentId missing when required
+     */
+    async exportCSV(scope, documentId) {
+        this.validateScope(scope, documentId);
+        const records = this.getRecordsForScope(scope, documentId);
+        const csvContent = this.transformToCSV(records);
+        return {
+            format: 'csv',
+            scope,
+            document_id: documentId,
+            exported_at: new Date().toISOString(),
+            record_count: records.length,
+            csv_content: csvContent,
+        };
+    }
+    /**
+     * Export provenance records to a file
+     *
+     * Creates parent directories if they don't exist.
+     *
+     * @param outputPath - Absolute path to output file
+     * @param format - 'json', 'w3c-prov', or 'csv'
+     * @param scope - 'document' (requires documentId), 'database', or 'all'
+     * @param documentId - Required when scope='document'
+     * @returns FileExportResult with bytes written and path
+     * @throws ExporterError if format invalid, scope invalid, or write fails
+     */
+    async exportToFile(outputPath, format, scope, documentId) {
+        // Get content based on format (export methods validate scope internally)
+        let content;
+        let recordCount;
+        switch (format) {
+            case 'json': {
+                const result = await this.exportJSON(scope, documentId);
+                content = JSON.stringify(result, null, 2);
+                recordCount = result.record_count;
+                break;
+            }
+            case 'w3c-prov': {
+                const result = await this.exportW3CPROV(scope, documentId);
+                content = JSON.stringify(result, null, 2);
+                recordCount = result.entity_count;
+                break;
+            }
+            case 'csv': {
+                const result = await this.exportCSV(scope, documentId);
+                content = result.csv_content;
+                recordCount = result.record_count;
+                break;
+            }
+            default:
+                throw new ExporterError(`Invalid export format: ${format}. Valid formats: json, w3c-prov, csv`, ExporterErrorCode.INVALID_FORMAT, { providedFormat: format, validFormats: ['json', 'w3c-prov', 'csv'] });
+        }
+        // Create parent directories if needed
+        const dir = dirname(outputPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        // Write file
+        try {
+            await writeFile(outputPath, content, 'utf-8');
+        }
+        catch (error) {
+            throw new ExporterError(`Failed to write export file: ${outputPath}`, ExporterErrorCode.FILE_WRITE_ERROR, {
+                outputPath,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+        const bytesWritten = Buffer.byteLength(content, 'utf-8');
+        return {
+            success: true,
+            format,
+            output_path: outputPath,
+            bytes_written: bytesWritten,
+            record_count: recordCount,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PRIVATE HELPERS
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Validate scope and documentId
+     * @throws ExporterError if invalid
+     */
+    validateScope(scope, documentId) {
+        const validScopes = ['document', 'database', 'all'];
+        if (!validScopes.includes(scope)) {
+            throw new ExporterError(`Invalid export scope: ${scope}. Valid scopes: ${validScopes.join(', ')}`, ExporterErrorCode.INVALID_SCOPE, { providedScope: scope, validScopes });
+        }
+        if (scope === 'document' && !documentId) {
+            throw new ExporterError('documentId is required when scope is "document"', ExporterErrorCode.DOCUMENT_REQUIRED, { scope });
+        }
+    }
+    /**
+     * Get provenance records for the given scope
+     * Note: validateScope() must be called before this to ensure documentId is present when needed
+     */
+    getRecordsForScope(scope, documentId) {
+        if (scope === 'document') {
+            return this.tracker.getProvenanceByRootDocument(documentId);
+        }
+        // 'database' and 'all' are equivalent - return all records
+        return this.getAllProvenance();
+    }
+    /**
+     * Get all provenance records from database
+     * Ordered by chain_depth ASC, created_at ASC
+     */
+    getAllProvenance() {
+        // H-5: Use iterate() to avoid double-allocation (.all() + .map())
+        const records = [];
+        const stmt = this.rawDb.prepare('SELECT * FROM provenance ORDER BY chain_depth ASC, created_at ASC');
+        for (const row of stmt.iterate()) {
+            records.push(rowToProvenance(row));
+        }
+        return records;
+    }
+    /**
+     * Transform provenance records to W3C PROV-JSON format
+     *
+     * Mapping rules:
+     * - Each ProvenanceRecord becomes an entity: ocr:<type>-<id>
+     * - Non-DOCUMENT types create an activity: ocr:activity-<id>
+     * - Unique agents per processor name
+     * - wasDerivedFrom links entities with source_id
+     * - wasGeneratedBy links entities to their activities
+     * - wasAttributedTo links all entities to their processor agents
+     */
+    transformToPROVJSON(records) {
+        const doc = {
+            prefix: {
+                prov: ProvenanceExporter.PROV_PREFIX,
+                ocr: ProvenanceExporter.OCR_PREFIX,
+                ocrp: ProvenanceExporter.OCRP_PREFIX,
+            },
+            entity: {},
+            activity: {},
+            agent: {},
+            wasDerivedFrom: {},
+            wasGeneratedBy: {},
+            wasAttributedTo: {},
+        };
+        // M-13: Map-based lookup to avoid O(N^2) find() in wasDerivedFrom
+        const recordById = new Map();
+        for (const record of records) {
+            recordById.set(record.id, record);
+        }
+        // Track unique agents
+        const agents = new Map(); // processor name -> agent ID
+        for (const record of records) {
+            // 1. Create entity
+            const entityId = `ocr:${record.type.toLowerCase()}-${record.id}`;
+            doc.entity[entityId] = {
+                'prov:type': `ocr:${record.type}`,
+                'prov:generatedAtTime': record.created_at,
+                'ocr:content_hash': record.content_hash,
+                'ocr:chain_depth': record.chain_depth,
+                'ocr:root_document_id': record.root_document_id,
+                'ocr:processor': record.processor,
+                'ocr:processor_version': record.processor_version,
+            };
+            // Add location if present
+            if (record.location) {
+                doc.entity[entityId]['ocr:location'] = record.location;
+            }
+            // Add source_path for DOCUMENT type
+            if (record.type === ProvenanceType.DOCUMENT && record.source_path) {
+                doc.entity[entityId]['ocr:source_path'] = record.source_path;
+            }
+            // Add specific attributes for IMAGE type
+            if (record.type === ProvenanceType.IMAGE) {
+                doc.entity[entityId]['prov:type'] = 'ocrp:Image';
+                if (record.location?.bounding_box) {
+                    doc.entity[entityId]['ocrp:bounding_box'] = record.location.bounding_box;
+                }
+                if (record.location?.page_number) {
+                    doc.entity[entityId]['ocrp:page_number'] = record.location.page_number;
+                }
+            }
+            // Add specific attributes for VLM_DESCRIPTION type
+            if (record.type === ProvenanceType.VLM_DESCRIPTION) {
+                doc.entity[entityId]['prov:type'] = 'ocrp:VLMDescription';
+            }
+            // Add file_hash if present
+            if (record.file_hash) {
+                doc.entity[entityId]['ocr:file_hash'] = record.file_hash;
+            }
+            // 2. Create activity for non-DOCUMENT types
+            if (record.type !== ProvenanceType.DOCUMENT) {
+                const activityId = `ocr:activity-${record.id}`;
+                doc.activity[activityId] = {
+                    'prov:type': `ocr:${record.source_type}Activity`,
+                    'prov:startTime': record.created_at,
+                    'prov:endTime': record.processed_at,
+                    'ocr:processor': record.processor,
+                    'ocr:processor_version': record.processor_version,
+                    'ocr:processing_params': record.processing_params,
+                };
+                if (record.processing_duration_ms !== null) {
+                    doc.activity[activityId]['ocr:processing_duration_ms'] = record.processing_duration_ms;
+                }
+                // 3. wasGeneratedBy - link entity to activity
+                const wgbId = `ocr:wgb-${record.id}`;
+                doc.wasGeneratedBy[wgbId] = {
+                    'prov:entity': entityId,
+                    'prov:activity': activityId,
+                    'prov:time': record.processed_at,
+                };
+            }
+            // 4. Create/link agent
+            const sanitizedProcessor = this.sanitizeAgentId(record.processor);
+            const agentId = `ocr:agent-${sanitizedProcessor}`;
+            if (!agents.has(record.processor)) {
+                agents.set(record.processor, agentId);
+                doc.agent[agentId] = {
+                    'prov:type': 'prov:SoftwareAgent',
+                    'ocr:name': record.processor,
+                    'ocr:version': record.processor_version,
+                };
+            }
+            // 5. wasAttributedTo - link entity to agent
+            const watId = `ocr:wat-${record.id}`;
+            doc.wasAttributedTo[watId] = {
+                'prov:entity': entityId,
+                'prov:agent': agents.get(record.processor),
+            };
+            // 6. wasDerivedFrom - link to source entity if present
+            if (record.source_id) {
+                // M-13: Use Map lookup instead of O(N) find()
+                const sourceRecord = recordById.get(record.source_id);
+                if (sourceRecord) {
+                    const sourceEntityId = `ocr:${sourceRecord.type.toLowerCase()}-${sourceRecord.id}`;
+                    const wdfId = `ocr:wdf-${record.id}`;
+                    doc.wasDerivedFrom[wdfId] = {
+                        'prov:generatedEntity': entityId,
+                        'prov:usedEntity': sourceEntityId,
+                    };
+                }
+            }
+        }
+        return doc;
+    }
+    /**
+     * Sanitize processor name for use as agent ID
+     * Only allows alphanumeric and hyphens
+     */
+    sanitizeAgentId(processor) {
+        return processor
+            .toLowerCase()
+            .replace(/[^a-z0-9-]+/g, '-')
+            .replace(/^-|-$/g, '');
+    }
+    /**
+     * Transform provenance records to CSV format
+     */
+    transformToCSV(records) {
+        const headers = [
+            'id',
+            'type',
+            'created_at',
+            'processed_at',
+            'source_type',
+            'source_path',
+            'source_id',
+            'root_document_id',
+            'content_hash',
+            'input_hash',
+            'file_hash',
+            'processor',
+            'processor_version',
+            'processing_params',
+            'processing_duration_ms',
+            'processing_quality_score',
+            'parent_id',
+            'parent_ids',
+            'chain_depth',
+            'chain_path',
+            'location',
+        ];
+        const headerRow = headers.join(',');
+        if (records.length === 0) {
+            return headerRow;
+        }
+        const dataRows = records.map((record) => {
+            const values = [
+                this.escapeCSV(record.id),
+                this.escapeCSV(record.type),
+                this.escapeCSV(record.created_at),
+                this.escapeCSV(record.processed_at),
+                this.escapeCSV(record.source_type),
+                this.escapeCSV(record.source_path ?? ''),
+                this.escapeCSV(record.source_id ?? ''),
+                this.escapeCSV(record.root_document_id),
+                this.escapeCSV(record.content_hash),
+                this.escapeCSV(record.input_hash ?? ''),
+                this.escapeCSV(record.file_hash ?? ''),
+                this.escapeCSV(record.processor),
+                this.escapeCSV(record.processor_version),
+                this.escapeCSV(JSON.stringify(record.processing_params)),
+                record.processing_duration_ms?.toString() ?? '',
+                record.processing_quality_score?.toString() ?? '',
+                this.escapeCSV(record.parent_id ?? ''),
+                this.escapeCSV(record.parent_ids),
+                record.chain_depth.toString(),
+                this.escapeCSV(record.chain_path ?? ''),
+                this.escapeCSV(record.location ? JSON.stringify(record.location) : ''),
+            ];
+            return values.join(',');
+        });
+        return [headerRow, ...dataRows].join('\n');
+    }
+    /**
+     * Escape a value for CSV
+     * - Wrap in quotes if contains comma, quote, or newline
+     * - Escape quotes by doubling them
+     */
+    escapeCSV(value) {
+        if (value.includes(',') ||
+            value.includes('"') ||
+            value.includes('\n') ||
+            value.includes('\r')) {
+            return '"' + value.replace(/"/g, '""') + '"';
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=exporter.js.map