Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

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.ts table. The header keeps its description, unknownCommandErrorHandler and groupCommandAction. The root rows pass rest.
  • Inline subgroups move to their own modules, so a table row can import them:
    • vault type;
    • datastore type, catalog, namespace and config. config migrate is a child of config, not of datastore: the prototype's generator got this wrong, and parity caught it as an extra datastore migrate command;
    • access token, which becomes a nested routed subgroup (createAccessTokenCommand(rest) with its own table), like model method in #4625. The access token list figure above was measured with nested routing.
  • Users of the old instances. extensionCommand, vaultCommand, datastoreCommand and accessCommand stop being module-level instances. Update their users (tests under src/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. Its reload, check-config and daemon subcommands live in serve.ts together with the roughly 7,000-line serve action 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-config 245 ms warm against version 152 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, and access 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 get and workflow run. Quote all of them before and after, from builds taken in the same session. Use paired, interleaved runs or --runs 15 or 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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 8 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/11/2026, 7:44:51 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/11/2026, 5:36:10 PM

Sign in to post a ripple.