fds-os/docs/media-tools.md

# Cartridge image tools

[Documentation index](README.md) · [Cartridge usage](cartridges.md)

For new software cartridges, use the [Linux workstation workflow](workstation.md):
`fds-cartridge` builds xz bundles and a complete metadata-first `1+m` GPT image,
then previews and verifies a whole-drive write. Software image creation is not
an on-Pi operation. The commands below cover existing target media management
and legacy compatibility.

Historical M9 software acceptance verified image creation for all four classes,
confirmed virtual USB writes, and boot of a newly written SYSTEM. Physical media
and Pi testing remain deferred; see [validation evidence](m9-validation.md).
Images built before M9 do not contain these commands. Build a new image to use
them:

```sh
make rootfs PROFILE=cli
make rootfs-test
make system-card PROFILE=cli
make media-image-test
make media-test
```

Run these build commands on the x86_64 host from the repository root, after the
[first-build prerequisites](getting-started.md). The integration checks use
disposable virtual disks. The `fds` examples below run at the ARM FDS console;
the static ARM executables do not run directly on an x86_64 shell. For an
interactive console, use `make console-vm`; its initial bay map is deliberately
unconfigured, so use the tests for the complete virtual write workflow.

## Images and cartridge writes

An image is a regular file containing a complete GPT and its filesystems. Legacy
classes use one partition; current software media use metadata plus payload
partitions. Creating
one does not touch a disk. Writing one selects a physical bay and requires a
confirmation tied to that insertion, image hash and operation identifier.

Configure the physical bay map first using the [cartridge guide](cartridges.md).
Unconfigured or ambiguous bays are refused. At the FDS console, inspect the target and eject any existing filesystem first:

```sh
fds inspect BAY04
fds eject BAY04
fds burn system /data/fds-system-cli.img BAY04
```

Do not eject a blank disk: it has no mounted filesystem. The running SYSTEM,
internal BOOT/RECOVERY/INTERNAL partitions, mounts, swap and device-mapper holders
are protected. The tools support 512-byte logical sectors. A larger target keeps
the image's filesystem size; GPT backup metadata moves to the actual disk end.
Unused space is not a secure erase of old data.

All cartridge eject requests are refused while a media operation is active. This
keeps a source DATA filesystem attached while the worker holds its image file.
Finish or cancel the operation first, then eject the source normally.

The preview shows the bay, model, serial when available, kernel insertion number,
capacity, image class and SHA-256. Type the complete displayed phrase to proceed.
There is no generic `--yes` switch. A wrong phrase, changed image or different
insertion is rejected. Completion requires a flush, cache invalidation, readback,
and valid final partition tables. A failed or interrupted write never reports SAFE.

For scripts, `fds --json burn CLASS IMAGE BAY04` stops at the prepared preview.
Use its exact `id` and `confirmation` fields with:

```sh
fds burn confirm OPERATION_ID 'EXACT PHRASE FROM PREVIEW'
fds burn status OPERATION_ID
fds burn wait OPERATION_ID
fds burn cancel OPERATION_ID
```

`wait` waits for a terminal result; confirm or cancel from another console if
the operation is still awaiting confirmation. Cartridge
status remains available while the worker hashes or writes. Confirmation expires
after five minutes. Removing/reinserting media invalidates its insertion identity.
A service restart records an unfinished operation as failed, leaving it unmounted.

## Existing DATA and ENVIRONMENT creation

Use a writable working directory with enough free space for both a filesystem
image and its GPT wrapper. `/home/fds` is temporary RAM storage; `/data` is better
for large images, provided the source DATA is not the cartridge being overwritten.

```sh
cd /home/fds
fds format data BAY04 --label FELIS
fds format environment BAY04 --profile windowmaker --label 'WINDOW SYSTEM'
```

Each command first creates an image, then presents the same explicit confirmation.
Labels are the display names shown by FDS; fixed GPT partition names identify
the cartridge class. DATA uses ext4 and normally fills the target's available whole MiB. Use
`--size-mib 512` to choose a smaller filesystem. Its root belongs to the ordinary
FDS user. Create PROGRAM software bundles on the workstation using the linked
workflow; target PROGRAM creation now reports that requirement.
ENVIRONMENT stores only a declarative profile. See [Desktop usage](desktop.md).

`fds burn data BAY04 --label FELIS` is the same creation workflow. `fds-inspect`
and `fds-eject` are static aliases of the corresponding `fds` commands.

## Build a regular image from a prepared directory

Prepare a directory containing a valid `FDS/CARTRIDGE.TOML`, plus the class's
payload. The manifest format is described in [Cartridges](cartridges.md). Then:

```sh
fds-burn create data data-tree data.img --size-mib 128
fds-burn create environment environment-tree environment.img
fds-burn create system prepared-root system.img
fds inspect image system.img
```

The output must be outside the source directory, and existing output files are
never replaced. SYSTEM requires a complete prepared FDS root, including native
init, cartridge management and Dasung; preserve its intended ownership, file
modes, capabilities and prebuilt caches. On the build host, the normal supported
SYSTEM workflow remains `make rootfs PROFILE=cli` followed by `make system-card`.
`fds format system prepared-root BAY04` combines prepared-root construction with
the confirmed write workflow. It does not install packages or change the running
read-only SYSTEM.

SYSTEM construction must be able to read every source file, including protected
account files, while preserving root ownership and capabilities. Run that
construction step from a privileged maintenance session with a correctly
prepared tree. The normal FDS console is UID 1000 and does not gain access to
protected source files merely by invoking `fds-burn`. The ordinary user's
supported workflow is to burn an already-built SYSTEM image. The VM acceptance
test separately exercises privileged SYSTEM creation and ordinary-user confirmed
writing, then boots the result.

## Dependencies and current evidence

The new static Rust crate uses pinned `sha2` 0.10.9 for streaming image hashes.
Its digest/block-buffer/crypto-common/generic-array/typenum dependencies provide
the hashing primitives; cpufeatures selects CPU implementations and version_check
is a build helper. These eight additions are locked in `Cargo.lock`; no glibc,
OpenSSL, async runtime or network client is added to an FDS executable.
[Upstream SHA-2 API](https://docs.rs/sha2/0.10.9/sha2/).

Filesystem construction uses the already-installed glibc `erofs-utils` and
`e2fsprogs`; the retained legacy preparation code uses GNU `cp` from `coreutils`. These are explicit
`fds-cli` package dependencies, and `fds-cartridged` depends on `fds-cli` for its
worker. They add no packages to the existing base selection. The static tool creates and verifies GPT itself. A read-only loop
inside a private mount namespace lets the worker validate the filesystem and
manifest before confirmation. The filesystem checker runs as UID 1000 through a
private, already-open read-only device handle; cartridge code is never executed.

The [M9 validation report](m9-validation.md) records the actual ARM construction,
virtual USB writes, independent GPT/filesystem checks and SYSTEM boot evidence.
Writer unit tests also cover source mutation, readback corruption, cancellation
and overlapping backup relocation on slightly larger targets. Physical flash
behavior and power-loss testing remain deferred.