Embedded PG: pglite WASM traps — Emscripten SIDE_MODULE dynamic linking not implemented

[acamarata]

Status

Integration — pglite boot has never passed on main (failures back to 2026-05-18, predating the v1.2.5 tag). Embedded Postgres does not boot on any platform. This is a real product defect, not CI flake.

Current failure

pglite exited unexpectedly: error while executing at wasm backtrace:
    0: 0x59fed6 - <wasm function 11139>
    1: 0x2408f9 - <wasm function 3146>
    2: 0x23e95c - <wasm function 3144>
    3: 0x50c033 - <wasm function 9716>
    4: 0x50c1ae - <wasm function 9719>
    5: 0x1c15ff - <wasm function 2534>

Root cause

pglite v0.2.17 is an Emscripten SIDE_MODULE. wasmtime_runtime.go defines the GOT.mem / GOT.func namespace globals but nothing performs the actual dynamic-linking relocation, so they keep their initial values and address computation lands outside linear memory.

Progress so far

• fix(embedded): raise pglite boot bound to fit the job budget #221 fixed a boot deadlock that was masking the real error behind bare test timeouts.
• fix(embedded): initialise __stack_pointer to the top of memory, not 0 #229 initialised __stack_pointer to the top of memory. This moved the failure from a single-frame trap at 0xfffffef0 to a 6-frame deep call stack, i.e. pglite now boots substantially further before trapping.

What a real fix needs

Host-side Emscripten dynamic linking: process the dylink.0 custom section, allocate memory/table segments, apply GOT.mem and GOT.func relocations, and set __memory_base / __table_base / __heap_base before calling __main_argc_argv.

Alternatives worth pricing first:

• ship pglite built as MAIN_MODULE / standalone WASI instead of SIDE_MODULE
• pin a pglite build known to run under wasmtime
• use a runtime with Emscripten dynamic-linking support

Prior work

Unmerged local branches carry earlier attempts: wip/pglite-got, wip/pglite-got-relocation, fix/pglite-trampoline-t11.

Why this issue exists

The four internal/embedded integration tests are being quarantined with t.Skip referencing this issue, so that main can go green for the v1.2.6 patch release. Per the CI/CD-100%-Green doctrine, skipping is only permitted with a linked issue — this is that issue. The skip must be removed as part of fixing this.

[acamarata]

Prior work archived (v1.2.6 cleanup, 2026-08-18)

The unmerged local branches holding earlier attempts at this were archived as tags before branch cleanup. Nothing was lost — recover with git checkout -b <name> <tag>:

Tag	Was
archive/2026-08-18/wip/pglite-got	wip/pglite-got (14 commits)
archive/2026-08-18/wip/pglite-got-relocation	wip/pglite-got-relocation (2 commits)
archive/2026-08-18/fix/pglite-trampoline-t11	fix/pglite-trampoline-t11 (5 commits)

All three are pushed to origin.

Current state

The four integration tests are quarantined via a skip in internal/embedded/integration_test.go (quarantined() in requireWasmPath) that names this issue. Run them with EMBEDDED_PG_WASM_FIXED=1.

Latest failure after #229 is a 6-frame deep call stack, versus the single-frame trap at 0xfffffef0 before it — pglite boots substantially further now, so #229 was real progress rather than a no-op.

Closing this issue requires removing that skip.

[acamarata]

Root cause narrowed to a single, decidable question

Established by parsing the pglite v0.2.17 binary directly rather than inferring from backtraces.

The blocker is the WASI memory export, not the GOT globals

memory imports	env::memory
memory exports	none — 0 of 1672 exports

wasmtime's WASI implementation resolves linear memory via the instance's memory export. pglite has none, so every WASI call traps:

Caused by: missing required memory export

This is inherent to pglite shipping as an Emscripten SIDE_MODULE. No amount of tuning __memory_base / __table_base / __stack_pointer / GOT.mem::* can resolve it.

What the earlier fixes did and did not do

• fix(embedded): raise pglite boot bound to fit the job budget #221 — fixed a boot deadlock that was masking the real error behind bare test timeouts. Real fix.
• fix(embedded): initialise __stack_pointer to the top of memory, not 0 #229 — set __stack_pointer to the top of memory. Real fix; the first-frame prologue no longer underflows.
• fix(embedded): derive __heap_base from the module's dylink.0 section #239 — sets __heap_base from dylink.0 (0x213000 for v0.2.17) instead of 0. Correct, but verified by A/B to change nothing today: forcing it back to 0 produces the identical failure, because boot stops at the WASI memory export before the heap is touched.

So the globals work is now complete and correct, and it is not enough.

The decision

1. Ship pglite as MAIN_MODULE / standalone WASI. It would export memory and the existing host ABI would mostly stand. Requires building or sourcing a different pglite artifact; needs pricing.
2. Replace linker.DefineWasi() with a hand-written WASI shim bound to the imported env::memory. Keeps the current artifact. Scope depends on which WASI calls pglite actually reaches — enumerable from the import section.
3. Drop wasmtime for a runtime with Emscripten dynamic-linking support.

Option 2 is the only one that needs no new artifact, and its cost is measurable up front by listing pglite's WASI imports. Recommend pricing 2 before 1.

Meanwhile

The four integration tests remain quarantined behind EMBEDDED_PG_WASM_FIXED=1, and removing that skip is still the definition of done for this issue.

[acamarata]

Status check 2026-08-26. Not worked this session; recording the blocker precisely so the next person does not re-derive it.

The diagnosis is settled and should not be re-run from backtraces: pglite v0.2.17 imports env::memory and exports zero memories (0 of 1672 exports). wasmtime's WASI binds linear memory through the instance's memory export, so every WASI call traps with missing required memory export. The globals work already done is correct and is not sufficient.

Three options, unchanged:

1. source a MAIN_MODULE/WASI pglite build
2. replace linker.DefineWasi() with a WASI shim bound to the imported memory
3. change runtime

Option 2 needs no new artifact and its cost is measurable up front by listing pglite's actual WASI imports. That pricing exercise is the next concrete step, and it has not been done.

The four integration tests stay quarantined behind EMBEDDED_PG_WASM_FIXED=1. Removing that skip is the definition of done.

[acamarata]

Option 2 priced: smaller than this issue assumes

Measured against the cached artifact at ~/.nself/cache/pglite/0.2.17/pglite.wasm (7.7 MB) with wasm-objdump -x. No guessing, no backtraces.

The diagnosis holds exactly

memory[0] pages: initial=2048 max=32768 <- env.memory
memory exports: 0
total exports:  1672

Memory is imported, never exported, so wasmtime's WASI has nothing to bind to. Confirmed.

The WASI surface is 12 functions, not hundreds

Imports break down as: 113 env, 12 wasi_snapshot_preview1, 1 GOT. The complete WASI list:

Function	Class
proc_exit	trivial
clock_time_get	real, small
environ_get, environ_sizes_get	real, small
fd_close, fd_fdstat_get, fd_pread, fd_pwrite, fd_read, fd_seek, fd_sync, fd_write	real, fd semantics

Nothing in the hard class. No poll_oneoff, no sock_*, no threads. Also no path_open, fd_prestat_get or fd_prestat_dir_name, so pglite never opens a file by path through WASI and never enumerates preopens. The fd surface is effectively stdio plus whatever Emscripten's own FS layer routes through the 113 env symbols.

The stated main risk is already retired

The concern was that a shim bound to imported memory must agree with pglite's allocator and memory growth. That work is already done and shipping: internal/embedded/emscripten_abi.go (585 lines) creates and owns env::memory itself, and its 113 host functions already read and write that exact memory correctly, including emscripten_resize_heap handling growth. A WASI shim would take the same handle by the same mechanism.

So option 2 is one call site: internal/embedded/wasmtime_runtime_boot.go:61 currently does linker.DefineWasi(). Replace it with 12 host functions defined the way the 113 already are.

Estimate

The existing precedent is 585 lines for 113 symbols. The 12 WASI functions carry more real semantics than the average env stub, so budget generously rather than pro rata: roughly 250 to 400 lines plus tests, in one new file next to emscripten_abi.go (mind the 300-line cap, so likely two files).

Remaining risks, in order:

1. fd_seek/fd_pread/fd_pwrite offset and whence semantics must match WASI exactly. Getting these subtly wrong corrupts data silently rather than trapping. Test against a fixture file with known contents.
2. fd_fdstat_get rights/flags must be plausible enough that pglite does not take an unexpected branch.
3. Errno mapping: WASI errnos are not Go's. A wrong errno turns a recoverable condition into a hang.

Options 1 and 3

Option 1 (MAIN_MODULE/WASI build): would remove the problem entirely, but it depends on upstream publishing such an artifact. Worth ten minutes checking the pglite releases before writing any shim, because if one exists it dominates. If it does not, this option means maintaining a custom Emscripten build, which is far more expensive than 12 functions.

Option 3 (change runtime): wazero resolves host memory differently and is a plausible fit, but swapping runtimes rewrites the boot path and revalidates all 113 env symbols that currently work. That is strictly more work than option 2 now that option 2's main risk is gone.

Recommendation: check option 1 for ten minutes, then do option 2. Option 3 only if something unexpected surfaces.

Quarantine intact

quarantined(t) in internal/embedded/integration_test.go:44-49 still gates on EMBEDDED_PG_WASM_FIXED, covering TestEmbeddedPGBootCycle, TestSocketBridgeProxy, TestMigrationRunnerEmbedded, TestColdStartBudget. Not touched. Removing that skip remains the definition of done.

[acamarata]

Option 1 checked and ruled out. Upgrading does not fix this either.

I said option 1 was worth ten minutes before writing any shim. I spent them. Result: option 1 does not exist, and neither does the "just upgrade" shortcut.

Upstream is now at @electric-sql/pglite@0.5.8; this repo pins 0.2.17. I pulled 0.5.8 from npm and ran the same wasm-objdump inspection:

0.5.8   memory[0] pages: initial=2048 max=32768 <- env.memory
        memory exports: 0

Identical shape. Memory is still imported, still never exported, three minor versions later. The published artifact is consistently Emscripten SIDE_MODULE-shaped, so there is no MAIN_MODULE/WASI build to source and upgrading pglite would not have helped.

The WASI surface is stable, which is good news

	0.2.17	0.5.8
wasi_snapshot_preview1 imports	12	13
env imports	113	122
memory exports	0	0

The only new WASI function across that whole range is random_get, which is in the trivial class. So the shim you write against 0.2.17 stays valid if you later upgrade, plus one easy function.

The env count moving 113 to 122 is worth noting separately: those nine are the existing emscripten_abi.go's problem, not the WASI shim's, and they are the reason a pglite upgrade is its own piece of work rather than a free ride.

Conclusion

Option 1 is dead. Option 3 remains strictly more work than option 2 now that option 2's memory-binding risk is retired by the existing emscripten_abi.go. Do option 2: 12 host functions (13 if you upgrade first), roughly 250 to 400 lines plus tests, replacing the single linker.DefineWasi() at internal/embedded/wasmtime_runtime_boot.go:61.

Method for anyone re-checking: wasm-objdump -x -j Import <pglite.wasm> and -j Export, against ~/.nself/cache/pglite/<version>/pglite.wasm.

[acamarata]

Not attempted this pass. Recording why, so the next person does not re-derive the estimate.

The analysis in this issue still holds and I did not find anything that changes it:

• pglite imports memory as env.memory and exports 0 memories of 1672
• only 12 WASI imports, none hard — no path_open, no poll_oneoff, no sockets, no threads
• internal/embedded/emscripten_abi.go already creates and owns env::memory for its 113 env symbols, so the main risk is already retired
• upgrading does not help; pglite 0.5.8 has the identical shape
• scope is ~250–400 lines replacing the single linker.DefineWasi() at internal/embedded/wasmtime_runtime_boot.go:61

Definition of done stays: remove the EMBEDDED_PG_WASM_FIXED=1 quarantine on the four tests in internal/embedded/integration_test.go. If those four do not go green unquarantined, it is not done.

Why not now: this is the only remaining item that is a feature implementation rather than a broken gate, and the machine running this work is at 94% swap with 13 concurrent agent processes, so it is not a safe place to start a multi-hour WASI linker rewrite. Everything else in the phase is finished; this is the one deliberate omission.

One thing that did land nearby and is worth knowing: internal/embedded/dylink.go now parses the dylink.0 section (pglite v0.2.17 → memorysize 2172900, align 2^12, heapBase 0x213000), so the metadata side is done.

[acamarata]

Update 2026-08-31 (P6-E11-W2-S1-T5)

Progress on the originally diagnosed blocker, plus a newly discovered downstream one.

Fixed: wasmtime's linker.DefineWasi() resolves guest memory via the instance's exported memory. pglite v0.2.17 is an Emscripten SIDE_MODULE — it imports env::memory (created host-side in emscripten_abi_globals.go) and exports nothing named memory. Every WASI call therefore trapped with missing required memory export on its first invocation.

Replaced linker.DefineWasi() entirely with a from-scratch WASI preview1 shim (internal/embedded/pg_wasi.go) bound directly to the host-owned env::memory object. Confirmed via wasmtime.Module.Imports() that pglite v0.2.17 imports only 12 wasi_snapshot_preview1 functions, not the ~40-function full surface: clock_time_get, environ_get, environ_sizes_get, fd_close, fd_fdstat_get, fd_pread, fd_pwrite, fd_read, fd_seek, fd_sync, fd_write, proc_exit. Notably absent: path_open, fd_prestat_get, fd_prestat_dir_name, args_get/args_sizes_get, random_get — consistent with every __syscall_* path-taking import already being permanently stubbed to ENOSYS in emscripten_abi_syscalls.go ("pglite uses its own VFS").

• Before: CGO_ENABLED=1 EMBEDDED_PG_WASM_FIXED=1 PGLITE_WASM_PATH=... go test -tags integration ./internal/embedded/... -run TestEmbeddedPGBootCycle -v → missing required memory export
• After: same command → boots substantially further, then traps with wasm \unreachable` instruction executed`

New blocker found: the post-fix trap is rooted in __syscall_pipe (import #93, confirmed via wasm-tools disassembly of the trapping function). Postgres's own startup (the latch.c self-pipe trick) calls pipe(); __syscall_pipe is permanently stubbed to return -38 (ENOSYS); that value is fed through musl's __syscall_ret errno-conversion helper (confirmed by reading its body — the classic if (result >= -4095u) { errno = -result; return -1; } pattern), the caller sees a negative return, and aborts via unreachable.

Fixing this needs real syscall emulation — at minimum pipe, fcntl64 (O_NONBLOCK), dup/dup3, and poll for the self-pipe read path, likely more downstream for real data-directory file I/O. That is a materially larger, separately-scoped body of work from the WASI-memory-export fix landed here.

Disposition: CLOSED-QUARANTINE-HARDENED. Re-ran the full integration suite fresh (TestEmbeddedPGBootCycle, TestSocketBridgeProxy, TestMigrationRunnerEmbedded, TestColdStartBudget) — all 4 FAIL identically and deterministically at the new trap point (not flaky). The t.Skip quarantine in integration_test.go still correctly names this issue and gates only itself (grep -rn EMBEDDED_PG_WASM_FIXED shows zero other consumers — no silent-pass risk). Keeping this issue open for the syscall-emulation gap; filing the WASI-memory-export commit against it for the record.

PR: nself-org/cli branch p6-e11-pglite-access.