myxce/.kiro/specs/scheduler-sim-repl-verbosity/requirements.md

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. It also extends a small number of specific, explicitly-scoped improvements to other parts of the REPL surfaced during this effort — the command prompt, info's job-identifier and resource-value listings, and help/break's discoverability — while leaving step mode's per-event and per-decision detail, and every other aspect of the REPL's existing commands, 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; the REPL prompt's display of current session/timestamp context, applicable in both step and continue modes; job-identifier range compression (Requirement 4) applied to the info command's job-listing output (for example info worker's assigned-job list); human-readable resource value formatting, table layout, and the new set units display-mode option (Requirement 6) applied to the info command's resource listings; and the organization/completeness of help's command listing and break's event-type discoverability (Requirement 7).
• 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, other than the prompt string itself; 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 status change, a job progress update, a job resource-usage update, a queue update, or a partial/delta 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, a full resource-value snapshot arriving, 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, round decision summaries, and the info command's job-identifier listings (for example info worker's assigned-job list).

Requirement 5: Preservation of Existing REPL Behavior Outside This Feature's Explicit Changes

Objective: As an operator relying on today's step behavior and info/break/delete/set/snapshot/help commands, I want everything this feature does not explicitly call out as changing (Requirements 4, 6, and 7, plus this requirement's own AC 5) to keep working exactly as before, so that existing debugging workflows aren't disrupted by scope creep.

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, snapshot, and help command behavior and output format unchanged, except where Requirement 4, 6, or 7 explicitly specifies a change. (This AC is intentionally a cross-reference, not a restated list, so a future requirement's own scoping ACs remain the single source of truth for what it changes.)
3. The REPL shall introduce no new top-level command as part of this feature; set units is a new option of the existing set command, following the same set <key> <value> form as today's set speed/set output/set verify.
4. The REPL shall not alter the scheduling decisions or final simulation state produced by a replay — only the console output describing them.
5. When the REPL displays its command prompt, the REPL shall include the current session identifier and timestamp, without altering any other step-mode or continue-mode output.

Requirement 6: Human-Readable Resource Value Formatting

Objective: As an operator reading info worker/info resource output, I want byte-denominated resource values shown in a readable unit and the listing laid out as a scannable table, with control over how much raw-vs-human detail I see, so I don't have to mentally parse 13-digit raw byte counts or hunt for one resource among 20 unstructured lines.

Acceptance Criteria

1. When the REPL displays a resource whose canonical wire unit is bytes (mem, tmp, maxmem, maxtmp, maxswap) or the swp resource (whose canonical wire unit is megabytes), the REPL shall render its value using the operator's selected units display mode.
2. The REPL shall support a set units raw|human|both option: raw shows only the numeric wire value, human shows only an adaptively-scaled unit (B/KB/MB/GB/TB/PB), and both shows the raw value with the human-readable form alongside.
3. Absent an explicit set units command, the REPL's units display mode shall default to both.
4. The REPL shall not alter the underlying stored/wire value of any resource, nor the deterministic outcome of a replay — only its console display.
5. The REPL shall display numeric resources with no canonical unit (for example load averages, factors, and counts) without a unit suffix, and without a trailing .00 when the value is a whole number. This rule applies to non-consumable (Load Metrics) values; a consumable/capacity resource's value=/used= pair keeps its existing unconditional two-decimal display (bug-1601/1613/1727's pinned shape) and is out of scope for this AC.
6. The REPL shall display info worker's and info resource's resource listings as an aligned table, grouping resources by category (consumable/capacity, load metrics, static hardware attributes) where applicable to that listing, rather than one flat list.

Requirement 7: Discoverable Help and Breakpoint Event Types

Objective: As an operator learning or re-learning the REPL's command surface, I want help's listing organized and complete, and every valid break event type discoverable without reading source, so I can find and use a command correctly on the first try instead of by trial-and-error.

Acceptance Criteria

1. The REPL's help output shall group commands into labeled sections by concern (execution control, breakpoints, state inspection, snapshot and parameters) instead of one flat list.
2. Within each section, the REPL shall align every command's description to a single column position computed consistently, rather than independently hand-padded per line.
3. The REPL's help output shall list info config together with the other info subcommands in the state-inspection section.
4. The REPL's help output shall enumerate the complete set of valid <EVENT_TYPE> values accepted by break.
5. When break is given an event type that matches none of its valid values, the REPL's error message shall list the complete set of valid values.
6. The REPL shall not alter which commands exist, their argument parsing, or any other command's output — only the organization of help's listing and the completeness of break's event-type discoverability.