unified-storage: Implement three-store pipeline for composefs and ostree backends

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 full pipeline into the ostree backend. When a system has
unified storage 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 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). 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 requiring a CLI flag to be threaded through every
installer.

bootc image list cross-references composefs tags against containers-storage
by config digest to report images as unified (in all three stores) or
partial (cstorage only, composefs import pending). bootc internals fsck
images checks consistency and --repair restores cstorage from composefs
when needed. 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.

On the composefs-native backend, onboarding must also reconcile the
non-booted deployments: a rollback or staged image lives in the composefs
repo but not yet in containers-storage. `bootc image set-unified` and the
new `bootc image sync` command now reconcile every bootloader-pinned
deployment (booted, rollback, staged) into bootc's containers-storage, so
`bootc internals fsck images` passes there too. The pinned set is grounded
in the bootloader entries (via list_bootloader_entries), which are the
authoritative record of what the system can boot, rather than the origin
state directories which can drift from it.

Reconciliation exports the missing image from the composefs repo. This
must preserve the config digest, since that is the image ID
containers-storage matches on: the export replays each layer's
uncompressed tar byte-exactly via SplitStreamReader::cat() (preserving the
diff_ids) and writes the original config JSON verbatim rather than
re-serializing it. The recovered image is imported into bootc's private
overlay store (not the host's default store) using the same bind-mount
plumbing as the booted-image copy path, so fsck actually sees it.

Assisted-by: OpenCode (claude-sonnet-4-6@default)
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