# Deliberation: kido-mem DTB-extent trim (2026-10-21, builder crew)

## Goal

Close the named future from session-10 deliberation C4 ("DTB trim
honestly out of scope -> kido-mem's future") and session-16 D3
("the reserved tree is safe by design for the image, by measured
layout for the DTB"). One solid piece: the firmware DTB blob lives
in RAM at [dtb, dtb+totalsize) — inside the /memory regions QEMU
virt describes — so the raw seed list published by
kido_mem_discover hands the DTB's own pages to the allocator.
Today a task stack can never actually land there only because
first-fit grows low->high from the region base while the DTB sits
at the top: safe by measured layout, the exact posture kido-image
closed for the kernel image in session 10. This session makes the
seed list usable-by-construction: discover trims the DTB extent
out of every region before primary selection and publication.

## The gap, stated plainly

kido_mem_discover(dtb, dtb_len, bi) parses the DTB, then publishes
the RAW firmware regions via kido_mem_regions(). kido_sched_init
feeds that list straight into kido_alloc_init. The DTB blob is
firmware-owned RAM for the whole boot; nothing in the tree reserves
it. On QEMU virt the DTB loads at the top of the 128 MiB region —
the allocator's free list covers it today. The image reservation
(kido-image, session 10) proved the pattern for closing this class
of gap: carve what the kernel owns out of the allocator's input,
by design, not by layout luck.

## Positions

- **P1 (discovery purist):** the trim belongs INSIDE
  kido_mem_discover, before publication. discover is the single
  producer of the seed list; a separate kido_mem_trim_dtb() API
  would create a second producer and a call-order trap —
  kido_sched_init reads regions(), and nothing could guarantee the
  trim ran first. One query, no duplicated truth: the seed list
  that leaves discover is the usable list.
- **P2 (honesty auditor):** the trim extent must be exactly what
  discover vouches for: [dtb, dtb+totalsize), with totalsize
  re-validated from the blob (the walk already enforces
  totalsize <= dtb_len and block-bounds sanity). Never the
  dtb_len slack — bytes past totalsize are caller slack, not DTB.
  Overlap-absence is a FACT (trim no-ops), never an error: a
  firmware that keeps its DTB outside the described regions is
  fine. This is deliberately different from /memreserve/ interior
  (a firmware CLAIM of a hole inside the primary -> still loud).
- **P3 (portability auditor):** the trimmer is pure portable C on
  (regions, extent_base, extent_size) — identical bytes on host
  and bare metal. The ONLY host/arch-dependent input is the
  extent source: the real firmware pointer on bare metal, the
  hosted test injector on the dev host. (uint64_t)(uintptr_t)dtb
  cannot truncate on any 32- or 64-bit target. Overflow guards use
  the established `x + y < x` idiom on every addition.
- **P4 (allocator client):** kido_sched_init needs ZERO changes —
  it reads the seed list, and the list is now DTB-free by
  construction. The image reservation still carves on top
  (unchanged). Layering holds: mem discovers, alloc owns, sched
  consumes. The HAL's caps->mem_base/mem_size become "first usable
  byte / usable bytes" — which is what those fields already claim
  to be ("first usable RAM byte, from firmware"). More true, not
  less; no allocator reads caps directly.
- **P5 (bound keeper):** KIDO_MEM_MAX_REGIONS 8 -> 16, still
  static, still never allocates. One blob can straddle at most
  the regions it touches; 16 covers 8 straddled regions with
  headroom to spare. A trim that would exceed 16 fails LOUD
  (pathological firmware, not a silent squeeze). Static arrays
  double to 256 bytes — trivial.
- **P6 (test keeper):** hosted injector
  kido_mem_test_set_dtb_extent(base, size), default (0,0) =
  vacuous no-op — the kido-image precedent (session 10, P4),
  deliberated and accepted there. The injector substitutes ONLY
  the extent source; the parser and the trimmer run the real
  code. New self-test sections pin every geometry: interior
  split, head trim, tail trim, full cover -> NO_MEMORY, no-overlap
  no-op, straddle across two regions, zero-size no-op, primary
  falling to the second region, injector reset -> raw behavior.

## Challenges

- **C1:** session-3 deliberation D2 overruled interior splitting
  ("fine carving is the allocator's job") — why is splitting OK
  here? **Answered:** D2 was about /memreserve/ interior holes
  versus the SINGLE-region bootinfo primary: one region, one
  hole, unrepresentable -> loud. The DTB trim operates on the
  MULTI-region seed list, where a split is representable (<=2
  survivors per region), and the extent is discover's OWN input,
  not a firmware claim about someone else's memory. Different
  object, different verdict. The /memreserve/ interior rule is
  UNCHANGED — it still fires on the trimmed primary.
- **C2:** order of operations vs /memreserve/? **Answered:** raw
  walk -> DTB trim -> primary selection (largest TRIMMED region)
  -> /memreserve/ leading/interior honoring on the trimmed
  primary (existing logic, untouched). The two removals are
  idempotent on overlap: trimming bytes a reservation already
  removed changes nothing, and vice versa. A reservation strictly
  interior to the TRIMMED primary is still unrepresentable ->
  still loud.
- **C3:** totalsize vs dtb_len for the extent end? **Answered
  (P2):** totalsize. The entry shim already passes
  dtb_len == totalsize (sanity-capped), and discover enforces
  totalsize <= dtb_len — so on the real path they agree, and
  totalsize is the bound discover itself validated. Trimming to
  dtb_len would claim pages discover never vouched for.
- **C4:** does any consumer expect RAW regions? **Answered:**
  the only consumer is kido_sched_init -> kido_alloc_init (seed).
  The header documented "raw firmware regions (untrimmed)"; the
  doc changes with the code — the seed list is now the usable
  list. No other module reads g_regions. interop/resonate/alloc
  are untouched.
- **C5:** can the QEMU run PROVE the trim, or only not-break?
  **Answered:** the bare-metal console cannot print the trimmed
  geometry (pristine-source discipline; session-16 D1 stands).
  The honest chain, stated not hand-waved: (a) the hosted
  injector test pins the trim geometry on the SAME kido-mem.c
  that cross-compiles into the image; (b) the QEMU regression
  executes the real parse+trim on the real virt DTB — the extent
  comes from the real firmware pointer, the tail-trim path runs,
  and any fault would appear in `-d int`; (c) the virt DTB load
  address is measured from the run's DTB (top of RAM, inside the
  pre-trim region), not assumed. Claimed: the path executes
  fault-free on real firmware input. NOT claimed: a printed
  numeric proof of the shave — that stays with the hosted test.
- **C6:** does the 8->16 bump break the session-3 bounded-table
  contract or any existing test? **Answered:** the contract is
  "bounded, never allocates" — 16 is still bounded. All 11
  existing self-test sections re-run with the injector at its
  vacuous default: the trim no-ops, region_count stays 2 in
  section 1, every expectation holds.

## Convergence

P1–P6 with C1–C6 answered. Deliverables: this record;
kido-mem.h (seed-list semantics rewritten, DTB-trim law,
hosted injector prototype, KIDO_MEM_MAX_REGIONS 16);
kido-mem.c (pure trimmer + trim inside discover before
selection/publication + injector + new self-test sections);
full hosted regression; ARM64 cross-compile of all TUs; QEMU
delta-0 regression with the trim live; ledger entry;
module-map note (kido-mem row: DTB trim landed; session-16 D3
closed).

## Preserved dissent

- **D1 (bound philosophy, P5 vs the minimalist):** keep 8 and
  fail loud on split-overflow instead of bumping to 16.
  Overruled: 16 is still static and bounded, and failing the
  boot on a 9th split would turn a benign firmware layout into
  a boot failure. The dissent's point stands as law: every
  bound is a bet — 16 is this session's bet, documented here.
- **D2 (injector honesty, standing note):** the hosted tests
  prove the trim LOGIC on the real parser, not that the bare-
  metal pointer arithmetic is right. The QEMU regression covers
  the pointer path by execution (real firmware pointer in,
  no fault out), not by numeric assertion. If a future
  kido-debug console verb ever prints the allocator's address
  map (session-16 D1), the trim's numeric effect on bare metal
  becomes directly assertable — until then the chain in C5 is
  the whole claim.
