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 a51790dcbb
docs(scheduler-sim-repl-verbosity): fix two documentation gaps from final validation 
Found by /kiro-validate-impl's cross-task requirements-coverage and
design-alignment checks, both documentation-only (no code changes):

1. AC 6.5 (whole-number/no-trailing-.00 formatting) is implemented as
   scoped to non-consumable (Load Metrics) values only - a consumable
   resource's value=/used= pair deliberately keeps its unconditional
   %.2f formatting to preserve bug-1601/1613/1727's already-pinned
   display shape. This carve-out existed only as an inline code
   comment (repl_info.c) and a test-file header comment, never
   sanctioned in requirements.md/design.md itself. Amended AC 6.5's
   text to state the scope explicitly and added a design.md Correction
   note cross-referencing it.

2. design.md's File Structure Plan never documented task 6.1's proactive
   split of the prompt-content tests into a new test_repl_prompt_context.c
   (every other analogous split in this spec got a Correction note;
   this one didn't), and task 9.1's later Correction note repeated the
   stale claim that test_repl_execution_control.c "already carries" the
   prompt-content tests - it doesn't, they moved to the new file at task
   6.1. Added the missing task 6.1 Correction note and fixed both stale
   references.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YAWMhfRJFnmmnG8h97yUDd
2026-09-02 21:55:50 +00:00

82 lines
12 KiB
Markdown
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. 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.
Reference in a new issue View git blame Copy permalink