Relationships
#4624 Lazy loading L6: opt-in bundled build (compile.ts --bundle)
Opened by zack · 11/10/2026· Shipped 11/11/2026
Next step of the bundling track in the lazy command loading plan. Its prerequisites have merged: the resource anchor (#4611), the build constants move (#4591), and the benchmark and parity scripts (#4590). Routing (#4592, #4613) has merged too, so this build is verified with routing in place.
Why
Measured on a prototype, bundling together with argv routing takes swamp version from 384 to ~111 ms, data get from 416 to ~132 ms, workflow run from 498 to ~358 ms and --help from 391 to ~377 ms (back below today after the route table made it slower), cuts peak RSS by 25–50%, and makes the binary about 29 MiB smaller. Routing alone leaves every module behind import(), which misses Deno's code cache; bundling removes most of that per-module cost.
This issue adds the bundled build without making it the default, so it can be verified while releases are unaffected. Making it the default is the next issue.
Scope
scripts/compile.ts --bundle. Inside today'srunStampedBuild, the order is: stamp, bundle, compile, restore. The bundle step goes insidebuild, after the stamp, so the bundle carries the stampedVERSIONandGIT_SHAfromsrc/infrastructure/runtime/build_info.ts.deno bundle --platform deno --format esm --code-splitting --outdir <dir>. Every npm package is external. Derive the list fromdeno.json'snpm:imports at build time rather than hard-coding it; a missed package fails the bundle (emojilib and ink's optionalreact-devtools-coredo not resolve).deno compileof the bundle entry, with today's flags: the individual--allow-*permissions,--unstable-bundle,--unstable-net,--exclude-unused-npm, and the same--includeand--excludelists.
<dir>is a git-ignored directory inside the repo (for examplebuild/bundle/; add it to.gitignore). Inside the repo,deno.jsonand the lockfile resolve the npm externals, the embedded file tree keeps the repo root as its root (which the #4611 anchor and the source-map paths rely on), and nothing else needs to move. Check that no--excludeentry covers it.- Cleanup goes through
restoreBuildState. Extend it to remove<dir>alongsideresources/deno, each in its ownfinallyand each tolerating a missing directory, so a failed bundle or a failed compile still restores the version stamp and leaves no bundle output behind. Extend its unit tests: a failing bundle step and a failing compile step both restore the stamp and remove both directories. - Ship source maps. Stack-frame paths are functional, not cosmetic:
unit_of_work_scope.tsfinds the caller of an unscoped write by matching frame paths againstsrc/infrastructure/persistence/, anderror_output.tsfilters stack lines. On Deno 2.9.8 a compiled binary applies a map that is--sourcemap=inline, or--sourcemap=linkedwith the.mapfiles passed to--include; a linked map that is not included is ignored. Prefer linked and included, so the maps stay out of the JavaScript the engine loads. The maps carrysourcesContent, so they add to the binary. - The bundling step stays in
scripts/compile.ts, not a new script: an edit tocompile.tsselects every command for UAT, and a new file underscripts/would select none, so later edits to the bundling step would ship without UAT selection. - Without
--bundle, the build is unchanged.
Not in scope
Changing what releases ship, re-baselining scripts/binary_size_limits.json, and a standing CI job for the bundled variant. The next issue makes the bundled build the default, which is the build CI already runs.
Acceptance
- All five release targets cross-compile from Linux with
--bundle. The PR lists each size with source maps, next to the unbundled size. deno run cli-paritypasses between the unbundled and bundled builds of the same commit.deno run bench-startupnumbers for both builds, taken with the source maps that will ship, are in the PR.- A
swamp-uatrun against the bundled Linux binary (SWAMP_BINARY_PATH) passes. - Checked by hand and noted in the PR, unless the UAT run is shown to cover them:
init --tool claude, and an extension bundle load through the embedded Deno;- the helper entries: dispatch runner, Litestream supervisor, bundle probe host and telemetry sender. Three modules guard a main block with
import.meta.main(replication_supervisor_entry.ts,bundle_probe_host.ts,telemetry_sender_entry.ts), andmain.tsimports the first two statically.deno bundle2.9.8 turns that guard off outside the entry module; this check confirms it; - the dashboard serving its assets, and one Ink screen. The prototype exercised neither;
- an internal error in log and
--jsonmode: the stack names source files and lines, as the unbundled build does; - the unscoped-write diagnostic names the same caller file as the unbundled build.
- A failed bundle leaves
build_info.tsunchanged and removes<dir>andresources/deno. - This PR also settles how a PR-built binary reaches
swamp-uat's macOS and Windows suites (SWAMP_INSTALL_URL, or a release dry run), because making the bundled build the default needs a full run on every target before merge.
Coordination
--code-splitting makes each literal import() in the route tables a chunk boundary, so route changes change the bundle. If the behavior / model group routing lands while this PR is open, rebase onto it before taking the final measurements and the UAT run.
Release impact
Edits scripts/compile.ts, so the attestation selects every command and the release UAT runs everything. Releases still ship the unbundled build.
Risk
Low for main, since it's opt-in. The bundler itself is a newer Deno feature; the full UAT cycle on the next issue is what contains that risk.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.