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

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.ts builds behavior (alias behaviour) from the shared createModel*Command(syntax) factories. It is flat: run, describe and history sit directly under the group.
  • createModelCommand(syntax, children) in src/cli/commands/model_create.ts builds model from the same factories, with run, describe and history under a method subgroup (createModelMethodCommand).
  • src/cli/behavior_twin.ts maps 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 model group header out of model_create.ts into its own module (for example src/cli/commands/model.ts), so model_create.ts holds only the create subcommand. Point the root route's module and load at the new file. Keep recordDefiningModule(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 literal import() of the factory, called with the surface's syntax so every load builds a fresh instance. From it:
    • behavior routes the shared rows plus run, describe and history at the top level;
    • model routes the shared rows plus method;
    • model method routes run, describe and history with the same mechanism, so model method run loads only run, as behavior run does.
  • Header factories, as in #4613: createBehaviorCommand(rest) and createModelCommand(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. search is also list in both spellings (model list resolves to model search today; hidden_aliases_test.ts covers it). Without the alias in the table, list would 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.ts stays import-free. Add a fitness rule that its word lists agree with the route tables: METHOD_LEVEL_WORDS equals both behavior's top-level method rows and the model method table, and BEHAVIOR_GROUP_WORDS equals the root behavior route's name and aliases.
  • rewriteDirectTypeArgs (arg_rewriter.ts) moves @type after run before routing runs. Add a test that a rewritten argv (model @type method run …) still selects model → method → run.
  • Module-level instances (behaviorCommand, behaviorRunCommand, modelCommand, and the model*Command instances passed as children) 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 the behavior_*_test.ts / model_*_test.ts files under src/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, model and model method;
    • every subcommand alias appears in its table;
    • schema parity and the per-route Worker test cover every subcommand path in both spellings;
    • the composition-root guard names the new tables.
  • integration/json_mode_conformance_test.ts reads recordDefiningModule. Moving the model header changes the defining module of the model group; 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-parity passes against the base binary. It covers both spellings' help and schema, help behavior … and help model …, and a mistyped subcommand in behavior, model and model method.
  • behavior run / model method run behaviour is unchanged, including @type invocations.
  • deno run bench-startup shows the gain for behavior run and no workflow run regression, both quoted before and after from builds taken in the same session.
  • affectedCommands produced by the attestation generator is unchanged on a sample of changes, compared with the base commit. Both group tables link the shared factories through literal import(), so an edit to one factory still selects both behavior and model.

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.

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

Shipped

11/11/2026, 12:09:20 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/10/2026, 10:54:48 PM
Editable. Press Enter to edit.

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.