docs/simulation.md

### Simulation Module — Engine, Allocator, and Policies

Directory: `scheduler/simulation/`

This package provides a discrete‑event simulation of the court scheduling system. It generates synthetic case flows (or consumes real‑like parameters), evaluates scheduling/ripeness policies, and produces quantitative outputs and reports.

#### Files overview

- `engine.py`
  - Purpose: Main simulation loop and state transition engine.
  - Key classes:
    - `CourtSimConfig`: Parameters (capacity, stage transition matrices, adjournment params, filings, horizon, etc.).
    - `CourtSimResult`: Aggregated outputs produced by a run.
    - `CourtSim`: The engine orchestrating daily cycles:
      - `_init_stage_ready()`: initializes stage readiness from configuration.
      - `_evaluate_ripeness(current)`: classify cases using `core.ripeness.RipenessClassifier`.
      - `_choose_cases_for_day(current)`: select candidates (potentially via policies/priority).
      - `_file_new_cases(current, n)`: generate new cases based on expected filings.
      - `_day_process(current)`: core daily loop combining filings, ripeness, scheduling, hearings, adjournments, and disposals.
      - `run()`: iterate over the configured horizon; write metrics and event logs.
  - Interactions: Uses domain models in `scheduler/core/*`, policies in `scheduler/simulation/policies/*`, and allocator.

- `allocator.py`
  - Purpose: Allocate prioritized cases to available courtroom capacity.
  - Typical responsibilities: respect per‑courtroom limits, avoid duplicate bookings, ensure eligibility constraints.
  - Interactions: Invoked by both the simulation engine and the core scheduling algorithm.

- `policies/`
  - Purpose: Pluggable case selection strategies.
  - Files:
    - `age.py`: age‑based prioritization (older cases first, possibly weighted).
    - `fifo.py`: first‑in first‑out ordering respecting readiness.
    - `readiness.py`: prioritization by computed readiness or ripeness score.
  - Interface: Each policy exposes a common callable/signature expected by `engine.py` and the core algorithm’s policy abstraction (`core/policy.py`).

#### Simulation flow (high level)
1) Initialize `CourtSimConfig` from data defaults and parameters.
2) Seed a case population and stage readiness.
3) For each simulated day: file new cases, evaluate ripeness, select cases, allocate to courtrooms, conduct hearings, sample adjournments/next stages/disposals.
4) Persist daily summaries, metrics, and event logs to `outputs/simulation_runs/<version_timestamp>/`.