/**
 * Operation Checkpoint Manager
 *
 * Manages checkpointing of expensive operations (API calls, LLM calls, etc.)
 * to enable recovery from failures without re-executing completed operations.
 */
import type { CacheProvider } from '@mondaydotcomorg/atp-protocol';
import { type ProvenanceExtractor, type ProvenanceAttacher } from '@mondaydotcomorg/atp-provenance';
import type { Checkpoint, OperationMetadata, CheckpointInfo, CheckpointConfig } from './checkpoint-types';
/**
 * Function type for extracting provenance from a value
 * This is injected at runtime to decouple from @mondaydotcomorg/atp-provenance
 * Re-exported from provenance package for convenience
 */
export type { ProvenanceExtractor };
/**
 * Function type for re-attaching provenance to a restored value
 * This is injected at runtime to decouple from @mondaydotcomorg/atp-provenance
 * Re-exported from provenance package for convenience
 */
export type { ProvenanceAttacher };
/**
 * Function type for attaching __prov_meta__ to objects before checkpoint buffering
 * This ensures provenance survives isolated-vm boundary crossing during restoration
 */
export type ProvenanceMetaAttacher = (value: unknown) => void;
/**
 * Manages operation-level checkpoints for an execution
 */
export declare class OperationCheckpointManager {
    private cache;
    readonly executionId: string;
    private strategy;
    private config;
    private checkpoints;
    private prefix;
    /**
     * Optional provenance extractor - injected at runtime
     * If not set, checkpoints will not capture provenance
     */
    private provenanceExtractor?;
    /**
     * Optional provenance attacher - injected at runtime
     * If not set, restored values will not have provenance re-attached
     */
    private provenanceAttacher?;
    /**
     * Optional function to attach __prov_meta__ before buffering
     * This ensures provenance survives isolated-vm boundary crossing
     */
    private provenanceMetaAttacher?;
    constructor(executionId: string, cache: CacheProvider, config?: CheckpointConfig);
    /**
     * Set the provenance extractor function
     * Should be called during initialization if provenance tracking is enabled
     */
    setProvenanceExtractor(extractor: ProvenanceExtractor): void;
    /**
     * Set the provenance attacher function
     * Should be called during initialization if provenance tracking is enabled
     */
    setProvenanceAttacher(attacher: ProvenanceAttacher): void;
    /**
     * Set the provenance meta attacher function
     */
    setProvenanceMetaAttacher(attacher: ProvenanceMetaAttacher): void;
    /**
     * Extract provenance from a result value
     * Recursively extracts provenance from nested objects/arrays (for Promise.all, loops, etc.)
     * Returns undefined if no provenance extractor is configured
     * Delegates to provenance package's extractProvenanceRecursive
     */
    private extractProvenance;
    /**
     * Create a checkpoint for an operation result (synchronous)
     * Note: For reference checkpoints, the full result is stored in _pendingResult
     * and persisted later via persistAll()
     *
     * SECURITY: Captures provenance and forces reference checkpoint for restricted data
     */
    private createCheckpoint;
    /**
     * Create a full snapshot checkpoint
     * Note: This is only called for public data (restricted data uses reference)
     */
    private createFullSnapshot;
    /**
     * Create a reference checkpoint
     * Stores full result in checkpoint, but only shows preview to LLM in error responses
     */
    private createReference;
    /**
     * Save a checkpoint to cache (immediate persist)
     * Note: For normal operation, use bufferResult() + persistAll() pattern instead
     */
    save(checkpoint: Checkpoint): Promise<void>;
    /**
     * Buffer a result in memory (does NOT persist to cache)
     * Use persistAll() to flush buffered checkpoints on error
     * This is the preferred method for transformed code
     * Note: This is synchronous - no await needed in generated code
     */
    bufferResult(checkpointId: string, result: unknown, metadata: OperationMetadata): void;
    /**
     * Persist all buffered checkpoints to cache
     * Called when an error occurs to save checkpoints for recovery
     */
    persistAll(): Promise<void>;
    /**
     * Load a checkpoint from cache
     */
    load(checkpointId: string): Promise<Checkpoint | null>;
    /**
     * Load a checkpoint from a different execution (for cross-execution recovery)
     */
    loadFromExecution(checkpointId: string, executionId: string): Promise<Checkpoint | null>;
    /**
     * Restore the result from a checkpoint
     * Both full snapshot and reference checkpoints store the result directly\
     * Provenance is re-attached if available
     */
    restore(checkpoint: Checkpoint): unknown;
    /**
     * Check if a checkpoint has restricted provenance
     * Delegates to the provenance package's hasRestrictedProvenance utility
     */
    hasRestrictedProvenance(checkpoint: Checkpoint): boolean;
    /**
     * Get all checkpoints created during this execution
     */
    getAllCheckpoints(): CheckpointInfo[];
    /**
     * Convert checkpoint to info format for error responses
     * Returns full checkpoint ID that includes execution ID for easy restore
     */
    private checkpointToInfo;
    /**
     * Get the full checkpoint ID including execution ID
     * Format: {executionId}:{shortId}
     */
    getFullCheckpointId(shortId: string): string;
    /**
     * Parse a full checkpoint ID to extract execution ID and short ID
     * Returns null if the ID doesn't contain an execution ID
     */
    static parseCheckpointId(fullId: string): {
        executionId: string;
        shortId: string;
    } | null;
    /**
     * Format operation metadata as a dot-notation string
     * For aggregate operations (loops, Promise.all), shows the underlying APIs used
     */
    private formatOperation;
    /**
     * Generate restore instructions for LLM
     * Provides a clean summary of available checkpoints with code snippets showing how to restore them
     * Clarifies when to use full snapshot data inline vs when to use __restore.checkpoint()
     */
    generateRestoreInstructions(): string;
    /**
     * Get statistics about checkpoints
     */
    getStats(): {
        total: number;
        fullSnapshots: number;
        references: number;
        totalSizeBytes: number;
    };
    /**
     * Generate cache key for a checkpoint
     */
    private getCheckpointKey;
}
/**
 * Set the current execution ID for checkpoint operations
 */
export declare function setCheckpointExecutionId(executionId: string): void;
/**
 * Clear the current execution ID
 */
export declare function clearCheckpointExecutionId(): void;
/**
 * Set the checkpoint manager for a specific execution
 */
export declare function setOperationCheckpointManager(manager: OperationCheckpointManager): void;
/**
 * Get the checkpoint manager for the current or specified execution
 */
export declare function getOperationCheckpointManager(executionId?: string): OperationCheckpointManager;
/**
 * Clear the checkpoint manager after execution completes
 */
export declare function clearOperationCheckpointManager(executionId?: string): void;
/**
 * Check if checkpoint manager is initialized for current or specified execution
 */
export declare function hasOperationCheckpointManager(executionId?: string): boolean;
//# sourceMappingURL=operation-checkpoint-manager.d.ts.map