Relationships
#4647 Lazy loading L8: load only the invoked subcommand in extension, vault, datastore and access
Opened by zack · 11/11/2026· Shipped 11/11/2026
Next step of the routing track in the lazy command loading plan. It applies the group pattern from #4613 and #4625 to four more groups, and uses the benchmark and parity scripts from #4590. The numbers below are from the bundled build (#4624), which becomes the default in #4637.
Why
The plan's gate for L8: route a group per subcommand, measure its busiest subcommand on the bundled binary, and keep the group only if it saves at least 20 ms warm. A prototype routed six of the eight remaining groups and measured them on Linux x86_64. Paired runs alternated the base and routed binaries run by run, so load drift hit both equally. Warm figures are medians of 21 runs (41 for worker), cold of 11 (21 for worker).
| group | subcommand | base cold / warm | routed cold / warm | warm Δ (IQR) | peak RSS Δ | qualifies |
|---|---|---|---|---|---|---|
| extension | extension list |
341 / 253 | 274 / 174 | −78 (−86…−70) | −12.9 MiB | yes |
| vault | vault get |
335 / 247 | 267 / 175 | −72 (−107…−61) | −8.7 MiB | yes |
| datastore | datastore status |
342 / 248 | 274 / 182 | −66 (−79…−51) | −9.3 MiB | yes |
| access | access token list (nested routing of token) |
346 / 254 | 266 / 185 | −73 (−78…−64) | −23.8 MiB | yes |
| report | report search |
402 / 306 | 408 / 311 | +6 (+4…+9) | −0.8 MiB | no |
| worker | worker list |
282 / 197 | 271 / 181 | −22 (−36…+2) | −6.3 MiB | no (borderline) |
A separate bench-startup pass on each binary agreed: −63, −65, −71 and −81 ms for the four winners, +12 for report, and −11 for worker.
Controls (warm Δ): version +4 / +7, data get +7, behavior run +7, workflow run +12. Unrouted serve and dashboard paths moved +7 to +18. So the routed binary pays roughly 5–10 ms on paths whose code did not change, probably because the bundle's chunk layout shifts. worker does not clear the gate against that: −11 to −22 depending on the run, with an IQR that crosses zero.
Scope
Route extension, vault, datastore and access the way #4613 routed data and workflow:
- Factories and tables. Each group gets a header factory (
createExtensionCommand(rest),createVaultCommand(rest),createDatastoreCommand(rest),createAccessCommand(rest)) and a*_routes.tstable. The header keeps its description,unknownCommandErrorHandlerandgroupCommandAction. The root rows passrest. - Inline subgroups move to their own modules, so a table row can import them:
vault type;datastore type,catalog,namespaceandconfig.config migrateis a child ofconfig, not ofdatastore: the prototype's generator got this wrong, and parity caught it as an extradatastore migratecommand;access token, which becomes a nested routed subgroup (createAccessTokenCommand(rest)with its own table), likemodel methodin #4625. Theaccess token listfigure above was measured with nested routing.
- Users of the old instances.
extensionCommand,vaultCommand,datastoreCommandandaccessCommandstop being module-level instances. Update their users (tests undersrc/cli/commands/, any integration fixture) to call the factories. - Fitness rules. Extend the route rules from #4613 to the new tables: each table equals the group's children in the full tree, subcommand aliases appear in the table, schema parity and the per-route Worker test cover each path, and the composition-root guard names the new tables.
Not in scope
report. Routing saved nothing (+6 ms).worker. It doesn't clear the gate reliably; see above.dashboard. It is a single command with no subcommands.serve. Itsreload,check-configanddaemonsubcommands live in serve.ts together with the roughly 7,000-lineserveaction and about 2,400 lines of helpers they share, so routing it means splitting that file first. The most it could save is about 93 ms (serve check-config245 ms warm againstversion152 ms), so it isn't ruled out. If anyone wants it, it needs its own spike.
The full-tree cost, and ordering
Routing makes the paths that load the whole tree slower. In the prototype, warm Δ against base:
--help+199 ms;completions bash+195 ms;- bare
swamp help(the JSON tree) +243 ms; - group help:
extension --help+45 ms,vault --help+37 ms.
Starting the imports in parallel does not recover this; #4646 has the details. Root --help is the path people hit most, and #4646 takes it off the full tree (158 ms in its prototype), so land #4646 before this. Quote the remaining full-tree costs (completions, help, group help for the four groups) in the PR, so the trade is visible.
Acceptance
- The parity script passes against the base binary, including each group's
--help,help <group>, a mistyped subcommand in each group, andaccess token --help. - The benchmark shows each of the four subcommands at least 20 ms faster warm than base, and no regression outside noise on
version,data getandworkflow run. Quote all of them before and after, from builds taken in the same session. Use paired, interleaved runs or--runs 15or more: on a busy machine, single 9-run passes moved the controls by up to 40 ms.
Release impact
Same as #4613: each group's modules sit only in their own group's closure, and each group module imports command_routes.ts, so edits to it select every routed group.
Risk
Low. It is the same mechanism as #4613 and #4625.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.