feat(scheduler-core): wire decision publishing and mode-selection into main.c (task 5.2)

Rewires main.c's live scheduling loop onto the new core-driven
architecture: xce_sched_driver_translate_pending_events() (task 5.1)
-> xce_core_begin_session() -> plugin_begin_session()+sched_account_jobs()
-> xce_core_signal_go() -> decision-drain via the registered
xce_core_decision_cb_t -> plugin_end_session() -> xce_core_end_session(),
all in the new exported xce_sched_driver_run_normal_mode_round()
(driver.c), replacing the old inline sched_update()+sched_begin_session()
+sched_go()+switch+sched_end_session() sequence.

xce_core_go() (task 4.4) is split into xce_core_begin_session()/
xce_core_signal_go() -- a pure decomposition (xce_core_go() itself is
now defined in terms of both, task 4.4's approved test suite passes
unmodified) -- specifically so the driver can interleave
plugin_begin_session()/sched_account_jobs() in the exact safety-critical
window task 4.4 deliberately excluded from pure-core scope: after the
resval reset, strictly before the picker thread is signaled. This is
empirically proven by test_driver_session_ordering.c via real
cross-thread happens-before assertions, not just documented.

xce_sched_driver_on_decision() is the new registered callback:
DISPATCH/PEND forward to the existing sched_publish_dispatch()/
sched_publish_pend_reason(); PREEMPT fails loudly (-ENOSYS, logged)
since no xcecli_preempt() client API exists and nothing in the live
allocator produces one yet (scheduler-preemption's territory).

Adds a --sim CLI flag (parse-only, loud not-yet-implemented failure,
since SimDriver is Phase 3).

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

src/scheduler/include/core.h

@@ -335,6 +335,56 @@ extern int xce_core_push_events(xce_sched_core_t*, xce_core_event_t*, int);
 extern int xce_core_set_decision_cb(xce_sched_core_t*, xce_core_decision_cb_t,
                                     void*);
 
+/*
+ * xce_core_begin_session / xce_core_signal_go - Req 5 AC 5 (task 4.4) split
+ * into two exported halves (task 5.2, Req 1 AC 7 / Req 5 AC 9) so a driver
+ * can interleave ITS OWN begin-session bookkeeping strictly between the
+ * state reset and the picker signal -- specifically
+ * plugin_begin_session()/sched_account_jobs() (the OLD per-plugin hook
+ * category and per-running-job resource-in-use accounting; both real,
+ * load-bearing production behavior, both xce_scheduler_t*-coupled and
+ * therefore outside this pure-core module's reach, same exclusion
+ * rationale core_session.c's own file header comment documents for why
+ * core_begin_session_internal() never called them itself).
+ *
+ * This split exists to preserve a safety property main.c's pre-task-5.2
+ * `sched_begin_session()` + `sched_go()` sequence already guaranteed: the
+ * picker thread must never observe a session whose resource-in-use
+ * accounting has been reset to zero (by the resval resets below) but not
+ * yet re-summed from currently running jobs (sched_account_jobs()) -- that
+ * would let the picker/allocator threads over-allocate resources already
+ * consumed by running jobs. A driver MUST call xce_core_signal_go() only
+ * AFTER any such bookkeeping following a successful xce_core_begin_session()
+ * completes; see driver.c's xce_sched_driver_run_normal_mode_round() for the
+ * real call site and testsuite/test_driver_session_ordering.c for the
+ * safety-property proof.
+ *
+ * xce_core_begin_session() - performs the begin-session state reset
+ * (select-eval-ctx, shared resval, per-worker resval/host-ctx). Does NOT
+ * signal the picker thread. Returns 0 on success; -EINVAL if core is NULL
+ * OR a session is already active (core->session_active != 0) -- the AC's
+ * required "distinct error" for the reentrancy-rejection case. On success,
+ * core->session_active is already 1 and core->session_start already
+ * stamped -- identical to xce_core_go()'s own post-condition at the
+ * equivalent point.
+ *
+ * xce_core_signal_go() - NON-BLOCKING: signals the picker thread via a
+ * single `cbuf_put(&core->wbuf, ...)` and returns immediately. Does NOT
+ * wait for the picker/allocator to produce any decisions -- draining
+ * `core->decisions` and invoking the registered `on_decision` callback is
+ * the driver's own responsibility, in the driver's own loop between this
+ * call and xce_core_end_session() (design.md's Normal-Mode Scheduling
+ * Round: "the drain loop in the driver thread interleaves
+ * cbuf_get/on_decision one at a time"). Only valid to call after a
+ * successful xce_core_begin_session() for the same session -- calling it
+ * without one first (or twice for one session) is a caller bug this
+ * function does not itself guard against (xce_core_go() below is the safe
+ * composition for callers with no bookkeeping to interleave). Returns
+ * -EINVAL if core is NULL.
+ */
+extern int xce_core_begin_session(xce_sched_core_t*);
+extern int xce_core_signal_go(xce_sched_core_t*);
+
 /*
  * xce_core_go - Req 5 AC 5 (scheduler-core spec, task 4.4). Starts a
  * scheduling session: NON-BLOCKING -- performs the begin-session state
@@ -347,6 +397,13 @@ extern int xce_core_set_decision_cb(xce_sched_core_t*, xce_core_decision_cb_t,
  * (design.md's Normal-Mode Scheduling Round: "the drain loop in the
  * driver thread interleaves cbuf_get/on_decision one at a time").
  *
+ * As of task 5.2, implemented as `xce_core_begin_session()` immediately
+ * followed by `xce_core_signal_go()` -- net behavior, return codes, and
+ * the existing test_core_session.c contract are all unchanged; this is a
+ * pure decomposition, kept as the simple, safe entry point for any caller
+ * (e.g. a future simulation driver) with no begin-session bookkeeping of
+ * its own to interleave.
+ *
  * Returns 0 on success; -EINVAL if core is NULL OR a session is already
  * active (core->session_active != 0) -- the AC's required "distinct
  * error" for the reentrancy-rejection case.

src/scheduler/include/driver.h

@@ -52,4 +52,82 @@
  */
 extern int xce_sched_driver_translate_pending_events(xce_sched_core_t* core);
 
+/*
+ * xce_sched_driver_on_decision - the normal-mode driver's decision-publish
+ * callback (scheduler-core spec, task 5.2, Req 5 AC 6 / AC 9's publishing
+ * half: "The driver shall publish core-emitted decisions back to the
+ * controller via the existing xcecli_ctx_t API"). Matches
+ * xce_core_decision_cb_t's signature (core.h) exactly -- registered via
+ * `xce_core_set_decision_cb(&sched->core, xce_sched_driver_on_decision,
+ * sched)` in main.c; `driver_ctx` is always the live xce_scheduler_t*, cast
+ * back inside driver.c so this function can reach
+ * sched_publish_dispatch()/sched_publish_pend_reason() (scheduler.h), both
+ * of which need the FULL xce_scheduler_t* (apictx) -- not just
+ * xce_sched_core_t*, which is why this declaration (unlike
+ * xce_sched_driver_translate_pending_events above) takes an opaque void*
+ * rather than pulling scheduler.h into this header (this file's own
+ * boundary comment: driver.h only depends on core.h).
+ *
+ * Replaces main.c's former inline `switch (decision->op)` (Req 5 AC 6:
+ * "This replaces the current internal decisions cbuf poll loop in
+ * main.c"). Called once per decision, in allocator-output order, by the
+ * driver's own drain loop between xce_core_signal_go() and
+ * xce_core_end_session() -- publishing immediately as each decision is
+ * drained, never batched (Req 5 AC 9).
+ *
+ * XCE_DECISION_PREEMPT: no live allocator path produces this decision type
+ * yet (preemption belongs to the sibling scheduler-preemption spec, out of
+ * this spec's boundary) and no `xcecli_preempt()` client API function
+ * exists anywhere in client.h to publish it through even if one did. This
+ * case fails loudly (logged, -ENOSYS) rather than silently no-op'ing or
+ * calling an undefined symbol -- see driver.c for the full reasoning.
+ *
+ * Returns 0 on successful publish (or a deliberate no-op case); a negative
+ * errno otherwise: -EINVAL if driver_ctx or decision is NULL; -ENOSYS for
+ * XCE_DECISION_PREEMPT (see above); or sched_publish_dispatch()'s/
+ * sched_publish_pend_reason()'s own negative return, passed straight
+ * through.
+ */
+extern int xce_sched_driver_on_decision(void*           driver_ctx,
+                                        xce_decision_t* decision);
+
+/*
+ * xce_sched_driver_run_normal_mode_round - one normal-mode scheduling round
+ * (scheduler-core spec, task 5.2, Req 1 AC 7 / Req 5 AC 6 / AC 8 / AC 9).
+ * Originally implemented as a `static` helper directly inside main.c's
+ * loop body; relocated here (same file, same naming convention as
+ * xce_sched_driver_translate_pending_events()/xce_sched_driver_on_decision()
+ * above) so it is a real, linkable, independently testable driver entry
+ * point rather than a main.c-private static function no test binary could
+ * reach -- see testsuite/test_driver_session_ordering.c, which white-box
+ * #includes driver.c to exercise this exact function.
+ *
+ * Takes an opaque `void*` (always the live `xce_scheduler_t*`, cast back
+ * inside driver.c) for the SAME reason xce_sched_driver_on_decision() above
+ * does: this function needs the FULL xce_scheduler_t* to reach
+ * plugin_begin_session()/sched_account_jobs()/plugin_end_session()/
+ * sched_publish_dispatch()/sched_publish_pend_reason() (all
+ * xce_scheduler_t*-coupled, scheduler.h), and this file's own boundary
+ * comment restricts driver.h to depending on core.h only.
+ *
+ * One round: xce_sched_driver_translate_pending_events() (task 5.1) drains
+ * buffered controller events; xce_core_begin_session() performs the
+ * begin-session state reset; plugin_begin_session()/sched_account_jobs()
+ * run (in that window specifically -- see core.h's doc comment on
+ * xce_core_begin_session()/xce_core_signal_go() for the full safety
+ * argument this ordering preserves); xce_core_signal_go() wakes the picker
+ * thread; the driver drains core->decisions, invoking the registered
+ * on_decision callback once per decision until the end-of-session NULL
+ * marker; plugin_end_session() and xce_core_end_session() close out the
+ * round.
+ *
+ * No return value (matches the original main.c helper's signature/
+ * behavior exactly -- a pure relocation, not a redesign): failures along
+ * the way (e.g. xce_core_begin_session() rejecting a reentrant call) are
+ * logged (ERROR) and the round is abandoned early: no picker signal, no
+ * decision drain, no plugin_end_session()/xce_core_end_session() for that
+ * malformed round -- the next call to this function tries again.
+ */
+extern void xce_sched_driver_run_normal_mode_round(void* driver_ctx);
+
 #endif

src/scheduler/include/scheduler.h

@@ -121,6 +121,17 @@ extern int  sched_update(xce_scheduler_t*);
 extern void sched_go(xce_scheduler_t*);
 extern void sched_begin_session(xce_scheduler_t*);
 extern void sched_end_session(xce_scheduler_t*);
+/* sched_account_jobs - per-running-job resource-in-use accounting
+ * (re-charges every RUN-state job's resources via sched_charge_account()
+ * after sched_begin_session()'s resval reset zeroes them). Exported as of
+ * scheduler-core spec task 5.2 so the new normal-mode driver loop
+ * (driver.c's xce_sched_driver_run_normal_mode_round()) can call it
+ * directly at the exact
+ * point xce_core_begin_session()'s caller must call it: after the resval
+ * reset, strictly before xce_core_signal_go() unblocks the picker thread.
+ * Was `static`; body unchanged, still also called from
+ * sched_begin_session() below (unchanged legacy call site). */
+extern int sched_account_jobs(xce_scheduler_t*);
 /* sched_get_job/sched_add_job/sched_get_queue/sched_add_queue/
  * sched_get_worker/sched_add_worker/sched_get_user/sched_add_user/
  * sched_get_project/sched_add_project/sched_job_is_ready/