# Deliberation circle — kido-entry-arm64 design (2026-10-14)

Circle: the entry-shim builder and the constraints inherited from the
Gate-approved kido-boot and kido-hal-arm64 modules. No prior
entry-shim deliberation existed; this record is the first.

## Positions

**P1 — Split the shim: .S for the pre-C world, C for everything after.**
_start does only what C cannot: EL drop, SP setup, BSS zeroing, then a
single `bl` into C. All policy (bootinfo fill, DTB check, boot call,
halt) lives in C where it is testable and readable. Rationale: assembly
is where bugs hide; minimize its surface to ~40 instructions.

**P2 — A minimal linker script ships with the module.**
_stack_top, _bss_start, _bss_end must come from somewhere. Depending on
firmware-provided layout would make the shim untestable under QEMU
-kernel. The script is 30 lines, QEMU-virt-specific, and documented as
such — per-arch build material living with per-arch code.

**P3 — Verify the DTB, don't trust it.**
x0 arrives from firmware; reading its first word to check the FDT
magic (0xd00dfeed) is one honest load that distinguishes "firmware
handed us a device tree" from "x0 is garbage." A missing/invalid DTB
still yields mem_valid=0 (loud), never a fabricated map.

**P4 — The board is a loud assumption, not a detection.**
This image targets exactly one board (QEMU virt). Claiming detection
would require a DTB compatible-string parse — kido-mem's in-progress
job. The constant is marked ASSUMPTION in all caps at the fill site,
and the HAL's fill() still refuses unknown boards at runtime.

## Challenges

**C1 — "Why not parse the DTB compatible string now and detect the board for real?"**
Because DTB parsing is the sibling kido-mem builder's bounded space,
drafting in parallel against this same bootinfo contract. Duplicating a
half-parser here would fork the contract. Overruled by P4 + the
parallel-build boundary.

**C2 — "The QEMU boot proves nothing if both failure modes look identical."**
Partially true: a spin at the EL check and a spin in kido_halt() are
indistinguishable from outside. Mitigated two ways: (1) `-d int`
logging — any fault in the EL drop, SP setup, BSS loop, or DTB read
would log a sync/prefetch abort, and the log was empty; (2) the
approved kido_boot_early() stack/BSS checks RAN during that boot, so
the shim's setup passed its own integration test. What remains
unproven: which EL path executed, and cycle-level BSS correctness —
stated, not hidden.

**C3 — "kido_entry_c_main can't be self-tested hosted — it halts."**
Accepted. The fill/DTB/accessor contract is self-tested (5 checks);
the never-returns path is proven by the QEMU boot (exit 124, zero
exceptions). Two different proofs for two different properties —
documented in the module header.

**C4 — "Should _start print an alive-ping to the UART for bring-up debug?"**
Rejected. The UART belongs to the HAL; the shim scribbling at
0x09000000 behind the HAL's back would violate the layering the Gate
approved. Observability comes from QEMU's `-d int`, not from breaking
the driver boundary.

## Convergence

The shim is a thin honest sandwich: ~40 instructions of .S that create
a C environment, then C that fills the contract and hands off. Every
unknown is loud (mem_valid=0, DTB-invalid flag, spin on wrong EL).
kido-boot.c untouched. The bootinfo struct is stashed in BSS with an
accessor so kido-mem and the pending HAL wiring read the same truth.

## Preserved dissent

**D1 — BSS-zero proof gap (C2's remainder).** The QEMU test cannot
distinguish "BSS was zeroed correctly" from "BSS happened to be zero."
QEMU -kernel loads zero pages, so the test is weaker than hardware.
Dissent noted; revisit with a BSS poison-fill debug build before any
hardware claim.
