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

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's runStampedBuild, the order is: stamp, bundle, compile, restore. The bundle step goes inside build, after the stamp, so the bundle carries the stamped VERSION and GIT_SHA from src/infrastructure/runtime/build_info.ts.
    1. deno bundle --platform deno --format esm --code-splitting --outdir <dir>. Every npm package is external. Derive the list from deno.json's npm: imports at build time rather than hard-coding it; a missed package fails the bundle (emojilib and ink's optional react-devtools-core do not resolve).
    2. deno compile of the bundle entry, with today's flags: the individual --allow-* permissions, --unstable-bundle, --unstable-net, --exclude-unused-npm, and the same --include and --exclude lists.
  • <dir> is a git-ignored directory inside the repo (for example build/bundle/; add it to .gitignore). Inside the repo, deno.json and 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 --exclude entry covers it.
  • Cleanup goes through restoreBuildState. Extend it to remove <dir> alongside resources/deno, each in its own finally and 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.ts finds the caller of an unscoped write by matching frame paths against src/infrastructure/persistence/, and error_output.ts filters stack lines. On Deno 2.9.8 a compiled binary applies a map that is --sourcemap=inline, or --sourcemap=linked with the .map files 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 carry sourcesContent, so they add to the binary.
  • The bundling step stays in scripts/compile.ts, not a new script: an edit to compile.ts selects every command for UAT, and a new file under scripts/ 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-parity passes between the unbundled and bundled builds of the same commit.
  • deno run bench-startup numbers for both builds, taken with the source maps that will ship, are in the PR.
  • A swamp-uat run 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), and main.ts imports the first two statically. deno bundle 2.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 --json mode: 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.ts unchanged and removes <dir> and resources/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.

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

Shipped

11/11/2026, 1:21:42 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/10/2026, 10:54:56 PM

Sign in to post a ripple.