Phase 207 — kernel + initramfs contract

At a glance

Phase 207 is another contract phase.

It does not copy a kernel into the image. It does not build an initramfs. It does not mount the image. It does not boot QEMU.

Phase 207 does not copy kernel files because the kernel is too important to smuggle in accidentally. If we copied a random host kernel now, the image might move forward, but ONIX would not have learned how it owns its own boot payload.

What the kernel is

The Linux kernel is the first real Linux program that runs after the bootloader.

Very simplified:

firmware
  -> bootloader
  -> kernel
  -> first userspace program

The kernel is responsible for things like:

CPU scheduling
memory management
device drivers
filesystems
processes
mounting the root filesystem

For ONIX, the future kernel path selected by Phase 206 is:

/boot/ONIX/vmlinuz

vmlinuz is the normal name for a compressed Linux kernel image.

What the initramfs is

initramfs means “initial RAM filesystem”.

It is a tiny temporary filesystem loaded into memory before the real root filesystem is mounted.

Boot flow with initramfs:

firmware
  -> systemd-boot
  -> kernel
  -> initramfs in RAM
  -> find real root filesystem
  -> mount real root filesystem at /
  -> run /usr/lib/systemd/systemd

The initramfs exists because the kernel often needs help before it can mount the real root filesystem. For example, it may need userspace tools or modules to find:

LABEL=onix-root

and mount it as:

/

For ONIX, the future initramfs path selected by Phase 206 is:

/boot/ONIX/initramfs.img

Why root=LABEL=onix-root needs initramfs help

The Phase 206 BLS entry contains:

root=LABEL=onix-root rootfstype=xfs rw init=/usr/lib/systemd/systemd

That means:

find the filesystem labeled onix-root
mount it as /
use xfs as the root filesystem type
start /usr/lib/systemd/systemd

Device names like /dev/vda3 can change. Labels are stable, so the contract keeps:

root=LABEL=onix-root

But resolving a label usually needs early userspace support. That is exactly the initramfs job.

Minimum early-boot capabilities

For the first QEMU ONIX image, the initramfs must be able to handle:

virtio_pci   QEMU virtio PCI transport
virtio_blk   QEMU virtio block disk
xfs          root filesystem type
vfat         ESP/boot filesystem type, useful for inspection and later tooling
devtmpfs     early /dev population
proc         /proc mount
sysfs        /sys mount

The must-have path is:

virtio disk -> find LABEL=onix-root -> mount xfs root -> exec systemd

If any of those pieces are missing, the bootloader can load the kernel but the kernel may panic because it cannot find or mount /.

ONIX ownership decision

The Phase 207 decision is:

do not use the host kernel as the final ONIX kernel

The host kernel belongs to the developer machine. The Alpine forge kernel belongs to the throwaway forge. A Nixpkgs kernel belongs to the toolbox/source environment.

ONIX needs its own explicit boot payload contract.

The planned package split is:

onix-kernel      owns the kernel image and kernel modules
onix-initramfs   owns or generates the initramfs image

That split may evolve, but the ownership boundary matters:

package content        -> /usr/lib/kernel and /usr/lib/modules
image boot material    -> /boot/ONIX/vmlinuz and /boot/ONIX/initramfs.img
bootloader config      -> /boot/loader/entries/*.conf

In other words, packages should provide reproducible boot inputs, and image assembly should place the selected boot artifacts where systemd-boot expects them.

Future file contract

The current Phase 206 BLS entry expects:

/boot/ONIX/vmlinuz
/boot/ONIX/initramfs.img

The future root filesystem must contain:

/usr/lib/systemd/systemd

The future package payload should make kernel/module content available from stable package-owned paths, such as:

/usr/lib/kernel/vmlinuz
/usr/lib/modules/<kernel-version>/

Then image assembly can copy or link the selected boot artifacts into:

/boot/ONIX/

What Phase 207 verifies

make phase 207 verifies:

• this Phase 207 section exists
• the contracted kernel path is /boot/ONIX/vmlinuz
• the contracted initramfs path is /boot/ONIX/initramfs.img
• the contracted init path is /usr/lib/systemd/systemd
• the boot arguments still use root=LABEL=onix-root
• the boot arguments still use rootfstype=xfs
• the plan mentions the minimum early-boot pieces:
  • virtio_pci
  • virtio_blk
  • xfs
  • vfat
• the plan names onix-kernel
• the plan names onix-initramfs
• the Phase 206 image script still writes the same BLS paths

This makes Phase 207 a checkpoint between “we have a bootloader entry” and “we are ready to build or import a real kernel/initramfs payload”.

What Phase 207 does not prove

Phase 207 does not prove:

kernel compiles
initramfs boots
systemd runs
QEMU reaches userspace

Those are later phases. Phase 207 only prevents us from taking a shortcut that would hide ownership problems.