Productize wizer pre-initialization: library entry point, setup action, discoverability

[lann]

Wizer pre-init is validated (#25, PR #82: findings 22–24) but currently invisible to consumers: the knowledge lives in the findings log, two issue threads, and a feature-gated bin's doc comment. This issue turns the experiment into something a downstream repo can find and adopt. Blocked on #82 merging.

What exists after #82

wizer-preinit (component-test-runner, feature wizer) wizens unmodified suite artifacts — init is the contract's own all() via version-last invoke syntax (polymorph:test/tests.all@0.1.0()), no SDK hook, no extra export. Tags sections survive; scheduling/drift/lock --check work unchanged on the wizened artifact; artifact-sha256 differences are provenance-only (#44). Measured on the 10k synthetic: per-instance all() 3.15ms → 663µs; K=1 full-isolation run 30.8s → 7.1s sequential, 1.14s at --jobs 8.

Tooling

• Library entry point for SUT-importing suites — the shipped bin only satisfies WASI + test-context, but real consumer suites (webcrypto, websocket) import a SUT host module, and component instantiation is eager, so wizening them fails even though init never calls the SUT. Expose wizen_with(configure_linker, make_data) in component-test-runner mirroring Runner::with_data, so consumers reuse the linker setup they already have; the bin becomes the plain-suite convenience wrapper.
• actions/setup wiring — install wizer-preinit at the consumer's Cargo.lock rev alongside ct-runner/component-test-cli (actions/setup: consumer tool bootstrap (install component-test-cli/ct-runner at the Cargo.lock rev, cache, pins gate) #56's pattern). Consider a wizen: true input on the relevant action so the CI path is one flag.
• Decide: component-test wizen subcommand — fits the CLI's composition/execution scope (component-test CLI: composition, execution, aggregation #13); would subsume the bin. Optional; don't hold the rest on it.
• wasm-opt post-pass spike — Pre-initialized suites (build-time wizer snapshot of the case table) #25 predicts init-only code goes dead after snapshotting; measure whether it claws back meaningful artifact size (bench: 122KB → 1.29MB).

Discoverability (the actual point)

• Runner execution-policy doc — Runner execution-policy guidance #22's owed consolidated document is the primary home: wizening is an instance-granularity decision, so the K-knob cost table gets a "K=1 at scale → wizen" row with the measured numbers, plus the anti-recommendation (deltic/browser: no CoW, instantiate 3×, net ~1.5× at best — K>1 stays the JS-leg lever; K=0: irrelevant, the build amortizes to one ~12ms).
• Suite-writing guide (components/sample-suite/README.md) — short "large suites" section: build normally, one wizer-preinit command, when it pays, link to the policy doc.
• Cross-references — one line each in ct-runner's rustdoc (next to the cases_per_instance docs) and the README scope list. Not the design commitments — this is guidance, not contract.
• Pre-initialized suites (build-time wizer snapshot of the case table) #25 close-out comment pointing at the doc once it lands (issue threads are where researchers of pre-init will arrive).

Caveats the docs must carry

• The snapshot freezes whatever registry construction observed (env, entropy, clocks — baked at wizen-time values for every future instance). For contract-conforming suites this is Pre-initialized suites (build-time wizer snapshot of the case table) #25's determinism feature, but it must be stated: an env-parameterized registry stops being parameterizable.
• Run the wizened artifact everywhere downstream (runners, lockfile generation, hashing) rather than mixing artifacts.
• Upstream edges, for anyone hitting them: keep_init_func strip rewrite is broken (Wizer components from Rust fail unless keep_init_func(false) bytecodealliance/wasmtime#13168, open; moot for all()-as-init where keeping is mandatory); the wave func-name lexer rejects prerelease versions (@0.3.0-rc-…) in call form; wasmtime wizer CLI can't stub resource imports or handle nested components, and defaults WASI off (-S cli) — which is why the library route is the mechanism.

[lann]

Downstream data point from polymorph-webcrypto's CI (run 31456208804, 19,091 + 772 cases, 4-vCPU runner): run-wasmtime spends 53s and run-composed runs several minutes of a ~5-minute nine-target parallel phase — per your 10k-case K=1 bench (30.8s → 1.14s at --jobs 8) both legs collapse to seconds once wizened, and on a shared runner their freed CPU share also pulls in the phase's tail.

The first checkbox is the blocking one for us, as predicted: the shared suite imports polymorph:webcrypto/* from the host under test, so the shipped bin can wizen only the composed artifact (wasi + test-context imports after wac plug); the wasmtime-rustcrypto leg needs wizen_with(configure_linker, …) to reuse the ct-driver linker setup. No JS-leg interest, agreeing with the anti-recommendation — our jco and deltic legs already run instance-reuse workers, which is the K-lever there.

[lann]

Five of the eight boxes landed in #86 and #87 (ticked in the body):

• Library entry point: wizen::wizen_with(wasm, make_data, configure_linker) in component-test-runner (feature wizer), argument order mirroring Runner::with_data — the sketch above had (configure_linker, make_data), contradicting its own "mirroring" clause; the code follows with_data. wizen::wizen() is the plain-suite wrapper.
• component-test wizen subcommand (alias wizer): decided yes; it subsumed and deleted the wizer-preinit bin. Gated by just verify-cli: the wizened sample suite passes lock --check, reproduces the host-embed golden byte-for-byte, and composes + runs identically. One new empirical fact recorded in CLI: migrate to clap; add wizen, compose-runner, run subcommands #86's commit: wizer output composes fine under wac-graph — the "nested components" limitation applies to wizer inputs, not outputs.
• actions/setup wiring, reshaped by the subsumption: there is no separate tool to install — the CLI hardwires the runner crate's wizer feature, so setup's existing component-test-cli install carries wizen. actions-setup-smoke now drives the installed binaries over a built suite (wizen → lock --check → ct-runner golden → run --jsonl golden — the last with no wac and no wasmtime CLI in the job). The considered wizen: true input deliberately landed nowhere: setup runs before the consumer's artifacts exist; it belongs to run-suite when that materializes (noted in actions/README.md).
• Suite-writing guide: "Large suites" section in components/sample-suite/README.md with the measured numbers and both caveats; its link to the policy doc lands with the doc.
• Cross-references: run_suite_with's cases_per_instance rustdoc + the README scope bullet.

Remaining: the execution-policy doc (#22's home for the K-knob/wizen cost table — next up), the #25 close-out comment (blocked on the doc), and the wasm-opt spike. Expectation-setting for the spike: the 122KB → 1.29MB growth is snapshot data segments, which dead-code elimination cannot reclaim, and wasm-opt lacks component-model support so the pass would have to target the extracted core module — likely outcome is a short findings entry, not a size win.

[lannbot]

All eight boxes done; closing.

• Tooling: CLI: migrate to clap; add wizen, compose-runner, run subcommands #86 (wizen subcommand + wizen/wizen_with library entry points, subsuming the bin), actions/setup wiring for wizen (#85): smoke the installed-tools path #87 (setup wiring — the installed CLI carries wizen; smoke drives the consumer path end to end).
• Discoverability: Runner execution policy: the consolidated doc; --only reports deselected #90 — docs/runner-policy.md is the consolidated home ("K=1 at scale → wizen" with the measured numbers and the JS-leg/K=0 anti-recommendations), the sample-suite README's "Large suites" section links to it, cross-refs sit in the ct-runner rustdoc and README scope list, and the Pre-initialized suites (build-time wizer snapshot of the case table) #25 close-out comment points researchers at the doc.
• The wasm-opt spike concluded negative with measurements (finding 25): binaryen refuses components, the growth is snapshot data (1.18MB/10,002 segments vs 93KB code), core-module -Oz reclaims 1.5%, and wasm-tools strip saves 0.38% while its default form deletes the tags inventory.

Writing the doc also forced #22's cost-tier rule to become true: --only now reports the unselected census as deselected (#90), with the JS leg's gap tracked in #89. The wizen: true CI flag deliberately landed nowhere — it belongs to the parked run-suite action (noted on its bullet in actions/README.md).