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

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