id: design: feature-leveled build variants on the crate split — client-only, server, headless, embedded (from #3447) #5788

Summary

Design the feature-leveled build variants the crate split exists to enable: client-only, server, headless/embedded, and provider-class builds of ID with defined feature sets — which capabilities each variant carries, how the levels are expressed, and how conformance is checked per variant.

Motivation

The crate split (#3447, Drew-prioritised) is repeatedly justified by what it unlocks. The answers review (PR #5707, §12) states it plainly: "The split is also the mechanism for feature-leveled variants — client-only builds stripping most of the server — once the seams exist." But the variants themselves have no design: the split issues (#4403–#4411) carve the seams, and nothing decides what the products on those seams are. The consumers are already queuing up with incompatible needs — the Android client (needs a client-only core with no server), the ESP32 line (needs a provider-class minimal build), Bevy incorporation (needs an embeddable world/client library), the terminal (client + occasional server). Without a variants design, each consumer invents its own feature set and the "levels" become per-consumer accidents. (Note: #3846 specified the F13.8 client-only boundary; this issue is the build/product design across all variants, a different artefact. #1797's "build-variants as a cargo artifact" was build hygiene, not this.)

Sketch

• The level set: name the variants (at minimum: client-only, full node/server, headless service, embedded/provider) and the capability matrix each carries — journal, sync, serve, presenters, providers — against the crate seams (pkgs/id: split the monolith crate into sub-crates along module seams (prioritized by Drew 2026-11-01) #3447's 11 crates).
• Expression: cargo features vs per-crate composition vs both — and the rule that a variant is a composition of crates, never a thicket of cfg inside the monolith's remains.
• Size/perf budgets: Drew's stated order for the split — shipped-binary runtime performance first, build time second — applied per variant: what each variant's binary must weigh and do (the client-only variant is where the ≤2 MiB-class discipline from the fleet work is the reference point).
• Conformance: the shell contract and receipt contract per variant — which contracts a client-only build must still honour, and how variant conformance is tested (the determinism infrastructure's replay fixtures as cross-variant oracles: same journal, every variant, same state).
• Upgrade/migration interplay: F12.9 program upgrade (id: F12.9 program upgrade with state migration and rollback #1066) semantics per variant — what a client-only build does when a world requires a newer program than it carries.

Open questions

• Are variants release artefacts (published binaries) or build-time choices for embedders only?
• Does the server variant ever lose features to a level (a "lite server"), or is server always the full set?
• Who owns variant drift — what stops a fifth consumer from quietly becoming a fifth variant?

Relations

Parent: epic #2056. Depends on: #3447 and steps #4403–#4411 (the seams). Consumers: the Android client design, the ESP32 platform design, the Bevy incorporation design, #788 (reference shell). Relations: #3846 (client-only boundary spec), #1066 (upgrade/migration), #5685 (per-interface benchmark matrix — variants belong in it). Filed in the 2026-11-04 gap pass (WS-F).