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 costworkflow run: 467 → 419 msdata get: 331 → 287 msversion: 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/windowscontainer. - Binaries. Cross-compile from Linux with
compile.ts --bundleat 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 runx86_64-apple-darwinunder Rosetta. On Windows, testx86_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
--jsonmode: the stack namessrc\…ts/src/…tsfiles 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 claudeinstalls 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.
- an internal error in log and
Only after this passes does the default flip go up for merge.
2. Scope
- Make bundling the default in
scripts/compile.ts. Keep--no-bundleas the fallback until one Deno version bump has shipped bundled, then delete it; a build path nobody uses goes stale. release.ymlkeeps callingscripts/compile.tsand 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.jsonfrom 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, warmversionis 115 ms instead of 139 ms. Stack-frame paths do work (the unscoped-write diagnostic anderror_output.tsdepend 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 readerror.constructor.name. - Update
contributing/and the verification conventions for the new default build. Adddeno run bench-startupanddeno 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/windowsVM, 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-uatrun 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-paritypasses between--no-bundleand the default build of the same commit.- The PR has
deno run bench-startupnumbers 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.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.