Backend-neutral builtin argument contract (spec -> parser), with three-engine benchmarks

[lu-zero]

Stacked on reubeno#1302 (bpaf port) — base is bpaf-port, so this diff shows only the contract work. Draft for inspection; benchmark data below.

What this does

Replaces per-builtin hand-rolled argument parsing with a backend-neutral contract:

static ECHO_SPEC: CommandSpec = CommandSpec {
    args: &[
        ArgSpec::flag("no_newline", &['n'], &[], "Do not output a trailing newline"),
        ArgSpec::value("delimiter", &['d'], &[], "DELIM", "Output delimiter"),
    ],
    positionals: &[PositionalSpec::many("operands", "OPERANDS")],
};

impl SpecCommand for Echo { /* spec() + from_matches(&ParsedValues) */ }

A build selects one engine via cargo features (parser-usage / parser-clap / parser-bpaf, priority in that order); ArgParserBackend translates the static spec into the engine's structures, parses, and maps results into slot-indexed ParsedValues. All ~49 builtins are converted.

On "this reimplements usage's approach"

Correct observation — deliberately so. usage-rs's derive already proved that static spec → parser structure is the fast shape; what it doesn't give you is engine neutrality. This contract keeps the shape (specs are compile-time statics, exactly what usage's derive would emit) but makes the target swappable:

	usage derive	this contract
spec source	derived from type definition	hand-written static
spec → parser graph	compile-time monomorphized	runtime translation, interned (one leaked graph per builtin, matching derive's statics)
result binding	direct to fields	slot-indexed ParsedValues (+ shell-specific semantics live in core, shared by all engines)

The measured cost of that indirection vs native single-engine builds is within noise (below).

Benchmark data

benchmarks/three-way.py (committed): pinned (taskset), interleaved sampling across all shells (drift hits every build equally), byte-for-byte output parity check before timing, medians of 12 samples. Workloads in benchmarks/real-world/.

7 shells, same machine, same run:

workload	bash	clap-upstream¹	contract+clap	bpaf-single²	contract+bpaf	usage-single³	contract+usage
startup (ms)	1.6	1.7	1.7	1.7	1.7	1.7	1.7
wordops-10k (ms)	151.8	54.3	53.0	52.7	53.1	52.8	52.6
config-lint-500 (ms)	23.8	95.5	79.5	74.7	71.6	50.6	50.0
deploy-sim (ms)	15.0	20.8	20.6	20.3	20.2	19.4	19.5
interp-loop (ms)	139.0	275.0	284.1	287.4	280.7	227.3	275.1

¹ upstream main (clap derive per builtin) · ² reubeno#1302 head (native bpaf impls) · ³ usage fork with #[derive(Cli)] builtins

Reading:

• Engine ranking on parse-dense work: usage ≫ bpaf > clap. config-lint is dominated by builtin invocation; usage halves upstream-clap's time.
• Contract overhead vs its own backend: ≤2% everywhere, often negative (c-clap beats upstream's own derive by ~17% on lint — the leaner static-spec-built Command wins over the derive path).
• interp-loop caveat: no argument parsing happens in that loop at all, so its spread (usage-single 227 vs everything else 275–288) reflects whole-binary codegen/layout variance between independently compiled trees, not arg-model work. bash still wins it outright (139).
• Startup and RSS are identical across all six brush builds (±0.1 MiB).

Correctness

• Compat suite: 1854 passed / 0 failed / 456 known-fail — identical to both baselines.
• New backend-parity unit tests: each engine must interpret specs identically (flags/values/positionals/strict flag-like rejection). These caught two latent bugs in the clap backend (pre-redesign positional storage, allow_hyphen_values swallowing -x) — fixed here.
• usage graphs are interned per (spec, name); total leakage matches what derive emits as statics (~50 small graphs), verified by pointer-stability test.

Known trade-offs / open questions for review

• Per-event id→slot resolution scans the spec arrays (linear in args-per-builtin, tiny n). Measured invisible; if it ever profiles hot, resolve slot tables once at intern time.
• Hand-written specs duplicate information that a derive could generate from types (usage-style). Kept manual to avoid proc-macro machinery; could add a derive later without changing the contract.
• declare/readonly/local share one spec under three names (cache keyed accordingly).

Assisted-by: ox-alpha (opencode)

[lu-zero]

Wrong venue — moving to upstream.