# 2026-10-31 — kido-topo deliberation (session 40, builder crew)

## The gap, stated first

Session 33 assigned each secondary CPU a slot by bring_up
order. Session 38 gave every PE a decodable identity. Since
then the tree has had no record of which identity lives in
which slot, and the workarounds available are exactly the
ones earlier sessions refused:

- Re-read firmware per slot (kido_smp_query) — but query
  answers STATE (ON/OFF), not identity. It cannot say
  which PE slot 3 is.
- Assume Aff0 == slot — the QEMU-virt accident mpidr's
  no-linear-index law forbids as arithmetic. On a
  multi-cluster system Aff0 repeats across clusters and
  two PEs alias into one slot.

The missing piece is a table, not a formula: register the
binding when it is known (bring_up knows the affinity it
passed to cpu_on; the arriving secondary knows its own
MPIDR), and look it up afterwards. This session drafts
kido-topo: that table. Zero existing files touched (the
session-24/25/26/33 fence pattern); the module-map row
and the ledger entry are the only other edits. No wiring
into smp arrival, ipi masks, or call slots — consumers
are Gate items, as with every leaf since session 33.

## Circle

- **P1 binding realist** — the table's reason to exist is
  the question "which PE is slot 3?", asked by the ipi
  mask validator, the CALL handler, and any scheduler
  that places work by affinity. All three currently
  have no honest answer.
- **P2 no-arithmetic auditor** — the slot is a label
  assigned by smp, passed explicitly, never computed
  from Aff. Any formula in this leaf would be mpidr's
  C2 invention wearing a new header file.
- **P3 conflict auditor** — a topology table that
  silently overwrote entries would let a late arrival
  steal a live CPU's identity. Both conflict arms
  (Aff known at another slot, slot held by another
  Aff) must refuse loud with the table untouched.
- **P4 absence auditor** — an unregistered Aff is a fact
  (that PE has not arrived yet), not a failure. The
  found-flag pattern from try_lock and resonate-defer
  already says how the tree reports absence.
- **P5 fence keeper** — leaf, no coupling beyond
  mpidr's decoded struct and sync's public lock API,
  no wiring. The smp arrival registration and the
  primary's registration are named consumers, not this
  session's edits.
- **P6 test keeper** — the hosted proof must pin the
  conflict arms, the idempotent arm, MT/U blindness,
  the multi-cluster alias guard, and concurrent
  registration under the real spinlock — the only
  things a host can pin about a topology table.

## Challenges, answered

- **C1 — module-global or caller-embedded?**
  Module-global. Topology is system-wide by nature:
  there is one answer to "which PE is slot 3?", not
  one per caller. The ipi registry (SGI ids are one
  system-wide namespace) and the call mailbox (slots
  belong to their target CPU) already set this
  precedent; the sync/barrier caller-embedded shape
  was argued for locks and rendezvous, whose scope
  genuinely is per-use. A caller-embedded topology
  table would let two callers disagree about the
  machine — the exact failure a registry exists to
  prevent.
- **C2 — why its own MAX_CPUS constant?** The ipi
  precedent: KIDO_IPI_MAX_CPUS is 8 with the comment
  "the smp table's count." Duplicating the value with
  the same comment, rather than including kido-smp.h,
  keeps the leaf's coupling at mpidr + sync instead of
  dragging in the whole smp state machine for one
  number. The cost is stated in the header: if the
  census ever grows, the three constants move together
  as a Gate reconciliation item, never by silent drift.
- **C3 — decoded struct or raw affinity?** Decoded
  struct, no raw API. smp stores affinities raw
  (uint64_t), so a Gate consumer holding one decodes
  it first with the pure kido_mpidr_decode() — one
  call, no register read — and comparison then lives
  in exactly one place (same_cpu). A raw lookup API
  would be a second comparison path that could drift
  from the decoded one (for example, by comparing
  MT/U bits the decoded path ignores). The stored
  struct carries raw whole, so a lookup result still
  answers "which PE" with full fidelity.
- **C4 — the two conflict arms and the idempotent
  arm.** Same Aff at a different slot refuses
  (aliasing: one PE in two slots). Different Aff at
  the same slot refuses (theft: two PEs in one slot).
  The exact same pair returns OK with the count
  unmoved — an arrival retry (secondary_arrived
  called twice, a Gate wiring re-running registration)
  must be safe, and making it an error would punish
  the retry path the tree most wants to be robust.
  Both conflict arms are checked in one scan, so no
  ordering between "Aff known" and "slot known" can
  produce a half-answer. A full table refuses through
  the slot-conflict arm (every slot occupied, so any
  new Aff collides) — no separate FULL code, and none
  invented, per the sched-D1 precedent.
- **C5 — absence is found = 0, never an error.**
  slot_for on an unregistered Aff and aff_for on an
  unoccupied slot return KIDO_OK with *found = 0 and
  the out-pointer untouched. The caller that needs a
  registered PE checks found; the caller probing
  "has it arrived yet?" gets a clean no. Only
  malformed calls refuse: NULL pointers, slot >= 8,
  any call before init.
- **C6 — why init() registers nothing.** The boot
  CPU's Aff is unknown to this leaf until a caller
  reads it, and the slot it belongs in is smp's
  assignment, not this leaf's guess. Auto-registering
  the caller at slot 0 inside init() would crown slot
  0 by fiat — the primary law the header states — and
  would couple init to "current CPU" policy. The Gate
  wiring (read, then register at the smp slot) is a
  Gate item. The zero Aff tuple is registrable: it is
  the uniprocessor-shaped value, and refusing it would
  refuse the UP machine's only CPU.
- **C7 — the lock, and its owner on the host.**
  One module-global spinlock, held across each whole
  operation; the only call made under it is the pure
  same_cpu(), so no lock-order question exists. The
  sync IRQ law applies unchanged. On the host the
  injector CPU id is constant across threads, and
  lock/unlock pair inside a single call on one thread,
  so the §6 pthread proof cannot trip a spurious
  stranger refusal — the lock proves contention
  safety, and the test's constancy is stated, not
  hidden.
- **C8 — init-once, no destroy.** init() succeeds
  exactly once; a second init refuses even over an
  empty table, because re-init would need a policy
  for existing entries and refusing keeps the table
  append-only. There is no destroy API: unlike sched's
  stacks, this leaf owns no resource a destroy would
  free (static BSS table, static lock) — the
  session-37 D1 distinction, applied here rather than
  inventing a teardown for symmetry's sake.

## Convergence

One leaf, five functions (init / register / slot_for /
aff_for / count), one module-global table of 8 entries
guarded by one spinlock, no new header codes (EARLY_ENV
for every refusal, found = 0 for absence), no coupling
beyond mpidr's decoded struct and sync's public lock
API, zero existing files touched. The slot is a label,
never arithmetic. The table is append-only, with two
loud conflict arms and one idempotent arm. The primary
is registered by a Gate wiring, not crowned by init.

## Preserved dissent

- **D1 — auto-register the primary in init()
  (overruled, C6).** Convenient (the table would never
  be missing the boot CPU) and wrong: init would have
  to read MPIDR itself and choose a slot, inventing
  exactly the policy the leaf refuses to own. The
  missing-primary state is visible (count 0, found 0)
  until the Gate wiring fills it — honest absence,
  not a gap to paper over.
- **D2 — a raw-affinity lookup API (overruled, C3).**
  Tempting for smp consumers holding raw uint64_t
  affinities, but a second comparison path. One decode
  call at the consumer keeps comparison in one place.
- **D3 — a linear index helper, Aff -> slot by
  formula for the single-cluster case (overruled,
  C2).** The mpidr D1 refusal, restated: QEMU virt's
  Aff0 == CPU number is a platform accident, and a
  helper that is correct on virt and aliasing on a
  multi-cluster system is worse than no helper. The
  table is the helper.
- **D4 — re-init clears the table (overruled, C8).**
  A resettable registry invites a caller to "fix" a
  bad registration by wiping the machine's topology
  under live CPUs. Append-only with loud refusal is
  the conservative shape; a genuine reset (for a
  reboot path) makes its own case to the Gate.

## Honest limits

WRITTEN, NOT ASSEMBLED, NEVER EXECUTED — toolchain
absent a 23rd time (no aarch64-linux-gnu-gcc, no
qemu-system-aarch64; `which` finds neither). The leaf
has no asm of its own — its ARM64 content is sync's
already-carried exclusive pair — so what awaits a
tooled VM is a QEMU virt -smp 2 run showing two
distinct Aff tuples registered at two distinct slots,
which also needs the Gate arrival wiring (C6) before
the registration proof means anything on silicon. The
hosted proof pins the table discipline — conflicts,
idempotence, MT/U blindness, the multi-cluster guard,
concurrent registration under the real spinlock —
not delivery across silicon. The non-hosted
-fsyntax-only build correctly REFUSES on the x86 host
(the arch-discipline error, working as designed, the
mpidr/cache precedent).
