myxce/.kiro/specs/libxce-alloc-preason-equality/research.md

# Research & Design Decisions

## Summary
- **Feature**: `libxce-alloc-preason-equality`
- **Discovery Scope**: Extension (relocate existing comparison logic, add public API, migrate consumers)
- **Key Findings**:
  1. The type-level equality comparators in `sim_verify.c` operate purely on libxce structs with zero scheduler/capnp/replay dependency — they are cleanly movable; the decision-level dispatcher and mismatch reporting are not.
  2. The comparators are already shared across four translation units, but via white-box `#include "../src/sim_verify.c"` + direct calls to `static` functions (`test_sim_equivalence.c`, `test_repl_equivalence.c`, `test_repl_limit_table.c`).
  3. The controller (`persist.c`, `resync.c`, `job.c`) already consumes `xce_job_alloc_t`/`xce_host_alloc_t`/`xce_job_preason_t`/`xce_alloc_t` with no equality API — confirming these structs are genuinely cross-component, not scheduler-only.
  4. One deliberate field exclusion is baked into the alloc comparators (`from`/`instid`), which generalizes cleanly into a shared identity contract. The preason comparator's main-reason-only narrowing is *not* an identity property — it is a replay artifact (bug-1845) that must stay in the simulator while the shared `job_preason_eq` becomes a full match.

## Research Log

### Where do the equality checks live?
- **Context**: locate all comparison logic in the scheduler simulator.
- **Sources Consulted**: `src/scheduler/src/sim_verify.c` (full read); `src/scheduler/src/sim_loop.c`, `sim_alloc.c`, `sim_picker.c`, `sim_limit.c` (grep for `_eq`/`_equal`/`compare`).
- **Findings**: `sim_verify.c` (474 lines) is the only file with equality logic. It holds five `static` leaf comparators plus `sim_decision_eq`, `sim_log_mismatch`, and two `describe_*` helpers. No other sim file compares these structs.
- **Implications**: the split point is exactly between the five `static` leaf functions and `sim_decision_eq`.

### Who consumes these comparators, and how?
- **Context**: understand the "future sharing" concern.
- **Sources Consulted**: grep for `sim_verify_job_alloc_eq`/`sim_verify_job_preason_eq`/`sim_verify_alloc_eq` across `src/scheduler/testsuite/`.
- **Findings**: three test files call the two leaf comparators directly after white-box-including `sim_verify.c`: `test_sim_equivalence.c:894,902`, `test_repl_equivalence.c:734,742`, `test_repl_limit_table.c:2662,2670`. Each builds its own `replay_decision_content_eq`-style helper on top of the two leaves.
- **Implications**: moving the leaves to libxce turns a fragile include-and-call-static hack into a normal public API; these three files must migrate their call sites.

### Are these structs shared beyond the scheduler?
- **Context**: justify libxce as the destination rather than "scheduler convenience".
- **Sources Consulted**: grep for the four struct names across `src/controller`, `src/worker`, `src/harness`, `src/lib`.
- **Findings**: `xce_job_alloc_t`/`xce_host_alloc_t`/`xce_job_preason_t`/`xce_alloc_t` are consumed by `src/controller/persist.c` (Cap'n Proto encode/decode), `src/controller/resync.c`, and `src/controller/job.c`, plus the scheduler. No equality API exists anywhere.
- **Implications**: the controller is a real future consumer of equality; the API belongs in libxce.

### Where do the structs' construction/dup helpers already live?
- **Context**: choose the destination module.
- **Sources Consulted**: `src/lib/xcealloc.c` (read full), `src/include/xcealloc.h`, `src/lib/preason.c`, `src/include/preason.h`.
- **Findings**: `make_alloc`/`make_host_alloc`/`make_job_alloc`/`dup_job_alloc`/`make_job_account` in `xcealloc.c`; `erase_job_preason`/`add_job_preason`/`make_pendreason` in `preason.c`. No existing `_eq`/`_equal` convention in libxce (only `float_equal` in `utils.h`); no NULL-safe string-equality helper exists.
- **Implications**: co-location with construction is the natural home; the string helper is new and only needed by the alloc family today.

## Architecture Pattern Evaluation

| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| Co-locate in existing modules | equality beside `make_*`/`dup_*`/`erase_*` | matches precedent, no new module | none material | selected |
| New `xce_equality.{c,h}` | one module for all four | single discoverable location | new module for 4 small functions | rejected (YAGNI) |
| Leave in scheduler, expose via header | promote the statics to scheduler-external | minimal | controller can't use them; wrong ownership | rejected |

## Design Decisions

(Full decisions live in `design.md`; the significant trade-offs are recapped here.)

### Decision: `job_preason_eq` is a full structural match; the simulator keeps its own main-reason-only PEND check
- **Context**: `sim_verify_job_preason_eq` compares only `main_reason`, deliberately (bug-1845) — sim has no alloc cache, so its full detail can never match a recorded cache-hit's main-reason-only shape; requiring detail to match produced systematic false mismatches. That narrowing answers "same replay outcome", not "identical pending-reason objects".
- **Alternatives Considered**:
  1. Publish full-deep `job_preason_eq` + keep a `static` main-reason-only helper in `sim_verify.c` for the PEND branch (selected).
  2. Publish `job_preason_eq` as main-reason-only (rejected — leaks a replay artifact into a general-purpose equality API).
- **Selected Approach**: `job_preason_eq(a, b)` returns non-zero iff `main_reason` matches and both detail lists (host-based, resource-based) match in order field-for-field. `sim_decision_eq`'s PEND branch uses a small simulator-local `static` main-reason-only comparison instead of `job_preason_eq`.
- **Rationale**: a public "same pending reason" predicate must be identity-honest; the replay asymmetry is a scheduler-only concern and stays where it belongs.
- **Trade-offs**: two PEND-comparison shapes exist (full-match in libxce, main-reason-only in sim_verify.c) — intentional, they answer different questions, and the sim-local helper is `static` and small.
- **Follow-up**: none expected; the sim-local helper is not exported.

### Decision: preserve NULL and order semantics exactly
- **Context**: the current leaf comparators use "identical pointer (including both NULL) → equal; exactly one NULL → not-equal", and ordered list comparison.
- **Selected Approach**: reproduce exactly in libxce.
- **Rationale**: the relocation is required to be zero-behavioral-change (Requirement 3); ordered comparison is correct because both sides come from the same deterministic construction.

## Risks & Mitigations
- Risk: a consumer silently relies on the excluded fields (`from`/`instid`, preason detail) → Mitigation: explicit doc contract on each function + revalidation triggers; no behavior change for existing consumers.
- Risk: migration of the three white-box test files breaks their `replay_decision_content_eq` helpers → Mitigation: mechanical call-site rename, verified by the full scheduler suite (task 7).
- Risk: duplicate-symbol collisions if a test both white-box-includes `sim_verify.c` and links libxce after the statics are removed → Mitigation: the statics are deleted from `sim_verify.c` (task 4) before the test files migrate (task 5), so the names resolve only against libxce.

## References
- `src/scheduler/src/sim_verify.c` — current home of the comparators (source of truth for field lists and exclusion rationale).
- `src/include/xce/types.h` — the four struct definitions.
- `src/lib/xcealloc.c`, `src/lib/preason.c` — destination modules and their construction/dup conventions.
- `.kiro/specs/scheduler-snapshot-job-allocation/` — precedent for a scheduler-driven spec adding libxce helpers (`dup_job_alloc`) to `xcealloc.c`.