docs/core.md

### Core Module — Domain and Scheduling Algorithm

Directory: `scheduler/core/`

This package defines the domain objects (cases, hearings, courtrooms, judges), the ripeness classifier, policy interfaces, and the main scheduling algorithm that orchestrates daily scheduling.

#### Files overview

- `algorithm.py`
  - Purpose: Implements the daily scheduling pipeline.
  - Key classes:
    - `SchedulingResult`: Aggregates scheduled cases, unscheduled reasons, applied overrides, and explanations.
    - `SchedulingAlgorithm`: Orchestrates the day’s scheduling.
      - `schedule_day(cases, courtrooms, current_date, overrides, preferences, max_explanations_unscheduled)`
        - Flow:
          1) Compute judge preference overrides (if provided).
          2) Filter by ripeness (via `RipenessClassifier`), tracking unscheduled reasons for unripe cases.
          3) Filter eligibility (age gaps, disposed, same‑day constraints) and compute priority.
          4) Apply manual overrides (add/remove cases; capacity changes).
          5) Allocate cases to courtrooms (via allocator interface used in simulation layer).
          6) Generate explanations for unscheduled cases (up to cap) and successful allocations.
        - Inputs: list of `Case`, list of `Courtroom`, `date`, optional `Override` list, optional `JudgePreferences`.
        - Outputs: `SchedulingResult` with scheduled list and explanations.
      - Internal helpers: `_filter_by_ripeness`, `_filter_eligible`, `_get_preference_overrides`, `_apply_manual_overrides`, `_allocate_cases`, `_clear_temporary_case_flags`.
  - Interactions: `core.ripeness`, `control.overrides`, `simulation.allocator`.

- `case.py`
  - Purpose: Core case model and priority logic.
  - Key classes:
    - `CaseStatus`: Enum of lifecycle statuses.
    - `Case`: Fields describe type, stage, history, last hearing, etc.
      - Selected methods: `progress_to_stage`, `record_hearing`, `update_age`, `compute_readiness_score`, `is_ready_for_scheduling`, `needs_alert`, `get_priority_score`, `mark_unripe`, `mark_ripe`, `mark_scheduled`, `is_disposed`, `to_dict`.
  - Interactions: Used by ripeness classifier, scheduler, and simulation.

- `courtroom.py`
  - Purpose: Represents courtroom capacity and scheduling slots.
  - Typical members: courtroom identifier, capacity/availability for a given `date`.
  - Interactions: Allocator consumes courtroom capacity when placing cases.

- `hearing.py`
  - Purpose: Hearing record representation (date, outcome, adjournment, etc.).
  - Interactions: Case history and scheduler eligibility checks (min gap, outcomes).

- `judge.py`
  - Purpose: Judge metadata and optional preference hooks.
  - Interactions: `control.overrides.JudgePreferences` integrates with algorithm preference overrides.

- `policy.py`
  - Purpose: Defines the scheduling policy interface and default implementations for prioritization heuristics.
  - Interactions: Injected into `SchedulingAlgorithm` to determine case ordering.

- `ripeness.py`
  - Purpose: Ripeness classifier and thresholds.
  - Key elements:
    - `RipenessStatus` enum with helpers `is_ripe()` and `is_unripe()`.
    - `RipenessClassifier` with methods:
      - `classify(case, current_date)`: returns `RipenessStatus` and sets reasons.
      - `get_ripeness_priority(case, current_date)`: numeric priority for scheduling.
      - `is_schedulable(case, current_date)`: boolean gate for eligibility.
      - `get_ripeness_reason(status)`: human‑readable reason strings.
      - `estimate_ripening_time(case, current_date)`: expected time until ready.
      - `set_thresholds(new_thresholds)`, `get_current_thresholds()`.
  - Interactions: Used both by `algorithm.py` and the simulation engine.

#### Core flow (within `SchedulingAlgorithm.schedule_day`)
1) Collect inputs (cases, courtrooms, date, optional overrides/preferences).  
2) Ripeness filter: mark unripe with reasons; compute ripeness‑based priority.  
3) Eligibility filter: ensure min gap since last hearing, exclude disposed, enforce capacity constraints.  
4) Apply overrides (manual changes and judge preferences).  
5) Allocate to courtrooms; finalize schedule.  
6) Produce explanations and a `SchedulingResult`.