FDS/OS 1.0

docs/workstation-tooling-plan.md

@@ -0,0 +1,60 @@
+# Workstation emulator and software cartridges
+
+Software implementation and acceptance are complete; see the
+[acceptance record](workstation-validation.md) and [user guide](workstation.md).
+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](https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html),
+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.