Editions and upgrades

Peios has no channels and no release cadence. It is a rolling release with a full archive: every version of every package ever published stays installable. What it has instead of a channel is an edition — a package that says what a Peios is.

The edition package #

peios-experimental is the edition today. It is an ordinary peipkg package with an unusual job:

• Its version is the OS version. peios-experimental 2026.8-1 is Peios 2026.8. The package writes /usr/lib/os-release (VERSION_ID="2026.8", VARIANT_ID=experimental, PRETTY_NAME="Peios 2026.8 Experimental") and the /usr/etc/os-release compatibility symlink, so a system's identity and its release are one fact, tracked in the package database.
• Its dependencies are the base system. Kernel, modules and firmware; the initramfs — prelude, its hooks, the module subset and its own base tree, each placed IN initramfs explicitly; the service manager, registry, identity and networking daemons; the installer. Installing the package into an empty root yields a bootable Peios.
• It provides peios-release. Depend on that virtual name to mean "some Peios"; depend on the edition to mean that edition.
• It ships release.toml: what the release asks of a system beyond its packages, as data.
• It declares an alternate upgrade path. peipkg refuses to install or upgrade it by name, holds it back from an upgrade of everything, and prints the message it carries: To upgrade Peios use the upgrade-peios command. The reasons are below.

"Experimental" is a name, not a channel. It marks that Peios is not yet production-ready and says nothing about cadence. When enough exists for the split to make sense it is replaced by peios-pro, peios-minimal, peios-desktop and so on — each its own package, each providing peios-release, each shipping its own os-release.

What the edition deliberately does not contain #

Three things a live medium needs are absent from the edition, because they are properties of the medium:

• live-boot and disk-boot. Which boot packages a system carries depends on what it boots from. The installer swaps one for the other on the target; an edition that named either would be installable on only one kind of medium.
• peios-dwe. The Developer Workstation Environment makes a machine ownable. It is added by peiso for a development medium and could never be a thing that arrives by installing a package.
• Anything the installer is not. peios-install is in the edition: an installed system can install another.

Pinning #

Experimental's dependencies are >= floors — a floor lets a package move without republishing the edition on every change, which is right for a pre-alpha. A production edition pins exact versions, and then something useful follows: peipkg upgrade cannot move a pinned dependency past what the edition allows, so a real release upgrades as a unit, through upgrade-peios, never piecemeal.

Why the package manager will not move it #

Installing a package on Peios cannot change system policy. A package delivers files; which services run and which policies apply is decided by registry seeds that a package can only offer. That is the deliberate weakness that lets packages be installed freely.

Moving from one release to the next is more than a package upgrade: the new release's seeds have to be reconciled, and that is precisely the thing peipkg must not do. So the edition declares, in its manifest, alternate_upgrade = { message = "To upgrade Peios use the upgrade-peios command." } (PSPU §5.18). The declaration grants nothing — a package cannot name a command for the consumer to run, let alone run one. Its whole effect is that peipkg stops and shows the message, with a warning that whatever the message names sits outside the package manager's protections. The person runs upgrade-peios, which drives peipkg with --bypass-alternate-upgrade and then does the reconciling itself.

Where an edition lives #

The recipe is pkgs/peios-experimental/ in the Peios tree: a pekit.toml whose build writes os-release and release.toml, and a package.pekit.toml with the dependency table. Changing what Peios contains is a change there, followed by a republish. peiso and its spec do not change.

An edition package ships /usr/share/peios/release.toml. It states what the release asks of a system beyond its packages. peipkg never reads it; two tools do:

• peiso, when composing an image, to stage the seeds into the medium.
• upgrade-peios, after moving an installed system to a new release, to stage and apply the new release's seeds.

Both act as the operator, deliberately; the package manager acts as neither.

Contents #

# Peios 2026.8 Experimental. Read by peiso and upgrade-peios.
[registry]
autoapply = [
  "port-reservations",
  "eudev-service",
  "authd-service",
  "authd-policy",
  "lpsd-service",
  "lpsd-authd-registration",
  "lpsd-first-account",
  "login-console",
  "eventd-config",
  "eventd-service",
  "netd-service",
  "netd-default-profile",
  "resolvd-service",
  "resolvd-port",
  "atriumd-service",
]

[registry] autoapply #

Seed names, in the order they should apply. Each names a master a package in the edition's closure ships at /usr/share/regim/<name>.reg; listing it here is what opts it in. A reader treats a name nothing ships as an error.

Nothing else is defined yet. Unknown keys are rejected by both readers, so the file can grow without silently meaning nothing to an older tool.

What is not here #

• dwed-service. The DWE seed is peiso's to add, for a development medium only; a release never applies it.
• Anything a medium adds. live-boot and the medium repository are the image's, not the release's.
• Seeds that were removed between releases. A seed present in 2026.8 and absent in 2026.9 is not un-applied by anything today; the registry keeps its history and that is where the record lives. This is the same limitation an edition has with packages it stops depending on, and it is deferred to the same future mechanism.

Why a file, and not a package field #

peipkg's manifest is the wrong place for this, on purpose. A field the package manager acted on — "apply these seeds when I am installed" — would let any package change system policy by being installed, which is the one thing Peios packages must not be able to do. As a file that only deliberate tools read, the list is inert until someone who has chosen to build an image or upgrade a system acts on it.

upgrade-peios

That is the whole procedure. It is safe to run again at any time: an interrupted upgrade is completed, and a system that is already current is left alone.

What happens #

1. Find the edition. upgrade-peios reads ID and VARIANT_ID from /usr/lib/os-release — the file the edition package itself wrote — and derives the package name: peios- plus the variant, peios-experimental. A system whose ID is not peios, or that has no variant, is refused (exit 2).
2. Upgrade the edition package. peipkg upgrade peios-experimental --bypass-alternate-upgrade (with --yes if you passed it). The edition declares an alternate upgrade path, so peipkg would otherwise stop and point here; the flag is upgrade-peios' whole privilege. The upgrade pulls the new release's closure with it. A peipkg failure is exit 3, and nothing further runs.
3. Stage the release's seeds. The new release.toml is read; each seed it names is copied from /usr/share/regim/ into /lcl/policy/autoapply.d/, and the drain script is placed in /lcl/policy/autorun.d/ if it is missing. A seed the release names that nothing ships is exit 4.
4. Apply them. reg apply --dir /lcl/policy/autoapply.d --once-delete --yes applies each seed and removes it from the queue. Services the seeds define start now. Failure is exit 5.

upgrade-peios never elevates. peipkg and reg run with the caller's token, exactly as they would if you typed the two commands yourself; KACS decides what each may do.

Options #

Why not peipkg upgrade #

peipkg upgrade upgrades every package it can and holds the edition back, printing the edition's message:

The package "peios-experimental" has an alternate upgrade path.

To upgrade Peios use the `upgrade-peios` command.

Warning: Alternate upgrade paths may bypass normal peipkg protections; ensure you fully trust the authors of the package before running.
held back: peios-experimental 2026.8-1 -> 2026.9-1

peipkg upgrade peios-experimental refuses outright with the same text. This is not peipkg being unable to upgrade the package; it is peipkg declining to do only half the job. Moving a release also means reconciling its seeds, and applying registry seeds is exactly what the package manager must never do on a package's behalf. The refusal keeps that line where it is, and the flag is the deliberate act that crosses it.

Once editions pin their dependencies exactly, this becomes the only way a release moves: peipkg upgrade cannot carry any pinned package past what the installed edition allows, so the system upgrades as a unit or not at all.

What it does not do #

• It does not upgrade packages outside the edition's closure that the edition merely floors. With >= floors, peipkg upgrade afterwards brings the rest current; with pins there is no "rest".
• It does not un-apply seeds the new release dropped. See release.toml.
• It does not reboot. Whether the new kernel is running is your call, as it is after any upgrade.