Relationships
#4625 Lazy loading L4: load only the invoked subcommand in behavior and model
Opened by zack · 11/10/2026· Shipped 11/11/2026
Next step of the routing track in the lazy command loading plan. It applies the group routing pattern from #4613 (data, workflow) to behavior and model, and uses the benchmark and parity scripts from #4590.
Why
behavior / model is the heaviest group after workflow (282–286 ms standalone under deno run, measured on a prototype), and the one most likely to be invoked. After #4592, swamp behavior run loads only the behavior group, but still loads every one of its 14 subcommands. model is worse: its group is built inside model_create.ts, so the root route for model loads the create subcommand's module and, through it, every other model subcommand.
How the two spellings are built today
src/cli/commands/behavior.tsbuildsbehavior(aliasbehaviour) from the sharedcreateModel*Command(syntax)factories. It is flat:run,describeandhistorysit directly under the group.createModelCommand(syntax, children)insrc/cli/commands/model_create.tsbuildsmodelfrom the same factories, withrun,describeandhistoryunder amethodsubgroup (createModelMethodCommand).src/cli/behavior_twin.tsmaps between the two paths ([behavior, run]↔[model, method, run]) with word lists only (BEHAVIOR_GROUP_WORDS,METHOD_LEVEL_WORDS) and no imports, so telemetry and the auth gate can use it without the command factories.- Cliffy re-parents a command attached under a second parent, so the two surfaces must never share an instance; each factory call builds a fresh one.
Scope
- Move the
modelgroup header out ofmodel_create.tsinto its own module (for examplesrc/cli/commands/model.ts), somodel_create.tsholds only thecreatesubcommand. Point the root route'smoduleandloadat the new file. KeeprecordDefiningModule(command, import.meta.url)on the moved header; the #4611 rule allows that call by pattern in any file. - One subcommand route table shared by both spellings. Each row has the word, its aliases, its
module, and a literalimport()of the factory, called with the surface'ssyntaxso every load builds a fresh instance. From it:behaviorroutes the shared rows plusrun,describeandhistoryat the top level;modelroutes the shared rows plusmethod;model methodroutesrun,describeandhistorywith the same mechanism, somodel method runloads onlyrun, asbehavior rundoes.
- Header factories, as in #4613:
createBehaviorCommand(rest)andcreateModelCommand(syntax, rest)(or equivalent). An unknown or missing subcommand word loads the whole group, so group help and the unknown-subcommand suggestion list see what they see today. - Subcommand aliases go in the table.
searchis alsolistin both spellings (model listresolves tomodel searchtoday;hidden_aliases_test.tscovers it). Without the alias in the table,listwould load the whole group. Third-level aliases (model output search→list,model method history search→list) stay with the subcommand that owns them. behavior_twin.tsstays import-free. Add a fitness rule that its word lists agree with the route tables:METHOD_LEVEL_WORDSequals bothbehavior's top-level method rows and themodel methodtable, andBEHAVIOR_GROUP_WORDSequals the rootbehaviorroute's name and aliases.rewriteDirectTypeArgs(arg_rewriter.ts) moves@typeafterrunbefore routing runs. Add a test that a rewritten argv (model @type method run …) still selectsmodel→method→run.- Module-level instances (
behaviorCommand,behaviorRunCommand,modelCommand, and themodel*Commandinstances passed aschildren) stop being what the CLI builds from. Update their users to call the factories:root_routes.ts,integration/usecase_sync_fixtures.ts,integration/behavior_parity_test.ts,integration/behavior_run_parity_test.ts,integration/ephemeral_output_retrieval_test.ts, and thebehavior_*_test.ts/model_*_test.tsfiles undersrc/cli/commands/that import them. - The spelling tests (
integration/behavior_root_spelling_test.ts,behavior_flag_spelling_test.ts,behavior_spelling_client_test.ts) keep passing unchanged. - Extend the route rules from #4592 and #4613:
- each table equals its fully loaded children (names, aliases, hidden, order), for
behavior,modelandmodel method; - every subcommand alias appears in its table;
- schema parity and the per-route
Workertest cover every subcommand path in both spellings; - the composition-root guard names the new tables.
- each table equals its fully loaded children (names, aliases, hidden, order), for
integration/json_mode_conformance_test.tsreadsrecordDefiningModule. Moving themodelheader changes the defining module of themodelgroup; update any expectation keyed on it, without weakening the check.
Not in scope
The remaining groups (extension, vault, datastore, report, serve, access, dashboard, worker); whether they are worth routing is decided after the bundled build ships.
Acceptance
deno run cli-paritypasses against the base binary. It covers both spellings' help and schema,help behavior …andhelp model …, and a mistyped subcommand inbehavior,modelandmodel method.behavior run/model method runbehaviour is unchanged, including@typeinvocations.deno run bench-startupshows the gain forbehavior runand noworkflow runregression, both quoted before and after from builds taken in the same session.affectedCommandsproduced by the attestation generator is unchanged on a sample of changes, compared with the base commit. Both group tables link the shared factories through literalimport(), so an edit to one factory still selects bothbehaviorandmodel.
Coordination
If the opt-in bundled build (#4624) is open when this merges, it rebases onto this before taking its final measurements: each new literal import() is a chunk boundary under --code-splitting.
Release impact
The changed files sit in the behavior / model closures, so the attestation selects those two commands.
Risk
Medium-low. The shared table across two surfaces and the moved model header are the unusual parts; the fresh-instance rule, the twin agreement rule and the unchanged spelling tests guard them.
Shipped
Click a lifecycle step above to view its details.
zack commented 11/10/2026, 11:39:05 PM
Correction to the verification_failed entry just recorded: it names commit 07c79686e473b809..., a typo. The commit that failed verification is [REDACTED-SECRET-1] (verify-build 1c4f174e, verify-reviews 74ce6bee).
Sign in to post a ripple.