lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
myxce/.kiro/specs/scheduler-sim-repl-verbosity/requirements.md
Rongsong Shen 979cd24f6c
docs(scheduler-sim-repl-verbosity): add approved spec (requirements/design/tasks) 
Full spec scaffold (requirements/design/research/tasks all approved,
ready_for_implementation=true) plus a roadmap backlog item recorded from
the dirty-content-fingerprint spec's task 4.3 findings (Makefile/meson
fingerprint-computation duplication risk).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-22 02:45:52 +00:00

7.2 KiB
Raw Blame History

Requirements Document

Introduction

xce_scheduler's --interactive simulation REPL (shipped by the scheduler-core spec) lets an operator step or continue through a recorded replay while inspecting scheduler state. Under continue, the REPL currently prints the same volume of output as single-stepping every round — a real 108-round replay produced roughly 2,700 lines, most of it either routine per-event chatter that carries no new information under continue, or an unchanged pending-job decision repeated identically round after round. This feature reorganizes REPL output during continue execution so an operator can track a long replay's progress without wading through repetitive, low-information lines, while leaving step mode and every other REPL command unchanged.

Boundary Context

  • In scope: console output shown by the --interactive simulation REPL during continue execution — which events are echoed, how scheduling-decision outcomes are summarized per round, how repetitive rounds are collapsed, and how multi-job identifier lists are displayed.
  • Out of scope: any new REPL command or newly inspectable data (for example limit usage or pend-reason detail — tracked separately under scheduler-sim-diagnostics); any change to scheduling/allocation behavior or to the deterministic outcome of a replay; any change to step mode's existing output; non-interactive (headless, no -i) scheduler output.
  • Adjacent expectations: this feature extends the existing REPL shipped by scheduler-core (implementation-complete) without changing its command surface. scheduler-sim-diagnostics (currently a discovery brief, not yet a formal spec) is expected to separately add pend-reason and limit-usage inspection; this feature's round summaries should remain compatible with, and not duplicate, that future work.

Requirements

Requirement 1: Mode-Aware Event Echo During Continuous Execution

Objective: As an operator running a simulation replay, I want continue to suppress routine per-event chatter while still alerting me to major state changes, so that I can watch a long replay without being flooded by lines carrying no new information.

Acceptance Criteria

  1. While the REPL is executing in continue mode, when a routine per-event notification (a job progress update, a job resource-usage update, or a resource value update) occurs, the REPL shall not print an individual line for that event.
  2. While the REPL is executing in step mode, when any event occurs, the REPL shall print an individual line for that event.
  3. When a structural change occurs (new jobs submitted, new workers added, new resources added, or configuration pushed), the REPL shall print a line describing that change regardless of execution mode.
  4. When an event matches a defined breakpoint, the REPL shall interrupt continue-mode execution and enter the interactive command loop, regardless of whether the event is routine or structural.

Requirement 2: Per-Round Decision Summary

Objective: As an operator watching simulation replay progress, I want one summary line per round showing what scheduling decisions were made, so that I can track scheduling outcomes without reading a separate line per affected job.

Acceptance Criteria

  1. While the REPL is executing in continue mode, when a round completes with at least one scheduling decision (dispatch, pend, or preempt), the REPL shall print one summary line for that round showing the count of each decision type and the identifiers of the jobs affected.
  2. When a round completes with zero scheduling decisions, the REPL shall not print an individual decision line for that round.
  3. While the REPL is executing in step mode, the REPL shall print full per-decision detail for every decision.
  4. When a job's tracked status changes from one round to the next, the REPL's round summary shall reflect that change.

Requirement 3: Collapsing of Repetitive Round Output

Objective: As an operator, I want consecutive rounds that produce no new information to be reported as a single range instead of one line each, so that long stretches of idle or unchanged simulation state don't dominate the output.

Acceptance Criteria

  1. When two or more consecutive rounds occur with zero scheduling decisions, the REPL shall report them as a single collapsed range instead of one line per round.
  2. When two or more consecutive rounds occur with an identical decision outcome (same decision counts and the same affected job identifiers), the REPL shall report them as a single collapsed range instead of repeating the same summary line for each round.
  3. The REPL shall include the first round number, the last round number, and the round count in every collapsed range notification.
  4. Where round timestamps are displayed, the REPL shall include the covered time span in each collapsed range notification.
  5. When a round's decision outcome differs from the immediately preceding reported round, or a structural event occurs, the REPL shall end the active collapsed range and report it before continuing.
  6. When continue-mode execution stops for any reason (a breakpoint hit or replay completion), the REPL shall end and report any active collapsed range before the stop is reported to the operator.

Requirement 4: Job Identifier Range Compression

Objective: As an operator reading REPL output that lists many job identifiers from the same job array submission, I want those identifiers compressed into an index range, so that I can read the list without scrolling past dozens of nearly-identical entries.

Acceptance Criteria

  1. When the REPL displays two or more job identifiers that belong to the same job array submission and have contiguous array indices, the REPL shall display them as a single compressed index range.
  2. When job identifiers from the same job array submission have non-contiguous indices, the REPL shall display each contiguous sub-range separately within the same listing.
  3. When a listing contains job identifiers from more than one job array submission, the REPL shall group and compress each job array submission's identifiers independently.
  4. When a listing mixes job-array and non-array job identifiers, the REPL shall display the non-array job identifiers individually while compressing the job-array identifiers as described above.
  5. The REPL shall apply job identifier range compression consistently everywhere it displays multiple job identifiers together, including job-arrival notifications and round decision summaries.

Requirement 5: No Change to Step-Mode Detail or Existing Commands

Objective: As an operator relying on today's step behavior and info/break/delete/set/snapshot commands, I want this feature to leave them unchanged, so that existing debugging workflows keep working exactly as before.

Acceptance Criteria

  1. The REPL shall preserve existing step command output exactly as before this feature, with no reduction in per-event or per-decision detail.
  2. The REPL shall preserve existing info, break, delete, set, and snapshot command behavior and output format unchanged.
  3. The REPL shall introduce no new command as part of this feature.
  4. The REPL shall not alter the scheduling decisions or final simulation state produced by a replay — only the console output describing them.