myxce/.kiro/specs/scheduler-sim-decision-parity/requirements.md

# Requirements Document

## Introduction
The scheduler's `.replay`-driven simulation mode (`--sim`/`--interactive`) exists so operators can debug and tune scheduling behavior against recorded production data, trusting that a replay reproduces what actually happened. That trust currently does not hold for any job already resolved (dispatched, pended, or preempted) *before* a given point in the replay: its resource usage is never reflected in worker/shared resource-in-use totals, and its decision is never visible in decision output — because the recorded decision stream, though fully decoded every round, is only ever used for optional `--sim-verify` comparison, never applied to reconstruct state or report the decision otherwise. This feature restores decision *and* resource-accounting state parity between the normal-mode and simulation-mode drivers, per the constraint documented in `.kiro/steering/scheduler-driver-equivalence.md`.

## Boundary Context
- **In scope**: resource-in-use accounting correctness during simulation-mode execution (interactive and batch); capacity-awareness correctness of simulation-mode scheduling decisions under resource contention; decision visibility (through existing decision-reporting channels) for jobs already resolved in the original recording; graceful behavior when recorded decision data for a job is unavailable.
- **Out of scope**: any change to REPL console output formatting (owned by the sibling `scheduler-sim-repl-verbosity` spec); any new inspectable data or REPL command (owned by the sibling `scheduler-sim-diagnostics` brief); any change to `--sim-verify`'s comparison logic itself, beyond not producing a false mismatch as a side effect of this feature; any change to scheduling/allocation policy; any change to normal-mode (non-simulation) behavior.
- **Adjacent expectations**: this feature restores an invariant `scheduler-core` (implementation-complete) was already expected to uphold; it does not reopen or modify that spec. `scheduler-sim-repl-verbosity`'s round-summary decision counts depend on decisions being reported through the same channel this feature restores, but that spec does not depend on this one to ship.

## Requirements

### Requirement 1: Accurate resource-usage reporting in simulation mode
**Objective:** As an operator inspecting simulation-mode resource state, I want per-worker and shared resource usage to reflect every currently-running job, so that what I inspect during a replay is trustworthy.

#### Acceptance Criteria
1. While a job is in a running state during simulation-mode execution, the scheduler shall include that job's resource consumption in its worker's resource-in-use total.
2. While a job is in a running state during simulation-mode execution, the scheduler shall include that job's resource consumption in any shared resource's resource-in-use total it consumes from.
3. When a scheduling round completes, the scheduler shall refresh resource-in-use totals to reflect every currently-running job, not only jobs whose resource consumption was already reflected in an earlier round.
4. When replaying a recorded run in simulation mode, the scheduler shall report the same resource-in-use totals as normal-mode execution reported at the equivalent point in the original run.

### Requirement 2: Correct capacity awareness under resource contention in simulation mode
**Objective:** As an operator relying on simulation mode to reflect realistic scheduling outcomes, I want the scheduler's capacity checks during simulation-mode execution to account for resources already consumed by running jobs, so that simulated scheduling behavior matches live behavior under contention.

#### Acceptance Criteria
1. While resource capacity is already consumed by running jobs, when the scheduler evaluates whether a job fits on a worker during simulation-mode execution, the scheduler shall treat that already-consumed capacity as unavailable, the same way normal-mode execution does.
2. The scheduler shall not make a simulation-mode scheduling decision that normal-mode execution of the same recorded state would not also make.

### Requirement 3: Decision visibility for jobs resolved before replay began
**Objective:** As an operator watching simulation-mode decision output, I want to see a decision for every job the replay reaches, including jobs already resolved in the original run, so I have a complete picture of scheduling activity.

#### Acceptance Criteria
1. When a job was dispatched, pended, or preempted in the original recorded run and simulation-mode replay reaches the point that event occurred, the scheduler shall make that decision observable through the same decision-reporting channel used for a freshly-computed decision.
2. The scheduler shall preserve the original decision's type and resource-allocation detail when reporting it during replay.
3. When simulation-mode independently computes a fresh decision for a job in a given round, the scheduler shall report only that one decision for the job in that round, not also a duplicate from the recorded stream.

### Requirement 4: Graceful degradation when recorded decision data is unavailable
**Objective:** As an operator running simulation mode against an incomplete or older recording, I want the scheduler to degrade gracefully rather than fail, so a data gap in one job's history doesn't block inspection of the rest of the replay.

#### Acceptance Criteria
1. If a job's originating decision cannot be found in the recorded data when simulation-mode needs it to report or account for that job, the scheduler shall report that job's resource usage as unavailable rather than fabricating a value.
2. If a job's originating decision cannot be found in the recorded data, the scheduler shall continue processing the remainder of the replay without terminating.

### Requirement 5: No regression to existing driver-equivalence and verification guarantees
**Objective:** As a maintainer relying on existing scheduler guarantees, I want this fix to preserve them, so existing verification workflows and tests continue to hold.

#### Acceptance Criteria
1. The scheduler shall continue to produce identical decisions between interactive (step-by-step) and batch simulation execution modes.
2. The scheduler shall continue to support decision verification mode (comparing freshly-computed decisions against recorded ones) without reporting a mismatch caused by this feature's own behavior.
3. While simulation mode is not enabled, the scheduler shall not change its existing resource-accounting or decision-reporting behavior.