# Deliberation — kido-hal-arm64 design (2026-10-14, second scaffold session)

Circle: builder crew (Mechane pattern). Question: what does the ARM64
bare-metal HAL honestly implement vs. stub, and how is it tested without
hardware? This closes the PARTIAL item from the boot conformance review
(the ARM64 bare-metal prober was a declared STUB).

Context: kido-boot's approved architecture gives the HAL a four-pointer
table (console_putc, console_puts, timer_ticks, timer_hz) plus a caps
struct (arch_name, mem_base, mem_size, timer_hz, has_fpu, has_mmu).
The HAL is the per-arch shim: ARM64 specifics live here and nowhere
else. N8toriousAi approved the boot architecture at the Gate; this module
builds on it without modifying it.

## Positions
- **P1 (registers-are-honest):** Implement everything readable from ARM64
  arch registers for real: generic timer (CNTPCT_EL0/CNTFRQ_EL0),
  FPU presence (ID_AA64PFR0_EL1), MMU presence (ID_AA64MMFR0_EL1),
  MIDR_EL1 identity. These need no firmware, no board knowledge — a
  bare-metal prober can honestly perform them. Stub ONLY what needs a
  firmware handoff: the memory map (needs DTB/UEFI) and board UART
  selection (needs to know which board).
- **P2 (one-real-UART):** Ship one genuinely working UART — QEMU 'virt'
  PL011 at 0x09000000, polled TX with TXFF flag check — because that is
  the board N8toriousAi will actually boot first. Other boards (RPi4) get
  declared IDs with loud STUB init, never silent wrong addresses.
- **P3 (test-the-contract):** The HAL's testable surface is its table-
  fill discipline: fill() populates all four pointers or fails loud;
  probe() fills caps honestly. Provide a hosted test double plus a
  self-test main (mirroring the boot module's harness pattern), and a
  documented syntax-test macro so the ARM64 asm paths get parsed on an
  x86_64 dev host. Report exactly what was and wasn't verified.

## Challenges
- **C1 against P2:** A minimal PL011 putc without a full init sequence
  (baud divisors, GPIO mux) assumes firmware configured the UART.
  Counter accepted with loud documentation: QEMU virt firmware does
  configure PL011; bare-metal-without-firmware is the documented STUB
  case, and unknown boards halt with NO_CONSOLE rather than scribbling
  at a guessed address. Assumption stated, not hidden.
- **C2 against P1:** ID_AA64* reads require EL1; CNTPCT_EL0 is EL0-safe
  by design. If the entry shim drops to EL0 before probe, the ID reads
  trap. Counter: the entry-shim contract (documented in the header)
  requires probe to run at EL1 or higher; the code comments state this
  at each ID read. Firmware-handoff discipline, not a code flaw.
- **C3 against P3:** Syntax-checking ARM64 asm on x86_64 proves parsing,
  not correctness — the assembler never runs. Counter accepted: the
  ledger and test report state this explicitly. Parsing + disciplined
  review is what a draft can honestly claim; execution proof waits for
  hardware or QEMU, which is N8toriousAi's call.

## Convergence
P1+P2+P3 all hold. Real: generic timer, FPU/MMU-presence/MIDR probing,
QEMU virt PL011 TX, board table with loud unknown-board refusal,
bootinfo struct as the entry-shim→HAL firmware-handoff contract.
Stub (loud): memory map without bootinfo, RPi4 UART init, MMU bring-up
(presence is probed; bring-up stays a STUB per the boot header).

## Preserved dissent
- **D1:** A minority held that device-tree parsing should be written now
  rather than stubbed, since memory discovery is on the critical path
  to any real boot. Overruled for this module: DTB parsing is a module-
  sized job (feeds kido-mem), and faking it here would violate the loud-
  stub discipline. The bootinfo struct is the honest seam.
- **D2:** Whether the hosted test double risks "testing the double, not
  the shim" (echo of the boot session's C1). Same mitigation: what is
  tested is the table-fill/probe contract discipline, identical across
  hosted and bare metal; the register primitives are arch and cannot be
  executed hosted. Stated in the test report.

## Decision
Write modules/kido-hal-arm64.[ch] per the converged design. Do NOT modify
the approved kido-boot.[ch]; the wiring point (boot adapt's bare-metal
branch calling kido_hal_arm64_fill) is documented as the explicit next
step for N8toriousAi's review.
