# 2026-10-28 — kido-sync design deliberation (builder crew)

Goal: the next module the tree can actually carry. Session 33's
remains are, again, all blocked or fenced: the QEMU virt PSCI
proof and the QEMU virt -smp proof need the toolchain (absent
a 17th time this session — `which` finds no
aarch64-linux-gnu-gcc, no qemu-system-aarch64); the Gate wirings
(vec into the boot path, GIC enable(30) + timer arm into the
scheduler tick, serial-irq init into the boot path, HAL wiring,
MMU call-site wiring, psci-init gating policy, secondary entry
stub) are Gate items, not things a scaffold session takes
unilaterally; the destroy bare-metal proof has its own design
(session 22, not swallowed here); D1 KIDO_ERR_NO_TASKS is
N8toriousAi's call; the BUBO peer is Phase 4. Per the session-22
precedent (degrade honestly to the next draftable module),
this session drafts kido-sync: the spinlock primitive that
session 33's secondaries need before they can share anything.
SMP brought CPUs up; nothing yet stops two of them writing
the same word at once. 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.

## Positions

- P1 (exclusives realist): on ARM64 the lock is the
  LDAXR/STLXR pair, acquire on take, release on give, with
  the WFE/SEV sleep/wake pattern from the architecture's own
  spinlock shape. No compiler-atomic spelling is substituted
  on the bare-metal path: the instruction sequence is the
  claim, and it must be auditable instruction-for-
  instruction when the toolchain returns.
- P2 (portability auditor): the hosted path uses GCC
  __atomic builtins (__atomic_compare_exchange_n for
  take, __atomic_store_n release for give), which are
  real atomic operations on the host, not a scripted
  double. The hosted proof therefore proves the lock's
  STATE MACHINE (init, take, contend, refuse, release,
  owner law) exactly; it does not prove the ARM64
  instruction sequence, and the header says so.
- P3 (honesty auditor): a lock that can be silently taken
  twice, silently released by a stranger, or silently
  released while free is worse than no lock — it launders
  races into "protected" code. Every one of those shapes
  refuses LOUD with KIDO_ERR_EARLY_ENV, and the lock's
  state is untouched on refusal.
- P4 (static-tables keeper): the lock is a caller-embedded
  struct, 16 bytes, no allocator, no module-global table.
  A lock must exist before any allocator policy, and a
  global lock registry would be a second invention.
- P5 (fence keeper): no scheduler, entry, boot, HAL, smp,
  or psci file moves. Sync is a leaf: it depends on
  kido-boot.h status codes only, and nothing yet depends
  on it. The scheduler/Gate wiring that USES the lock is
  a future Gate item, not this session's.
- P6 (test keeper): the hosted self-test pins every
  refusal path, including the stranger-unlock path — via
  a hosted-only CPU-id injector, the kido-image /
  kido-mem injector precedent, so the refusal is proven
  rather than code-reviewed.

## Challenges, answered

- C1 (no BUSY code exists): the status enum has no
  "contended" value, and inventing one is N8toriousAi's call
  by the sched-D1 precedent. So try_lock does NOT return
  a failure on contention: it returns KIDO_OK with
  *acquired = 0, the resonate-defer precedent (accepted/
  refused out-params, failure reserved for real errors).
  Contention is a fact the caller reads, never a failure
  code. NULL lock or NULL out-pointer, and an
  uninitialized lock, are real errors: EARLY_ENV loud.
- C2 (unbounded spin vs the bounded-polls law): mbox and
  pl011 bound every poll, and a spinlock that spins
  forever looks like a violation. It is not: a lock held
  by a LIVE holder always progresses, so lock() spins
  until it holds — that is the primitive's definition.
  The bounded door exists alongside it (try_lock), and
  the dead-holder case is stated, not hidden: if the
  holder CPU dies holding the lock, lock() never
  returns, and no timeout would make that safe — a
  timeout would let two CPUs into the critical section
  together, which is the exact corruption the lock
  exists to prevent. Callers that cannot wait use
  try_lock.
- C3 (IRQ context): the lock does NOT disable
  interrupts, and taking the same lock in an IRQ handler
  that interrupted its holder deadlocks the CPU (the
  handler spins for a holder that cannot run). Stated
  as law in the header: locks are CPU-to-CPU exclusion,
  not IRQ exclusion. IRQ handlers use try_lock or a
  separate discipline; the scheduler/Gate wiring owns
  that policy, not this module.
- C4 (owner tracking): the lock records its owner's CPU
  id — MPIDR_EL1 raw on ARM64 (readable at EL1, unique
  per CPU in practice, never parsed: smp/psci's opaque-
  affinity law), the hosted injector's value on hosted.
  unlock() refuses EARLY_ENV when the caller is not the
  owner, and the lock stays held. The owner word is
  written while the lock word is held (so only the
  holder writes it) and cleared before the release
  store; STLR's release semantics order the clear
  before the unlock visibly lands. Owner value
  UINT64_MAX means "free" and is never a valid CPU id
  (MPIDR_EL1 raw never reads all-ones on a real CPU;
  the injector refuses it, pinned by test).
- C5 (WFE sleep vs pure spin): lock() sleeps with WFE
  after observing the lock held, and unlock() sends SEV.
  Pure spinning burns the interconnect and starves the
  holder on a shared core; WFE/SEV is the documented
  shape. One liveness trap, closed in the asm: the WFE
  sits ONLY on the "observed held" branch. A failed
  STLXR retries the LDAXR immediately, never through
  WFE — otherwise a spurious exclusive failure with a
  free lock and no future SEV could sleep forever.
  SEVL primes the first iteration so a lock freed
  before we arrive never makes us sleep at all.
- C6 (memory ordering): LDAXR is acquire, STLXR/STLR
  are release; the header states the guarantee plainly
  (writes before unlock are visible after a later lock)
  and nothing stronger is claimed. No DMB is needed for
  the lock itself: the acquire/release pair IS the
  ordering. The barrier primitive that will build on
  this (named future) owns any further ordering.
- C7 (init on a live lock): init() refuses EARLY_ENV if
  the lock word is nonzero — re-initializing a held
  lock would silently free it under its holder. Init
  on a free lock (including a previously used, properly
  unlocked one) succeeds and resets owner to free. A
  magic field (KIDO_SYNC_MAGIC) makes "uninitialized"
  detectable: every API refuses a bad magic before
  touching the word.
- C8 (is_locked is a snapshot): is_locked() reads the
  word once and reports it. On a live system another
  CPU may take or release the lock in the next instant;
  the value is a diagnostic snapshot, never a
  synchronization point, and the header says so in
  those words. Callers that need certainty use
  try_lock.

## Convergence

- API, six functions: init / lock / try_lock /
  unlock / is_locked / (hosted-only) test_set_cpu_id.
  No new header codes (sched-D1 precedent, smp P6).
- Struct: { uint32_t word; uint32_t magic; uint64_t
  owner } — 16 bytes, 8-aligned, caller-embedded.
  The word is the ONLY field the exclusive pair
  touches; magic and owner are plain words guarded by
  the lock word itself.
- Hosted proof proves the state machine with real
  atomics; the ARM64 instruction sequence is WRITTEN,
  NOT ASSEMBLED, NEVER EXECUTED until the toolchain
  returns — stated in the header, as every session
  since 22 has stated it.
- No lock is wired anywhere this session. The first
  consumer (scheduler/Gate wiring, or an smp shared-
  state guard) is a Gate item with its own design.

## Preserved dissent

- D1 (bounded-spin lock with a timeout): overruled.
  A timeout on lock() converts a dead holder into two
  holders — silent corruption instead of a loud hang.
  try_lock is the bounded door; lock() is honest
  about what it is.
- D2 (ownerless simple lock): overruled. A 4-byte word
  alone cannot tell a stranger's unlock from the
  owner's, and stranger-unlock is silent corruption
  with a "protected" label on it. The 8-byte owner
  word costs nothing and makes the refusal loud.
- D3 (ticket lock / FIFO fairness): overruled for this
  version. A test-and-set lock can starve a waiter
  under heavy contention; the SMP bring-up path is
  low contention, and fairness is a measurable
  property to add when a contended consumer exists,
  not a guess to bake in now. Named future, with the
  starvation documented, not hidden.
- D4 (disable IRQs inside lock): overruled. IRQ
  masking policy belongs to the vec/GIC wiring and
  the scheduler, not to a leaf primitive — and on SMP
  masking local IRQs does not exclude other CPUs
  anyway. The IRQ law (C3) is the honest boundary.

## Proof gate (queued, toolchain)

- Hosted self-test this session (real __atomic
  compare-exchange/store, injector-proven stranger refusal); plain
  hosted -c clean; full hosted battery re-run;
  collision check (zero kido_sync references outside
  the two new files before writing).
- ARM64 proof (queued): assemble the inline asm,
  disassemble the LDAXR/STLXR/WFE/SEV sequence,
  cross-compile -ffreestanding -Werror clean, then a
  QEMU virt -smp 2 run where CPU 1 takes a lock CPU 0
  holds (try_lock sees 0, then 1 after release) with
  zero exceptions. That run needs the toolchain AND
  the Gate secondary stub, so it waits on both —
  stated, not hidden.
