feat(rootfs): add rootfs provider boundary with containerd-backed provider

Adds openshell-rootfs, the rootfs provider boundary for compute
drivers: a provider resolves an OCI image reference into
provider-neutral PreparedRootfs mounts keyed by a per-sandbox key, and
owns image resolution, acquisition, unpacking, and the lifetime of the
backend resources realizing the root filesystem.

ContainerdRootfsProvider is the first implementation, backed by a
system-provided containerd used only for image pull/unpack and
snapshot management via its Transfer/Images/Content/Snapshots/Leases
services. containerd concepts (snapshots, chain IDs, leases) are fully
encapsulated: prepare() pulls, resolves the OCI chain ID, prepares a
per-sandbox writable snapshot protected from containerd's GC by a
lease, and cleans up after itself on failure; release() removes the
snapshot and lease at teardown.

Keeping the containerd daemon behind this boundary (rather than in a
compute driver's own contract) leaves room to swap in a daemonless
provider, or converge the VM driver's image acquisition pipeline onto
the same types, without redesigning the sandbox provisioner on top.

Related: #2255
Signed-off-by: Eric Curtin <eric.curtin@docker.com>

Author: ericcurtin

AGENTS.md

@@ -45,6 +45,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `crates/openshell-driver-podman/` | Podman compute driver | In-process `ComputeDriver` backend for local Podman sandbox containers |
 | `crates/openshell-driver-vm/` | VM compute driver | Standalone libkrun-backed `ComputeDriver` subprocess (embeds its own rootfs + runtime) |
 | `crates/openshell-nft-ruleset/` | nftables rulesets | Shared per-sandbox NAT + default-deny nftables ruleset generation used by compute drivers |
+| `crates/openshell-rootfs/` | Rootfs providers | Rootfs provider boundary for compute drivers; containerd-backed provider for image pull/unpack and snapshots |
 | `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
 | `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |
 | `crates/openshell-supervisor-middleware/` | Middleware runtime | Generic middleware registry, remote service integration, and chain execution |

Cargo.lock

@@ -30,6 +30,25 @@ The gateway records driver identity and version from the startup capability
 response. Elevated gateway info reports that initialized driver snapshot instead
 of re-querying drivers on each request.
 
+## Rootfs Provisioning Boundary
+
+Rootfs provisioning — resolving an OCI image reference into a root filesystem
+a sandbox can be launched from — is a provider concern, separate from sandbox
+provisioning (namespaces, cgroups, VM boot). `openshell-rootfs` defines that
+boundary: a provider produces provider-neutral `PreparedRootfs` mounts keyed
+by a per-sandbox key, and owns image resolution, acquisition, unpacking, and
+the lifetime of whatever backend resources realize the root filesystem.
+Backend concepts (containerd snapshots, leases, chain IDs) must stay behind
+the provider and out of the compute-driver contract, so a daemon-backed
+provider can be replaced by a daemonless one without redesigning the
+provisioner on top of it.
+
+`ContainerdRootfsProvider` is the first implementation, backed by a
+system-provided containerd used only for image pull/unpack and snapshot
+management. The VM driver's image acquisition and ext4 materialization
+pipeline is the same boundary shape; converging it onto the shared types is
+tracked follow-up work.
+
 ## Runtime Summary
 
 | Runtime | Best fit | Sandbox boundary | Notes |

architecture/compute-runtimes.md

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "openshell-rootfs"
+description = "Rootfs provider boundary for OpenShell compute drivers, with a containerd-backed provider"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lib]
+name = "openshell_rootfs"
+path = "src/lib.rs"
+
+[dependencies]
+# containerd's own generated gRPC client. This is the "system-provided
+# containerd" integration point behind `ContainerdRootfsProvider`, used
+# only for image pull/unpack and snapshot management -- never bundled,
+# installed, or managed by OpenShell. containerd's container/task
+# services and shim are never used; consumers of a prepared rootfs (the
+# OCI compute driver) spawn the low-level OCI runtime themselves.
+containerd-client = "0.9"
+
+futures = { workspace = true }
+serde_json = { workspace = true }
+sha2 = "0.10"
+thiserror = { workspace = true }
+tonic = { workspace = true, features = ["transport"] }
+
+[lints]
+workspace = true