docs(scheduler-sim-live-allocation): reconcile equivalence suites (task 5.3)

Re-ran test_repl_equivalence.c, test_sim_equivalence.c, and
test_sim_contention_parity.c in full: all pass, 85/85, zero assertion
changes anywhere. Confirmed all three still exercise their own
link-satisfying always-PEND sched_job_picker/sched_allocator stub
(added task 4.1), correctly proving the new two-thread jbuf timing
didn't disturb decision ordering -- but not proving real live-path
resource-based dispatch parity, which is already covered separately
by tasks 4.1/4.3/5.1/5.2's real-scheduler_srcs-linked fixtures.

Fixed a stale documentation defect: all three files' header/inline
comments claimed sim mode "structurally CANNOT emit a DISPATCH
decision" via sim_picker_thread_fn(), a function this feature removed
in tasks 3.1/4.1. That claim is now false of production sim mode
(disproved by test_sim_live_allocation.c and others); corrected with
a RECONCILIATION addendum rather than rewriting the original
historical rationale. No production code or assertion values changed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RLSNJhNoULvVcUhXEFafQC

.kiro/specs/scheduler-sim-live-allocation/tasks.md

@@ -107,7 +107,7 @@
   - _Depends: 4.1, 4.2, 4.3_
   - _Requirements: 2.1, 2.2, 2.3, 2.4_
 
-- [ ] 5.3 Re-run existing simulation-mode equivalence suites and reconcile any behavior change
+- [x] 5.3 Re-run existing simulation-mode equivalence suites and reconcile any behavior change
   - Re-run the REPL/batch decision-equivalence suite and the existing normal-mode-recording-vs-simulation-replay decision-identity suites in full
   - Investigate and explain, rather than silently update, any assertion whose expected output changes as a result of this feature
   - Observable: all three suites pass, or every changed assertion has a written explanation of why the new behavior is correct
@@ -131,3 +131,4 @@
 - **Task 1.2**: retyping a widely-called function's signature (e.g. `plugin_job_election`, `plugin_prepare_allocation`, `plugin_commit_decision`) breaks ALL of its call sites as hard compile errors in one step (this toolchain treats `-Wincompatible-pointer-types` as an error, not a warning) — there is no way to migrate a signature and keep the build green without touching every call site in the same commit, even when those call sites live in files nominally owned by a later task. The correct scope is the *minimal* fix (wrap the existing argument, e.g. `sched` → `&(sched->core)`; touch nothing else in that function), not a rewrite of the caller. Also: design.md's Implementation Notes said `plugin_prepare_allocation()` has "one normal-mode call site" — it actually has two (`resource.c`'s `sched_try_alloc_on_host_()` and `schedobj.c`'s `sched_ctx_set_primary()`). Grep for ALL call sites before assuming a design doc's count is exhaustive.
 - **Task 5.1**: the pre-existing `test_sim_contention_parity.c` fixture could not be reused because it drives reconciliation only (its own white-box stubs hard-code the old always-PEND behavior), so proving live-path contention parity required two new fixtures spawning the real `sched_job_picker()`/`sched_allocator()` pair directly against bare normal-mode and sim-mode core state. Confirmed as a genuine, requirement-consistent scope boundary (not a silent narrowing): `build_limit_vres_requests()`/`get_vres_value()` (`plugins/limit.c`) are `#if 0`'d dead code with zero live callers — no limit, in either mode, currently gates/denies admission anywhere in this codebase, only tracks/displays usage. Any future task attempting real limit-based admission denial must first un-stub these two functions; that is out of boundary for this feature.
 - **Task 5.2**: this is the feature's concrete bug-1826 acceptance test, and it deliberately goes one level higher-fidelity than every prior task's fixtures — a real capnp-encoded `.replay` (genuine `ReplayHeader`/`SnapshotEntry`/`Conf4Sched`, real generated `encode_Conf4Sched()`) driven through the real, unmodified `sched_sim_driver_run()` entry point, not a bare-`&(sim->core)` shortcut. `repl_info_limit()`/`repl_dispatch()` (the literal functions behind the `info limit` CLI command) are both `static` and unreachable from a real-`scheduler_srcs`-linked test binary, so the test reads `limit_get_configured_limits()`/`limit_get_usage_instances()` directly — confirmed (by tracing `repl_print_limit_usage()`'s own body) to be the exact same accessors `info limit` itself calls, not a weaker substitute. RED-phase evidence for a task this late in a long dependency chain doesn't need a full feature revert: a targeted revert of just task 4.3's 4 files (the specific commit that closed the host-scoped-limit fan-out gap this test's host-scoped half exercises) reproduced the predicted failure exactly (global limit's usage still populated, host-scoped usage instance missing), then a restore-to-HEAD reproduced GREEN — this is sufficient, targeted regression-detection proof without needing to unwind 8+ interdependent commits. Also closed bug-1826 itself (the bug this whole feature exists to fix) — updated its buglog entry from "NOT FIXED" to "FULLY FIXED," citing this test.
+- **Task 5.3**: confirmed all three named suites (`test_repl_equivalence.c`, `test_sim_equivalence.c`, `test_sim_contention_parity.c` — the only files matching "REPL/batch decision-equivalence" and "normal-mode-recording-vs-simulation-replay decision-identity"; no fourth file exists despite the task text's plural "suites" wording, confirmed by grepping the whole spec/steering corpus and `testsuite/meson.build` for any other candidate name) pass, and pass for the right, non-vacuous reason, but NOT the reason a shallow read of their own header comments would suggest. All three exercise the REAL, genuinely-changed production code path in one dimension — `sim_loop.c`'s `sched_sim_driver_run()` now spawns `sched_job_picker()`/`sched_allocator()` via a real two-thread `jbuf` producer/consumer hand-off instead of the old single fused `sim_picker_thread_fn()` thread, exactly the decision-timing/ordering risk `requirements.md`/`design.md` flagged for this migration — but all three still exercise a STUB, not the real allocation chain, in the other dimension: each file (being a white-box `#include` of `sim_loop.c` without linking `sched_election.c`/`scheduler.c`/`resource.c`) supplies its own link-satisfying `sched_job_picker()`/`sched_allocator()` definitions (added by task 4.1, unmodified since) that faithfully reproduce the OLD always-PEND contract. Verified via `git show` across this feature's commits that the only changes made to any of these three files were adding those stubs (task 4.1, commit 08df6493) and, for `test_sim_contention_parity.c` alone, one earlier mechanical call-site signature migration (task 1.3, commit 55173fca, e.g. `sched_check_host_satisfy(sched, ...)` → `sched_check_host_satisfy(core, ...)` — an argument-type change, not a value/logic change) — zero pre-existing assertions were touched in any of them, so there is no "changed expected value" to explain for this task's own AC. This means these three suites correctly prove "the new two-thread timing didn't disturb decision ordering," which is genuinely what they were built to prove and is not vacuous — but they do NOT prove "sim mode's real live allocator now matches normal mode under contention," which is a materially different, and separately covered, claim. That second claim already has its own dedicated, non-duplicative proof: `sched_sim_live_allocation_test` (task 4.1), `sched_sim_alloc_limit_fanout_test` (task 4.3), `sched_sim_contention_resource_driver_parity_test` / `sched_sim_contention_limit_driver_parity_test` (task 5.1), and `sched_sim_e2e_limit_visibility_test` (task 5.2) — all five link the real `scheduler_srcs` and drive the real `sched_job_picker()`/`sched_allocator()` pair, several explicitly under resource contention and active limits. So this task's own job for these three suites is exactly what its Observable text implies when read carefully ("all three suites pass, or every changed assertion has a written explanation") — reconciliation and documentation, not a new proof, since nothing changed and the missing proof already exists elsewhere. One genuine documentation defect found and fixed: all three files' header comments (and one inline comment in `test_repl_equivalence.c`) still asserted, in the present tense, that "the simulation driver structurally CANNOT emit a DISPATCH decision" and attributed this to `sim_picker_thread_fn()` — a function this same feature removed in task 3.1/4.1. That claim is now false of production sim mode (proved false by the five tests above) and was only ever true of these three files' own local stub choice — a reader skimming the header without noticing the file never links `sched_election.c` could easily conclude sim mode itself still can't dispatch. Corrected with a RECONCILIATION addendum in each of the three files' own header comments (plus the one inline comment) rather than rewriting the original historical rationale, which is still accurate as a record of why the fixture was scoped to PEND-only at the time it was written. No production code was touched; no assertion values changed; full suite re-run at 85/85 pass after the documentation fix, identical to the pre-task baseline.

src/scheduler/testsuite/test_repl_equivalence.c

@@ -18,9 +18,14 @@
  * completion produces the same output as `--sim` without `--interactive`."
  *
  * Fixture (a genuine, non-trivial, PEND-only sequence -- see
- * test_sim_equivalence.c's own header comment for why every decision the
- * simulation driver can produce today is PEND, never DISPATCH:
- * sim_picker_thread_fn()'s documented, out-of-this-task's-scope gap): TWO
+ * test_sim_equivalence.c's own header comment, and that comment's
+ * scheduler-sim-live-allocation task 5.3 RECONCILIATION addendum, for why
+ * every decision THIS FILE's own fixture produces is PEND, never DISPATCH:
+ * this file provides its own link-satisfying sched_job_picker()/
+ * sched_allocator() stub, below, reproducing the old always-PEND contract
+ * the now-removed sim_picker_thread_fn() used to provide -- production sim
+ * mode itself can genuinely DISPATCH today, proved elsewhere, see that
+ * addendum): TWO
  * queues at different priorities ("high"=5, "normal"=1, forcing the real
  * builtin_fcfs cross-queue priority ordering to run for real) and FOUR jobs
  * split across THREE separate ReplaySession boundaries (2 jobs before
@@ -883,8 +888,11 @@ test_repl_step_continue_to_completion_matches_batch_decision_sequence(void)
             /* Independently pin the decision TYPE on each side (matches
              * test_sim_equivalence.c's own "pin the type, don't just diff
              * the two sides against each other" guard) -- every decision
-             * this fixture can produce is PEND (sim_picker_thread_fn()'s
-             * documented, out-of-scope DISPATCH gap). */
+             * this fixture can produce is PEND (this file's own
+             * link-satisfying sched_allocator() stub -- see header comment
+             * and test_sim_equivalence.c's task 5.3 RECONCILIATION
+             * addendum for why, and why production sim mode itself is not
+             * limited this way). */
             TEST_ASSERT_EQUAL_INT((int)ReplayDecision_body_pend,
                                   (int)bd->body_which);
             TEST_ASSERT_EQUAL_INT((int)ReplayDecision_body_pend,

src/scheduler/testsuite/test_sim_contention_parity.c

@@ -137,6 +137,35 @@
  * WRONGLY granted a hypothetical job wanting JOBB_WANT (5.0) against sim's
  * post-replay state -- then confirmed to pass again once the call site was
  * restored. See this task's own Status Report for the exact commands run.
+ *
+ * RECONCILIATION (scheduler-sim-live-allocation spec, task 5.3, 2026-09-19):
+ * the "sim_picker_thread_fn() ... structurally can only ever PEND" and
+ * "real resource-matching allocation belongs to the not-yet-designed
+ * scheduler-allocation spec" framing above is now historical -- that
+ * function was removed (scheduler-sim-live-allocation task 3.1/4.1),
+ * scheduler-allocation has since been completed, and this feature makes
+ * production sim mode genuinely dispatch via the shared sched_job_picker()/
+ * sched_allocator() pair (sched_election.c). This file's OWN rationale for
+ * NOT simply replaying task 1.2's recorded file is still correct and
+ * load-bearing for a different reason than originally stated, though: this
+ * TU supplies its own link-satisfying sched_job_picker()/sched_allocator()
+ * stub (below, added unmodified by task 4.1) that deliberately preserves
+ * the old always-PEND contract, so it could not detect real resource-based
+ * dispatch even if the fixture were replayed unmodified -- Recorded-
+ * Decision Reconciliation's own narrow trigger shape (a job already RUN by
+ * the time the live picker reaches it) is genuinely the mechanism this file
+ * tests, independent of whether the live allocator can also dispatch a
+ * fresh candidate for itself. `git show` on task 4.1's commit confirms the
+ * only change made to this file was adding that stub -- zero pre-existing
+ * assertions were touched, and this file's own test still passes for the
+ * same reason it always did. The genuine question this feature raised --
+ * does production sim mode's real live allocator (not reconciliation)
+ * produce the same admission/pend outcome as normal mode under contention,
+ * including limit-constrained contention -- is answered by task 5.1's
+ * sched_sim_contention_resource_driver_parity_test and
+ * sched_sim_contention_limit_driver_parity_test (meson.build), which link
+ * real scheduler_srcs and drive the real sched_job_picker()/sched_allocator()
+ * pair directly; this file does not duplicate that proof.
  */
 #include <errno.h>
 #include <limits.h>

src/scheduler/testsuite/test_sim_equivalence.c

@@ -72,6 +72,39 @@
  *   This is reported explicitly in this task's own status report, not
  *   hidden here.
  *
+ * RECONCILIATION (scheduler-sim-live-allocation spec, task 5.3, 2026-09-19):
+ * sim_picker_thread_fn() named throughout the paragraphs above no longer
+ * exists -- it was removed by that spec's task 3.1/4.1, replaced in
+ * PRODUCTION by the shared sched_job_picker()/sched_allocator() pair
+ * (sched_election.c), which sim mode now spawns for real against
+ * &(sim->core), genuinely reaching sched_make_allocation() and capable of
+ * emitting a real DISPATCH. The "simulation driver structurally CANNOT emit
+ * a DISPATCH decision" claim above is therefore no longer true of production
+ * sim mode -- see test_sim_live_allocation.c and the
+ * sched_sim_contention_resource_driver_parity_test/sched_sim_contention_
+ * limit_driver_parity_test/sched_sim_e2e_limit_visibility_test family
+ * (meson.build), which link the real scheduler_srcs and prove genuine live
+ * DISPATCH/PEND parity between normal and sim mode, including under
+ * resource contention and active limits -- the requirement this feature's
+ * task 5.3 exists to satisfy. It remains true of THIS file's own fixture
+ * only, because this TU never links sched_election.c: task 4.1 gave it (and
+ * test_repl_equivalence.c/test_sim_contention_parity.c) their OWN
+ * link-satisfying sched_job_picker()/sched_allocator() stub definitions
+ * (below) that faithfully reproduce the old always-PEND contract, precisely
+ * so this file's pre-existing assertions stay valid unchanged. Confirmed via
+ * `git show` on task 4.1's commit: the only change made to this file by the
+ * whole scheduler-sim-live-allocation feature was adding those stubs -- zero
+ * existing assertions were touched. What this test still genuinely proves
+ * post-feature: sim_loop.c's real sched_sim_driver_run() now drives its
+ * picker/allocator via a genuine two-thread jbuf hand-off (the same
+ * production entry points, resolved here to this file's stub instead of the
+ * real allocation chain) rather than the old single fused thread, and that
+ * change did not alter the recorded-vs-replayed decision sequence -- the
+ * decision-timing/ordering risk requirements.md/design.md flagged for this
+ * migration. It does NOT re-prove resource-based dispatch equivalence,
+ * which is proved elsewhere (tasks 4.1/5.1/5.2, cited above) rather than
+ * duplicated here.
+ *
  * The fixture is still a genuine, non-trivial regression guard, not a
  * single-job happy path that could pass by accident: TWO queues at
  * different priorities ("high"=5, "normal"=1) and FOUR jobs split across