OS Update Mechanism — koder-os-update

Direction for OS-level updates on installed Koder Kodix: how a running system discovers, downloads, applies, and (eventually) rolls back updates to its base system + the koder-suite packages that came from hook 0060. Today the only way to "update" a Koder Kodix install is to re-flash the ISO or run `apt upgrade` per-package; this RFC defines the user-facing CLI (`koder-os-update`), the underlying transport, and the trade-offs between three candidate mechanisms (ostree, apt-only, delta packs). Recommended path: **apt-only over Koder Hub** for v0 (ships in weeks, reuses #012/#116/#117), with A/B partition / ostree evaluated for v1+ once #018's CLI is live.

Version: 0.1.0 — Draft Status: Proposed (2026-05-20) Owner: Koder Kodix WG (infra/linux/kodix) Discussion ticket: infra/linux/kodix #018

Abstract

Installed Koder Kodix currently has no first-class "system update" path. Users can run apt upgrade package-by-package (no awareness of which upgrades are OS-relevant) or re-flash the ISO (loses local state). This RFC defines the koder-os-update CLI, picks the transport, and lays out the rollout from v0 (apt-only over Hub) to v1+ (rollback-capable, likely ostree or A/B partitions). It explicitly does not specify a kolide notification UX (that is a separate Kolide ticket) or per-app auto-update (specskoder-appbehaviors.kmd §4 already covers that — different scope).

Motivation

Today's gap

  1. Discoverability: the user has no command that answers "is my system

    up to date?" Per-package apt list --upgradable is too noisy and doesn't distinguish OS-relevant updates from random Debian packages.

  2. Atomicity: apt upgrade mid-flight can leave a half-upgraded

    kernel + initramfs pair if power is cut. No rollback.

  3. Reproducibility: policies/releases.kmd tags every component for

    per-component release engineering, but the OS itself (kernelglibc systemd + all koder-suite packages from hook 0060) doesn't have a "Koder Kodix release" version anywhere a running install can see.

  4. UX: specs/koder-app/behaviors.kmd §4 made per-app updates a

    smooth, default-ON background process. The OS update story should feel equally low-effort, not "drop to a terminal and remember 4 commands".

Why now

Three of the four blockers for the simplest viable transport just shipped (2026-05-19): products/dev/hub #116 (apt surface), #117 (GPG signing key), and #103 (Flow→Hub publish pipeline) are all in backlog/done/. That makes apt-get install -y koder-os-update; apt-get update; apt-get upgrade a 30-line ship-in-weeks v0, vs. weeks-to-months for any rollback-aware design. Shipping v0 now buys us a tracker for what "upgrade-friction" actually looks like in the field, which is the information we need to size v1 properly.

Candidate transports

Three concrete options were considered. Each is scored against five criteria taken from policies/self-hosted-first.kmd + Koder Kodix specifics: implementation cost, rollback story, bandwidth efficiency, operational complexity, and migration risk away from this choice later.

Option A — apt-only over Koder Hub (Recommended for v0)

hub.koder.dev/apt already serves the canonical koder-* packages under suites stablepredev (per hub #116, #117, #131). A koder-os-update CLI is a thin wrapper:

  • check → apt-get update -q && apt-get -s upgrade filtered to a

    curated OS-RELEVANT_PACKAGES=(linux-image-* initramfs-tools dracut systemd glibc dbus kolide-* koder-* …) list.

  • apply → apt-get install --only-upgrade -y <filtered list> +

    post-upgrade hooks (update-initramfs -u, update-grub).

  • rollback → not supported in v0; prints

    "rollback requires ostree mode (see RFC §A/B partitions); v0 workaround: reinstall the previous .deb via 'apt install <pkg>=<old_version>'".

Pros:

  • Ships in ~2 weeks. CLI is mostly argument parsing + apt wrappers.
  • Reuses every piece of infrastructure we just shipped (#116#117#103).
  • Zero new daemons, zero new on-disk layout changes.
  • Plays well with policies/multi-tenant-by-default.kmd — apt's lock is

    one writer at a time, which matches existing semantics.

Cons:

  • No atomic apply. Power loss mid-upgrade can leave a broken kernel

    + initramfs pair. Mitigation: do kernel + initramfs last in the apply order, after all userspace upgrades. Documents the risk; doesn't solve it.

  • No rollback. Documented as a known v0 limitation with a v1 plan.
  • Not all OS-relevant state lives in .deb packages (e.g. NetworkManager

    config drift, custom systemd overrides). v0 simply won't touch those.

Score: cost 15 (~2 weeks); rollback 45 (no); bandwidth 3/5 (apt's delta-debs help but no chunk-level dedup); ops 2/5 (familiar shape); migration 2/5 (v0 → v1 is additive — koder-os-update CLI keeps the same surface, only transport swaps under it).

Option B — ostree (Atomic-style, immutable rollback)

Reorganise the rootfs so /usr is a versioned tree on libostree, with the running system being a deployment checkout. Same model as Fedora Silverblue, CoreOS, EndlessOS.

Pros:

  • True atomic upgrade: deploy a new tree, reboot into it. Old tree

    stays on disk for one-keystroke rollback.

  • Tree integrity is content-addressed — no half-state windows.
  • Diff between two deployments is precise (single chunk graph).
  • Fits well with the future Koder Kodix server use case (s.khost*

    fleet management).

Cons:

  • Filesystem reorganisation. /usr rdonly breaks the

    "edit etckodix