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

Relationships

#4637 Lazy loading L7: ship the bundled build (bundled by default, tested on macOS and Windows first)

Opened by zack · 11/11/2026· Shipped 11/11/2026

This is the last step of the bundling track in the lazy command loading plan. Its prerequisites have merged: the opt-in bundled build (#4624), the resource anchor (#4611), and the benchmark and parity scripts (#4590). Routing has merged too (#4592, #4613, #4625), so the build shipped here has routing in it.

Why

This is what the bundling work was for. #4624 measured the bundled build against the unbundled one on Linux x86_64, warm, median of 5:

  • --help: 559 → 410 ms, which wins back the help speed the route table cost
  • workflow run: 467 → 419 ms
  • data get: 331 → 287 ms
  • version: 175 → 139 ms

Peak memory falls on every command, and each target binary is about 4 MiB smaller even with the source maps included.

1. Test on macOS and Windows first

Do this before the default flip merges. #4624 tested the bundled build on Linux only: it cross-compiled every target but ran none of them on macOS or Windows. The bundler is a newer Deno feature, and its output has not run on those platforms yet. Things that differ there and depend on the bundle's layout include path separators in source-map sources and stack frames, the embedded file tree that the #4611 anchor walks, and the helper entries started as child processes.

This runs on machines we already have, not in swamp-uat's CI workflows. Those accept only a release version, and #4624 left open how a PR-built binary could reach them.

  • Machines. A macOS machine we have access to, and a Windows VM running in the dockurr/windows container.
  • Binaries. Cross-compile from Linux with compile.ts --bundle at this PR's commit, and also build the unbundled binary of the same commit for comparison. On macOS, test the binary for the machine's architecture. If the machine is Apple Silicon, also run x86_64-apple-darwin under Rosetta. On Windows, test x86_64-pc-windows-msvc.
  • swamp-uat. On each machine, run the swamp-uat CLI suite locally against the bundled binary (SWAMP_BINARY_PATH), and again against the unbundled one. Any failure that only the bundled build has gets fixed before the PR goes up. A failure in both builds is not caused by this change, but list it in the PR.
  • By hand, on both machines, unless the suite is shown to cover these:
    • an internal error in log and --json mode: the stack names src\…ts / src/…ts files and lines, the same as the unbundled build on that platform;
    • the unscoped-write diagnostic names the same caller file as the unbundled build;
    • repo init --tool claude installs the same skill files;
    • a local extension model bundles through the embedded Deno and runs;
    • the helper roles start: bundle probe host, telemetry sender, dispatch runner, Litestream supervisor;
    • the dashboard serves its assets.

Only after this passes does the default flip go up for merge.

2. Scope

  • Make bundling the default in scripts/compile.ts. Keep --no-bundle as the fallback until one Deno version bump has shipped bundled, then delete it; a build path nobody uses goes stale.
  • release.yml keeps calling scripts/compile.ts and so gets the bundled build. Check that none of its five invocations passes a flag that conflicts with bundling.
  • Re-baseline scripts/binary_size_limits.json from the bundled sizes, with the source maps that ship.
  • Decide on the source-map cost. #4624 found that the maps cost about 18 MiB of memory and 16–24 ms at startup, and make the binary about 21 MiB bigger. Without maps and --keep-names, warm version is 115 ms instead of 139 ms. Stack-frame paths do work (the unscoped-write diagnostic and error_output.ts depend on them), so the maps stay unless there is a replacement. Find out whether Deno can load the maps lazily, and note what you found in the PR. Keep --keep-names: telemetry and serve read error.constructor.name.
  • Update contributing/ and the verification conventions for the new default build. Add deno run bench-startup and deno run cli-parity (unbundled vs bundled) to the Deno-upgrade steps, because how the bundler behaves depends on the version pinned in .tool-versions.

Not in scope

The lazy startup refactors, and routing for the remaining groups. Both come after this.

Acceptance

  • Before merge, the swamp-uat CLI suite has run against this PR's bundled binaries on the macOS machine and in the dockurr/windows VM, and no failure is unique to the bundled build (section 1). For each platform, the PR lists the binary's architecture, the pass and fail counts for both builds, and every failure that only the bundled build had.
  • A full credentialed swamp-uat run against the bundled Linux binary passes before merge. The #4624 run was local and had no credentials, so 107 auth-gated tests could not be checked.
  • deno run cli-parity passes between --no-bundle and the default build of the same commit.
  • The PR has deno run bench-startup numbers for the old default and the new one. They match #4624's bundled numbers within noise, or the PR says why not.
  • The hand checks from section 1 are listed in the PR, with their results for each platform.
  • Rolling back is a one-line flip of the default.

Review gate

agent-constraints/ is a trust root, so this PR triggers claude-review-integrity.

Release impact

Edits scripts/compile.ts, so the attestation selects every command and the release UAT runs everything. From this release on, every target ships the bundled build. If a bundling problem gets past the gate above, it blocks promotion of every later release until the default is flipped back.

Risk

Medium. Running macOS and Windows first, the full Linux run, and the --no-bundle fallback keep it contained.

Size

½ day for the flip. Add a suite run and the hand checks on the macOS machine and in the Windows VM, plus the full Linux run.

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

Shipped

11/11/2026, 6:06:16 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/11/2026, 2:17:38 PM

Sign in to post a ripple.