bee/bible-local/decisions/2026-04-01-memtest-build-strategy.md

Decision: Treat memtest as explicit ISO content, not as trusted live-build magic

Date: 2026-04-01 Status: active

Context

We have already iterated on memtest multiple times and kept cycling between the same ideas. The commit history shows several distinct attempts:

• f91bce8 — fixed Bookworm memtest file names to memtest86+x64.bin / memtest86+x64.efi
• 5857805 — added a binary hook to copy memtest files from the build tree into the ISO root
• f96b149 — added fallback extraction from the cached .deb when chroot/boot/ stayed empty
• d43a9ae — removed the custom hook and switched back to live-build built-in memtest integration
• 60cb8f8 — restored explicit memtest menu entries and added ISO validation
• 3dbc218 / 3869788 — added archived build logs and better memtest diagnostics

Current evidence from the archived easy-bee-nvidia-v3.14-amd64 logs dated 2026-04-01:

• lb binary_memtest does run and installs memtest86+
• but the final ISO still does not contain boot/memtest86+x64.bin
• the final ISO also does not contain memtest menu entries in boot/grub/grub.cfg or isolinux/live.cfg

So the assumption "live-build built-in memtest integration is enough on this stack" is currently false for this project until proven otherwise by a real built ISO.

Decision

For bee, memtest must be treated as an explicit ISO artifact with explicit post-build validation.

Project rules from now on:

• Do not trust --memtest memtest86+ by itself.
• A memtest implementation is considered valid only if the produced ISO actually contains:
  • boot/memtest86+x64.bin
  • boot/memtest86+x64.efi
  • a GRUB menu entry
  • an isolinux menu entry
• If live-build built-in integration does not produce those artifacts, use an explicit project-owned mechanism such as:
  • a binary hook copying files into binary/boot/
  • extraction from the cached memtest86+ .deb
  • another deterministic build-time copy step
• Do not remove such explicit logic later unless a fresh real ISO build proves that built-in integration alone produces all required files and menu entries.

Current implementation direction:

• keep the live-build memtest stage enabled if it helps package acquisition
• but enforce memtest explicitly in a project-owned binary hook
• patch the generated binary/boot/grub/grub.cfg and binary/isolinux/live.cfg directly in the binary stage if memtest entries are missing

Consequences

• Future memtest changes must begin by reading this ADR and the commits listed above.
• We should stop re-introducing "prefer built-in live-build memtest" as a default assumption without new evidence.
• Memtest validation in build.sh is not optional; it is the acceptance gate that prevents another silent regression.
• If we change memtest strategy again, we must update this ADR with the exact build evidence that justified the change.