fds-os/docs/workstation-tooling-plan.md

Workstation emulator and software cartridges

Software implementation and acceptance are complete; see the acceptance record and user guide. This follow-up extends the accepted 0.1.0 checkpoint. That signed release remains unchanged and does not contain the new format or emulator interface. Physical hardware acceptance remains deferred.

Required result

• A Linux workstation CLI boots the real FDS kernel, initramfs and SYSTEM image with QEMU, exposes its console, and controls twelve virtual USB cartridge bays.
• Cartridge image insertion and removal use QMP USB hotplug. Safe eject asks the guest to release the cartridge; forced removal explicitly simulates pulling it.
• Software cartridges use GPT with exactly 1 + m partitions. Partition 1 is FDS_METADATA; partitions 2 through m + 1 are FDS_PAYLOAD02, and so on. All are read-only EROFS containers. This permits multiple software archives in one partition without inventing a raw-partition archive container format.
• Metadata includes the cartridge identity and a catalogue locating every software bundle, its version, architecture, commands, lengths and SHA-256. Each software payload is an xz-compressed tarball, stored as bundles/<software-id>.tar.xz in its declared payload partition.
• Workstation tools build software from explicit trusted recipes, package the resulting trees, construct and verify a complete disk image, then separately preview/confirm a whole-USB write and verify its readback. Building must not depend on running on the Pi or on an Arch-specific container.
• The guest recognizes this layout, reports its software catalogue, and runs a selected software command as the ordinary user. Archives never run build hooks on the guest. Runtime extraction is bounded, verified and temporary; eject and surprise removal stop consumers and release every associated resource.
• SYSTEM and writable DATA retain their boot/data layouts. Legacy PROGRAM reading may remain for existing images, but newly built software cartridges use the metadata-first multi-partition format.

Acceptance gates

1. Typed Clap host CLIs, actionable help and Linux prerequisite diagnostics.
2. Real workstation builds of at least two software programs, including an AArch64 executable; archive inspection and independent xz/tar checks.
3. 1 + m images with multiple software packages sharing a partition as well as packages in separate partitions; independent GPT/filesystem inspection.
4. Negative checks for overlapping/corrupt GPT, wrong catalogue mappings, archive corruption, unsupported architecture, unsafe paths/types and size limits. Existing image/write rejection tests remain passing.
5. Complete-image write/readback using disposable regular files, including a larger target and confirmation/source/target-change rejection. Actual USB writes are deferred until the user selects physical hardware.
6. Real FDS boot under the public emulator, insert, catalogue, run, safe eject, reinsert, forced removal during execution, and cleanup/restart behavior. Every software partition must be exercised, not just the first payload.
7. Required rootfs/native-init regression and relevant DATA, PROGRAM, media and shutdown checks; English installation, usage, troubleshooting and format docs.

The QMP implementation follows the QEMU reference, including waiting for completed device deletion before releasing block nodes. The Rust tar library supplies archive entry decoding; FDS imposes stricter path, entry-type and size rules instead of trusting an archive's ownership or permissions. The existing xz utility supplies streaming compression and decompression with a memory limit. QEMU is host-only; no emulator or software build daemon is added to the Pi boot graph.