docs(spec): scheduler-allocator-runner and scheduler-sim-decision-trace requirements

scheduler-allocator-runner: brief and requirements for moving the duplicated
seqjob/parjob my_alloc() body into one framework-owned allocator runner.

scheduler-sim-decision-trace: brief and requirements for a per-job decision
trace in the simulator REPL (converged after 9 review rounds). The
decision-reasoning seed capability in scheduler-sim-diagnostics now points to
this spec.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Rongsong Shen 2026-09-29 08:57:23 +00:00
parent c89e4e4520
commit b283f3b93c
Signed by untrusted user: rshen
GPG key ID: 80533536B0EB651C
6 changed files with 554 additions and 2 deletions

View file

@ -23,7 +23,7 @@ Extend the existing REPL/simulation-driver surface (not a new component). Each n
**Seed capability 1 — Limit inspection**: expose limit config (name, per_user/queue/project/host scope, value/percent) and live usage (per-vres-instance current value vs limit) via a new `info limit <name|all>` REPL command. Requires plumbing a read path from the `limit` plugin's private kvmgr tables to the REPL (core has no existing accessor for plugin-private state).
**Seed capability 2 — Decision-reasoning trace**: capture *why* each scheduling decision was made — not just the outcome. For PEND, surface the existing `xce_pendreason_t` (currently captured but not printed). For DISPATCH, there is currently no trail at all of which limit/resource checks were evaluated and passed; this needs new instrumentation in the allocation path (`sched_try_alloc_on_host_`, `limit_prepare_allocation`) to record a per-attempt reasoning trace, then a REPL command to print it for a given job/decision.
**Seed capability 2 — Decision-reasoning trace** *(MOVED 2026-09-28 to its own spec `scheduler-sim-decision-trace` — see `.kiro/specs/scheduler-sim-decision-trace/brief.md`; text below kept for history)*: capture *why* each scheduling decision was made — not just the outcome. For PEND, surface the existing `xce_pendreason_t` (currently captured but not printed). For DISPATCH, there is currently no trail at all of which limit/resource checks were evaluated and passed; this needs new instrumentation in the allocation path (`sched_try_alloc_on_host_`, `limit_prepare_allocation`) to record a per-attempt reasoning trace, then a REPL command to print it for a given job/decision.
## Scope

View file

@ -5,7 +5,7 @@ Operators investigating scheduler behavior in the `--interactive` simulation REP
## Boundary Context
- **In scope**: REPL-visible display of a limit's configured setting (the resource it constrains, its configured value or percentage, and which scope dimensions it effectively varies by, including any host-scoping implied by a percentage value on a resource that is not shared cluster-wide) and its live accounted usage (per distinct scope instance, including explicit exclusion-based scope restrictions), in simulation mode only.
- **Out of scope**: any command that mutates scheduler state; live, controller-connected (non-simulation) inspection; explaining *why* a specific job did or did not trigger a limit (decision-reasoning trace — expected to be added later as a separate requirement of this same open-ended spec, not covered here); any change to scheduling, allocation, or limit-matching behavior.
- **Out of scope**: any command that mutates scheduler state; live, controller-connected (non-simulation) inspection; explaining *why* a specific job did or did not trigger a limit (decision-reasoning trace — moved 2026-09-28 to its own spec `scheduler-sim-decision-trace`, not covered here); any change to scheduling, allocation, or limit-matching behavior.
- **Adjacent expectations**: this capability extends the REPL's existing `info` command family (shipped by `scheduler-core`, implementation-complete) without altering any existing subcommand's behavior or output; it must not perturb the guarantee that a simulation replay reproduces identical scheduling decisions and identical accounting state regardless of what inspection commands are issued during it. Requirement 6 (added 2026-09-19, following operator feedback that a limit's raw byte amounts are hard to read) relies on the REPL's existing byte-unit display convention already used by other `info` subcommands for byte-valued resource amounts, including an operator's existing ability to select how those amounts are displayed — it extends that existing convention to limit displays rather than introducing a new one.
## Requirements