feat(uffd): MAP_PRIVATE base-file backing + MISSING|MINOR registration (substrate v2b)

[nikhilunni]

Summary

The engrams ADR 0045 unified-memory-substrate (v2b) fork surface — D1 of the substrate program. Clean-room (kernel primitives + the engrams spec; never any AGPL fork).

A new optional top-level load param uffd_base_file: when set with the Uffd memory backend, guest memory is created as MAP_PRIVATE of this shmem file (reusing the existing snapshot_file region builder with shared=false) instead of anonymous, and UFFD registration becomes MISSING|MINOR (userfaultfd crate feature linux5_13). The external handler then resolves:

• base-identical pages → UFFDIO_CONTINUE: one page-cache copy shared by every same-template microVM on the host (the density mechanism, now available to restores)
• session-divergent pages → UFFDIO_COPY: private
• guest writes → kernel-native COW; the base file is never written through the mapping

Invariants held

• Inert/opt-in: field unset ⇒ every path byte-identical to stock (the registration mode ternary is the only touched line on the default path).
• Never touches src/vmm/src/snapshot/; SNAPSHOT_VERSION stays 10.0.0 (R2 byte-compat preserved).
• Invalid with the File backend (loud error); rejected for hugetlbfs (MINOR is shmem-only here). Kernel floor ≥5.13.

Validation

• Unit test (test_create_guest_memory_with_base_file): read-through from the base, COW privacy (write never reaches the file), mapping offsets, hugetlbfs rejection — green on engram-dev (kernel 6.8).
• Pre-existing TAP-EPERM test failures confirmed identical on the base commit (environmental, unprivileged TAP creation).
• Static musl release build green.
• Kernel-level behaviors (cross-process CONTINUE on MAP_PRIVATE shm, COPY privacy, KVM-under-memslot, dirty-log) are gated by the engrams-side substrate_kernel_capabilities suite (engrams #163).

Consumed by the engrams D2 PR (client field + handler CONTINUE arm + base-shm provisioning); the submodule bump there runs the build-firecracker job + R2 diff-guard end-to-end.

🤖 Generated with Claude Code