# Deliberation — kido-mem design (2026-10-14, third scaffold session)

Circle: builder crew (Mechane pattern). Question: what does memory
discovery honestly implement — how far does the DTB parser go, what
fails loud, and where does the entry shim call in?

Context: the HAL builder deferred DTB parsing to kido-mem explicitly
(D1 dissent in the HAL deliberation, overruled toward this module).
The contract is fixed: kido_bootinfo_t (mem_base, mem_size, mem_valid,
board_id) in kido-hal-arm64.h, consumed by kido_hal_arm64_probe().
A sibling builder is drafting the entry shim in parallel against the
same contract. kido.json describes Kido as portable and adaptive from
birth — memory discovery must not invent platform facts.

## Positions
- **P1 (parse-is-portable):** Write the full DTB parser as portable C,
  not a stub. The device-tree format is big-endian by specification;
  manual byte loads mean zero arch assumptions. Unlike the ARM64 asm
  paths, this module is genuinely testable on the dev host — so test
  it for real with synthetic DTB bytes, not fixtures.
- **P2 (never-invent):** Every failure mode — corrupt magic, truncated
  blob, no memory nodes, all regions disabled or reserved, arithmetic
  overflow — returns KIDO_ERR_NO_MEMORY with mem_valid left 0. The HAL
  probe then fails loud downstream. No DTB, no regions, no guessing.
- **P3 (largest-wins):** When firmware reports multiple regions, the
  bootinfo primary is the largest (ties: lowest base). /memreserve/
  entries are honored: a leading reservation trims the base upward; a
  strictly interior reservation fails LOUD, because a single-region
  bootinfo cannot represent a hole and silently handing one to the
  allocator would be worse than failing. Fine carving is the future
  allocator's job, not discovery's.

## Challenges
- **C1 against P1:** A hand-rolled DTB parser risks subtle spec
  drift (e.g. #address-cells inheritance, reg tuple widths). Counter
  accepted with bounds: the walk caps depth at 16, regions at 8,
  reservations at 8, cells at 4; every read is bounds-checked against
  the DTB's own totalsize; 21 self-test checks cover the walk, the
  edge cases, and the failure modes. A draft earns trust through its
  test suite, and this one has it.
- **C2 against P3:** Failing loud on an interior reservation could
  refuse to boot on firmware that reserves a small hole (e.g. a
  framebuffer carve-out) inside the main region. Counter accepted:
  the failure is loud and diagnosable (NO_MEMORY at discover time,
  not corruption at runtime), and the allocator module — which owns
  carving — can relax this rule with a real carve implementation.
  Discovery's job is a faithful map, not a convenient one.
- **C3 against the interface:** The entry shim is being drafted in
  parallel — what if its DTB handoff differs (physical vs virtual
  address, length unknown)? Counter: the interface takes (pointer,
  length) precisely so the shim passes what firmware gave it; the
  parser validates totalsize against the passed length and never
  reads past it. The contract is defensive on both sides.

## Convergence
P1+P2+P3 all hold. Real: header validation, /memreserve/ parsing,
structure walk, memory-node identification (name prefix OR
device_type, status=disabled skipped, reserved-memory excluded),
reg parsing with parent cells, region collection, largest-primary
selection, leading-trim rule. Loud: UEFI path (STUB_REACHED),
interior reservation (NO_MEMORY). Exposed: region seed list for the
future allocator. board_id stays the shim's call — mem fills the map,
not the board.

## Preserved dissent
- **D1:** A minority held that discovery should return the full
  carved region list as the bootinfo (multi-region bootinfo struct)
  rather than a single primary, arguing the single-region shape
  discards firmware truth. Overruled: the contract was fixed by the
  HAL builder and approved at the Gate; the raw list IS preserved
  via kido_mem_regions() for the allocator, so no truth is lost —
  only the HAL-facing primary is single.
- **D2:** A minority wanted the interior-reservation case to trim
  around the hole by splitting into two bootinfo regions. Overruled
  for this draft: splitting belongs to the allocator module with a
  real carve data structure; discovery failing loud is the honest
  placeholder, and the ledger records the relaxation as allocator
  work.
