fds-os/docs/developer/clap-validation.md

Clap command-line migration validation

Development reference and historical context. For current operating instructions, use the user manual. Acceptance applies only to the source and artifacts identified in each record.

Documentation index · Command usage · M12 evidence

Software acceptance completed on 2026-09-21. Every Rust command-line interface uses the shared, locked Clap 4.6.7 dependency. The migration adds no third-party crate versions or shared runtime libraries. Dasung already used Clap; its workspace dependency now shares the same definition. The dependency-free smoketest has no argument interface.

Implemented behavior

• Typed commands cover fds, its inspect/eject/power aliases, stage0, boottrace, cartridge/profile services, media creation/writing, and release signing.
• fds burn and fds-burn share one grammar. Format options are specific to the selected class, with duplicate and conflicting options rejected.
• Clap generates command-specific help, versions, required-option errors and typed bay/size validation. Global --json works around nested commands.
• fds run BAY -- EXECUTABLE ARGS... preserves every child argument, including --help, --json, empty strings, spaces and an additional --.
• Private s6 flags and default daemon/PID-1 behavior are preserved. Stage0 enters its emergency path on argument errors as PID 1 instead of exiting.
• VM client and write/stress helpers now build through Cargo and use Clap. No project-owned Rust source reads or slices a raw process argument vector. Kernel command-line files and metadata remain separate domain parsers.

A regression test caught that Clap's broad argument/subcommand conflict rule also rejected fds-inspect --json image IMAGE. The final implementation uses Clap's typed conversion hook to reject only simultaneous target/image forms; it accepts global options before or after the image subcommand. This behavior passed host parser tests and execution of the actual ARM binary.

Build and runtime evidence

The final tooling run passed 48 Rust unit tests, ELF checks for every ARM executable/alias, real ARM help/version/invalid-input tests, strict metadata checks and stage0 diagnostic fixtures. Evidence: out/logs/clap-tooling-test.log. The independent Dasung simulator/service and host/ARM/OpenSSL signing suites passed in out/logs/clap-dasung-test.log and out/logs/clap-signing-test.log (out/m12-signing.9xgbool5/).

make bootstrap, make smoke-test, and make check passed. The complete make all build passed in out/logs/clap-all-final.log; the earlier clap-all.log attempt was intentionally stopped before fixing the inspection option-placement regression. The final make check also passed in out/logs/clap-check-final.log.

All suites below passed against the rebuilt images. Each has its own out/logs/clap-<make-target>.log and retained VM/image evidence:

Make target	Evidence directory
init-test	out/m2-vm.lsptD3/
boot-test	out/m4-vm.4VJHfm/
console-test	out/m5-vm.ktln7za0/
cartridge-test	out/m6-vm.nv3oq41q/
data-test	out/m7-vm.yv53pjkk/
desktop-test	out/m8-vm.q8nwbhgc/
media-image-test	out/m9-images.9ts4w_qb/
media-test	out/m9-vm.06yddrko/, out/m9-system.a9n8xxb_/
power-test	out/m10-vm.yk62sod6/
stress-test	out/m11-vm.vg5dicrw/, out/m11-faults.pd52oxs7/
recovery-test	out/m12-recovery.0604mqgm/
internal-test	out/m12-internal.uj0rbf4i/
clock-test	out/m12-clock.f54asrop/
development-test	out/m12-development.mu29x4mr/

These checks include actual SYSTEM creation/write/readback/boot, confirmed DATA repair, interrupted-checker quarantine, persistent settings across reboot, window manager and DHCP control, sustained writes, all twelve overlapping I/O intervals, and injected write/flush/readback/worker/daemon failures. They use regular-file images and isolated ARM VMs. No physical media was written.

Executable size and startup measurements

Clap increases executable sizes. All eight production Rust programs (including Dasung) remain statically linked and contain no personal build-path prefix. out/clap-binary-sizes.json records the final hashes and these sizes:

Executable	Before, bytes	After, bytes
fds	900,720	1,097,960
fds-burn	821,344	990,312
fds-stage0	474,336	633,880
fds-boottrace	442,152	606,672
fds-cartridged	917,328	1,064,832
fds-profile	527,880	687,904
fds-release	434,720	595,776

Five alternating QEMU TCG boot pairs compare the previous complete image set with the rebuilt images, using the same Pi kernel. The previous images also precede Rust source-path normalization; this is an image-level comparison, not an isolated microbenchmark of the parser. Each measurement uses Linux CLOCK_BOOTTIME from kernel start to the first ordinary-user console.

Image set	Five samples, ms	Median, ms
before	1958.754852, 2031.634456, 1998.790409, 1951.843302, 1961.052514	1961.052514
clap	1917.447815, 1909.301394, 1923.776234, 1955.579658, 2053.676925	1923.776234

The median change was −37.276280 ms, below the +100 ms regression threshold. This does not establish a speedup on the Pi. Input hashes, all sample reports and serial logs are in out/clap-console-pairs.qyyoppcj/; the replay script is out/clap-boot-comparison.py.

The updated stage0 was also built at all three optimization levels and booted three times per level (out/rust-profiles.8hnnusn8/comparison.json):

Optimization	Stage0 bytes	Median kernel-to-console, ms
z	633,880	1922.658965
2	730,568	1938.769685
3	757,168	1950.010662

Retain z; these VM samples do not establish a physical-hardware winner. The separate twelve-device test observed a +180.457 ms median versus empty bays. That comparison adds twelve emulated USB devices and is not the before/after Clap comparison. Its readiness-gate test still proved that cartridge service readiness does not block the console. Physical Pi boot and shutdown targets, USB electrical behavior, display recovery and flash durability remain deferred.

Release status

The requested CLI migration is complete and included in the signed local 0.1.0 release. Fresh v5 offline builds produced 27 byte-identical artifacts, which also match the normal images used by every runtime suite above. The old v4 candidate was stopped before acceptance. See final M12 evidence and the 67-section implementation ledger.