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.
- `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; 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.
- 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.

## 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.
- Divergences found in discovery that the design MUST resolve explicitly
  (they are not in the 2026-09-23 proposal):
  1. parjob does `xvec_idval_fini/init(&ctx->alloc_req.host)` per bucket
     (`parjob_allocator.c:452`); seqjob never resets it. Decide whether the
     shared loop always resets, and prove it is a no-op for seqjob.
  2. seqjob builds its halloc directly from `ctx->alloc_req.host`; under the
     shared per-claim snapshot it gains a new `-ENOMEM` path. It must go
     through the same rollback (`sched_ctx_uncommit_host`).
  3. seqjob does not set `ctx->nslots/nhosts` in its loop. Its values come
     from `seqjob_prepare_allocation` (1,1). `sched_try_alloc_on_host_()`
     (`resource.c`) does not read them directly; check which hook does, and
     that `bucket_slots[0] == 1` for seqjob.
  4. seqjob has no `maxTasks` guard today. A `seqjob_accepts`
     (`maxTasks == 1`) changes behaviour for any direct caller with another
     value (several testsuite files reference `seqjob_allocator`). Either
     make `accepts` NULL for seqjob or audit those callers.
  5. Proposal-sketch defects to avoid: `sched_ctx_primary == NULL` typo;
     `claims[plan->nbuckets]` VLA (heap-allocate or bound by `maxTasks`).
- 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).