# 2026-10-23 — kido-mem UEFI discovery design (builder crew)

**Piece:** draft `kido_mem_discover_uefi` for real — the no-DTB memory
path, a loud `KIDO_ERR_STUB_REACHED` stub since session 3
(2026-10-14). It is the last open DEFERRED item from the session-3
conformance review (allocator: landed session 5; interior-carving
relaxation: its premise was closed by the session-19 C1 distinction —
the loud interior rule stands as designed, and relaxing it would mean
a multi-region `kido_bootinfo_t`, a Gate item). This session closes it.

**Why this piece now:** "UEFI/RPi4/MMU" were the named remains;
kido-mmu drafted session 22 (2026-10-22). UEFI is the next unbuilt
module-path draftable without hardware: pure data parsing, portable
C, host-testable with synthetic memory maps — the session-3 DTB
pattern exactly. RPi4 UART init stays queued (board-specific register
sequences; nothing to test them against on this VM). The destroy
bare-metal proof and PENDING #1 stay queued on the toolchain
(absent again this session — 6th data point, apt main pocket
unreachable).

**Source contract:** after `ExitBootServices`, the loader hands
`GetMemoryMap`'s outputs: the descriptor array, its byte length, the
descriptor stride (`DescriptorSize`), and the descriptor version
(`DescriptorVersion`). Kido parses descriptor v1 (the version UEFI
ships in practice): `{ Type u32, Pad u32, PhysicalStart u64,
VirtualStart u64, NumberOfPages u64, Attribute u64 }`, little-endian
by UEFI mandate on AArch64.

## Positions

- **P1 contract realist:** the seam must carry `desc_size` and
  `desc_version`. The stub's 3-arg prototype (`mmap, mmap_len, bi`)
  cannot name the stride or the version — a v2 descriptor would be
  silently mis-parsed, which is exactly the "never invent" violation
  the stub was avoiding. Extend to five args. The stub was declared
  "for the entry shim's future use" and the shim never calls it:
  zero downstream churn, so the seam is ours to fix.
- **P2 classifier:** the type table is the module's honesty core.
  Seeded: `EfiConventionalMemory` (7), `EfiBootServicesCode` (3),
  `EfiBootServicesData` (4) — reclaimable once boot services are
  gone. Excluded, each declared: loader code/data (1, 2;
  loader-owned; Kido's own image is protected downstream by
  kido-image's carve-out), ACPI reclaim (9; reclaimable only after
  ACPI parse — no ACPI parser exists, named future), persistent
  memory (14; no PM driver — claiming it as DRAM would be fiction),
  reserved/runtime/unusable/NVS/MMIO/port/PAL (0, 5, 6, 8, 10, 11,
  12, 13), unknown types (skipped, never loud). `VirtualStart`
  ignored — Kido never calls `SetVirtualAddressMap`. `Attribute`
  unread — declared.
- **P3 pipeline keeper:** same pipeline shape as the DTB path, so
  there is one discovery law, not two. Parse+classify ->
  sort-by-base (insertion sort; no documented bet on firmware
  ordering) -> coalesce adjacent contiguous usable -> trim the map
  buffer's own `[mmap, mmap+mmap_len)` extent with the EXISTING
  trimmer (no duplicated truth) -> bound-check against the one
  16-region table -> shared publish (largest wins, ties to lowest
  base). The seed list is usable-by-construction, like session 21.
- **P4 honesty auditor:** overlapping descriptors are contradictory
  firmware — fail loud (`KIDO_ERR_NO_MEMORY`), never merge guesses.
  Page-count and address overflow fail loud (the trimmer's `x+y<x`
  idiom). Zero-page entries are no-ops, not errors. The map buffer
  trim runs even though the loader "should" own the buffer: trim
  and survive beats fail-loud on a loader quirk, and the buffer
  holds our ground truth — trimming it cannot corrupt the parse.
- **P5 test keeper:** synthetic v1 descriptors, little-endian,
  built by a small emitter in the self-test — the session-3 "the
  bytes are the test" law. The buffer-trim test uses the REAL
  buffer address overlapped by a synthetic region: the trimmer runs
  on real addresses, not fixtures of convenience. The old §11 stub
  test is replaced, not kept alongside.

## Challenges

- **C1 — 3-arg seam vs 5-arg:** overruled the keep. The stub's
  prototype was never called by anyone; keeping it would force the
  version/stride into undocumented assumptions. Five args matches
  `GetMemoryMap` exactly; the version check is the first gate.
- **C2 — BootServices code/data as seed:** the EBS guarantee is a
  CALLER CONTRACT, stated in the header: the future entry-shim UEFI
  path may only call post-`ExitBootServices`. Before EBS those
  regions are live firmware; after, they are free RAM. The contract
  is the mechanism — same as the DTB path's "entry shim obtains
  the DTB from the firmware handoff" contract.
- **C3 — overlap: loud vs merge:** loud. Real firmware never
  overlaps; a self-contradictory map is untrustworthy ground truth.
  Merging would invent geometry the firmware didn't state.
  (Session-3 precedent: interior holes in the single-region
  primary fail loud rather than invent.)
- **C4 — map-buffer trim vs loader-owned declaration:** trim.
  The DTB precedent (session 21) is "usable by construction";
  the trimmer is pure and shared. A no-overlap map makes it
  vacuous — zero cost on honest loaders.
- **C5 — unknown types: skip vs loud:** skip, declared. Matches
  the DTB path's disabled-node handling: absence is a fact, not an
  error. A future usable type costs memory, not correctness.
- **C6 — publish extraction regression risk:** the shared
  `kido_mem_publish()` is a pure move of the DTB path's tail;
  the existing 53-check suite pins byte-identical behavior
  (primary selection, memreserve adjustment order, seed
  publication). One subtlety preserved exactly: the memreserve
  loop adjusts the PUBLISHED primary in `bi` but not the seed
  list — publish runs first, memreserve adjusts `bi` after,
  clearing `mem_valid` on its loud paths.
- **C7 — ACPI reclaim excluded forever?:** no — declared future.
  Reclaiming it needs an ACPI parser (to find the tables before
  freeing their pages). Named, not built; excluding it is honest
  today, revisiting it is a Gate item.
- **C8 — `desc_size > 40` with version 1:** parse the v1 prefix
  at each stride. Real loaders pad; the v1 fields are a prefix by
  the version's definition. `desc_size < 40` fails loud (cannot
  hold the fields); ragged maps (`mmap_len % desc_size != 0`)
  fail loud.

## Convergence

Draft `kido_mem_discover_uefi(mmap, mmap_len, desc_size,
desc_version, bi)` in `modules/kido-mem.c` (+ header docs in
`modules/kido-mem.h`): manual little-endian bounds-checked loads
(the `fdt_u32` idiom's LE twin — no struct casts, so a misaligned
loader buffer can never fault the parse); version/stride gates;
page/address overflow guards; pairwise overlap audit over a
bounded 64-entry walk (documented bet; more is pathological
firmware, loud); insertion sort + coalesce; shared trimmer for
the map-buffer extent; one 16-region bound (the same table, the
same law); shared `kido_mem_publish()`. Self-test §§21+: guards,
version/stride rejection, mixed-type classification, all-excluded
loud, zero-page no-op, overflow loud, coalescing, overlap loud,
64-entry bound, unknown-type skip, stride-48 acceptance, BS-large
primary, real-address buffer-trim split. Old §11 (stub test)
replaced.

## Preserved dissent

- **D1 — separate `kido-uefi` module:** overruled. The stub lived
  in kido-mem since session 3; the seed table, the trimmer, and
  the publish law are one truth. A split module would duplicate
  them or reach across — both worse.
- **D2 — fail loud on map-buffer overlap instead of trimming:**
  overruled. The DTB-extent precedent is trim-and-survive; a
  loader quirk should not refuse a bootable machine, and the
  trim provably cannot corrupt the already-parsed map.
- **D3 — trust firmware ordering, skip the sort:** overruled.
  No documented bet on firmware ordering exists; insertion sort
  is ten lines and makes coalescing order-independent.

## Proof posture

Hosted battery on this VM (gcc 13.3.0, `-Wall -Wextra -Werror`,
zero warnings): full kido-mem suite incl. the new UEFI sections.
Cross-compile + QEMU: queued on the toolchain (absent — 6th data
point). The new code's only arch-sensitive surface is the
`(uintptr_t)mmap` extent computation, which mirrors the DTB
path's existing line. No `.S`, no boot-path, no Gate-file changes.
