/**
 * Unique identifier for a task in the system.
 * Typically a Solana public key string or UUID.
 */
export type TaskId = string;

/**
 * Unique identifier for an agent.
 * Corresponds to the agent's Solana wallet address.
 */
export type AgentId = string;

/**
 * Unix timestamp in milliseconds.
 */
export type TimestampMs = number;

/**
 * Amount in lamports (1 SOL = 1_000_000_000 lamports).
 */
export type Lamports = bigint;

/**
 * Represents a task node in the dependency graph.
 * Contains all metadata needed for speculative execution decisions.
 */
export interface TaskNode {
  /** Unique identifier for this task */
  readonly id: TaskId;
  
  /** Agent that claimed this task */
  readonly agentId: AgentId;
  
  /** Parent task this depends on (null for root tasks) */
  readonly dependsOn: TaskId | null;
  
  /** Current execution status */
  status: TaskStatus;
  
  /** When the task claim expires (ms since epoch) */
  readonly claimExpiry: TimestampMs;
  
  /** When this task was created/claimed */
  readonly createdAt: TimestampMs;
  
  /** Estimated compute time in milliseconds */
  readonly estimatedComputeMs: number;
  
  /** Actual compute time once completed */
  computeTimeMs?: number;
  
  /** Task payload/input data hash */
  readonly inputHash: string;
  
  /** Task output data hash (set after completion) */
  outputHash?: string;
  
  /** Current speculation depth (0 = confirmed ancestor chain) */
  speculationDepth: number;
  
  /** Metadata for tracking and debugging */
  metadata: TaskNodeMetadata;
}

/**
 * Additional metadata attached to task nodes.
 */
export interface TaskNodeMetadata {
  /** Human-readable task name/description */
  name?: string;
  
  /** Task type/category for analytics */
  taskType?: string;
  
  /** Priority level (higher = more urgent) */
  priority: number;
  
  /** Number of retry attempts */
  retryCount: number;
  
  /** Maximum allowed retries */
  maxRetries: number;
  
  /** Custom labels for filtering/grouping */
  labels: Recordstring, string>;
  
  /** Trace ID for distributed tracing */
  traceId?: string;
  
  /** Span ID for distributed tracing */
  spanId?: string;
}

/**
 * Possible states for a task in the speculative execution system.
 */
export enum TaskStatus {
  /** Task is waiting for dependencies */
  PENDING = 'PENDING',
  
  /** Task is ready to execute (dependencies met or speculating) */
  READY = 'READY',
  
  /** Task is currently being executed */
  EXECUTING = 'EXECUTING',
  
  /** Task execution completed, generating proof */
  PROVING = 'PROVING',
  
  /** Proof generated, waiting for ancestor confirmation */
  AWAITING_ANCESTORS = 'AWAITING_ANCESTORS',
  
  /** Proof submitted, waiting for on-chain confirmation */
  CONFIRMING = 'CONFIRMING',
  
  /** Task fully confirmed on-chain */
  CONFIRMED = 'CONFIRMED',
  
  /** Task was rolled back due to ancestor failure */
  ROLLED_BACK = 'ROLLED_BACK',
  
  /** Task failed during execution */
  FAILED = 'FAILED',
  
  /** Task was cancelled */
  CANCELLED = 'CANCELLED',
  
  /** Task claim expired before completion */
  EXPIRED = 'EXPIRED',
}

/**
 * Represents a directed edge in the dependency graph.
 */
export interface DependencyEdge {
  /** Source task (parent/dependency) */
  readonly from: TaskId;
  
  /** Target task (child/dependent) */
  readonly to: TaskId;
  
  /** When this edge was created */
  readonly createdAt: TimestampMs;
  
  /** Edge type for multi-dependency scenarios */
  readonly edgeType: DependencyEdgeType;
  
  /** Weight for scheduling priority (optional) */
  weight?: number;
}

/**
 * Types of dependency relationships.
 */
export enum DependencyEdgeType {
  /** Standard data dependency (output -> input) */
  DATA = 'DATA',
  
  /** Ordering constraint only (no data flow) */
  ORDER = 'ORDER',
  
  /** Resource dependency (shared resource lock) */
  RESOURCE = 'RESOURCE',
}

/**
 * Unique identifier for a speculative commitment.
 */
export type CommitmentId = string;

/**
 * Represents a speculative commitment made by an agent.
 * This is the core data structure for tracking speculative execution.
 */
export interface SpeculativeCommitment {
  /** Unique commitment identifier */
  readonly id: CommitmentId;
  
  /** Task this commitment is for */
  readonly taskId: TaskId;
  
  /** Agent making the commitment */
  readonly agentId: AgentId;
  
  /** Amount of stake bonded for this commitment */
  readonly bondedStake: Lamports;
  
  /** Speculation depth (distance from last confirmed ancestor) */
  readonly depth: number;
  
  /** Current status of the commitment */
  status: CommitmentStatus;
  
  /** Hash of the speculative output */
  readonly outputHash: string;
  
  /** Hash of the input state (for verification) */
  readonly inputStateHash: string;
  
  /** When the commitment was created */
  readonly createdAt: TimestampMs;
  
  /** When the commitment expires if not confirmed */
  readonly expiresAt: TimestampMs;
  
  /** Parent commitment ID (null for depth-1 speculation) */
  readonly parentCommitmentId: CommitmentId | null;
  
  /** Child commitment IDs (dependents) */
  childCommitmentIds: CommitmentId[];
  
  /** Proof status for this commitment */
  proofStatus: ProofStatus;
  
  /** On-chain transaction signature (if submitted) */
  onChainTxSignature?: string;
  
  /** Slot when confirmed on-chain */
  confirmedAtSlot?: number;
}

/**
 * Status of a speculative commitment.
 */
export enum CommitmentStatus {
  /** Commitment is active and valid */
  ACTIVE = 'ACTIVE',
  
  /** Commitment has been confirmed on-chain */
  CONFIRMED = 'CONFIRMED',
  
  /** Commitment was rolled back */
  ROLLED_BACK = 'ROLLED_BACK',
  
  /** Commitment expired without confirmation */
  EXPIRED = 'EXPIRED',
  
  /** Commitment was invalidated (parent failed) */
  INVALIDATED = 'INVALIDATED',
  
  /** Agent was slashed for invalid commitment */
  SLASHED = 'SLASHED',
}

/**
 * Status of proof generation and submission.
 */
export interface ProofStatus {
  /** Current state of proof generation */
  state: ProofState;
  
  /** Proof data (when generated) */
  proofData?: Uint8Array;
  
  /** Proof generation job ID */
  jobId?: string;
  
  /** When proof generation started */
  startedAt?: TimestampMs;
  
  /** When proof generation completed */
  completedAt?: TimestampMs;
  
  /** Error message if proof generation failed */
  error?: string;
  
  /** Number of proof generation attempts */
  attempts: number;
  
  /** Whether proof is deferred (waiting for ancestors) */
  isDeferred: boolean;
}

/**
 * States for proof generation.
 */
export enum ProofState {
  /** Proof not yet started */
  NOT_STARTED = 'NOT_STARTED',
  
  /** Proof generation queued */
  QUEUED = 'QUEUED',
  
  /** Proof currently being generated */
  GENERATING = 'GENERATING',
  
  /** Proof generated, awaiting submission */
  GENERATED = 'GENERATED',
  
  /** Proof submitted to chain */
  SUBMITTED = 'SUBMITTED',
  
  /** Proof verified on-chain */
  VERIFIED = 'VERIFIED',
  
  /** Proof generation failed */
  FAILED = 'FAILED',
}

/**
 * Represents a proof generation job in the deferral queue.
 */
export interface ProofGenerationJob {
  /** Unique job identifier */
  readonly id: string;
  
  /** Task this proof is for */
  readonly taskId: TaskId;
  
  /** Commitment this proof validates */
  readonly commitmentId: CommitmentId;
  
  /** Job priority (higher = processed first) */
  priority: number;
  
  /** Current job status */
  status: ProofJobStatus;
  
  /** When the job was created */
  readonly createdAt: TimestampMs;
  
  /** When the job started processing */
  startedAt?: TimestampMs;
  
  /** When the job completed */
  completedAt?: TimestampMs;
  
  /** Worker ID processing this job */
  workerId?: string;
  
  /** Inputs required for proof generation */
  readonly inputs: ProofInputs;
  
  /** Generated proof output */
  output?: ProofOutput;
  
  /** Error details if failed */
  error?: ProofJobError;
  
  /** Number of retry attempts */
  retryCount: number;
  
  /** Ancestor commitments that must be confirmed first */
  readonly requiredAncestors: CommitmentId[];
  
  /** Whether all ancestors are confirmed */
  ancestorsConfirmed: boolean;
}

/**
 * Inputs required for proof generation.
 */
export interface ProofInputs {
  /** Input state hash */
  inputStateHash: string;
  
  /** Output state hash */
  outputStateHash: string;
  
  /** Execution trace (compressed) */
  executionTrace: Uint8Array;
  
  /** Public inputs for the circuit */
  publicInputs: bigint[];
  
  /** Private witness data */
  witnessData: Uint8Array;
}

/**
 * Output from proof generation.
 */
export interface ProofOutput {
  /** The generated proof */
  proof: Uint8Array;
  
  /** Public inputs verified by the proof */
  publicInputs: bigint[];
  
  /** Proof type/system used */
  proofType: ProofType;
  
  /** Verification key hash */
  vkHash: string;
  
  /** Proof generation duration in ms */
  generationTimeMs: number;
  
  /** Proof size in bytes */
  proofSizeBytes: number;
}

/**
 * Supported proof systems.
 */
export enum ProofType {
  GROTH16 = 'GROTH16',
  PLONK = 'PLONK',
  STARK = 'STARK',
  MOCK = 'MOCK',
}

/**
 * Status of a proof generation job.
 */
export enum ProofJobStatus {
  /** Job is queued, waiting for processing */
  QUEUED = 'QUEUED',
  
  /** Job is waiting for ancestor proofs */
  WAITING_ANCESTORS = 'WAITING_ANCESTORS',
  
  /** Job is currently being processed */
  PROCESSING = 'PROCESSING',
  
  /** Job completed successfully */
  COMPLETED = 'COMPLETED',
  
  /** Job failed */
  FAILED = 'FAILED',
  
  /** Job was cancelled */
  CANCELLED = 'CANCELLED',
  
  /** Job timed out */
  TIMED_OUT = 'TIMED_OUT',
}

/**
 * Error details for failed proof jobs.
 */
export interface ProofJobError {
  /** Error code */
  code: ProofErrorCode;
  
  /** Human-readable error message */
  message: string;
  
  /** Stack trace (if available) */
  stack?: string;
  
  /** Whether this error is retryable */
  retryable: boolean;
  
  /** Suggested retry delay in ms */
  retryDelayMs?: number;
}

/**
 * Error codes for proof generation failures.
 */
export enum ProofErrorCode {
  /** Invalid inputs provided */
  INVALID_INPUTS = 'INVALID_INPUTS',
  
  /** Witness generation failed */
  WITNESS_GENERATION_FAILED = 'WITNESS_GENERATION_FAILED',
  
  /** Proof generation timed out */
  TIMEOUT = 'TIMEOUT',
  
  /** Out of memory during proof generation */
  OUT_OF_MEMORY = 'OUT_OF_MEMORY',
  
  /** Circuit constraint violation */
  CONSTRAINT_VIOLATION = 'CONSTRAINT_VIOLATION',
  
  /** Worker crashed during generation */
  WORKER_CRASH = 'WORKER_CRASH',
  
  /** Unknown/internal error */
  INTERNAL_ERROR = 'INTERNAL_ERROR',
  
  /** Ancestors not yet confirmed */
  ANCESTORS_PENDING = 'ANCESTORS_PENDING',
  
  /** Ancestor proof was invalidated */
  ANCESTOR_INVALIDATED = 'ANCESTOR_INVALIDATED',
}

/**
 * Status of deferred proofs waiting for ancestors.
 */
export interface DeferredProofStatus {
  /** The proof job being deferred */
  readonly jobId: string;
  
  /** Commitment this proof is for */
  readonly commitmentId: CommitmentId;
  
  /** Ancestor commitments being waited on */
  readonly pendingAncestors: AncestorStatus[];
  
  /** When deferral started */
  readonly deferredAt: TimestampMs;
  
  /** Estimated time until all ancestors confirmed */
  estimatedWaitMs?: number;
  
  /** Whether any ancestor has failed */
  hasFailedAncestor: boolean;
  
  /** Current position in deferral queue */
  queuePosition: number;
}

/**
 * Status of a single ancestor in the chain.
 */
export interface AncestorStatus {
  /** Ancestor commitment ID */
  readonly commitmentId: CommitmentId;
  
  /** Ancestor task ID */
  readonly taskId: TaskId;
  
  /** Depth of this ancestor (relative to current) */
  readonly depth: number;
  
  /** Current status */
  status: CommitmentStatus;
  
  /** Proof status */
  proofState: ProofState;
  
  /** Estimated time to confirmation */
  estimatedConfirmationMs?: number;
}

/**
 * Result of a rollback operation.
 */
export interface RollbackResult {
  /** Unique identifier for this rollback operation */
  readonly rollbackId: string;
  
  /** Root cause commitment that triggered the rollback */
  readonly triggerCommitmentId: CommitmentId;
  
  /** Reason for the rollback */
  readonly reason: RollbackReason;
  
  /** Tasks that were rolled back */
  readonly rolledBackTasks: RolledBackTask[];
  
  /** Commitments that were invalidated */
  readonly invalidatedCommitments: CommitmentId[];
  
  /** Total stake that was released */
  readonly totalReleasedStake: Lamports;
  
  /** Total stake that was slashed (if any) */
  readonly totalSlashedStake: Lamports;
  
  /** Duration of the rollback operation in ms */
  readonly durationMs: number;
  
  /** When the rollback started */
  readonly startedAt: TimestampMs;
  
  /** When the rollback completed */
  readonly completedAt: TimestampMs;
  
  /** Whether any errors occurred during rollback */
  readonly hadErrors: boolean;
  
  /** Error details if any */
  errors?: RollbackError[];
  
  /** Metrics about the rollback */
  metrics: RollbackMetrics;
}

/**
 * Reasons for triggering a rollback.
 */
export enum RollbackReason {
  /** Ancestor proof verification failed */
  ANCESTOR_PROOF_FAILED = 'ANCESTOR_PROOF_FAILED',
  
  /** Ancestor task execution failed */
  ANCESTOR_EXECUTION_FAILED = 'ANCESTOR_EXECUTION_FAILED',
  
  /** Ancestor commitment expired */
  ANCESTOR_EXPIRED = 'ANCESTOR_EXPIRED',
  
  /** Ancestor was slashed for invalid output */
  ANCESTOR_SLASHED = 'ANCESTOR_SLASHED',
  
  /** Manual rollback requested */
  MANUAL_REQUEST = 'MANUAL_REQUEST',
  
  /** System detected inconsistency */
  CONSISTENCY_CHECK_FAILED = 'CONSISTENCY_CHECK_FAILED',
  
  /** Claim expired before proof submission */
  CLAIM_EXPIRED = 'CLAIM_EXPIRED',
  
  /** Configuration change required rollback */
  CONFIG_CHANGE = 'CONFIG_CHANGE',
  
  /** Emergency shutdown initiated */
  EMERGENCY_SHUTDOWN = 'EMERGENCY_SHUTDOWN',
}

/**
 * Information about a single rolled back task.
 */
export interface RolledBackTask {
  /** Task that was rolled back */
  readonly taskId: TaskId;
  
  /** Associated commitment ID */
  readonly commitmentId: CommitmentId;
  
  /** Agent who owned this task */
  readonly agentId: AgentId;
  
  /** Depth at which this task was speculating */
  readonly speculationDepth: number;
  
  /** Previous status before rollback */
  readonly previousStatus: TaskStatus;
  
  /** Stake that was bonded */
  readonly bondedStake: Lamports;
  
  /** Stake that was released (not slashed) */
  readonly releasedStake: Lamports;
  
  /** Stake that was slashed (if any) */
  readonly slashedStake: Lamports;
  
  /** Compute time wasted on this task */
  readonly wastedComputeMs: number;
  
  /** State snapshot that was restored (if any) */
  readonly restoredSnapshotId?: string;
  
  /** Order in which this task was rolled back */
  readonly rollbackOrder: number;
  
  /** Whether rollback was successful for this task */
  readonly success: boolean;
  
  /** Error if rollback failed for this task */
  error?: string;
}

/**
 * Metrics collected during rollback.
 */
export interface RollbackMetrics {
  /** Total number of tasks rolled back */
  totalTasksRolledBack: number;
  
  /** Maximum depth of rollback chain */
  maxRollbackDepth: number;
  
  /** Total compute time wasted */
  totalWastedComputeMs: number;
  
  /** Number of state snapshots restored */
  snapshotsRestored: number;
  
  /** Number of proof jobs cancelled */
  proofJobsCancelled: number;
  
  /** Time spent in each rollback phase */
  phaseTimings: RecordRollbackPhase, number>;
  
  /** Number of agents affected */
  affectedAgents: number;
  
  /** Rollback cascade depth (how many levels) */
  cascadeDepth: number;
}

/**
 * Phases of the rollback operation.
 */
export enum RollbackPhase {
  /** Identifying affected tasks */
  IDENTIFICATION = 'IDENTIFICATION',
  
  /** Topological sort for rollback order */
  ORDERING = 'ORDERING',
  
  /** Cancelling in-flight operations */
  CANCELLATION = 'CANCELLATION',
  
  /** Restoring state snapshots */
  STATE_RESTORATION = 'STATE_RESTORATION',
  
  /** Releasing/slashing stakes */
  STAKE_SETTLEMENT = 'STAKE_SETTLEMENT',
  
  /** Cleaning up resources */
  CLEANUP = 'CLEANUP',
  
  /** Emitting events and notifications */
  NOTIFICATION = 'NOTIFICATION',
}

/**
 * Decision made by the scheduler about whether to speculate.
 */
export interface SpeculationDecision {
  /** Task being considered for speculation */
  readonly taskId: TaskId;
  
  /** Whether to proceed with speculation */
  readonly shouldSpeculate: boolean;
  
  /** Reasons for the decision */
  readonly reasons: DecisionReason[];
  
  /** Calculated speculation depth if proceeding */
  readonly depth?: number;
  
  /** Required stake if proceeding */
  readonly requiredStake?: Lamports;
  
  /** Risk assessment score (0-100) */
  readonly riskScore: number;
  
  /** Expected value calculation */
  readonly expectedValue?: ExpectedValueCalculation;
  
  /** Constraints that were evaluated */
  readonly evaluatedConstraints: ConstraintEvaluation[];
  
  /** Timestamp of decision */
  readonly decidedAt: TimestampMs;
  
  /** Time to live for this decision (ms) */
  readonly ttlMs: number;
  
  /** ID of this decision for tracking */
  readonly decisionId: string;
}

/**
 * Reasons that influenced the speculation decision.
 */
export interface DecisionReason {
  /** Type of reason */
  type: DecisionReasonType;
  
  /** Weight of this reason in decision (-100 to 100) */
  weight: number;
  
  /** Human-readable description */
  description: string;
  
  /** Relevant threshold or value */
  value?: number;
  
  /** Threshold that was compared against */
  threshold?: number;
}

/**
 * Types of reasons for speculation decisions.
 */
export enum DecisionReasonType {
  /** Depth exceeds maximum allowed */
  DEPTH_EXCEEDED = 'DEPTH_EXCEEDED',
  
  /** Insufficient stake available */
  INSUFFICIENT_STAKE = 'INSUFFICIENT_STAKE',
  
  /** Claim expiry too close */
  CLAIM_EXPIRY_RISK = 'CLAIM_EXPIRY_RISK',
  
  /** Parent commitment not found */
  PARENT_NOT_FOUND = 'PARENT_NOT_FOUND',
  
  /** Parent commitment in bad state */
  PARENT_INVALID_STATE = 'PARENT_INVALID_STATE',
  
  /** Resource limits reached */
  RESOURCE_LIMIT = 'RESOURCE_LIMIT',
  
  /** Historical success rate too low */
  LOW_SUCCESS_RATE = 'LOW_SUCCESS_RATE',
  
  /** Expected value too low */
  LOW_EXPECTED_VALUE = 'LOW_EXPECTED_VALUE',
  
  /** Feature flag disabled */
  FEATURE_DISABLED = 'FEATURE_DISABLED',
  
  /** Agent in cooldown period */
  AGENT_COOLDOWN = 'AGENT_COOLDOWN',
  
  /** Parallel branch limit reached */
  BRANCH_LIMIT = 'BRANCH_LIMIT',
  
  /** All checks passed */
  ALL_CHECKS_PASSED = 'ALL_CHECKS_PASSED',
  
  /** High confidence in parent */
  HIGH_PARENT_CONFIDENCE = 'HIGH_PARENT_CONFIDENCE',
  
  /** Fast expected confirmation */
  FAST_CONFIRMATION = 'FAST_CONFIRMATION',
}

/**
 * Expected value calculation for speculation.
 */
export interface ExpectedValueCalculation {
  /** Probability of successful confirmation */
  successProbability: number;
  
  /** Value gained on success (in compute time saved) */
  successValue: number;
  
  /** Probability of rollback */
  rollbackProbability: number;
  
  /** Cost of rollback (wasted compute + potential slash) */
  rollbackCost: number;
  
  /** Net expected value */
  expectedValue: number;
  
  /** Factors used in calculation */
  factors: ExpectedValueFactors;
}

/**
 * Factors used in expected value calculation.
 */
export interface ExpectedValueFactors {
  /** Historical confirmation rate for this depth */
  historicalConfirmationRate: number;
  
  /** Average confirmation time at this depth */
  avgConfirmationTimeMs: number;
  
  /** Parent's current confirmation likelihood */
  parentConfidenceScore: number;
  
  /** Network congestion factor (0-1) */
  networkCongestionFactor: number;
  
  /** Agent's historical success rate */
  agentSuccessRate: number;
  
  /** Task type historical success rate */
  taskTypeSuccessRate: number;
}

/**
 * Result of evaluating a single constraint.
 */
export interface ConstraintEvaluation {
  /** Name of the constraint */
  constraint: string;
  
  /** Whether the constraint passed */
  passed: boolean;
  
  /** Current value */
  currentValue: number | string | boolean;
  
  /** Required value or threshold */
  requiredValue: number | string | boolean;
  
  /** Whether this constraint is blocking */
  isBlocking: boolean;
}

/**
 * Complete configuration for the speculative execution system.
 */
export interface SpeculationConfig {
  /** Whether speculation is enabled */
  enabled: boolean;
  
  /** Operating mode */
  mode: SpeculationMode;
  
  /** Core speculation settings */
  core: SpeculationCoreConfig;
  
  /** Stake management settings */
  stake: StakeConfig;
  
  /** Proof generation settings */
  proof: ProofConfig;
  
  /** Resource limits */
  limits: ResourceLimitsConfig;
  
  /** Feature flags */
  features: FeatureFlagsConfig;
  
  /** Scheduler settings */
  scheduler: SchedulerConfig;
  
  /** Rollback settings */
  rollback: RollbackConfig;
}

/**
 * Operating modes for speculation.
 */
export enum SpeculationMode {
  /** Low risk, shallow depth */
  CONSERVATIVE = 'conservative',
  
  /** Balanced risk/reward */
  BALANCED = 'balanced',
  
  /** High throughput, accept risk */
  AGGRESSIVE = 'aggressive',
  
  /** User-defined settings */
  CUSTOM = 'custom',
}

/**
 * Core speculation settings.
 */
export interface SpeculationCoreConfig {
  /** Maximum speculation chain depth */
  maxDepth: number;
  
  /** Maximum parallel speculation branches */
  maxParallelBranches: number;
  
  /** Timeout for confirmation (ms) */
  confirmationTimeoutMs: number;
  
  /** Minimum buffer before claim expiry (ms) */
  claimBufferMs: number;
  
  /** Minimum confidence score to speculate (0-100) */
  minConfidenceScore: number;
  
  /** Whether to allow cross-agent speculation */
  allowCrossAgentSpeculation: boolean;
}

/**
 * Stake management configuration.
 */
export interface StakeConfig {
  /** Minimum stake to speculate */
  minStake: Lamports;
  
  /** Maximum total stake per agent */
  maxStake: Lamports;
  
  /** Base stake required per speculation */
  baseBond: Lamports;
  
  /** Stake multiplier per depth level */
  depthMultiplier: number;
  
  /** Percentage of stake slashed on failure */
  slashPercentage: number;
  
  /** Portion of slash to protocol (rest to affected) */
  protocolSlashShare: number;
  
  /** Cooldown after slash (ms) */
  cooldownPeriodMs: number;
}

/**
 * Proof generation configuration.
 */
export interface ProofConfig {
  /** Proof system to use */
  generator: ProofType;
  
  /** Number of worker threads */
  workerThreads: number;
  
  /** Maximum queue size */
  queueSize: number;
  
  /** Proof generation timeout (ms) */
  timeoutMs: number;
  
  /** Batch size for proof generation */
  batchSize: number;
  
  /** Maximum retries on failure */
  maxRetries: number;
  
  /** Retry delay base (ms) */
  retryDelayMs: number;
  
  /** Retry delay multiplier (exponential backoff) */
  retryMultiplier: number;
  
  /** Whether to generate proofs optimistically */
  optimisticGeneration: boolean;
}

/**
 * Resource limits configuration.
 */
export interface ResourceLimitsConfig {
  /** Maximum memory for speculation state (MB) */
  maxMemoryMb: number;
  
  /** Maximum pending operations */
  maxPendingOperations: number;
  
  /** Maximum state snapshots */
  maxStateSnapshots: number;
  
  /** Garbage collection interval (ms) */
  gcIntervalMs: number;
  
  /** Maximum commitment age before expiry (ms) */
  maxCommitmentAgeMs: number;
  
  /** Maximum rollback cascade size */
  maxRollbackCascadeSize: number;
}

/**
 * Feature flags configuration.
 */
export interface FeatureFlagsConfig {
  /** Enable parallel speculation branches */
  enableParallelSpeculation: boolean;
  
  /** Enable cross-agent speculation */
  enableCrossAgentSpeculation: boolean;
  
  /** Enable optimistic proof generation */
  enableOptimisticProofs: boolean;
  
  /** Enable stake delegation */
  enableStakeDelegation: boolean;
  
  /** Enable on-chain commitments (vs runtime-only) */
  enableOnChainCommitments: boolean;
  
  /** Rollout percentage (0-100) */
  rolloutPercentage: number;
  
  /** Enable detailed metrics */
  enableDetailedMetrics: boolean;
}

/**
 * Scheduler configuration.
 */
export interface SchedulerConfig {
  /** How often to run scheduling loop (ms) */
  schedulingIntervalMs: number;
  
  /** Maximum tasks to process per cycle */
  maxTasksPerCycle: number;
  
  /** Priority weight for depth (lower depth = higher priority) */
  depthPriorityWeight: number;
  
  /** Priority weight for claim expiry urgency */
  expiryPriorityWeight: number;
  
  /** Priority weight for task type priority */
  taskPriorityWeight: number;
  
  /** Whether to use expected value for decisions */
  useExpectedValueDecisions: boolean;
  
  /** Minimum expected value to speculate */
  minExpectedValue: number;
}

/**
 * Rollback configuration.
 */
export interface RollbackConfig {
  /** Rollback policy to use */
  policy: RollbackPolicy;
  
  /** Maximum concurrent rollbacks */
  maxConcurrentRollbacks: number;
  
  /** Rollback operation timeout (ms) */
  rollbackTimeoutMs: number;
  
  /** Whether to preserve state snapshots after rollback */
  preserveSnapshotsAfterRollback: boolean;
  
  /** Grace period before forcing rollback (ms) */
  gracePeriodMs: number;
  
  /** Whether to notify affected agents */
  notifyAffectedAgents: boolean;
}

/**
 * Rollback policies.
 */
export enum RollbackPolicy {
  /** Roll back all dependents */
  CASCADE = 'cascade',
  
  /** Only roll back directly affected */
  SELECTIVE = 'selective',
  
  /** Roll back to last checkpoint */
  CHECKPOINT = 'checkpoint',
}

/**
 * Base interface for all speculation events.
 */
export interface SpeculationEventT extends SpeculationEventType = SpeculationEventType> {
  /** Event type */
  readonly type: T;
  
  /** Unique event ID */
  readonly eventId: string;
  
  /** When the event occurred */
  readonly timestamp: TimestampMs;
  
  /** Source component that emitted the event */
  readonly source: EventSource;
  
  /** Correlation ID for tracing */
  readonly correlationId?: string;
  
  /** Event payload (type-specific) */
  readonly payload: SpeculationEventPayloads[T];
}

/**
 * All speculation event types.
 */
export enum SpeculationEventType {
  // Task events
  TASK_ADDED = 'task.added',
  TASK_READY = 'task.ready',
  TASK_STARTED = 'task.started',
  TASK_COMPLETED = 'task.completed',
  TASK_FAILED = 'task.failed',
  
  // Commitment events
  COMMITMENT_CREATED = 'commitment.created',
  COMMITMENT_CONFIRMED = 'commitment.confirmed',
  COMMITMENT_EXPIRED = 'commitment.expired',
  COMMITMENT_INVALIDATED = 'commitment.invalidated',
  
  // Proof events
  PROOF_JOB_QUEUED = 'proof.job.queued',
  PROOF_JOB_STARTED = 'proof.job.started',
  PROOF_JOB_COMPLETED = 'proof.job.completed',
  PROOF_JOB_FAILED = 'proof.job.failed',
  PROOF_JOB_DEFERRED = 'proof.job.deferred',
  PROOF_SUBMITTED = 'proof.submitted',
  PROOF_VERIFIED = 'proof.verified',
  
  // Rollback events
  ROLLBACK_STARTED = 'rollback.started',
  ROLLBACK_TASK_REVERTED = 'rollback.task.reverted',
  ROLLBACK_COMPLETED = 'rollback.completed',
  ROLLBACK_FAILED = 'rollback.failed',
  
  // Stake events
  STAKE_BONDED = 'stake.bonded',
  STAKE_RELEASED = 'stake.released',
  STAKE_SLASHED = 'stake.slashed',
  
  // Decision events
  SPECULATION_DECISION = 'speculation.decision',
  
  // System events
  DEPTH_LIMIT_REACHED = 'system.depth.limit',
  RESOURCE_LIMIT_REACHED = 'system.resource.limit',
  CONFIG_CHANGED = 'system.config.changed',
  SYSTEM_PAUSED = 'system.paused',
  SYSTEM_RESUMED = 'system.resumed',
}

/**
 * Event source components.
 */
export enum EventSource {
  DEPENDENCY_GRAPH = 'DependencyGraph',
  COMMITMENT_LEDGER = 'CommitmentLedger',
  PROOF_DEFERRAL_MANAGER = 'ProofDeferralManager',
  ROLLBACK_CONTROLLER = 'RollbackController',
  SPECULATIVE_TASK_SCHEDULER = 'SpeculativeTaskScheduler',
  STAKE_MANAGER = 'StakeManager',
  SYSTEM = 'System',
}

/**
 * Map of event types to their payload interfaces.
 */
export interface SpeculationEventPayloads {
  // Task events
  [SpeculationEventType.TASK_ADDED]: TaskAddedPayload;
  [SpeculationEventType.TASK_READY]: TaskReadyPayload;
  [SpeculationEventType.TASK_STARTED]: TaskStartedPayload;
  [SpeculationEventType.TASK_COMPLETED]: TaskCompletedPayload;
  [SpeculationEventType.TASK_FAILED]: TaskFailedPayload;
  
  // Commitment events
  [SpeculationEventType.COMMITMENT_CREATED]: CommitmentCreatedPayload;
  [SpeculationEventType.COMMITMENT_CONFIRMED]: CommitmentConfirmedPayload;
  [SpeculationEventType.COMMITMENT_EXPIRED]: CommitmentExpiredPayload;
  [SpeculationEventType.COMMITMENT_INVALIDATED]: CommitmentInvalidatedPayload;
  
  // Proof events
  [SpeculationEventType.PROOF_JOB_QUEUED]: ProofJobQueuedPayload;
  [SpeculationEventType.PROOF_JOB_STARTED]: ProofJobStartedPayload;
  [SpeculationEventType.PROOF_JOB_COMPLETED]: ProofJobCompletedPayload;
  [SpeculationEventType.PROOF_JOB_FAILED]: ProofJobFailedPayload;
  [SpeculationEventType.PROOF_JOB_DEFERRED]: ProofJobDeferredPayload;
  [SpeculationEventType.PROOF_SUBMITTED]: ProofSubmittedPayload;
  [SpeculationEventType.PROOF_VERIFIED]: ProofVerifiedPayload;
  
  // Rollback events
  [SpeculationEventType.ROLLBACK_STARTED]: RollbackStartedPayload;
  [SpeculationEventType.ROLLBACK_TASK_REVERTED]: RollbackTaskRevertedPayload;
  [SpeculationEventType.ROLLBACK_COMPLETED]: RollbackCompletedPayload;
  [SpeculationEventType.ROLLBACK_FAILED]: RollbackFailedPayload;
  
  // Stake events
  [SpeculationEventType.STAKE_BONDED]: StakeBondedPayload;
  [SpeculationEventType.STAKE_RELEASED]: StakeReleasedPayload;
  [SpeculationEventType.STAKE_SLASHED]: StakeSlashedPayload;
  
  // Decision events
  [SpeculationEventType.SPECULATION_DECISION]: SpeculationDecisionPayload;
  
  // System events
  [SpeculationEventType.DEPTH_LIMIT_REACHED]: DepthLimitReachedPayload;
  [SpeculationEventType.RESOURCE_LIMIT_REACHED]: ResourceLimitReachedPayload;
  [SpeculationEventType.CONFIG_CHANGED]: ConfigChangedPayload;
  [SpeculationEventType.SYSTEM_PAUSED]: SystemPausedPayload;
  [SpeculationEventType.SYSTEM_RESUMED]: SystemResumedPayload;
}

// Task Event Payloads
export interface TaskAddedPayload {
  task: TaskNode;
  parentTaskId?: TaskId;
}

export interface TaskReadyPayload {
  taskId: TaskId;
  isSpeculative: boolean;
  speculationDepth: number;
}

export interface TaskStartedPayload {
  taskId: TaskId;
  agentId: AgentId;
  isSpeculative: boolean;
  speculationDepth: number;
}

export interface TaskCompletedPayload {
  taskId: TaskId;
  outputHash: string;
  computeTimeMs: number;
  isSpeculative: boolean;
}

export interface TaskFailedPayload {
  taskId: TaskId;
  error: string;
  isRetryable: boolean;
  isSpeculative: boolean;
}

// Commitment Event Payloads
export interface CommitmentCreatedPayload {
  commitment: SpeculativeCommitment;
}

export interface CommitmentConfirmedPayload {
  commitmentId: CommitmentId;
  taskId: TaskId;
  confirmedAtSlot: number;
  txSignature: string;
}

export interface CommitmentExpiredPayload {
  commitmentId: CommitmentId;
  taskId: TaskId;
  expiredAt: TimestampMs;
  bondedStake: Lamports;
}

export interface CommitmentInvalidatedPayload {
  commitmentId: CommitmentId;
  taskId: TaskId;
  reason: RollbackReason;
  triggerCommitmentId: CommitmentId;
}

// Proof Event Payloads
export interface ProofJobQueuedPayload {
  job: ProofGenerationJob;
  queuePosition: number;
  estimatedStartMs: number;
}

export interface ProofJobStartedPayload {
  jobId: string;
  taskId: TaskId;
  workerId: string;
}

export interface ProofJobCompletedPayload {
  jobId: string;
  taskId: TaskId;
  generationTimeMs: number;
  proofSizeBytes: number;
}

export interface ProofJobFailedPayload {
  jobId: string;
  taskId: TaskId;
  error: ProofJobError;
  willRetry: boolean;
}

export interface ProofJobDeferredPayload {
  jobId: string;
  taskId: TaskId;
  pendingAncestors: CommitmentId[];
  estimatedWaitMs: number;
}

export interface ProofSubmittedPayload {
  jobId: string;
  taskId: TaskId;
  txSignature: string;
  slot: number;
}

export interface ProofVerifiedPayload {
  jobId: string;
  taskId: TaskId;
  commitmentId: CommitmentId;
  verifiedAtSlot: number;
}

// Rollback Event Payloads
export interface RollbackStartedPayload {
  rollbackId: string;
  triggerCommitmentId: CommitmentId;
  reason: RollbackReason;
  estimatedTaskCount: number;
}

export interface RollbackTaskRevertedPayload {
  rollbackId: string;
  task: RolledBackTask;
}

export interface RollbackCompletedPayload {
  result: RollbackResult;
}

export interface RollbackFailedPayload {
  rollbackId: string;
  error: string;
  partialResult?: PartialRollbackResult>;
}

// Stake Event Payloads
export interface StakeBondedPayload {
  agentId: AgentId;
  commitmentId: CommitmentId;
  amount: Lamports;
  totalBonded: Lamports;
}

export interface StakeReleasedPayload {
  agentId: AgentId;
  commitmentId: CommitmentId;
  amount: Lamports;
  reason: 'confirmed' | 'rollback' | 'expiry';
}

export interface StakeSlashedPayload {
  agentId: AgentId;
  commitmentId: CommitmentId;
  slashedAmount: Lamports;
  reason: RollbackReason;
  protocolShare: Lamports;
  affectedAgentsShare: Lamports;
}

// Decision Event Payloads
export interface SpeculationDecisionPayload {
  decision: SpeculationDecision;
}

// System Event Payloads
export interface DepthLimitReachedPayload {
  taskId: TaskId;
  currentDepth: number;
  maxDepth: number;
}

export interface ResourceLimitReachedPayload {
  resourceType: 'memory' | 'operations' | 'snapshots' | 'branches';
  currentValue: number;
  limitValue: number;
}

export interface ConfigChangedPayload {
  changedKeys: string[];
  previousValues: Recordstring, unknown>;
  newValues: Recordstring, unknown>;
  changedBy: string;
}

export interface SystemPausedPayload {
  reason: string;
  pendingCommitments: number;
  pausedBy: string;
}

export interface SystemResumedPayload {
  pauseDurationMs: number;
  resumedBy: string;
}

/**
 * Manages task dependencies as a directed acyclic graph.
 * Thread-safe for concurrent reads, serialized writes.
 * 
 * @example
 * ```typescript
 * const graph = new DependencyGraph(config);
 * 
 * // Add a root task
 * graph.addTask(rootTask);
 * 
 * // Add dependent task
 * graph.addTask(childTask, rootTask.id);
 * 
 * // Get all tasks ready for execution
 * const ready = graph.getReadyTasks();
 * ```
 */
export class DependencyGraph extends EventEmitter {
  /**
   * Creates a new DependencyGraph instance.
   * 
   * @param config - Configuration options
   * @throws {ConfigurationError} If config is invalid
   */
  constructor(config: DependencyGraphConfig);

  /**
   * Adds a task to the dependency graph.
   * 
   * @param task - The task to add
   * @param dependsOn - Optional parent task ID
   * @returns The added task node
   * @throws {DuplicateTaskError} If task ID already exists
   * @throws {InvalidDependencyError} If parent doesn't exist
   * @throws {CycleDetectedError} If adding would create a cycle
   * 
   * @emits task.added
   * 
   * @example
   * ```typescript
   * const task = graph.addTask({
   *   id: 'task-123',
   *   agentId: 'agent-abc',
   *   status: TaskStatus.PENDING,
   *   claimExpiry: Date.now() + 300000,
   *   // ...
   * }, 'parent-task-id');
   * ```
   */
  addTask(task: TaskNode, dependsOn?: TaskId): TaskNode;

  /**
   * Removes a task from the graph.
   * 
   * @param taskId - ID of the task to remove
   * @param cascade - If true, also remove all dependents
   * @returns Array of removed task IDs
   * @throws {TaskNotFoundError} If task doesn't exist
   * @throws {HasDependentsError} If cascade=false and task has dependents
   * 
   * @example
   * ```typescript
   * const removed = graph.removeTask('task-123', true);
   * console.log(`Removed ${removed.length} tasks`);
   * ```
   */
  removeTask(taskId: TaskId, cascade?: boolean): TaskId[];

  /**
   * Retrieves a task by ID.
   * 
   * @param taskId - The task ID to look up
   * @returns The task node or undefined if not found
   */
  getTask(taskId: TaskId): TaskNode | undefined;

  /**
   * Gets all tasks that are ready for execution.
   * A task is ready if all its dependencies are in CONFIRMED status,
   * or if speculation is enabled and dependencies are speculatively complete.
   * 
   * @param includeSpeculative - Include speculatively ready tasks
   * @returns Array of ready task nodes
   */
  getReadyTasks(includeSpeculative?: boolean): TaskNode[];

  /**
   * Gets all descendants of a task (children, grandchildren, etc.).
   * 
   * @param taskId - The task ID to start from
   * @returns Array of descendant task IDs in topological order
   * @throws {TaskNotFoundError} If task doesn't exist
   */
  getDescendants(taskId: TaskId): TaskId[];

  /**
   * Gets all ancestors of a task (parents, grandparents, etc.).
   * 
   * @param taskId - The task ID to start from
   * @returns Array of ancestor task IDs, nearest first
   * @throws {TaskNotFoundError} If task doesn't exist
   */
  getAncestors(taskId: TaskId): TaskId[];

  /**
   * Gets direct children of a task.
   * 
   * @param taskId - The parent task ID
   * @returns Array of child task IDs
   */
  getChildren(taskId: TaskId): TaskId[];

  /**
   * Gets the parent task ID.
   * 
   * @param taskId - The child task ID
   * @returns Parent task ID or null if root task
   */
  getParent(taskId: TaskId): TaskId | null;

  /**
   * Calculates the speculation depth for a task.
   * Depth is the number of unconfirmed ancestors.
   * 
   * @param taskId - The task ID
   * @returns Speculation depth (0 = all ancestors confirmed)
   * @throws {TaskNotFoundError} If task doesn't exist
   */
  getSpeculationDepth(taskId: TaskId): number;

  /**
   * Updates the status of a task.
   * 
   * @param taskId - The task to update
   * @param status - New status
   * @param metadata - Optional additional updates
   * @throws {TaskNotFoundError} If task doesn't exist
   * @throws {InvalidStateTransitionError} If transition is not allowed
   * 
   * @emits task.ready (if transition makes task ready)
   * @emits task.completed (if transition is to CONFIRMED)
   */
  updateTaskStatus(
    taskId: TaskId,
    status: TaskStatus,
    metadata?: PartialTaskNodeMetadata>
  ): void;

  /**
   * Returns tasks in topological order (dependencies before dependents).
   * 
   * @param taskIds - Optional subset of tasks to sort
   * @returns Topologically sorted task IDs
   */
  topologicalSort(taskIds?: TaskId[]): TaskId[];

  /**
   * Returns tasks in reverse topological order (dependents before dependencies).
   * Useful for rollback operations.
   * 
   * @param taskIds - Optional subset of tasks to sort
   * @returns Reverse topologically sorted task IDs
   */
  reverseTopologicalSort(taskIds?: TaskId[]): TaskId[];

  /**
   * Finds all root tasks (tasks with no dependencies).
   * 
   * @returns Array of root task IDs
   */
  getRootTasks(): TaskId[];

  /**
   * Finds all leaf tasks (tasks with no dependents).
   * 
   * @returns Array of leaf task IDs
   */
  getLeafTasks(): TaskId[];

  /**
   * Gets statistics about the graph.
   * 
   * @returns Graph statistics
   */
  getStats(): DependencyGraphStats;

  /**
   * Validates the graph for consistency.
   * 
   * @returns Validation result with any issues found
   */
  validate(): GraphValidationResult;

  /**
   * Clears all tasks from the graph.
   * 
   * @param force - If true, clear even if tasks are in-progress
   * @throws {OperationInProgressError} If force=false and tasks are executing
   */
  clear(force?: boolean): void;

  /**
   * Exports the graph to a serializable format.
   * 
   * @returns Serialized graph data
   */
  export(): SerializedDependencyGraph;

  /**
   * Imports a previously exported graph.
   * 
   * @param data - Serialized graph data
   * @throws {ImportError} If data is invalid
   */
  import(data: SerializedDependencyGraph): void;
}

/**
 * Configuration for DependencyGraph.
 */
export interface DependencyGraphConfig {
  /** Maximum number of tasks in the graph */
  maxTasks: number;
  
  /** Maximum depth of the graph */
  maxDepth: number;
  
  /** Whether to allow multiple parents (DAG vs tree) */
  allowMultipleParents: boolean;
  
  /** Whether to validate on every mutation */
  validateOnMutation: boolean;
}

/**
 * Statistics about the dependency graph.
 */
export interface DependencyGraphStats {
  totalTasks: number;
  tasksByStatus: RecordTaskStatus, number>;
  totalEdges: number;
  maxDepth: number;
  avgDepth: number;
  rootTaskCount: number;
  leafTaskCount: number;
  speculativeTaskCount: number;
}

/**
 * Result of graph validation.
 */
export interface GraphValidationResult {
  valid: boolean;
  issues: GraphValidationIssue[];
}

/**
 * A validation issue found in the graph.
 */
export interface GraphValidationIssue {
  type: 'cycle' | 'orphan' | 'invalid_status' | 'missing_parent';
  taskIds: TaskId[];
  message: string;
}

/**
 * Serialized dependency graph for export/import.
 */
export interface SerializedDependencyGraph {
  version: string;
  exportedAt: TimestampMs;
  tasks: TaskNode[];
  edges: DependencyEdge[];
}

/**
 * Manages the lifecycle of speculative commitments.
 * Provides the source of truth for commitment state and stake tracking.
 * 
 * @example
 * ```typescript
 * const ledger = new CommitmentLedger(config);
 * 
 * // Create a commitment
 * const commitment = await ledger.createCommitment({
 *   taskId: 'task-123',
 *   agentId: 'agent-abc',
 *   outputHash: '0x...',
 *   bondedStake: 1000000n,
 * });
 * 
 * // Later, confirm it
 * await ledger.confirmCommitment(commitment.id, txSignature, slot);
 * ```
 */
export class CommitmentLedger extends EventEmitter {
  /**
   * Creates a new CommitmentLedger instance.
   * 
   * @param config - Configuration options
   * @param dependencyGraph - DependencyGraph instance for depth calculation
   * @throws {ConfigurationError} If config is invalid
   */
  constructor(config: CommitmentLedgerConfig, dependencyGraph: DependencyGraph);

  /**
   * Creates a new speculative commitment.
   * 
   * @param params - Commitment creation parameters
   * @returns The created commitment
   * @throws {InsufficientStakeError} If agent lacks required stake
   * @throws {DepthExceededError} If speculation depth exceeds limit
   * @throws {DuplicateCommitmentError} If commitment for task exists
   * @throws {ParentNotFoundError} If parent commitment doesn't exist
   * @throws {ParentInvalidStateError} If parent is not in valid state
   * 
   * @emits commitment.created
   * @emits stake.bonded
   */
  createCommitment(params: CreateCommitmentParams): PromiseSpeculativeCommitment>;

  /**
   * Retrieves a commitment by ID.
   * 
   * @param commitmentId - The commitment ID
   * @returns The commitment or undefined
   */
  getCommitment(commitmentId: CommitmentId): SpeculativeCommitment | undefined;

  /**
   * Retrieves a commitment by task ID.
   * 
   * @param taskId - The task ID
   * @returns The commitment or undefined
   */
  getCommitmentByTaskId(taskId: TaskId): SpeculativeCommitment | undefined;

  /**
   * Gets all commitments for an agent.
   * 
   * @param agentId - The agent ID
   * @param status - Optional status filter
   * @returns Array of commitments
   */
  getCommitmentsByAgent(
    agentId: AgentId,
    status?: CommitmentStatus
  ): SpeculativeCommitment[];

  /**
   * Gets all child commitments of a parent.
   * 
   * @param parentCommitmentId - The parent commitment ID
   * @returns Array of child commitments
   */
  getChildCommitments(parentCommitmentId: CommitmentId): SpeculativeCommitment[];

  /**
   * Confirms a commitment after on-chain verification.
   * 
   * @param commitmentId - The commitment to confirm
   * @param txSignature - On-chain transaction signature
   * @param slot - Slot when confirmed
   * @throws {CommitmentNotFoundError} If commitment doesn't exist
   * @throws {InvalidStateError} If commitment not in confirmable state
   * 
   * @emits commitment.confirmed
   * @emits stake.released
   */
  confirmCommitment(
    commitmentId: CommitmentId,
    txSignature: string,
    slot: number
  ): Promisevoid>;

  /**
   * Invalidates a commitment and triggers rollback.
   * 
   * @param commitmentId - The commitment to invalidate
   * @param reason - Reason for invalidation
   * @returns Array of invalidated commitment IDs (includes descendants)
   * @throws {CommitmentNotFoundError} If commitment doesn't exist
   * 
   * @emits commitment.invalidated (for each affected commitment)
   */
  invalidateCommitment(
    commitmentId: CommitmentId,
    reason: RollbackReason
  ): PromiseCommitmentId[]>;

  /**
   * Marks a commitment as expired.
   * 
   * @param commitmentId - The commitment to expire
   * @throws {CommitmentNotFoundError} If commitment doesn't exist
   * 
   * @emits commitment.expired
   * @emits stake.released
   */
  expireCommitment(commitmentId: CommitmentId): Promisevoid>;

  /**
   * Slashes stake for an invalid commitment.
   * 
   * @param commitmentId - The commitment to slash
   * @param reason - Reason for slashing
   * @returns Slash result with amounts
   * @throws {CommitmentNotFoundError} If commitment doesn't exist
   * @throws {AlreadySlashedError} If already slashed
   * 
   * @emits stake.slashed
   */
  slashCommitment(
    commitmentId: CommitmentId,
    reason: RollbackReason
  ): PromiseSlashResult>;

  /**
   * Gets the total bonded stake for an agent.
   * 
   * @param agentId - The agent ID
   * @returns Total bonded stake in lamports
   */
  getBondedStake(agentId: AgentId): Lamports;

  /**
   * Gets the available stake (max - bonded) for an agent.
   * 
   * @param agentId - The agent ID
   * @returns Available stake in lamports
   */
  getAvailableStake(agentId: AgentId): Lamports;

  /**
   * Calculates required stake for a given depth.
   * Uses formula: baseBond × (2 ^ depth)
   * 
   * @param depth - Speculation depth
   * @returns Required stake in lamports
   */
  calculateRequiredStake(depth: number): Lamports;

  /**
   * Checks if an agent is in cooldown after slash.
   * 
   * @param agentId - The agent ID
   * @returns Cooldown status
   */
  isAgentInCooldown(agentId: AgentId): AgentCooldownStatus;

  /**
   * Gets all active (non-confirmed/invalidated) commitments.
   * 
   * @returns Array of active commitments
   */
  getActiveCommitments(): SpeculativeCommitment[];

  /**
   * Gets commitments that are expiring soon.
   * 
   * @param withinMs - Time window in milliseconds
   * @returns Array of expiring commitments
   */
  getExpiringCommitments(withinMs: number): SpeculativeCommitment[];

  /**
   * Runs garbage collection on expired/old commitments.
   * 
   * @returns Number of commitments cleaned up
   */
  gc(): Promisenumber>;

  /**
   * Gets ledger statistics.
   * 
   * @returns Ledger statistics
   */
  getStats(): CommitmentLedgerStats;
}

/**
 * Parameters for creating a commitment.
 */
export interface CreateCommitmentParams {
  taskId: TaskId;
  agentId: AgentId;
  outputHash: string;
  inputStateHash: string;
  bondedStake?: Lamports; // If not provided, calculates from depth
}

/**
 * Configuration for CommitmentLedger.
 */
export interface CommitmentLedgerConfig {
  /** Stake configuration */
  stake: StakeConfig;
  
  /** Default commitment TTL (ms) */
  commitmentTtlMs: number;
  
  /** Maximum commitments per agent */
  maxCommitmentsPerAgent: number;
  
  /** GC interval (ms) */
  gcIntervalMs: number;
  
  /** How long to keep confirmed commitments */
  retainConfirmedMs: number;
}

/**
 * Result of a slash operation.
 */
export interface SlashResult {
  commitmentId: CommitmentId;
  agentId: AgentId;
  totalSlashed: Lamports;
  protocolShare: Lamports;
  affectedAgentsShare: Lamports;
  affectedAgents: Array<{
    agentId: AgentId;
    share: Lamports;
    wastedComputeMs: number;
  }>;
}

/**
 * Agent cooldown status.
 */
export interface AgentCooldownStatus {
  inCooldown: boolean;
  cooldownEndsAt?: TimestampMs;
  remainingMs?: number;
  reason?: RollbackReason;
}

/**
 * Commitment ledger statistics.
 */
export interface CommitmentLedgerStats {
  totalCommitments: number;
  activeCommitments: number;
  confirmedCommitments: number;
  invalidatedCommitments: number;
  totalBondedStake: Lamports;
  totalSlashedStake: Lamports;
  avgDepth: number;
  maxDepth: number;
  commitmentsByStatus: RecordCommitmentStatus, number>;
}

/**
 * Manages proof generation jobs with deferral for ancestor dependencies.
 * Ensures proofs are only submitted when all ancestors are confirmed.
 * 
 * @example
 * ```typescript
 * const manager = new ProofDeferralManager(config);
 * 
 * // Queue a proof job
 * const job = await manager.queueProofJob({
 *   taskId: 'task-123',
 *   commitmentId: 'commitment-456',
 *   inputs: { ... },
 * });
 * 
 * // Check deferred status
 * const status = manager.getDeferredStatus(job.id);
 * ```
 */
export class ProofDeferralManager extends EventEmitter {
  /**
   * Creates a new ProofDeferralManager instance.
   * 
   * @param config - Configuration options
   * @param commitmentLedger - CommitmentLedger for ancestor tracking
   * @throws {ConfigurationError} If config is invalid
   */
  constructor(config: ProofDeferralConfig, commitmentLedger: CommitmentLedger);

  /**
   * Queues a proof generation job.
   * Job will be deferred if ancestors are not yet confirmed.
   * 
   * @param params - Job parameters
   * @returns The created job
   * @throws {DuplicateJobError} If job for task already exists
   * @throws {QueueFullError} If queue is at capacity
   * 
   * @emits proof.job.queued
   * @emits proof.job.deferred (if ancestors pending)
   */
  queueProofJob(params: QueueProofJobParams): PromiseProofGenerationJob>;

  /**
   * Gets a proof job by ID.
   * 
   * @param jobId - The job ID
   * @returns The job or undefined
   */
  getJob(jobId: string): ProofGenerationJob | undefined;

  /**
   * Gets a proof job by task ID.
   * 
   * @param taskId - The task ID
   * @returns The job or undefined
   */
  getJobByTaskId(taskId: TaskId): ProofGenerationJob | undefined;

  /**
   * Gets the deferral status of a job.
   * 
   * @param jobId - The job ID
   * @returns Deferral status or undefined if not deferred
   */
  getDeferredStatus(jobId: string): DeferredProofStatus | undefined;

  /**
   * Notifies the manager that an ancestor was confirmed.
   * May trigger deferred jobs to proceed.
   * 
   * @param commitmentId - The confirmed commitment
   * @returns Jobs that are now ready to proceed
   * 
   * @emits proof.job.started (for each unblocked job)
   */
  onAncestorConfirmed(commitmentId: CommitmentId): PromiseProofGenerationJob[]>;

  /**
   * Notifies the manager that an ancestor failed.
   * Cancels all dependent jobs.
   * 
   * @param commitmentId - The failed commitment
   * @param reason - Reason for failure
   * @returns Jobs that were cancelled
   * 
   * @emits proof.job.failed (for each cancelled job)
   */
  onAncestorFailed(
    commitmentId: CommitmentId,
    reason: RollbackReason
  ): PromiseProofGenerationJob[]>;

  /**
   * Cancels a proof job.
   * 
   * @param jobId - The job to cancel
   * @param reason - Reason for cancellation
   * @throws {JobNotFoundError} If job doesn't exist
   * @throws {JobNotCancellableError} If job is already completed
   * 
   * @emits proof.job.failed
   */
  cancelJob(jobId: string, reason: string): Promisevoid>;

  /**
   * Retries a failed job.
   * 
   * @param jobId - The job to retry
   * @returns The updated job
   * @throws {JobNotFoundError} If job doesn't exist
   * @throws {MaxRetriesExceededError} If retry limit reached
   * @throws {JobNotRetryableError} If job is not in failed state
   */
  retryJob(jobId: string): PromiseProofGenerationJob>;

  /**
   * Gets all jobs in a given status.
   * 
   * @param status - Status filter
   * @returns Array of matching jobs
   */
  getJobsByStatus(status: ProofJobStatus): ProofGenerationJob[];

  /**
   * Gets the current queue depth.
   * 
   * @returns Number of jobs in queue
   */
  getQueueDepth(): number;

  /**
   * Gets the number of deferred jobs.
   * 
   * @returns Number of deferred jobs
   */
  getDeferredCount(): number;

  /**
   * Gets statistics about proof generation.
   * 
   * @returns Proof manager statistics
   */
  getStats(): ProofDeferralStats;

  /**
   * Starts the proof generation worker pool.
   */
  start(): Promisevoid>;

  /**
   * Stops the worker pool gracefully.
   * 
   * @param timeoutMs - Max time to wait for in-progress jobs
   */
  stop(timeoutMs?: number): Promisevoid>;

  /**
   * Pauses accepting new jobs (in-progress jobs continue).
   */
  pause(): void;

  /**
   * Resumes accepting new jobs.
   */
  resume(): void;
}

/**
 * Parameters for queuing a proof job.
 */
export interface QueueProofJobParams {
  taskId: TaskId;
  commitmentId: CommitmentId;
  inputs: ProofInputs;
  priority?: number;
}

/**
 * Configuration for ProofDeferralManager.
 */
export interface ProofDeferralConfig {
  /** Proof generation settings */
  proof: ProofConfig;
  
  /** Maximum queue size */
  maxQueueSize: number;
  
  /** Maximum deferred jobs */
  maxDeferredJobs: number;
  
  /** How often to check deferred jobs (ms) */
  deferralCheckIntervalMs: number;
  
  /** Timeout for waiting on ancestors (ms) */
  ancestorWaitTimeoutMs: number;
}

/**
 * Statistics for proof deferral.
 */
export interface ProofDeferralStats {
  totalJobsQueued: number;
  totalJobsCompleted: number;
  totalJobsFailed: number;
  totalJobsDeferred: number;
  currentQueueDepth: number;
  currentDeferredCount: number;
  avgGenerationTimeMs: number;
  avgWaitTimeMs: number;
  successRate: number;
  workerUtilization: number;
  jobsByStatus: RecordProofJobStatus, number>;
}

/**
 * Orchestrates rollback of speculative execution chains.
 * Ensures rollback happens in correct order (leaves first).
 * 
 * @example
 * ```typescript
 * const controller = new RollbackController(config, dependencyGraph, commitmentLedger);
 * 
 * // Trigger rollback when ancestor fails
 * const result = await controller.rollback(failedCommitmentId, RollbackReason.ANCESTOR_PROOF_FAILED);
 * 
 * console.log(`Rolled back ${result.rolledBackTasks.length} tasks`);
 * ```
 */
export class RollbackController extends EventEmitter {
  /**
   * Creates a new RollbackController instance.
   * 
   * @param config - Configuration options
   * @param dependencyGraph - DependencyGraph for traversal
   * @param commitmentLedger - CommitmentLedger for commitment updates
   * @param proofDeferralManager - ProofDeferralManager for job cancellation
   */
  constructor(
    config: RollbackControllerConfig,
    dependencyGraph: DependencyGraph,
    commitmentLedger: CommitmentLedger,
    proofDeferralManager: ProofDeferralManager
  );

  /**
   * Initiates a rollback from a failed commitment.
   * Rolls back all dependent speculative work in reverse topological order.
   * 
   * @param triggerCommitmentId - The commitment that failed
   * @param reason - Why the rollback is happening
   * @returns Complete rollback result
   * @throws {RollbackInProgressError} If rollback already in progress for this chain
   * @throws {CommitmentNotFoundError} If trigger commitment doesn't exist
   * 
   * @emits rollback.started
   * @emits rollback.task.reverted (for each task)
   * @emits rollback.completed
   */
  rollback(
    triggerCommitmentId: CommitmentId,
    reason: RollbackReason
  ): PromiseRollbackResult>;

  /**
   * Performs a dry-run of rollback without making changes.
   * Useful for impact analysis.
   * 
   * @param triggerCommitmentId - The commitment that would fail
   * @returns Simulated rollback result
   */
  simulateRollback(triggerCommitmentId: CommitmentId): PromiseRollbackSimulation>;

  /**
   * Checks if a rollback is currently in progress.
   * 
   * @param commitmentId - Optional commitment to check
   * @returns Whether rollback is in progress
   */
  isRollbackInProgress(commitmentId?: CommitmentId): boolean;

  /**
   * Gets the status of an ongoing rollback.
   * 
   * @param rollbackId - The rollback operation ID
   * @returns Current rollback status or undefined
   */
  getRollbackStatus(rollbackId: string): RollbackStatus | undefined;

  /**
   * Cancels an in-progress rollback (if possible).
   * Only works in early stages before state changes.
   * 
   * @param rollbackId - The rollback to cancel
   * @throws {RollbackNotCancellableError} If rollback has progressed too far
   */
  cancelRollback(rollbackId: string): Promisevoid>;

  /**
   * Gets history of completed rollbacks.
   * 
   * @param limit - Maximum results to return
   * @param offset - Offset for pagination
   * @returns Array of rollback results
   */
  getRollbackHistory(limit?: number, offset?: number): RollbackResult[];

  /**
   * Gets statistics about rollbacks.
   * 
   * @returns Rollback statistics
   */
  getStats(): RollbackControllerStats;
}

/**
 * Configuration for RollbackController.
 */
export interface RollbackControllerConfig {
  /** Rollback policy */
  policy: RollbackPolicy;
  
  /** Maximum concurrent rollbacks */
  maxConcurrentRollbacks: number;
  
  /** Timeout for rollback operations (ms) */
  rollbackTimeoutMs: number;
  
  /** Whether to preserve state snapshots */
  preserveSnapshots: boolean;
  
  /** Grace period before forcing (ms) */
  gracePeriodMs: number;
  
  /** Whether to notify affected agents */
  notifyAgents: boolean;
  
  /** Maximum rollback cascade size */
  maxCascadeSize: number;
  
  /** How long to retain rollback history */
  historyRetentionMs: number;
}

/**
 * Simulated rollback result (without actual changes).
 */
export interface RollbackSimulation {
  triggerCommitmentId: CommitmentId;
  affectedTasks: TaskId[];
  affectedCommitments: CommitmentId[];
  estimatedDurationMs: number;
  totalStakeAtRisk: Lamports;
  totalComputeAtRisk: number;
  maxCascadeDepth: number;
  affectedAgents: AgentId[];
}

/**
 * Status of an in-progress rollback.
 */
export interface RollbackStatus {
  rollbackId: string;
  phase: RollbackPhase;
  progress: number; // 0-100
  tasksRolledBack: number;
  totalTasksToRollback: number;
  startedAt: TimestampMs;
  estimatedCompletionMs: number;
  currentTask?: TaskId;
  errors: RollbackError[];
}

/**
 * Statistics about rollbacks.
 */
export interface RollbackControllerStats {
  totalRollbacks: number;
  successfulRollbacks: number;
  failedRollbacks: number;
  totalTasksRolledBack: number;
  totalStakeSlashed: Lamports;
  totalComputeWasted: number;
  avgRollbackDurationMs: number;
  avgCascadeDepth: number;
  rollbacksByReason: RecordRollbackReason, number>;
  activeRollbacks: number;
}

/**
 * High-level orchestrator for speculative task execution.
 * Coordinates all components and makes speculation decisions.
 * 
 * @example
 * ```typescript
 * const scheduler = new SpeculativeTaskScheduler(config);
 * 
 * // Start the scheduler
 * await scheduler.start();
 * 
 * // Submit a task for scheduling
 * const decision = await scheduler.scheduleTask(task, 'parent-task-id');
 * 
 * if (decision.shouldSpeculate) {
 *   console.log(`Speculating at depth ${decision.depth}`);
 * }
 * ```
 */
export class SpeculativeTaskScheduler extends EventEmitter {
  /**
   * Creates a new SpeculativeTaskScheduler instance.
   * 
   * @param config - Complete speculation configuration
   */
  constructor(config: SpeculationConfig);

  /**
   * Starts the scheduler and all sub-components.
   * 
   * @throws {AlreadyStartedError} If already running
   */
  start(): Promisevoid>;

  /**
   * Stops the scheduler gracefully.
   * Waits for in-progress operations to complete.
   * 
   * @param timeoutMs - Maximum time to wait
   */
  stop(timeoutMs?: number): Promisevoid>;

  /**
   * Pauses scheduling (in-progress work continues).
   * 
   * @param reason - Reason for pausing
   * 
   * @emits system.paused
   */
  pause(reason: string): void;

  /**
   * Resumes scheduling after pause.
   * 
   * @emits system.resumed
   */
  resume(): void;

  /**
   * Schedules a task for execution, deciding whether to speculate.
   * 
   * @param task - The task to schedule
   * @param dependsOn - Optional parent task ID
   * @returns Speculation decision
   * @throws {SchedulerNotRunningError} If scheduler is stopped
   * @throws {TaskValidationError} If task is invalid
   * 
   * @emits speculation.decision
   * @emits task.added
   * @emits commitment.created (if speculating)
   */
  scheduleTask(task: TaskNode, dependsOn?: TaskId): PromiseSpeculationDecision>;

  /**
   * Manually triggers evaluation of speculation decision.
   * 
   * @param taskId - Task to evaluate
   * @returns Updated speculation decision
   */
  evaluateSpeculation(taskId: TaskId): PromiseSpeculationDecision>;

  /**
   * Reports task completion.
   * 
   * @param taskId - Completed task
   * @param output - Task output
   * @throws {TaskNotFoundError} If task doesn't exist
   * 
   * @emits task.completed
   * @emits proof.job.queued
   */
  reportCompletion(taskId: TaskId, output: TaskOutput): Promisevoid>;

  /**
   * Reports task failure.
   * 
   * @param taskId - Failed task
   * @param error - Error details
   * @throws {TaskNotFoundError} If task doesn't exist
   * 
   * @emits task.failed
   * @emits rollback.started (if speculative)
   */
  reportFailure(taskId: TaskId, error: Error): Promisevoid>;

  /**
   * Reports on-chain confirmation of a task's proof.
   * 
   * @param taskId - Confirmed task
   * @param txSignature - Transaction signature
   * @param slot - Confirmation slot
   * 
   * @emits commitment.confirmed
   * @emits proof.verified
   */
  reportConfirmation(
    taskId: TaskId,
    txSignature: string,
    slot: number
  ): Promisevoid>;

  /**
   * Gets the next batch of tasks ready for execution.
   * 
   * @param maxTasks - Maximum tasks to return
   * @param includeSpeculative - Include speculatively ready tasks
   * @returns Array of ready tasks
   */
  getReadyTasks(maxTasks?: number, includeSpeculative?: boolean): TaskNode[];

  /**
   * Gets the current state of a task.
   * 
   * @param taskId - Task to query
   * @returns Task state or undefined
   */
  getTaskState(taskId: TaskId): TaskState | undefined;

  /**
   * Gets the full speculation chain for a task.
   * 
   * @param taskId - Task to query
   * @returns Speculation chain details
   */
  getSpeculationChain(taskId: TaskId): SpeculationChain;

  /**
   * Updates configuration at runtime.
   * 
   * @param config - Partial config to update
   * @throws {InvalidConfigError} If config is invalid
   * 
   * @emits system.config.changed
   */
  updateConfig(config: PartialSpeculationConfig>): void;

  /**
   * Gets the current configuration.
   * 
   * @returns Current config
   */
  getConfig(): SpeculationConfig;

  /**
   * Gets comprehensive statistics.
   * 
   * @returns Scheduler statistics
   */
  getStats(): SchedulerStats;

  /**
   * Gets health status of all components.
   * 
   * @returns Health check result
   */
  healthCheck(): HealthCheckResult;

  // Component accessors
  readonly dependencyGraph: DependencyGraph;
  readonly commitmentLedger: CommitmentLedger;
  readonly proofDeferralManager: ProofDeferralManager;
  readonly rollbackController: RollbackController;
}

/**
 * Task output after completion.
 */
export interface TaskOutput {
  outputHash: string;
  executionTrace: Uint8Array;
  computeTimeMs: number;
  gasUsed?: bigint;
  logs?: string[];
}

/**
 * Complete task state.
 */
export interface TaskState {
  task: TaskNode;
  commitment?: SpeculativeCommitment;
  proofJob?: ProofGenerationJob;
  speculationDecision?: SpeculationDecision;
  rollbackResult?: RollbackResult;
}

/**
 * Speculation chain details.
 */
export interface SpeculationChain {
  taskId: TaskId;
  depth: number;
  ancestors: Array<{
    taskId: TaskId;
    commitmentId: CommitmentId;
    status: CommitmentStatus;
    proofState: ProofState;
  }>;
  descendants: Array<{
    taskId: TaskId;
    commitmentId: CommitmentId;
    status: CommitmentStatus;
  }>;
  totalStakeBonded: Lamports;
  estimatedConfirmationMs: number;
}

/**
 * Comprehensive scheduler statistics.
 */
export interface SchedulerStats {
  uptime: number;
  tasksScheduled: number;
  tasksCompleted: number;
  tasksFailed: number;
  speculativeExecutions: number;
  confirmations: number;
  rollbacks: number;
  avgSpeculationDepth: number;
  maxSpeculationDepth: number;
  avgConfirmationTimeMs: number;
  throughputTasksPerSecond: number;
  latencyReduction: number; // Percentage improvement from speculation
  graph: DependencyGraphStats;
  ledger: CommitmentLedgerStats;
  proofs: ProofDeferralStats;
  rollbackController: RollbackControllerStats;
}

/**
 * Health check result.
 */
export interface HealthCheckResult {
  healthy: boolean;
  components: Recordstring, ComponentHealth>;
  issues: string[];
  lastCheck: TimestampMs;
}

/**
 * Health of a single component.
 */
export interface ComponentHealth {
  name: string;
  healthy: boolean;
  status: 'running' | 'paused' | 'stopped' | 'error';
  lastActivity: TimestampMs;
  errorCount: number;
  latencyMs?: number;
}

import { EventEmitter } from 'events';

/**
 * Type-safe event emitter for speculation events.
 */
export interface TypedEventEmitterEvents extends Recordstring, unknown>> {
  onE extends keyof Events>(event: E, listener: (payload: Events[E]) => void): this;
  onceE extends keyof Events>(event: E, listener: (payload: Events[E]) => void): this;
  offE extends keyof Events>(event: E, listener: (payload: Events[E]) => void): this;
  emitE extends keyof Events>(event: E, payload: Events[E]): boolean;
}

/**
 * Map of event names to payload types.
 */
export interface SpeculationEvents {
  // Task events
  'task.added': TaskAddedPayload;
  'task.ready': TaskReadyPayload;
  'task.started': TaskStartedPayload;
  'task.completed': TaskCompletedPayload;
  'task.failed': TaskFailedPayload;
  
  // Commitment events
  'commitment.created': CommitmentCreatedPayload;
  'commitment.confirmed': CommitmentConfirmedPayload;
  'commitment.expired': CommitmentExpiredPayload;
  'commitment.invalidated': CommitmentInvalidatedPayload;
  
  // Proof events
  'proof.job.queued': ProofJobQueuedPayload;
  'proof.job.started': ProofJobStartedPayload;
  'proof.job.completed': ProofJobCompletedPayload;
  'proof.job.failed': ProofJobFailedPayload;
  'proof.job.deferred': ProofJobDeferredPayload;
  'proof.submitted': ProofSubmittedPayload;
  'proof.verified': ProofVerifiedPayload;
  
  // Rollback events
  'rollback.started': RollbackStartedPayload;
  'rollback.task.reverted': RollbackTaskRevertedPayload;
  'rollback.completed': RollbackCompletedPayload;
  'rollback.failed': RollbackFailedPayload;
  
  // Stake events
  'stake.bonded': StakeBondedPayload;
  'stake.released': StakeReleasedPayload;
  'stake.slashed': StakeSlashedPayload;
  
  // Decision events
  'speculation.decision': SpeculationDecisionPayload;
  
  // System events
  'system.depth.limit': DepthLimitReachedPayload;
  'system.resource.limit': ResourceLimitReachedPayload;
  'system.config.changed': ConfigChangedPayload;
  'system.paused': SystemPausedPayload;
  'system.resumed': SystemResumedPayload;
}