Module rootfs 

Guest rootfs management module.

This module handles preparation and management of guest rootfs for MicroVM instances. The rootfs contains the minimal filesystem required to boot the guest agent.

Rootfs staging providers are selected by host capability:

• CopyProvider — full recursive copy (works everywhere)
• OverlayProvider — Linux overlayfs mount (near-instant CoW)
• guest-native ext4 on macOS, with case-sensitive APFS for compatibility

A provider finalizes the staging tree into the directory or guest-native block source handed to the VMM.

Structs

AttachedRootfs

A temporarily attached persistent rootfs.

CopyProvider

Full recursive copy provider — works on all platforms.

Ext4Artifact

Paths and metadata for one complete, validated artifact generation.

Ext4ArtifactManifest

Durable metadata committed in the same atomically published directory as the raw filesystem image.

Ext4ArtifactOptions

Determinism inputs and capacity policy for one ext4 artifact.

GuestLayout

Guest filesystem layout.

OverlayProvider

Overlayfs provider — near-instant CoW mounts (Linux only).

ResumedRootfs

A validated rootfs generation that no longer has a host directory view.

RootfsArtifactCacheOptions

Exact identity and resource bounds for an immutable provider artifact.

RootfsBuilder

Builder for creating guest rootfs.

RootfsFileInfo

Minimal file metadata needed to classify rootfs changes.

RootfsFinalizeOptions

Lifecycle constraints that a provider must honor before handing the rootfs to the VMM.

RootfsOciPrepareOptions

Verified OCI inputs for a provider that can publish a bootable artifact without first materializing a host-visible rootfs directory.

RootfsResumeOptions

Constraints for reopening an already guest-owned rootfs generation.

Constants

DIFF_BASELINE_FILE

Filename stored beside each box rootfs.

EXT4_ARTIFACT_SCHEMA

Versioned A3S wrapper contract for a published ext4 artifact directory.

EXT4_BUILDER_ID

Exact writer identity included in cache keys and artifact manifests.

GUEST_WORKDIR

Working directory inside the guest VM.

Traits

RootfsProvider

Abstracts how a rootfs directory is prepared for a box from a cached lower layer.

Functions

attach_persistent_rootfs

Attach an existing platform-backed persistent rootfs for offline access.

create_diff_baseline_if_absent

Persist the first pristine baseline for a box without ever replacing it.

default_provider

Auto-detect the best available rootfs provider for a new boot.

default_provider_for_box

Select the provider for an existing box generation.

guest_diff_baseline_required

Return whether the next guest generation must capture the first baseline.

guest_native_ext4_disk_mib

Return the logical disk capacity owned by a retained guest-native rootfs.

guest_native_ext4_generation_exists

Return whether a box has a retained guest-native raw rootfs generation.

publish_ext4_artifact

Build, validate, and atomically publish a raw ext4 filesystem.

publish_guest_diff_baseline

Validate and publish the baseline captured inside guest-init.

read_persisted_exit_code

Read the exit code persisted by guest-init.

resolve_workload_exit_code

Resolve a workload exit code without treating a clean provider shutdown as proof that the guest workload succeeded.

stage_box_terminal_rootfs_metadata

Invalidate the last clean-shutdown metadata generation before launching a box, retaining it at the one-shot replay path used by guest-init.

unmount_box_overlay

Unmount a box’s overlayfs merged view — best-effort and idempotent.

unmount_box_rootfs

Unmount a platform-specific writable rootfs mount.

walk_rootfs

Capture a rootfs tree while excluding runtime-owned control files.