diff --git a/src/scheduler/CLAUDE.md b/src/scheduler/CLAUDE.md index c2e6e63b..e905f136 100644 --- a/src/scheduler/CLAUDE.md +++ b/src/scheduler/CLAUDE.md @@ -16,6 +16,15 @@ C-based job scheduling engine with a plugin architecture. Determines job-to-node - **Replay/recording** — `recording.c`/`recording_events.c`/`recording_session.c` (live capture) and `sim.c`/`sim_loop.c` (simulation-side decode) do the actual capnp encode/decode of the `.replay` binary stream (`src/schema/controller.capnp`); `snapshot.c`/`snapshot_wire.c`/`snapshot_load.c` only populate/consume the plain in-memory `sched_snapshot_data_t` struct that `recording.c`'s `write_snapshot_entry()` then serializes — no capnp or file I/O lives in the snapshot files themselves. Controlled via `OPCode_schedAdmin` (`src/controller/cluster.c`) and `xceadmin scheduler record start|stop|status` / `scheduler dump `. - **Interactive REPL** (`repl.c`/`repl_break.c`/`repl_info.c`/`repl_params.c`, `--interactive`) — single-step/breakpoint/state-inspection/snapshot-capture control over the simulation driver; drives the exact same `sched_sim_driver_run()` as batch `--sim`, gated only by `sim->interactive`, so REPL and batch runs are decision-equivalent by construction (`test_repl_equivalence.c`). +- **Decision trace** (`scheduler-sim-decision-trace`, simulator REPL only) — `include/sched/trace.h` is the public interface and the `SCHED_TRACE(core, call)` hook macro, which evaluates `call` only while `core->trace_rec` is set; live never sets it, so hooks cost one pointer test. The sources are split to stay under the line cap: + - `sched_trace.c`: the record, its arena, the entry sequence and line budget, and requirement/plan/check entries. + - `sched_trace_scan.c`: positions, host verdicts and rows, summary tallies, rollback, commit and search end. + - `sched_trace_capture.c`: copies selection facts, cluster-wide limits, check rows and attempt reasons out of scheduler state. + - `sched_trace_outcome.c`: dispatch and pend outcomes, and reconstructed-dispatch records. + - `sched_trace_internal.h`: helpers shared between those files (`sti_` prefix). + + None of them may use stdio, file I/O or logging, and none belongs in `sched_core_isolation_lib`; `test_core_isolation.c` scans all five. Every white-box test that `#include`s a hooked source (resource, host_iter, alloc_runner, scheduler, sched_election, driver) must also `#include` the four trace `.c` files, exactly once. + Links against `libxce` from `src/lib/`. Full design/requirements: `.kiro/specs/scheduler-core/`. ## Conventions