myxce/.kiro/specs/scheduler-allocator-runner/brief.md

Brief: scheduler-allocator-runner

Problem

Scheduler plugin authors and maintainers. seqjob_allocator.c (my_alloc, line 213, ~215 lines) and parjob_allocator.c (my_alloc, line 545, ~220 lines) each own the entire allocation algorithm, although only plan generation is plugin-specific. ~100+ lines are duplicated verbatim (lazy pend-reason, sched_ctx_get_uncomit_shared, sched_check_shared_satisfy + PREASON_NO_RESOURCE fill, add-uncommitted-shared, plan-iterator loop skeleton, commit tail with sched_make_allocs + -ENOMEM cleanup chain). Every bug fix (bug-1882, bug-1767, bug-1768) has to land twice, and a new allocator plugin must copy the whole my_alloc(). Driver: issues/new_requirements.md item 4.

Current State

• Framework dispatch sched_make_primary_alloc_() (scheduler.c:235) picks core->seqjob_allocator (maxTasks == 1) or core->parjob_allocator and calls plugin->job_alloc_fn(plugin, ctx).
• Plan generation is already abstracted behind xce_alloc_plan_iter_t (include/sched/alloc_iter.h); host scan behind xce_host_iter_t.
• The picker side already uses a framework-owned iface pattern (xce_job_picker_iface_t, plugin->picker_iface, plugin.h:88).
• alloc_iter.h init's third parameter is xce_scheduler_t*, unused by both implementations ((void)sched); sim mode has no real scheduler.
• parjob has parjob_try_plan_ / parjob_rollback_claims_ / parjob_snapshot_host_req_ claim bookkeeping; seqjob keeps a single w.

Desired Outcome

• Neither plugin defines my_alloc(); both register .job_alloc_fn = sched_allocator_run and supply only an xce_sched_allocator_iface_t (optional accepts guard + plan iterator) plus their existing prepare_allocation.
• One framework function owns shared-resource prep, the bucket -> host-claim loop with rollback, and the commit tail.
• Allocation decisions are bit-for-bit identical to today for every existing test and sim-parity fixture. Intentional differences, all outside the decision and main pend reason: pending seqjob jobs may gain per-host NO_RESOURCE reasons (Constraints item 1); spurious shared reasons are recorded for the first time (bug-1893, item 6); seqjob gets the -EINVAL guard and OOM rollback (Req 5 AC 1/5).
• new_requirements.md item 4 closed.

Approach

Framework runner, lean (chosen 2026-09-28). The design proposal of 2026-09-23 (§5), with the optional commit hook left out because nothing uses it yet:

• xce_sched_allocator_iface_t { accepts; plan_init; plan_next; plan_fini; } in plugin.h; allocator_iface pointer on xce_sched_plugin_t with the same ownership as picker_iface.
• sched_allocator_run() = guards -> accepts -> sched_alloc_prepare_shared_() -> plan loop -> sched_try_plan_() (promoted parjob_try_plan_) -> sched_finalize_job_alloc_() (one make_host_alloc per claim -> make_job_alloc -> allocs_shared block).
• Retype alloc_iter.h init's third parameter to xce_sched_core_t*.
• Staged migration keeps the suite green: (1) extract shared helpers used by both existing my_alloc()s; (2) runner + iface, parjob first; (3) seqjob; (4) retype plan_init; (5) close item 4.

Rejected: adding the commit override hook (an unused extension point that would need its own tests); only extracting helpers (would not meet item 4's goal that plugins no longer export my_alloc()).

Scope

• In: new allocator iface + framework runner; shared prep/try-plan/ finalize helpers; delete both my_alloc()s and parjob's claim helpers; retype xce_alloc_plan_iter_t.init to xce_sched_core_t*; equivalence tests; the bug-1893 loop-bound fix (Constraints item 6); update issues/new_requirements.md item 4.
• Out: see Out of Boundary.

Boundary Candidates

• Plugin ABI (plugin.h iface + plugin template wiring)
• Framework allocation runner (new plugin_alloc.c or scheduler.c) — shared-resource prep, claim loop/rollback, commit tail
• Plan-iterator contract (alloc_iter.h retype; seqjob/parjob plan iters)

Out of Boundary

• Retyping sched_make_allocs() to xce_sched_core_t* and removing the (xce_scheduler_t*)plugin->sched cast (follow-up; callers outside allocators).
• Collapsing sched_make_seqjob_allocation / sched_make_parjob_allocation dispatch in scheduler.c (optional, only if trivially falls out).
• The commit override hook.
• bug-1892 (unsatisfy_() reads the index-keyed uncommitted vector by list position; wrong admission for later primaries of COMPOUND/ALTER jobs). It lives in resource.c's satisfy checks, which the runner calls unchanged; fix it separately. Equivalence tests for COMPOUND/ALTER must not encode its wrong outcomes as expected values.
• The FIXME: no duration now (NULL duration to sched_make_allocs): carry it over unchanged, don't fix it here.
• Any change to plan ordering, host ordering, pend-reason content, or preemption, except the decided seqjob host-reason change in Constraints item 1.

Upstream / Downstream

• Upstream: scheduler-allocation (plan/host iterators, Req 4 combinatorial parjob, Req 9 no-regression); scheduler-core (plugin/picker iface pattern, sim mode); libxce-alloc-preason-equality (job_alloc_eq used by sim verify).
• Downstream: any future allocator plugin (it would need only a plan iterator); scheduler-preemption; the follow-up sched_make_allocs retype.

Existing Spec Touchpoints

• Extends: none (scheduler-allocation is implementation-complete; its Req 9 is inherited as a constraint, not reopened).
• Adjacent: scheduler-allocation, scheduler-core, scheduler-sim-discrete-clock (in flight, touches sim_loop — avoid overlapping files), libxce-alloc-preason-equality.

Constraints

• TDD: tests in src/scheduler/testsuite/ first; full ASAN build via /xce-build scheduler.
• Behavioral equivalence is mandatory. Preserve exactly: bug-1882 (half-built alloc never left on ctx->alloc), bug-1767 (parjob maxTasks <= 1 returns 0 with no fabricated reason, and before the lazy reason is created), bug-1768; -ENOMEM cleanup order of both current tails, plus the seqjob OOM rollback of item 2 (Req 5 AC 5).
• Divergences found in discovery that the design MUST resolve explicitly (they are not in the 2026-09-23 proposal):
  1. Decided 2026-09-29, revised 2026-09-30 (task 2.2 finding, user decision): the runner clears ctx->alloc_req.host before every candidate host (at the start of each bucket and after every rejected candidate), for both allocators. The per-host request used by the authoritative check is rebuilt for every candidate anyway (plugin_prepare_allocation() with ctx->worker set, plugin.c:639). What the clear changes is the host iterator's pre-filter (host_iter.c:143), which reads alloc_req.host before that rebuild and silently skips hosts that fail. The 2026-09-29 plan (clear once per bucket, as parjob does) turned out not to be enough: task 2.2's characterization showed that a rejected candidate leaves its own request behind, so parjob today records reasons only for the first rejected candidate of a bucket search, and a once-per-bucket clear would give seqjob the same partial reasons. With a clear before every candidate, the pre-filter only applies the select expression, and every selection-matching unclaimed short host gets its host/resource reasons, in both allocators. Accepted consequences (intentional changes): host choice, main reason and decisions are unchanged (a host the stale pre-filter rejects also fails the authoritative check while the per-host request is host-independent; where a limit makes it host-specific, the stale filter could wrongly skip a host, which the clear fixes). Pending jobs of both allocators carry more host/resource reasons (res_based_reasons; not main_reason, so the unsatisfiable cache and sim parity are unaffected). The per-host prepare fan-out, including the limit plugin's lazy host-limit instantiation, now runs on every short host (decision-neutral; one prepare + check per short host per bucket search). Larger reason sets are published and persisted; publishing reasons only when they change is a follow-up (user, 2026-09-30), out of scope here. Rejected: clearing once per bucket (partial reasons, still stale-state dependent); keeping today's per-plugin behaviour.
  2. Decided (requirements Req 5 AC 5): seqjob builds its halloc directly from ctx->alloc_req.host; under the shared per-claim snapshot it gains a new -ENOMEM path, which goes through the same rollback (sched_ctx_uncommit_host) as parjob's.
  3. Decided 2026-09-29: for seqjob, ctx->nslots and ctx->nhosts are always 1. Their only consumer is sched_fill_limit_requests() in plugin_prepare_allocation() (plugin.c:682 job-level pass, :699 per-host pass); sched_try_alloc_on_host_() does not read them. Today seqjob sets 1/1 only in its job-level prepare pass (seqjob_allocator.c:92) and relies on the values carrying into the per-host passes. The shared loop sets ctx->nslots = plan->bucket_slots[b] and ctx->nhosts = 1 before every bucket's host scan (as parjob does, parjob_allocator.c:492); seqjob's plan is always one bucket of one slot (seqjob_allocator.c:163), so seqjob sees exactly 1/1 in every pass. The seqjob plan iterator must keep nbuckets == 1 and bucket_slots[0] == 1 (assert in tests).
  4. Decided (requirements Req 5 AC 3): seqjob's accepts is NULL. seqjob has no maxTasks guard today, and a seqjob_accepts (maxTasks == 1) would change behaviour for direct callers with another value (48 testsuite files reference the allocators).
  5. Proposal-sketch defects to avoid: sched_ctx_primary == NULL typo; claims[plan->nbuckets] VLA (heap-allocate or bound by maxTasks).
  6. Decided 2026-09-29 (requirements review), corrected 2026-09-30 (task 2.1): the shared pend-reason loop iterates the unmet list (ctx->unmeet.count) and skips only on vget() < 0, fixing bug-1893. Both current my_alloc()s skip on vget() <= 0, but vget returns 0 on success, so today no shared NO_RESOURCE reason is ever recorded (the loop also runs to alloc_req.shared.count). After the fix a job pending on shared resources names each short one; main reason and decisions are unaffected.
• Claim host_req snapshots are owned by the framework: fini on every exit path (success, bucket failure, OOM).
• Verify with: test_seqjob_*, test_parjob_*, test_seqjob_rewrap_equivalence, test_maxtasks_wiring_*, test_sim_*_parity, test_sim_live_allocation, test_snapshot_load_allocator_regression; /xce-audit-invariants scheduler (driver state-equivalence).