myxce/.kiro/specs/scheduler-sim-discrete-clock/research.md

# Research & Design Decisions

## Summary
- **Feature**: `scheduler-sim-discrete-clock`
- **Discovery Scope**: Extension (light discovery): the simulator is already event-driven; the work is to pin its clock, retire a CLI option, remove a REPL parameter, and align docs/specs.
- **Key Findings**:
  - The core already has a frozen-clock mode: `xce_core_now() = virtual_clock_base + (monotonic_now - real_clock_base) * speed_num / speed_den` (`core_clock.c:80-119`), and `speed_num = 0` makes it return `virtual_clock_base` exactly. Every simulator test that runs a replay already uses it. Pinning simulation mode to 0/1 delivers Requirement 1 without touching the core formula.
  - In simulation mode exactly three places write the clock: `sim_set_virtual_clock()` at start (`sim.c:309-329`), `sim_advance_virtual_clock()` per event (`sim_loop.c:417`, after the `endSession` return) and per session `beginRound` (`sim_loop.c:1528`, before `xce_core_begin_session()` sets `session_start`). REPL `set output`/`snapshot` only read it. With speed 0 these are the only clock movements (Req 1.5), and `session_start`, the written `beginRound`, decision `ts` and `durationNs` all derive from `xce_core_now()` at `beginRound` (Req 1.4, 1.7, 1.8).
  - `parse_opt` runs before `mylog_init()` (`main.c:265` vs `:325`); a `WARN` issued before `mylog_init()` goes to stdout, not `--logfile`. The deprecation warning therefore belongs right after `mylog_init()` and before the `--sim` branch, which covers both modes.
  - `repl_cmd_set()` checks `ntok < 3` (`repl_params.c:400`) before dispatching on the parameter name, so bare `set speed` never reaches the speed branch today (Req 3.1 needs the name check first).

## Research Log

### Clock mechanics and who writes the clock atoms
- **Context**: Requirement 1 (event-driven clock) and whether `speed_num`/`speed_den` can be dropped from the core.
- **Sources Consulted**: `src/scheduler/src/core_clock.c`, `include/core.h:264-302,706-716`, `core.c:130-143`, `sim.c:309-329,594`, `sim_loop.c:175-202,411-417,1520-1545`, `repl_params.c:202-226`, `scheduler.c:757`.
- **Findings**: Writers of the four atoms: core init (speed 1/1), `xce_core_set_wallclock_anchor()` (normal mode, 1/1), `sim_set_virtual_clock()` (sim start, `speed_num = args->sim_speed`), `sim_advance_virtual_clock()` (bases only), `repl_set_speed()` (speed). No production code reads `speed_num`/`speed_den` except `xce_core_now()`. Normal mode is always 1/1.
- **Implications**: Removing the fields from the core would need a replacement freeze flag and would churn 28 test files and the core-isolation surface for no behavioral gain. Keep them; simulation mode sets 0/1 unconditionally; nothing else ever sets another value.

### CLI parsing and logging order
- **Context**: Requirement 2 (deprecated no-op in both modes, one warning naming the last value).
- **Sources Consulted**: `src/scheduler/src/main.c:53,74,92-94,149-151,265-400`; `src/include/utils.h:154-160`; vendored tlog early-print path.
- **Findings**: `--sim-speed` is stored as a raw string; argp keeps the last occurrence; a trailing `--sim-speed` with no value is an argp error. Validation (`strtoull`, exit 1) happens only in the `--sim` branch; normal mode ignores the option silently. Logging before `mylog_init()` goes to stdout.
- **Implications**: Drop the numeric validation and the `sim_args.sim_speed` plumbing; warn once after `mylog_init()`. `main()` is not unit-testable, so the warning goes in a small function a test can call with the existing `capture_stdout_around()` pattern (`test_repl_help.c:437-460`; test binaries never call `mylog_init()`, so `WARN` reaches stdout — `test_scheduler_decision_publish_retry.c:61-70`).

### REPL surface
- **Context**: Requirement 3.
- **Sources Consulted**: `repl_params.c:171-226,388-435`, `repl_info.c:1770-1806`, `repl.c:253-254,314,401-463`, `repl_internal.h`.
- **Findings**: `repl_dispatch()` returns true (resume) or false (re-prompt); every `set` path returns false. `info config` prints `speed=%llu` from the shadow copy `sim->sim_speed_num`, its only production reader. Help line at `repl.c:314`.
- **Implications**: Handle `speed` before the argument-count check, print a fixed removal message, return false. Delete `repl_set_speed()` and the shadow copy.

### Tests, docs and specs touched
- **Context**: File Structure Plan and Requirement 5.
- **Findings**: 22 test files only assign `args.sim_speed = 0` (mechanical removal); `test_sim_startup.c` (which also assigns 1 in its failure-path tests) and `test_repl_snapshot_params.c` also carry behavioral assertions; `test_clock.c`, `test_sim_startup.c`, `test_repl_snapshot_params.c` and `test_repl_help.c` test speed behavior, the help text or the `info config` line; `test_sim_event_loop.c`, `test_maxtasks_wiring_sim_driver_parity.c` and `test_sched_alloc_from_stamp.c` write the core atoms directly (unaffected, since the core keeps them). No test runs the `xce_scheduler` binary as a subprocess. Docs: `deployment.md:214,220,223`. scheduler-core requirements/design passages listed in requirements.md 5.2. The only in-repo command line passing `--sim-speed` is `run-ha-soak.sh:738`, which counts only `decision verification MISMATCH` lines.

## Architecture Pattern Evaluation

| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| A. Pin sim to speed 0/1 (selected) | Keep the core formula; `sim_set_virtual_clock()` always stores 0/1; remove every sim/CLI/REPL path that sets another speed | Smallest change; reuses the exact mode all replay tests already exercise; core untouched | Core formula still supports N/M values no product path uses | Document the two values in `core.h` |
| B. Replace speed with a `clock_frozen` flag | Core formula becomes `vbase + (frozen ? 0 : elapsed)` | Removes unused generality | Touches core, core isolation surface, 28 test files; no behavioral gain | Rejected (simplification lens) |
| C. Simulator-private clock | Sim stops using the core clock | None over A | Breaks the "one core, two consumers" model and driver equivalence | Rejected |

## Design Decisions

### Decision: Frozen clock via existing `speed_num = 0`
- **Context**: Req 1.1-1.8.
- **Alternatives Considered**: Options B and C above.
- **Selected Approach**: `sim_set_virtual_clock(sim, snapshot_ts)` sets `virtual_clock_base = snapshot_ts`, `speed_num = 0`, `speed_den = 1`; `sim_advance_virtual_clock()` unchanged in behavior (exact, unclamped set).
- **Rationale**: Delivers exactness by construction; zero change to the core module.
- **Trade-offs**: The core formula keeps a generality nothing uses; documented as "normal mode 1/1, simulation mode 0/1".
- **Follow-up**: Tests prove that real time elapsing inside a replay does not move the clock.

### Decision: Deprecation warning in a testable helper, emitted after `mylog_init()`
- **Context**: Req 2.1-2.6.
- **Selected Approach**: New `sched_cli_warn_deprecated_options(const char* sim_speed)` in `src/scheduler/src/cli_compat.c`, called once from `main()` after `mylog_init()` and before the `--sim` branch. It logs one `WARN` naming the value when the pointer is non-NULL, and nothing otherwise.
- **Rationale**: Goes to `--logfile` in both modes; unit-testable; argp already gives last-value and missing-value semantics.
- **Trade-offs**: One small new file for one function; justified by testability and by giving the later removal a single place.

### Decision: `set speed` handled before the argument-count check
- **Context**: Req 3.1, 3.2.
- **Selected Approach**: In `repl_cmd_set()`, if `ntok >= 2` and `tokens[1]` is `speed`, print the removal message and return false; then the usual `ntok < 3` usage check.

### Generalization / Build vs. Adopt / Simplification
- **Generalization**: Requirements 1.1-1.8 are one property ("the sim clock moves only at recorded timestamps"); a single mechanism (speed 0/1 plus the three existing writers) satisfies all of them.
- **Build vs. Adopt**: Adopt the core's existing frozen mode; no new dependency.
- **Simplification**: Remove `sched_sim_args_t.sim_speed`, the `sim_speed_num`/`sim_speed_den` shadow copy, `repl_set_speed()` and the numeric validation in `main.c`; keep the core fields (Option B rejected).

## Review Gate
- Pass 1 (independent reviewer): GATE PASS, no must-fix. Ten nits applied: `--help` test mechanism (`popen` of the built binary via `-DXCE_SCHEDULER_BIN`), meson source-list placement, default log file path, line ranges, stale comments, a stronger warning test, a realistic 1.3 case, 4.2 wording, invariant-1 wording, and the test-file count here.

- Design review round 1: two must-fix issues fixed. (1) The in-process clock tests cannot fail on the pre-change code (zero-initialized args already meant speed 0), so an end-to-end `popen` test of the binary with default options and with every `--sim-speed` variant was added. (2) The snapshot's `session_duration_ns` claim was corrected: snapshots written before the first replayed session carry the recorded value. Nine nits applied (test registration, line ranges, stale comments, observation points, build-order constraint, `RUN_TEST` lines, SimClock rationale).
- Design review round 2: one must-fix issue fixed. The `--sim` branch returns without `mylog_fini()`, and tlog writes asynchronously with no exit hook, so a startup warning could be lost; superseded in round 3. Seven nits applied (1.4 proof attribution, non-vacuous decision check, popen pipe handling, absent log file, output comparison method, line references, tests for a trailing `--sim-speed` and piped `set speed`).
- Design review round 3: one must-fix issue fixed. Interactive runs exit through the REPL's `exit(0)` and never return from `main()`, and calling `tlog_exit()` at the returns or at quit is unsafe because the picker/allocator threads are never joined. The design now drains the logger (`mylog_fini()` + `mylog_init()`) right after the warning while `main()` is still single-threaded, covering every exit path; an interactive end-to-end case (e) was added. Nits applied: tlog citation, the real scripted-REPL test pattern (`freopen` of a script file), the unreachable `-ENOSYS` branch noted, a mid-replay snapshot observation for 1.5.
- Design review round 4: one must-fix issue fixed. The mid-replay snapshot check could not fail (wrong code path, masked by the next event, and the start-snapshot scan would select the later snapshot); it now runs the real skip branch with `sim_start_ts` pinned and checks the clock after the run. The end-to-end cases now use a fresh output and log file per run. Nits applied (tlog line reference, drain in the sequence diagram, 5.3 coverage in the components table, drain side effects, REPL position under 1.6, test-local capture helper).
- Design review round 5: one must-fix issue fixed (1.5 coverage disagreed between the Traceability and Components tables; ReplSet now covers 1.5 because removing `repl_set_speed()` removes the only other clock writer). Nits applied: line ranges, a pinned `endSession` timestamp in the mid-replay test, fresh output file in E2E case (c), stale four-mode comments, component names in Traceability, drain calls in Allowed Dependencies.
- Design review round 6: no must-fix issues (40+ line references verified). Four nits applied: a line range, the neutral 1/1 core-init citation, the drain's repeated gzip notice noted against Req 2.2, and the test-file count reconciled with requirements.md.

## Risks & Mitigations
- A test relies on drift at speed 1 (the three `test_sim_startup.c` failure-path tests set speed 1): they fail before the clock matters; mechanical removal of the assignment.
- Code outside the scheduler parses `speed=` from `info config`: none found (grep of xceadmin, harness, tools, frontend, .claude).
- The soak script's log now contains a warning: it counts only `decision verification MISMATCH` lines (`run-ha-soak.sh:737-739`); verified by 5.3's check.
- Old recordings whose events precede their first snapshot's timestamp move the clock backwards: accepted by Req 1.3; exact set, no error.

## References
- `.kiro/steering/scheduler-driver-equivalence.md` — one core, two drivers; the change stays in the sim driver.
- `.claude/skills/xce-audit-invariants/SKILL.md` — scheduler dimensions 1-4 (cross-checked in design.md).
- `.kiro/specs/libxce-alloc-preason-equality` — task 5.3 depends on Req 1.2-1.4.