unified-storage: implement the ostree three-store pipeline

The goal of unified storage is to make the same on-disk layer data
simultaneously visible to containers-storage (for `podman run`),
composefs (for the boot overlay), and ostree (for deployment tracking),
using reflinks so layers are stored once regardless of how many stores
reference them.

This wires the pipeline into the ostree backend. When unified storage is
enabled — either at install time via the `[install.storage]` config key,
or post-install via `bootc image set-unified` — upgrades and switches
route through pull_via_composefs:

  Stage 1: pull the image into bootc-owned containers-storage
  Stage 2: zero-copy reflink import into the composefs OCI repo
  Stage 3: synthesize an ostree commit from the composefs tree

Whether unified storage is active is tracked by composefs/bootc.json
(BootcRepoMeta) and the ostree repo config `[composefs] unified` key.
This replaces the previous heuristic that checked per-image presence in
containers-storage, which broke when switching to a new image reference.

The install config gains a `storage.unified` key with three values:
disabled (default), enabled (fail if reflinks unavailable), and
enabled-with-copy (copy fallback). This lets an image opt into unified
storage without threading a CLI flag through every installer.

User-facing onboarding is a single verb with a required mode:

  bootc image set-unified <composefs|full>

`composefs` enables the ostree↔composefs binding only: it is a flag-only
operation that writes `[composefs] unified = true` and does not fetch,
synthesize, or stage anything. The next `bootc upgrade` re-pulls through
the composefs pipeline, synthesizes the commit, and stages a deployment;
a reboot then activates bound-only mode. `full` additionally onboards the
booted image into containers-storage so it is visible to `podman run`.
`bootc image sync` reconciles every bootloader-pinned deployment into
bootc's containers-storage on a unified system.

For the binding to actually activate, the upgrade path had to learn that
a classic (non-synthesized) booted commit must be re-staged even when the
image's manifest digest is unchanged: the synthesized commit is a
*different* ostree commit. Without this, `bootc upgrade` after
`set-unified composefs` would report "No update available." and the
binding could never take effect.

`bootc internals fsck images` validates consistency across the stores.
On a bound-only system the OS image lives in the composefs repo and is
intentionally absent from containers-storage, so checks are driven from
the live ostree deployments. A booted-but-not-yet-synthesized live image
(the window between `set-unified composefs` and the activating reboot) is
reported as `pending` with `ok: true` — an expected transient state, not
a corruption. `--repair` restores a missing composefs tag when the
objects are still present.

The cstorage GC is extended to protect images that have composefs tags,
since the composefs splitstreams reference the cstorage layer data;
pruning one without the other would corrupt the repo.

Assisted-by: OpenCode (Claude Opus 4.8)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

.github/workflows/ci.yml

@@ -158,6 +158,13 @@ jobs:
           # These tests may mutate the system live so we can't run in parallel
           sudo bootc-integration-tests system-reinstall localhost/bootc --test-threads=1
 
+          # Unified storage case
+          sudo podman build -t localhost/bootc-unified-storage -f ci/Containerfile.install-unified-storage
+          sudo podman run --privileged --pid=host localhost/bootc-unified-storage bootc install to-existing-root --stateroot=unified-storage --acknowledge-destructive --skip-fetch-check
+          # Verify unified storage was activated; composefs/bootc.json is written relative to
+          # the target physical root (/target bind-mounted to host /), so the file appears at /composefs/bootc.json
+          sudo test -f /composefs/bootc.json
+
           # And the fsverity case
           sudo podman run --privileged --pid=host localhost/bootc-fsverity bootc install to-existing-root --stateroot=other \
             --acknowledge-destructive --skip-fetch-check

Justfile

@@ -290,12 +290,27 @@ test-tmt-baseconfig baseconfig *ARGS:
         --seal-state={{seal_state}} \
         {{base_img}} readonly {{ARGS}}
 
+# Run unified-storage baseconfig test (works with ostree variant, no composefs required)
+[group('testing')]
+test-tmt-baseconfig-unified-storage *ARGS:
+    just baseconfigs=unified-storage build
+    just baseconfigs=unified-storage _build-upgrade-image
+    cargo xtask run-tmt \
+        --env=BOOTC_baseconfigs=unified-storage \
+        --upgrade-image={{upgrade_img}} \
+        --bootloader={{bootloader}} \
+        --filesystem={{filesystem}} \
+        --boot-type={{boot_type}} \
+        --seal-state={{seal_state}} \
+        {{base_img}} readonly {{ARGS}}
+
 # Run readonly tests for all standard baseconfigs
 [group('testing')]
 test-baseconfigs *ARGS:
     just test-tmt-baseconfig etc-transient {{ARGS}}
     just test-tmt-baseconfig root-transient {{ARGS}}
     just test-tmt-baseconfig var-volatile {{ARGS}}
+    just test-tmt-baseconfig-unified-storage {{ARGS}}
 
 # Run tmt tests on Fedora CoreOS
 [group('testing')]

ci/Containerfile.install-unified-storage

@@ -0,0 +1,8 @@
+# Enable unified storage (composefs+ostree) at install time via image-embedded config
+FROM localhost/bootc-install
+RUN <<EORUN
+set -xeuo pipefail
+mkdir -p /usr/lib/bootc/install
+printf '[install.storage]\nunified = "enabled-with-copy"\n' > /usr/lib/bootc/install/00-storage.toml
+bootc container lint
+EORUN

contrib/packaging/inject-baseconfig

@@ -11,21 +11,8 @@ if [ -z "${BASECONFIGS}" ]; then
   exit 0
 fi
 
-# setup-root-conf.toml is composefs-specific; ostree uses prepare-root.conf
-# which has a different (INI) format and different option names.
-case "${VARIANT}" in
-  composefs*)
-    TARGET="/usr/lib/composefs/setup-root-conf.toml"
-    ;;
-  *)
-    echo "inject-baseconfig: baseconfigs not supported for variant '${VARIANT}'" >&2
-    exit 1
-    ;;
-esac
-
-mkdir -p "$(dirname "${TARGET}")"
-
-# Split on commas and process each token
+# Split and process tokens; unified-storage is handled before the variant check
+# because it is backend-independent (works with both ostree and composefs).
 IFS=',' read -ra TOKENS <<< "${BASECONFIGS}"
 for raw_token in "${TOKENS[@]}"; do
   # Trim leading/trailing spaces
@@ -35,27 +22,50 @@ for raw_token in "${TOKENS[@]}"; do
   [ -z "${token}" ] && continue
 
   case "${token}" in
-    etc-transient)
-      printf '[etc]\ntransient = true\n' >> "${TARGET}"
-      ;;
-    root-transient)
-      printf '[root]\ntransient = true\n' >> "${TARGET}"
-      ;;
-    var-volatile)
-      # Mount /var as a fresh tmpfs on every boot via systemd.volatile=state.
-      # bootc-root-setup detects this karg in the initramfs and automatically
-      # skips the /var state bind-mount, leaving /var as an empty directory
-      # from the composefs image.  systemd-fstab-generator then mounts a fresh
-      # tmpfs there at local-fs.target.  Using a plain tmpfs avoids the
-      # overlayfs-on-overlayfs restriction that breaks tools like podman which
-      # use overlayfs under /var/lib/containers.
-      mkdir -p /usr/lib/bootc/kargs.d
-      printf 'kargs = ["systemd.volatile=state"]\n' \
-        > /usr/lib/bootc/kargs.d/50-var-volatile.toml
+    unified-storage)
+      # Write the bootc install config to enable unified storage at install time.
+      # This is backend-independent and works with both ostree and composefs variants.
+      mkdir -p /usr/lib/bootc/install
+      printf '[install.storage]\nunified = "enabled-with-copy"\n' \
+        > /usr/lib/bootc/install/00-storage.toml
       ;;
     *)
-      echo "Unknown baseconfig: ${token}" >&2
-      exit 1
+      # All other tokens require the composefs variant (they write to composefs-specific paths).
+      # Validate variant here, not at the top, so unified-storage can run on any variant.
+      case "${VARIANT}" in
+        composefs*)
+          TARGET="/usr/lib/composefs/setup-root-conf.toml"
+          mkdir -p "$(dirname "${TARGET}")"
+          ;;
+        *)
+          echo "inject-baseconfig: baseconfig '${token}' not supported for variant '${VARIANT}'" >&2
+          exit 1
+          ;;
+      esac
+      case "${token}" in
+        etc-transient)
+          printf '[etc]\ntransient = true\n' >> "${TARGET}"
+          ;;
+        root-transient)
+          printf '[root]\ntransient = true\n' >> "${TARGET}"
+          ;;
+        var-volatile)
+          # Mount /var as a fresh tmpfs on every boot via systemd.volatile=state.
+          # bootc-root-setup detects this karg in the initramfs and automatically
+          # skips the /var state bind-mount, leaving /var as an empty directory
+          # from the composefs image.  systemd-fstab-generator then mounts a fresh
+          # tmpfs there at local-fs.target.  Using a plain tmpfs avoids the
+          # overlayfs-on-overlayfs restriction that breaks tools like podman which
+          # use overlayfs under /var/lib/containers.
+          mkdir -p /usr/lib/bootc/kargs.d
+          printf 'kargs = ["systemd.volatile=state"]\n' \
+            > /usr/lib/bootc/kargs.d/50-var-volatile.toml
+          ;;
+        *)
+          echo "Unknown baseconfig: ${token}" >&2
+          exit 1
+          ;;
+      esac
       ;;
   esac
 done