Plutonium-239

1. Overview

Pu-239 is a Linux distribution based on the unmodified Arch Linux package set. It changes the deployment model, not the package selection. The official Arch repositories supply everything except the performance kernel and the updater, which are compiled from source, signed, and served from a self-hosted repository.

Three properties define the system.

• Atomic deployments. The root filesystem is read-only and managed by ostree as a series of deployments. Each update commits a new tree and switches to it atomically. A boot that fails is rolled back automatically.
• Optimized kernel. The kernel is linux-cachyos, compiled from CachyOS source with a 1000 Hz tick rate and the EEVDF scheduler, delivered in all five x86-64 variants instead of only four.
• Declarative packages. Package state is a single list file. The system converges to it on every update, and it covers the official repositories and the AUR.

A hardware detection step runs at install time and on every update to select the CPU microcode, the kernel variant, and the GPU stack.

2. Rationale

Arch Linux has no rollback mechanism and no kernel build service. Recovery from a failed update is manual. Pu-239 adds both on top of the unmodified package set. The deployment model is ostree plus systemd-boot boot counting, which is the same mechanism Fedora Atomic and SteamOS use, built here from the official Arch packages rather than from a vendor image.

3. Partition layout

Without LUKS, the default

With LUKS, user opt-in

The ESP is unencrypted because systemd-boot reads it directly.

Internal btrfs layout

Deployments are plain directories managed by ostree. There are no btrfs subvolumes. /boot is a plain btrfs directory because ostree rejects a vfat /boot.

• ostree/repo/ : object store
• ostree/deploy/pu-239/ : stateroot
• deploy/<sha>.0/ and deploy/<sha>.1/ : two read-only deployments
• var/ : shared persistent /var
• home/ : user homes
• cache/pacman/ : pacman database and cache

4. Atomic model

Deployments

The operating system is a series of ostree deployments. Each update builds a new root tree and commits it. The previous tree is never modified, so it is always a valid rollback target. Unchanged files are hardlinked between deployments, so a new deployment uses little additional disk space.

Updates are incremental. ostree checkout produces a hardlinked copy of the current tree, pacman updates that copy, mkinitcpio runs inside it, and the result is committed and deployed. A full build from scratch happens only at install time.

The build engine copies its complete directory into /usr/lib/pu-239 of every deployment, so newly added units and scripts are present on all future updates.

Committed tree rules

The committed tree must satisfy the following.

• It contains /usr/etc, not /etc, because ostree manages /etc and the runtime /etc is provided by a state overlay.
• It contains an empty /sysroot directory with mode 0755. ostree-prepare-root bind-mounts the physical root onto it in the initramfs.
• It contains the symlink /ostree pointing to sysroot/ostree so the plain ostree command line works on the running system.
• It ships nothing under /boot. ostree-prepare-root bind-mounts the sysroot /boot onto the deployment /boot at runtime.

Runtime mount layout

The root superblock is mounted read-write. The read-only seal is applied later in the boot sequence so the update path retains write access. /root and /opt are symlinks into /var.

/etc persistence

/etc is provided by ostree-state-overlay@etc.service. The lower layer is the /etc of the deployment and the upper and work directories live at /var/ostree/state-overlays/etc/. When the booted deployment changes, the upper layer is pruned at boot.

• Files the operating system ships in /etc reset to the new deployment's values on update.
• Files the user creates in /etc persist.

A systemd drop-in pre-creates the upper directory with mode 0755. The upstream unit creates it with mode 0700, which makes the merged /etc unreadable to non-root processes.

5. Boot and fallback

The boot path is ostree plus systemd-boot plus systemd-bless-boot. There are no custom boot scripts.

• The repository configuration sets boot-counting-tries to 3.
• ostree admin deploy writes a Boot Loader Spec entry named ostree-<n>+3.conf.
• Each failed boot makes systemd-boot decrement the counter, so +3 becomes +2 then +1 then +0.
• A successful boot makes systemd-bless-boot strip the counter and leave ostree-<n>.conf as the stable entry.
• An entry that reaches +0 is marked bad and skipped.
• systemd-boot sorts bad entries first and good or indeterminate entries last, and the last menu item is the default, so the newest stable deployment always boots with no loader.conf.

A deployment that fails to boot exhausts its attempts and the firmware falls back to the previous stable deployment with no user action. A systemd-bless-boot drop-in pins the ESP path so the counter is stripped from the correct loader.

Kernel placement and ESP mirror

The kernel and initramfs live at /boot/ostree/pu-239-<bootcsum>/. ostree writes kernels and Boot Loader Spec entries only to the sysroot /boot and never to the ESP. esp-sync.sh mirrors the kernels and syncs the Boot Loader Spec entries additively, preserving the live boot-counting renames when the kernel and options are unchanged. It runs at install, at update, and as a service on every boot, where it is a no-op in steady state.

Kernel command line

Without LUKS: root=PARTUUID=<uuid> rw ostree=/ostree/deploy/pu-239/deploy/<hash>.0

With LUKS: root=/dev/mapper/cryptroot rw rd.luks.name=<luks-uuid>=cryptroot ostree=/ostree/deploy/pu-239/deploy/<hash>.0

initramfs

HOOKS=(base systemd ostree microcode kms modconf block keyboard sd-vconsole sd-encrypt filesystems)

There is no autodetect hook because the initramfs must be hardware-agnostic across deployments and machines.

6. Kernel

Pu-239 ships linux-cachyos, the performance kernel of the CachyOS project, featuring a 1000 Hz tick rate, EEVDF scheduler, and optimizations tailored to modern CPUs. I compile it myself from their GPL licensed build scripts and host it on my own infrastructure, in accordance with CachyOS repository policy. However unlike them, I ship it for every single x86_64 microarchitecture, from x86_64-v2 for old dual Xeon workstations to x86_64-znver4 for modern AM5 CPUs.

Five variants

NVIDIA

NVIDIA support is pre-built linux-cachyos-nvidia-open for Turing and newer, with no DKMS. Maxwell, Pascal, Volta, and older are detected by PCI identifier and fall back to the open-source nouveau driver. The legacy drivers like 580.XX can still be chosen to install through the AUR if the user wishes to.

7. Hardware detection

Detection reads /proc/cpuinfo and /sys/bus/pci/devices directly. It runs at install time and on every update.

CPU microcode. GenuineIntel installs intel-ucode, AuthenticAMD installs amd-ucode.

Kernel variant, checked in order.

• AMD CPU family 25 or 26 maps to x86_64-znver4
• avx512f maps to x86_64-v4
• avx2 maps to x86_64-v3
• SSE4.2, SSE4.1, SSSE3, and POPCNT present map to x86_64-v2
• otherwise x86_64

GPU stack, additive.

• Intel 8086 installs vulkan-intel and intel-media-driver
• AMD 1002 installs vulkan-radeon
• NVIDIA Turing and newer installs nvidia-utils, nvidia-settings, and linux-cachyos-nvidia-open
• mesa and egl-wayland are unconditional
• hybrid machines get one stack per GPU

8. Update stack

The update stack is a single application, pu-239-update. It presents one update button and behaves like the standard arch-update tool. In the background it applies your package list, builds a new deployment, and stages a reboot into the new tree. If the new deployment fails to boot, the bootloader returns to the previous one automatically.

Using the graphical updater

Open Pu-239 Update from the application launcher. The window has two views.

• The package list editor shows every installed package and lets you add or remove entries. The search bar queries the official repositories and the AUR. The Installed only checkbox filters the list you already have.
• When you choose Save & Update, the update runs in an embedded terminal and a reboot button appears when the new deployment is staged.

Changes to the package list take effect on the next update. Save the list, run the update, and reboot.

Using the command line

Run arch-update in a terminal. It checks the official repositories and the AUR, applies the package list, builds the new deployment, and asks whether to reboot now, defaulting to yes. Answer yes to boot into the new tree.

The package list

The file /var/lib/pu-239/packages.list is the complete desired state of the system. Packages listed here are installed on the next update. Packages removed here are uninstalled on the next update. There is no protected core set, so you may remove anything the system shipped with. The list is filled automatically on first boot with everything currently installed, so it starts as an accurate picture of the machine.

You may edit this file with any text editor, or use the built-in editor in the graphical pu-239-update.

AUR packages

Prefix a package name with aur/ in the list to install it from the AUR. The updater builds it from source during the update and installs the result. A build failure is reported but does not stop the rest of the update.

Direct pacman is disabled

The root filesystem is read-only, so pacman -S, -R, -U, and -D cannot work and are blocked with a message pointing you to the package list. Read-only pacman queries such as -Ss and -Qi still work. Install and remove software through the package list instead.

Atomic apply flow

atomic-update.sh checks ostree, the engine, and the repository, asserts boot counting, runs the engine, runs ostree admin deploy with a kernel-argument fallback from /proc/cmdline, verifies status and Boot Loader Spec sanity, records bookkeeping, and touches /run/pu-239/update-staged before prompting for a reboot.

The graphical updater runs in the calling user's session because pkexec strips WAYLAND_DISPLAY and XDG_RUNTIME_DIR and terminates GTK4 before it paints. Privilege escalation is per action only.

9. Declarative package management

The desired state lives at /var/lib/pu-239/packages.list. It is seeded on first boot by seed-userlist.sh, which writes every explicitly installed package into the list and prefixes foreign packages with aur/.

The user list is the absolute system state at update time. Packages present are installed, packages absent are removed, and there is no protected core set. The manifest and the hardware detection seed the fresh install only.

Direct pacman use is blocked. /usr/bin/pacman is a wrapper around pacman-real that refuses -S, -R, -U, and -D with an explanation of the declarative path, and allows read-only operations. The engine bypasses the wrapper through PU239_ENGINE=1.

AUR packages use the aur/ prefix. aur-build.sh builds them from source in a systemd-nspawn container from a git clone of aur.archlinux.org and injects the resulting package into the staging tree. Failures are reported but do not abort the update.

10. Installer

Calamares is the only interface. The ISO boots directly into the installer on tty1 and the user never sees a live terminal.

Sequence.

• show: welcome, locale, keyboard, network-setup, partition, users, summary
• exec: partition, mount, atomic-deploy, fstab, keyboard, locale, localecfg, users, displaymanager, networkcfg, hwclock, atomic-finish, services-systemd, umount
• show: finished

Properties.

• Online only, downloading from live Arch mirrors on the target machine.
• btrfs only, GPT required, ESP at /boot/efi 1 GiB, LUKS2 opt-in with automated partitioning.
• Locale and keyboard come before Wi-Fi so the network password is typed with the user's own key layout.
• The welcome page runs no system checks. A diskless machine is stopped on the partition page.

11. Constraints

• The root is read-only, so direct pacman installs do not persist and are blocked.
• systemd-boot is the only supported bootloader. GRUB and Limine are not supported because boot counting requires systemd-boot.
• One desktop, KDE Plasma, with no choice at install time.
• Online-only installer, UEFI only, no offline updates.
• NVIDIA legacy GPUs use nouveau unless the user adds a DKMS driver from the AUR.
• Files the operating system ships in /etc reset to the new deployment's values on update. User-created /etc files persist.