# Clap command-line migration validation

Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.


[Documentation index](README.md) · [Command usage](tooling.md) · [M12 evidence](m12-validation.md)

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](m12-validation.md#final-local-release-acceptance)
and the [67-section implementation ledger](implementation-status.md).