fix(compile): ensure bytecode alignment accounts for section header

[robobun]

Summary

Fixes bytecode alignment in standalone executables to prevent crashes when loading bytecode cache on Windows.

The bytecode offset needs to be aligned such that when loaded at runtime, the bytecode pointer is 128-byte aligned. Previously, alignment was based on arbitrary memory addresses during compilation, which didn't account for the 8-byte section header prepended at runtime. This caused the bytecode to be misaligned, leading to segfaults in JSC::CachedJSValue::decode on Windows.

Root Cause

At runtime, embedded data starts 8 bytes after the PE/Mach-O section virtual address (which is page-aligned, hence 128-byte aligned). For bytecode at offset O to be aligned:

(section_va + 8 + O) % 128 == 0
=> (8 + O) % 128 == 0
=> O % 128 == 120

The previous code used std.mem.alignInSlice() which found aligned addresses based on the compilation buffer's arbitrary address, not accounting for the 8-byte header offset at load time.

Changes

• src/StandaloneModuleGraph.zig: Calculate bytecode offset to satisfy offset % 128 == 120 instead of using alignInSlice
• test/regression/issue/26298.test.ts: Added regression tests for bytecode cache in standalone executables

Test plan

• Added regression test test/regression/issue/26298.test.ts with 3 test cases
• Existing HelloWorldBytecode test passes
• Build succeeds

Fixes #26298

🤖 Generated with Claude Code

[robobun]

^{Updated 8:45 AM PT - Jan 20th, 2026}

❌ Your commit 0b340105 has 2 failures in Build #35405 (All Failures):

• test/cli/hot/watch-many-dirs.test.ts - pid 1551 segmentation fault on 🐧 13 x64
• test/integration/next-pages/test/dev-server.test.ts - 1 failing on 🍎 14 aarch64

---

🧪   To try this PR locally:

bunx bun-pr 26299

That installs a local version of the PR into your bun-26299 executable, so you can run:

bun-26299 --bun

[coderabbitai]

Walkthrough

Replaces the prior 256-byte alignment approach with a padding-based alignment that ensures (current_offset + padding) % 128 == 120 when embedding bytecode into the standalone executable; adds a regression test validating standalone bytecode compilation, execution, multi-module behavior, and disk-cache handling.

Changes

Cohort / File(s)	Summary
Bytecode alignment logic src/StandaloneModuleGraph.zig	Reworked bytecode embedding: compute current_offset, calculate padding so (current_offset + padding) % 128 == 120, advance the string builder by padding, use the aligned offset for the bytecode write, copy bytecode into the writable region, compute unaligned_space and total length, and update the StringPointer offset and builder length.
Regression test suite test/regression/issue/26298.test.ts	Added tests for building/running standalone executables with --compile --bytecode covering single- and multi-module apps and exercising the disk bytecode cache (verbose), asserting stdout/stderr and exit codes; handles Windows .exe.

Possibly related PRs

• fix(compile): use 8-byte header for embedded section to ensure bytecode alignment #25377: Changes bytecode embedding alignment/offset logic and PE/Mach-O header accounting in StandaloneModuleGraph.zig, closely related to the alignment adjustments here.
• feat(build): add --compile-executable-path CLI flag #25934: Wires a new compile_executable_path through to StandaloneModuleGraph.toExecutable, touching the standalone executable generation path impacted by these bytecode layout changes.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'fix(compile): ensure bytecode alignment accounts for section header' clearly and specifically summarizes the main change: fixing bytecode alignment by accounting for the section header.
Description check	✅ Passed	The PR description comprehensively covers both required template sections: it explains what the PR does (fixes bytecode alignment issue) and how it was verified (regression tests added, existing tests pass, build succeeds).
Linked Issues check	✅ Passed	Code changes fully address issue #26298 requirements: bytecode offset now calculated to satisfy (offset % 128 == 120) for proper alignment accounting for the 8-byte header, preventing segfaults on Windows.
Out of Scope Changes check	✅ Passed	All changes are directly in-scope: StandaloneModuleGraph.zig implements the alignment fix and regression test adds validation for bytecode cache behavior in standalone executables as required.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@test/regression/issue/26298.test.ts`:
- Around line 34-41: The variable buildStdout captured from Promise.all is
unused; update the destructuring to either omit it (e.g., const [, buildStderr,
buildExitCode] = await Promise.all([...]) or destructure only build.stderr and
build.exited) or rename it to _buildStdout to mark it intentionally unused;
apply the same change to the other similar destructuring block that collects
build.stdout, build.stderr, build.exited so there are no unused variable
warnings.

[robobun]

Fixed the unused variable warning by changing const [buildStdout, buildStderr, buildExitCode] to const [, buildStderr, buildExitCode] in both test cases.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@test/regression/issue/26298.test.ts`:
- Around line 138-141: The test depends on an exact internal JSC diagnostic
string ("[Disk Cache] Cache hit for sourceCode") which is brittle; update the
assertion around exeStderr in test/regression/issue/26298.test.ts to be
resilient: either replace the strict toContain check with a relaxed check (e.g.,
assert that exeStderr contains "Disk Cache" or matches a regex like /Disk
Cache.*Cache hit/), or convert it to an optional/non-fatal verification (log a
warning instead of failing) and add a short comment near the expect for future
maintainers explaining the dependency on an internal JSC message; keep the
existing checks on exeStdout and exeExitCode unchanged (exeStdout, exeExitCode).

[robobun]

Updated the disk cache assertion to use a more flexible regex pattern (/\[Disk Cache\].*Cache hit/i) instead of the exact string match. This makes the test more resilient to potential changes in JSC's diagnostic format while still verifying that the bytecode cache is being used.

[coderabbitai]

Actionable comments posted: 1

[robobun]

Addressed the review comment about platform-specific alignment:

• Added comprehensive documentation explaining how the alignment works on each platform:

  • PE (Windows) / Mach-O (macOS): Data is memory-mapped 8 bytes after a page-aligned section start
  • ELF (Linux): Data is read into a heap-allocated buffer with natural alignment

• Changed the magic number 120 to 128 - @sizeOf(u64) to make the relationship to the 8-byte header explicit

• Explained why the target_mod=120 strategy works safely for all platforms (it's the worst-case offset needed for the 8-byte header scenario)

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@test/regression/issue/26298.test.ts`:
- Around line 114-145: The test currently runs the Bun.spawn build (variable
build) but doesn't assert its stdout/stderr or exit code before running the
produced executable; capture the build outputs (await Promise.all for
build.stdout.text(), build.stderr.text(), and build.exited or await build.exited
then read streams) and add assertions that the build exit code is 0 and
optionally that build.stderr is empty or contains expected messages, referencing
the existing Bun.spawn call that creates build and the outfile variable so
failures during the build are diagnosed before running exe.

[robobun]

Added build step assertions to the third test case - now captures and validates that build stderr is empty and exit code is 0 before running the produced executable, matching the pattern used in the other two tests.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/StandaloneModuleGraph.zig`:
- Around line 432-472: The code advances string_builder.len by padding without
writing bytes, which can leave uninitialized data in the embedded blob; before
bumping string_builder.len use the string_builder.writable() slice at the
current offset (or writable[0..padding] relative to current writable) and memset
or fill it with zeros (or write zero bytes) to ensure deterministic
output—adjust the logic around computing padding and before setting
string_builder.len and aligned_offset (symbols: target_mod, padding,
string_builder.len, writable, aligned_offset) so the padding region is
explicitly zeroed.

[robobun]

Fixed the uninitialized padding bytes issue - now explicitly zeroing the padding region with @memset(writable[0..padding], 0) before advancing string_builder.len. This ensures deterministic output in the embedded blob.