/**
 * CAELFork + CAELDream — Phase 3: Counterfactual Forking and Offline Replay Perturbation
 *
 * ## Forking (Experiment 2: Counterfactual Planning)
 *
 * An agent at timestep T faces a decision. Instead of committing to one action,
 * it forks the simulation: same state, different actions. Each fork runs under
 * its own contract, producing its own CAEL trace. The agent compares outcomes
 * and chooses the better branch — with proof of both futures.
 *
 *   trace[0..T] → fork → branch A (action X) → outcome A (with provenance)
 *                       → branch B (action Y) → outcome B (with provenance)
 *
 * The fork point links both branches to the same parent hash. Replay of either
 * branch starts from the same verified state.
 *
 * ## Dreaming (Experiment 5: Offline Replay Perturbation)
 *
 * An agent replays its own CAEL trace with perturbations: ±10% load, ±5% material
 * properties, rotated geometry. Each dream is a valid contracted simulation —
 * not noise, but a physically grounded counterfactual. The SNN consolidates
 * across dreams, generalizing from experiences it never had in waking.
 *
 *   waking trace → perturb config → replay under contract → dream trace
 *                → perturb differently → replay → another dream trace
 *                → SNN consolidates across N dream traces
 *
 * Each dream trace has its own hash chain rooted at a dream-genesis entry
 * that references the original waking trace's run ID and fork point.
 */
import type { CAELRecorder } from './CAELRecorder';
import type { CAELTrace } from './CAELTrace';
import type { SimSolver } from './SimSolver';
import type { ContractConfig } from './SimulationContract';
import type { ActionDecision, CAELAgentConfig } from './CAELAgent';
/**
 * A fork point in a CAEL trace. Identifies where the timeline branches.
 */
export interface CAELForkPoint {
    /** Run ID of the original (parent) trace */
    parentRunId: string;
    /** Index in the parent trace where the fork occurs */
    forkIndex: number;
    /** Hash of the parent entry at fork point (integrity link) */
    parentHash: string;
    /** Simulation time at the fork */
    simTime: number;
}
/**
 * A completed fork branch with its outcome.
 */
export interface CAELForkBranch {
    /** Identifier for this branch (e.g., "branch-A", "reinforce-left") */
    branchId: string;
    /** The action that was taken in this branch */
    action: ActionDecision;
    /** The complete CAEL trace for this branch */
    trace: CAELTrace;
    /** JSONL export of the branch trace */
    jsonl: string;
    /** Summary metrics extracted from the final state */
    outcome: Record<string, unknown>;
}
/**
 * Result of a fork-compare-choose operation.
 */
export interface CAELForkResult {
    /** The fork point in the parent trace */
    forkPoint: CAELForkPoint;
    /** All branches that were explored */
    branches: CAELForkBranch[];
    /** Which branch was chosen (index into branches array) */
    chosenIndex: number;
    /** Why this branch was chosen */
    chosenReason: string;
}
/**
 * Factory that creates a solver from a config snapshot.
 * Used to reconstruct simulation state at a fork point.
 */
export type SolverFactory = (config: Record<string, unknown>) => SimSolver;
/**
 * Evaluates a branch outcome and returns a scalar utility.
 * Used by forkAndChoose to compare branches automatically.
 */
export type BranchEvaluator = (branch: CAELForkBranch, solver: SimSolver) => number;
/**
 * Fork a CAEL trace at a given index, creating a new recorder that
 * continues from the fork point with a different action.
 *
 * The new recorder's first entry is a special 'fork' interaction that
 * references the parent trace's run ID and fork hash, establishing
 * the provenance link between timelines.
 *
 * @param parentTrace The original CAEL trace (or JSONL string)
 * @param forkIndex Index in the trace to fork from
 * @param solverFactory Creates a new solver from the original config
 * @param contractConfig Contract configuration for the new branch
 * @returns A new CAELRecorder ready for the alternative timeline
 */
export declare function forkTrace(parentTrace: CAELTrace | string, forkIndex: number, solverFactory: SolverFactory, contractConfig?: ContractConfig): {
    recorder: CAELRecorder;
    forkPoint: CAELForkPoint;
};
/**
 * Fork-Compare-Choose: the complete counterfactual planning pattern.
 *
 * 1. Fork the trace at the decision point
 * 2. For each alternative action, run a branch forward N steps
 * 3. Evaluate each branch's outcome
 * 4. Choose the best branch
 * 5. Return all branches with provenance (the proof of both futures)
 *
 * @param parentTrace The original trace up to the decision point
 * @param forkIndex Where to fork
 * @param alternatives Actions to try in each branch
 * @param stepsPerBranch How many simulation steps to run per branch
 * @param dt Time delta per step
 * @param solverFactory Creates solvers for each branch
 * @param evaluator Scores each branch outcome
 * @param agentConfig Optional: run a full agent loop in each branch
 * @param contractConfig Contract config for branches
 */
export declare function forkAndChoose(parentTrace: CAELTrace | string, forkIndex: number, alternatives: ActionDecision[], stepsPerBranch: number, dt: number, solverFactory: SolverFactory, evaluator: BranchEvaluator, agentConfig?: CAELAgentConfig, contractConfig?: ContractConfig): Promise<CAELForkResult>;
/**
 * A perturbation applied to a simulation config for dreaming.
 */
export interface DreamPerturbation {
    /** What was perturbed */
    field: string;
    /** Original value */
    original: unknown;
    /** Perturbed value */
    perturbed: unknown;
    /** Perturbation magnitude (e.g., 0.1 for ±10%) */
    magnitude: number;
}
/**
 * Configuration for a dream session.
 */
export interface DreamConfig {
    /** Number of dream episodes to generate */
    episodeCount: number;
    /** Maximum perturbation magnitude (0.1 = ±10%) */
    maxPerturbation: number;
    /** Which config fields to perturb */
    perturbableFields: string[];
    /** Steps per dream episode */
    stepsPerEpisode: number;
    /** Time delta per step */
    dt: number;
    /** Random seed for reproducible dreams (optional) */
    seed?: number;
}
/**
 * Result of a single dream episode.
 */
export interface DreamEpisode {
    /** Episode index */
    index: number;
    /** Perturbations applied */
    perturbations: DreamPerturbation[];
    /** The dream's CAEL trace */
    trace: CAELTrace;
    /** JSONL export */
    jsonl: string;
    /** Whether the dream simulation converged/completed */
    completed: boolean;
}
/**
 * Result of a complete dream session.
 */
export interface DreamSession {
    /** The waking trace this dream session is based on */
    wakingRunId: string;
    /** All dream episodes */
    episodes: DreamEpisode[];
    /** Summary: how many completed, average perturbation magnitude */
    summary: {
        total: number;
        completed: number;
        avgPerturbation: number;
    };
}
/**
 * Run a dream session: replay a waking trace N times with random perturbations.
 *
 * Each dream episode:
 * 1. Clone the original config
 * 2. Apply random perturbations to specified fields
 * 3. Create a new contracted simulation with the perturbed config
 * 4. Run the simulation for the specified number of steps
 * 5. Record the dream's CAEL trace with a link to the waking trace
 *
 * The SNN agent (if provided via agentConfig) processes each dream,
 * accumulating experiences across physically grounded counterfactuals.
 *
 * @param wakingJSONL The waking trace to dream about
 * @param dreamConfig Dream session parameters
 * @param solverFactory Creates solvers for dream episodes
 * @param agentConfig Optional: run agent loop in dreams
 * @param contractConfig Contract config for dream simulations
 */
export declare function dream(wakingJSONL: string, dreamConfig: DreamConfig, solverFactory: SolverFactory, agentConfig?: CAELAgentConfig, contractConfig?: ContractConfig): Promise<DreamSession>;
//# sourceMappingURL=CAELFork.d.ts.map