From 66435d100d1a89b7a792dbda10570d90c1d07773 Mon Sep 17 00:00:00 2001 From: Rongsong Shen Date: Tue, 29 Sep 2026 05:21:11 +0000 Subject: [PATCH] docs(scheduler-sim-discrete-clock): deployment guide describes the event-driven sim clock and deprecated --sim-speed (task 4.1) Co-Authored-By: Claude Opus 5.5 (1M context) --- .kiro/specs/scheduler-sim-discrete-clock/tasks.md | 2 +- src/docs/deployment.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.kiro/specs/scheduler-sim-discrete-clock/tasks.md b/.kiro/specs/scheduler-sim-discrete-clock/tasks.md index f61cdc25..1bbbcebc 100644 --- a/.kiro/specs/scheduler-sim-discrete-clock/tasks.md +++ b/.kiro/specs/scheduler-sim-discrete-clock/tasks.md @@ -44,7 +44,7 @@ Test-first throughout (red → green → refactor). Every sub-task leaves the bu - _Depends: 2.1, 2.2, 2.3_ - [ ] 4. Documentation and specification alignment -- [ ] 4.1 (P) Update the operator documentation of simulation mode +- [x] 4.1 (P) Update the operator documentation of simulation mode - Describe the simulator clock as moving only at recorded timestamps, describe `--sim-speed` as deprecated with no effect, remove it from the example command line, and remove the claim that REPL and batch runs differ in pacing. - Done when the simulation section of the deployment guide contains none of real-time, speed modes or pacing, and names `--sim-speed` only as deprecated. - _Requirements: 5.1_ diff --git a/src/docs/deployment.md b/src/docs/deployment.md index eb39f7c7..be118bfa 100644 --- a/src/docs/deployment.md +++ b/src/docs/deployment.md @@ -211,16 +211,17 @@ xce_scheduler --peers "ctrl-1=controller-host:9990" --record-dir /var/log/xce/sc `--sim` runs the scheduler as a **standalone replay tool** against a previously recorded (or hand-built) `.replay` file — zero connection to any controller, safe to run against a production recording on a laptop: ```bash -xce_scheduler --sim /path/to/session.replay --sim-speed 0 # replay as fast as possible +xce_scheduler --sim /path/to/session.replay # replay the recording xce_scheduler --sim /path/to/session.replay --sim-verify # replay + diff against the recorded decisions xce_scheduler --sim /path/to/session.replay --sim-output /tmp/resim.replay --sim-alt-events /path/to/edited-events.replay # "what-if": substitute events, record the new decisions xce_scheduler --sim /path/to/session.replay --interactive # step through it interactively (REPL) ``` -- `--sim-speed`: `0` = as-fast-as-possible, `1` = real-time (default), `N>1` = `N`x real-time. +- The simulator's clock moves only at recorded timestamps, never with the wall clock: it is set to the start snapshot's timestamp, then to each recorded event's timestamp and each session's recorded `beginRound`, exactly, even when that value is earlier than the current one. Between those points it does not move, so a session's recorded duration in simulation output (`--sim-output`) is 0, and a replay's decisions do not depend on host speed or load. +- `--sim-speed` is deprecated and has no effect. It is still accepted with any value so existing command lines keep working, logs one deprecation warning, and will be removed in a future release; drop it from scripts. - `--sim-verify` re-derives decisions from the recorded events and asserts they match the decisions the file already recorded — the feature's core "deterministic replay" regression check, usable ad hoc against any recording. - `--sim-alt-events FILE` swaps in a different event stream after the initial snapshot for what-if branching; `--sim-output FILE` records the resulting decisions as a new `.replay` file. -- `--interactive` opens a REPL (`step`, `continue`, breakpoints, state inspection, snapshot capture) driving the *same* simulation run a batch `--sim` would — REPL and batch produce byte-identical decisions for the same input, only the pacing differs. +- `--interactive` opens a REPL (`step`, `continue`, breakpoints, state inspection, snapshot capture) driving the *same* simulation run a batch `--sim` would — REPL and batch produce byte-identical decisions for the same input. - Simulation mode never opens a socket to any controller and never touches `--peers`/`--record-dir` — see `.kiro/specs/scheduler-core/design.md`'s Boundary Commitments for the full isolation contract. ## Deploying apiserver