/**
 * Checkpoint Types for Operation-Level Checkpointing
 *
 * This module defines the types for checkpointing expensive operations
 * (API calls, LLM calls, etc.) to enable recovery from failures without
 * re-executing already completed operations.
 */
import type { CheckpointProvenanceSnapshot, ProvenanceExtractor, ProvenanceAttacher } from '@mondaydotcomorg/atp-provenance';
export type { CheckpointProvenanceSnapshot, ProvenanceExtractor, ProvenanceAttacher, };
export type { ProvenanceMetadata as CheckpointProvenanceMetadata } from '@mondaydotcomorg/atp-provenance';
export { ProvenanceSource as CheckpointProvenanceSource } from '@mondaydotcomorg/atp-provenance';
export type { ReaderPermissions as CheckpointReaderPermissions } from '@mondaydotcomorg/atp-provenance';
/**
 * Type of checkpoint storage strategy
 */
export declare enum CheckpointType {
    /** Store the complete result value */
    FULL_SNAPSHOT = "full_snapshot",
    /** Store a reference/summary with full value in cache */
    REFERENCE = "reference"
}
/**
 * Type of operation being checkpointed
 */
export declare enum OperationType {
    API = "api",
    LLM = "llm",
    EMBEDDING = "embedding",
    CLIENT_TOOL = "client_tool",
    APPROVAL = "approval"
}
/**
 * Metadata about the operation being checkpointed
 */
export interface OperationMetadata {
    /** Type of operation */
    type: OperationType;
    /** Top-level namespace (e.g., 'atp') */
    namespace: string;
    /** API group (e.g., 'github', 'database') */
    group?: string;
    /** Method/function name (e.g., 'getUser', 'call') */
    method: string;
    /** Parameters passed to the operation */
    params: Record<string, unknown>;
    /** Original code expression that triggered this checkpoint */
    sourceExpression?: string;
    /** Variable names used to store the result (e.g., ['result'], ['myUser', 'galTestUser']) */
    usedVariables?: string[];
}
/**
 * Base checkpoint interface
 */
export interface BaseCheckpoint {
    /** Unique checkpoint identifier within execution */
    id: string;
    /** Execution ID this checkpoint belongs to */
    executionId: string;
    /** Type of checkpoint storage */
    type: CheckpointType;
    /** Metadata about the operation */
    operation: OperationMetadata;
    /** When checkpoint was created */
    timestamp: number;
    /** Time-to-live in seconds (optional) */
    ttl?: number;
    /**
     * Provenance snapshot for security policy enforcement
     * If present, provenance will be re-attached on restore
     */
    provenance?: CheckpointProvenanceSnapshot;
}
/**
 * Full snapshot checkpoint - stores complete result
 * Use for: small results, single entities, focused data
 */
export interface FullSnapshotCheckpoint extends BaseCheckpoint {
    type: CheckpointType.FULL_SNAPSHOT;
    /** Complete serialized result */
    result: unknown;
    /** Size in bytes (for monitoring) */
    sizeBytes?: number;
}
/**
 * Reference to a checkpoint result stored elsewhere
 * No preview data is provided - must use __restore.checkpoint() to access
 */
export interface CheckpointReference {
    /** Human-readable description of what's stored */
    description: string;
    /** Code snippet to restore this checkpoint */
    restoreCode: string;
}
/**
 * Reference checkpoint - stores full result but shows preview to LLM
 * Use for: large results, arrays, search results, bulk data
 *
 * Note: The full result is stored in the checkpoint, but when shown to LLM
 * in error responses, only the preview/summary is included (not the full data).
 * The LLM can restore the full data using __restore.checkpoint(id).
 */
export interface ReferenceCheckpoint extends BaseCheckpoint {
    type: CheckpointType.REFERENCE;
    /** Summary/reference information (shown to LLM) */
    reference: CheckpointReference;
    /** Complete result (stored but not shown to LLM in error response) */
    result: unknown;
    /** Size in bytes of full result (for monitoring) */
    sizeBytes?: number;
}
/**
 * Union type for all checkpoints
 */
export type Checkpoint = FullSnapshotCheckpoint | ReferenceCheckpoint;
/**
 * Information about a checkpoint for error responses
 */
export interface CheckpointInfo {
    /** Checkpoint identifier */
    id: string;
    /** Storage type */
    type: CheckpointType;
    /** Formatted operation name (e.g., "atp.api.github.getUser") */
    operation: string;
    /** Description of the checkpointed data */
    description: string;
    /** When checkpoint was created */
    timestamp: number;
    /** Full result (only for full_snapshot checkpoints WITHOUT restricted access) */
    result?: unknown;
    /**
     * Whether this checkpoint has restricted provenance
     * If true, LLM MUST use __restore.checkpoint() to access data
     * Full data will NOT be included in error response
     */
    hasRestrictedProvenance?: boolean;
    /**
     * Security notice shown to LLM when data has restricted provenance
     */
    securityNotice?: string;
    /**
     * Variable names used to store the result (e.g., ['result'], ['myUser', 'galTestUser'])
     * Used to generate helpful restore code snippets
     */
    usedVariables?: string[];
}
/**
 * Checkpoint data attached to execution results
 */
export interface CheckpointData {
    /** Available checkpoints from the execution */
    available: CheckpointInfo[];
    /** Human-readable instructions for using checkpoints */
    restoreInstructions: string;
}
/**
 * Strategy for deciding checkpoint type and creating references
 */
export interface CheckpointStrategy {
    /**
     * Decide whether to use full snapshot or reference based on result size/structure
     * @param result The operation result
     * @param provenance Optional provenance metadata for security decisions
     * @returns true for full snapshot, false for reference
     */
    shouldUseFullSnapshot(result: unknown, provenance?: CheckpointProvenanceSnapshot): boolean;
    /**
     * Create a reference for a large result
     * @param result The operation result
     * @param metadata Operation metadata (used for description generation)
     * @returns Reference information
     */
    createReference(result: unknown, metadata: OperationMetadata): CheckpointReference;
    /**
     * Generate a description for a checkpoint
     * @param result The operation result
     * @param metadata Operation metadata
     * @returns Human-readable description
     */
    generateDescription(result: unknown, metadata: OperationMetadata): string;
}
/**
 * Configuration for checkpoint behavior
 */
export interface CheckpointConfig {
    /** Maximum size for full snapshots (bytes) */
    maxFullSnapshotSize?: number;
    /** Maximum array length for full snapshots */
    maxArrayItemsFull?: number;
    /** TTL for checkpoints in cache (seconds) */
    defaultTTL?: number;
    /** Custom strategy implementation */
    strategy?: CheckpointStrategy;
    /** Enable/disable checkpointing */
    enabled?: boolean;
}
/**
 * Error thrown when operation checkpoint operations fail
 */
export declare class OperationCheckpointError extends Error {
    readonly checkpointId: string;
    readonly operation: 'save' | 'load' | 'restore' | 'create';
    constructor(message: string, checkpointId: string, operation: 'save' | 'load' | 'restore' | 'create');
}
//# sourceMappingURL=checkpoint-types.d.ts.map