/**
 * ProvenanceTracker - High-level service for provenance chain management
 *
 * 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, no silent failures
 */
import { DatabaseService } from '../storage/database/index.js';
import { ProvenanceRecord, CreateProvenanceParams } from '../../models/provenance.js';
/** Error codes for provenance operations */
export declare const ProvenanceErrorCode: {
    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 ProvenanceErrorCodeType = (typeof ProvenanceErrorCode)[keyof typeof ProvenanceErrorCode];
/**
 * ProvenanceError - Typed error for provenance operations
 * FAIL FAST: Always throw with detailed error information
 */
export declare class ProvenanceError extends Error {
    readonly code: ProvenanceErrorCodeType;
    readonly details?: Record<string, unknown> | undefined;
    constructor(message: string, code: ProvenanceErrorCodeType, details?: Record<string, unknown> | undefined);
}
/** Result of getProvenanceChain */
interface ProvenanceChainResult {
    /** The record we started from */
    current: ProvenanceRecord;
    /** Ancestors ordered: immediate parent first, root last */
    ancestors: ProvenanceRecord[];
    /** The root DOCUMENT record */
    root: ProvenanceRecord;
    /** Chain depth of current record */
    depth: number;
    /** Human-readable chain path */
    chainPath: string[];
    /** Whether chain has expected number of records */
    isComplete: boolean;
}
/**
 * ProvenanceTracker - High-level provenance chain management
 *
 * Provides clean API for:
 * 1. Creating provenance records with automatic parent_ids chain building
 * 2. Traversing provenance chains from any item to root document
 * 3. Querying provenance by type, root document, or ID
 */
export declare class ProvenanceTracker {
    private readonly db;
    constructor(db: DatabaseService);
    /**
     * Create provenance record with automatic parent_ids chain building
     *
     * For DOCUMENT type: parent_ids=[], chain_depth=0, root_document_id=self
     * For OCR_RESULT type: parent_ids=[docId], chain_depth=1
     * For CHUNK type: parent_ids=[docId, ocrId], chain_depth=2
     * For EMBEDDING type: parent_ids=[docId, ocrId, chunkId], chain_depth=3
     *
     * @param params - Creation parameters
     * @returns Created provenance record ID
     * @throws ProvenanceError if parent not found or params invalid
     */
    createProvenance(params: CreateProvenanceParams): string;
    /**
     * Get provenance record by ID
     * @throws ProvenanceError if not found
     */
    getProvenanceById(id: string): ProvenanceRecord;
    /**
     * Get provenance record by ID, returns null if not found
     */
    getProvenanceByIdOrNull(id: string): ProvenanceRecord | null;
    /**
     * Get complete provenance chain from item to root
     *
     * Returns ProvenanceChainResult with:
     * - current: the starting record
     * - ancestors: all ancestors from immediate parent to root
     * - root: the DOCUMENT type root record
     * - isComplete: whether chain has expected depth
     *
     * @throws ProvenanceError if record not found
     */
    getProvenanceChain(id: string): ProvenanceChainResult;
    /**
     * Get root document provenance for any item
     *
     * @param provenanceId - Any provenance record ID in the chain
     * @returns The root DOCUMENT type record
     * @throws ProvenanceError if not found or root is not DOCUMENT type
     */
    getRootDocument(provenanceId: string): ProvenanceRecord;
    /**
     * Get all provenance records for a root document
     * Returns records ordered by chain_depth (DOCUMENT first, then OCR_RESULT, etc.)
     */
    getProvenanceByRootDocument(rootDocumentId: string): ProvenanceRecord[];
    /**
     * Get child provenance records for a parent
     */
    getProvenanceChildren(parentId: string): ProvenanceRecord[];
    /**
     * Build parent_ids array from source_id
     * Returns array of ALL ancestor IDs ordered from oldest to most recent
     * Example: For EMBEDDING, returns [docId, ocrId, chunkId]
     *
     * @param sourceId - Immediate parent provenance ID (null for DOCUMENT)
     * @returns Array of all ancestor IDs
     * @throws ProvenanceError if parent not found (CHAIN_BROKEN)
     */
    private buildParentIds;
    /**
     * Build chain_path array based on type
     * Returns human-readable path from root to current type
     *
     * Note: For EMBEDDING, the chain_path depends on the parent type.
     * This method returns the default CHUNK->EMBEDDING path.
     * For VLM_DESCRIPTION->EMBEDDING, the chain_path is built dynamically from parent.
     */
    private buildChainPath;
}
/**
 * Get or create ProvenanceTracker singleton
 * @param db - DatabaseService instance
 */
export declare function getProvenanceTracker(db: DatabaseService): ProvenanceTracker;
/**
 * Reset singleton for testing
 */
export declare function resetProvenanceTracker(): void;
export {};
//# sourceMappingURL=tracker.d.ts.map