Tooling

Bun

The repo pins Bun 1.4.3. The pin entered the 1.4.x line at 1.4.0, the release that made the Rust runtime rewrite generally available; before that it tracked the canary channel for the three months 1.3.14 spent as the newest stable. That is over, and nothing here floats any more.

Install it with bun upgrade, or curl -fsSL https://bun.sh/install | bash from cold.

bun-types is pinned to 1.4.3 through the root override while the @types/bun wrapper remains at its latest published version, 1.4.2. Remove that override when the wrapper publishes 1.4.3 and the workspace dependency ranges can move with it.

Two fields name the same toolchain, for two different consumers

Two consumers, one answer, and they must now agree — scripts/tests/bun-toolchain.unit.test.ts fails if one is bumped without the other. They were allowed to disagree under canary because their requirements were mutually exclusive there:

• setup-bun resolves release tags, and Bun published exactly one canary tag — the literal canary, rebuilt per commit on main. There was no bun-v1.4.0-canary.1 tag to point at, so the installed build could only be named canary.
• Turborepo parses packageManager as semver or a URL and refuses to resolve the workspace at all against bun@canary. It needs a version-shaped string.

.bun-version remains the single source of truth for which Bun. Only it is ever installed; packageManager is a floor Turborepo reads and nothing else.

What the canary period left behind

Two habits are worth keeping, because they cost nothing and a released pin is not guaranteed to be permanent:

• Install-cache keys use bun --revision, not bun --version. --version is unique per release and would work today; --revision appends the commit (1.4.3+c6da4a4d3) and stays correct for a rebuilt tag or a channel too. A key on --version was what handed one canary build’s extracted packages to a different one.
• The distribution manifest records bunRevision alongside bunVersion. Bun.version reports 1.4.3; Bun.revision names the commit that built it. Note the two spellings differ — bun --revision prints 1.4.3+c6da4a4d3 while the JS Bun.revision returns the full 40-character sha, and they do not compare equal.

One mechanism is now dormant, not deleted: scripts/lib/bun-cross-runtime.ts. bun build --compile builds a foreign-platform binary by downloading a prebuilt Bun and resolving it from Bun.version; on canary that asked for an unreleased tag and every non-host target failed. The module fetched the channel asset per target and passed it to --compile-executable-path. Against a released pin bunCrossCompileChannel() returns null, --compile resolves bun-v1.4.3 itself, and none of that runs. Moving .bun-version back to a channel is the whole switch.

Because it is dormant, the two lanes that verified it are gone — cross-runtimes in ci.yml and cross-runtime-nightly.yml both existed to catch a stalled download from a channel that moved daily, and against a pin they spend a runner to assert nothing. scripts/ci/verify-cross-runtimes.ts is kept and still runs by hand; restoring the lanes, with their five-minute bound, is part of moving back to a channel rather than a separate change. The bound is the feature there: the failure mode is a stall, not an assertion.

To bisect a suspected Bun regression, move .bun-version and packageManager together to another released tag (1.3.14) on a scratch branch — that is all it takes, and no assertion has to be flipped. Going back to a channel does need two flips in scripts/tests/bun-toolchain.unit.test.ts: the two-fields-agree test, and the one asserting bunCrossCompileChannel() is null. They are the tripwires that say the pin is still in place.

TypeScript 7

The monorepo type-checks with TypeScript 7, the native Go port. TS 7 ships a single tsc binary that parallelizes parsing, type-checking, and emitting across cores, typically 8–12x faster than TS 6 on full builds.

Type-checking

Each workspace runs tsc --noEmit (pinned to 7.0.2) via its typecheck script. Turbo starts these across workspaces together, and each tsc invocation further parallelizes internally — the two layers compose without conflict. Nothing waits for an upstream workspace: tsc reads sources and writes no output, so the order between workspaces carries no data. What a downstream workspace needs from upstream is the cache key, which the script-less transit task supplies (see the task table below).

Do not list the upstream typechecks under with in a workspace turbo.json to keep them in a filtered run. Turbo stops a with task when the task that lists it exits, so a slower workspace’s type error is lost and its cache entry is never written. typecheck:with-deps selects them instead.

Parallelization tuning

TS 7 exposes experimental flags for fine-tuning parallelism:

The defaults are left in place; the monorepo is small enough that --checkers 4 is the sweet spot. If CI runners run low on memory, set --checkers 2 or --checkers 1 in the workspace typecheck scripts.

Compatibility API

TS 7.0 does not expose a stable programmatic API. The QA-gate coverage scripts (scripts/qa-gate/source-*-coverage.ts) import the compiler API from @typescript/typescript6 (pinned to 6.0.2), the official side-by-side compatibility package. When TS 7.1 ships a new API, the compat dependency can be removed.

Turborepo

This monorepo uses Turborepo 2.x (currently 2.11.7) as its shared build-system layer. Turborepo orchestrates task execution across workspaces and provides a content-addressable cache so that unchanged work is never rebuilt.

Policy

• Stable 2.x only. The pinned version in the root package.json is the single source of truth. No canary builds, no floating ranges.
• No Remote Cache yet. Local cache only until the task model is proven.
• Root Bun wrappers are the public interface. bun run dev, bun run build, bun run check, and bun run test remain the canonical commands. Turborepo is invoked through them or via the turbo:* inspection scripts.

Configuration

The task graph lives in turbo.jsonc at the repository root. The .jsonc extension is used so that inline comments can document migration decisions.

Current task definitions:

Inspection Scripts

Cache Directory

Turborepo writes its local task-output cache to .turbo/cache at the repository root. This directory is gitignored and should never be committed.

Linked worktrees share the main checkout’s cache by default. Set TURBO_CACHE_DIR=.turbo/cache when a worktree needs its own cache, including when comparing cached and uncached QA collection.

CI persists the local Turbo cache through the shared cache-scoped composite. Check, test and build keep separate lane validity and write scopes. Successful runs save a rotated snapshot only when Turbo writes new *.tar.zst payloads; the run ID and attempt distinguish each save, while a run that only hits saves nothing. Pull requests restore their own earlier snapshots and trusted main entries; main never restores a pull request’s cache.

CI_CACHE_EPOCH is the repository-wide emergency invalidation variable, with a v1 fallback. The key policy, restore order, retention and invalidators are specified in CI Cache Policy.

The check lane has no separate TypeScript build-info cache. incremental is off in every tsconfig, so tsc leaves no build info behind to cache, and TypeScript 7.0.2 reports TS2589 when it reads one produced from different sources (scripts/tests/typescript-incremental.unit.test.ts). The Turbo cache is the only typecheck cache.

Future Work

• Remote Cache for CI.
• --affected filtering in CI pipelines.
• Package-specific Turbo configuration once the base graph is stable.

Elysia build-time AOT — evaluated, not adopted

Elysia 2 ships a Bun build plugin (elysia/plugin/aot/bun) that moves handler and validator compilation from process start to build time. It was measured against MangoStudio on 2026-08-13 and not adopted: it is correct here, but it buys nothing this repository can spend.

What was measured

Elysia 2.0.0-beta.4, Bun 1.3.14, linux-x64, ten runs per figure, each under a throwaway HOME and database. Both binaries were produced by the same programmatic Bun.build({ compile }) call from the same source, so the only variable is the plugin.

Reproduce the startup halves with scripts/bench/startup.ts against two binaries; see scripts/README.md.

Why there is nothing to win

Startup is not spent in Elysia. It goes to migrations, opening SQLite, Better Auth initialization, and evaluating a ~111 MB bundle. Route compilation is a small enough slice that removing it entirely stays inside run-to-run noise — which is also why the AOT binary measured marginally slower: it carries a larger manifest to load.

What the evaluation did establish

The plugin is not broken here. Both binaries served a byte-identical OpenAPI document with the same 188 operations, so route and contract parity is not the objection. Three findings are worth keeping:

• The capture step imports the app inside the build process. Anything the app does at import time therefore happens during a build — which is how the eager getDb() defaults in the repository factories were found, and why apps/api/tests/integration/server/app-import-side-effects.integration.test.ts now pins that importing the app opens no database.
• Sealed validators carrying a coercion or codec schema report their 422 field detail coarsely. That is 15 routes — across api-keys, environments, external-agents, git, library, respond, settings, and tool-identities — trading error-message precision for the compile-time win. The plugin only says so under verbose: true, so adopting it without that flag would ship the coarser errors silently.
• scripts/build.ts shells out to the bun build CLI, which has no plugin flag. Adopting AOT means moving binary compilation to programmatic Bun.build({ compile }) for every target — a build-pipeline rewrite that the measurements above do not pay for.

Revisit if Elysia’s own startup share grows, if migrations and bundle evaluation stop dominating, or if a target appears (workerd) where runtime JIT is unavailable rather than merely slower.

Bun.Archive — adopted for reading, rejected for writing

Every archive this repository reads is read in-process by Bun.Archive (scripts/lib/archive.ts). Every archive it writes still shells out to tar or zip. Release asset creation on Windows uses the system’s native bsdtar and PowerShell ZIP support rather than MSYS tar or an external zip utility. Tar commands write a local filename from the output directory, so Windows drive prefixes cannot be interpreted as remote hosts. scripts/lib/archive-creation.ts owns these commands. Native bsdtar on macOS and Windows omits the gzip creation timestamp so identical inputs keep identical compressed bytes; archived file mtimes and modes are preserved. The split is not a staged migration: creation cannot convert until Bun.Archive can store a file mode.

The blocker

Bun.Archive writes every entry 0644 and offers no way to say otherwise. Re-verified on 1.4.2: a mode passed in the options object or per-entry is accepted and ignored, and unknown options are accepted silently, so there is no error to notice. (Per-entry, { data, mode } is worse than ignored — the object itself gets serialized instead of the blob.) A natively created platform archive therefore ships a hub binary that will not run:

• scripts/test-build.ts fails the build on it directly, asserting mode & 0o111 on both binaries in the extracted archive.
• The Homebrew formula does libexec.install Dir["*"] with no chmod, so the mode in the tarball is the mode users get. Its own test do block would fail.
• tar -xzf mangostudio-*.tar.gz && ./mangostudio is a documented install path.
• The npm platform packages are published from an extracted distribution bundle, so a 0644 binary inside that bundle reaches the registry.

scripts/install/install.sh, stage-docker-ctx.ts and bun-cross-runtime.ts all chmod after extracting and would not have noticed.

What the conversion is worth

Measured 2026-08-20 on this machine against a two-binary, 160 MB payload — the shape of a real platform archive:

So the adopted half is worth roughly 1.8× on extraction, and the rejected half — the larger prize, 2.7× on creation with a smaller artifact — stays on the table until upstream stores modes.

Other limits found while probing

All verified against the Bun the repository pins, not inherited from docs:

• gzip and stored tar, both directions. .tar.xz and .tar.bz2 throw Unrecognized archive format where GNU tar auto-detects them. Zip is not readable at all, so the Windows targets and the Bun cross-runtime download keep their unzip/PowerShell/bsdtar subprocesses. Stored tar is detected from the bytes rather than the name, which is what lets the target distribution bundles ship uncompressed. See releasing.md.
• files() is an async method returning Promise<Map<string, File>>, and it omits symlink and directory entries. Anything guarding on that listing sees fewer entries than tar -tzf reports.
• extract() does preserve modes and, on POSIX, in-tree symlinks. It silently strips leading .. segments and drops symlinks pointing outside the destination. On Windows it skips every symlink regardless of privilege (upstream’s documented extract contract). Safety guards still run first, because silent sanitization in a release lane is worse than a named error.
• Passing a lazy Bun.file() handle as an entry value writes a 0-byte entry with no error, and passing one to the constructor throws Unrecognized archive format. Read the bytes first.
• The extension is ignored: Bun.Archive.write('x.tar.gz', files) with no compress option writes an uncompressed tar named .tar.gz.

Revisit when Bun.Archive gains a mode option; archive-assets.ts and bundle-distribution.ts carry the pointer at their creation functions. Upstream tracks it as oven-sh/bun#33212, with an unmerged PR at #33213 — check whether that landed before re-probing the option parser.

Runtime startup budgets

The hub keeps three clocks on a runtime and they are not interchangeable. Provisioning — an image pull, a release download, a WSL install — runs under its own timeouts and finishes before a child is started. The handshake budget bounds one thing: from the launcher returning a process (or a socket dial starting) to the runtime’s hello. Liveness after that is the protocol’s ping/pong. The handshake numbers live in apps/api/src/services/runtime-client/handshake-budget.ts:

A remote budget is its flat number floored at the local one, so no transport that does more than a local spawn gets less time than one. A WSL first provision executes the new binary with --version before it returns, so that first run is paid under provisioning, not here. A connect released while its child is still handshaking terminates the child at once.

What a start costs

scripts/bench/runtime-handshake.ts spawns the runtime over stdio the way the hub does and times each phase. 30 runs each, fresh MANGO_HOME per run, one machine (Intel Xeon E5-2699 v3, 2.30 GHz; Windows 11 Pro 26200 with 36 logical CPUs and 64 GiB, and its WSL2 Linux 6.18 guest with 28 CPUs and 27 GiB), Bun 1.4.2, 2026-09-25. Linux ran this branch’s cargo builds; Windows ran the CI windows-x64 release artifact of the same base (0.1.1-pr.1077.g4be9c25, 38.4 MiB). Milliseconds, as min / median / p95 / max:

“Fresh copy” runs a byte-identical copy at a new path each time, the closest a script gets to the first execution of a just-installed binary; neither mode empties the OS page cache. What it shows:

• On Windows the first-execution cost lands in the spawn, not the handshake. Starting a never-seen file costs ~1.8s inside the launcher’s synchronous spawn call (the antivirus and loader’s first look). The hub’s handshake clock starts after that call returns, so what the budget bounds stayed at ~0.35s. The CI smoke’s elapsedMs (6288ms on windows-x64) includes the spawn; the hub’s budget does not.
• hello is most of a start. The runtime builds its capability manifest — shells, Git, gh, feature flags — before it greets, and that is ~0.3s on both systems here.
• The child says nothing before it answers. No run wrote a stderr byte before its first response, and the wire has no frame ahead of hello. That is why the budget stays a wall clock: a liveness-keyed budget (#1055) needs a pre-hello progress signal from the runtime, which is a protocol change, not a hub change.

Hosted runners

A one-off manual smoke run on a measurement branch ran scripts/bench/runtime-handshake.ts against the release-shaped runtime each binary leg staged, on GitHub’s hosted runners. Run 36219246581, source 46558e95 (release profile with fat LTO), 2026-09-26, Bun 1.4.2, milliseconds as min / median / p95 / max:

• Every runner fits its budget. The slowest warm handshake is macOS x64 (1.39s median, 2.0s max) against the 5s non-Windows budget; Windows tops out at 2.3s (a first run) against 30s.
• macOS spends ~0.6–1.4s before hello (Intel ~1.4s median), Linux ~80ms. The spawn itself is under 3ms on both, so the time is the runtime building its capability manifest (shell, Git and gh probes) before it greets. It is inside budget; making those probes lazy is the lever if it ever matters.
• Windows’ first executions of a binary are the outliers (2.1s to hello, 4.4s to the first answer on windows-x64), then 140–230ms warm. On a hosted runner the fresh-copy cost is ~0.12–0.25s in the spawn, far below the ~1.8s measured on a desktop with a full antivirus scan.

Re-measure on the machine in question before changing a number here, and record the result the same way:

bun run scripts/bench/runtime-handshake.ts target/release/mangostudio-runtime --runs 30
bun run scripts/bench/runtime-handshake.ts <binary> --runs 30 --fresh-copy --build release-ci