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 dropped (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: the shared loop resets ctx->alloc_req.host to empty before every bucket's host scan, for both allocators. Background: the per-host request used by the authoritative check is already rebuilt for every candidate (sched_try_alloc_on_host_() -> plugin_prepare_ allocation() with ctx->worker set resets and refills it, plugin.c:639). The per-bucket reset only affects the host iterator's pre-filter (host_iter.c:143), which reads alloc_req.host before that rebuild and silently skips hosts that fail. parjob already resets (parjob_allocator.c:479), so its pre-filter does no resource filtering. seqjob does not, so its pre-filter reads stale content: the job-level slots:1 for the first candidate, then the last rejected candidate's full request. Resetting for seqjob too drops the stale-state dependency and makes seqjob's pre-filter a resource no-op, like parjob's. Accepted consequence (intentional change): host choice is 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 reset fixes). But a pending seqjob job now gets a PREASON_NO_RESOURCE host/resource reason from the authoritative check (resource.c:575) for every host that passes the select filter and lacks resources, not only for hosts the stale pre-filter let through. main_reason is unaffected (host/resource reasons go to res_based_reasons, lib/preason.c:147), so sim parity (sim_verify_pend_main_reason_eq) is unaffected; no testsuite file asserts PREASON_* host reasons (checked 2026-09-29). Also accepted (found in design review): seqjob now runs the per-host prepare fan-out on those hosts too, so the limit plugin may instantiate a host limit's virtual resource and set its value on the worker earlier than before (decision-neutral, lazy creation moves earlier), at the cost of one prepare + check per short host per pending seqjob attempt. Rejected: keeping the reset parjob-only (preserves the stale-state quirk in shared code); staging each bucket's real request before the scan so the pre-filter filters correctly (changes parjob's pend reasons too; a separate follow-up if wanted).
  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): the shared pend-reason loop iterates the unmet list (ctx->unmeet.count), fixing bug-1893. Both current my_alloc()s loop to ctx->alloc_req.shared.count over ctx->unmeet, whose tail is zero-filled, and add reasons naming resource index 0. Moving the loop into the runner is the natural point to fix it; 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).