perf(wasix): add direct OPFS storage fast path

[f0rr0]

Summary

• Add a same-worker synchronous filesystem bridge backed by an OPFS FileSystemSyncAccessHandle pool, removing the extra storage-worker and whole-directory hydration path from supported dedicated-worker browsers.
• Keep the portable fallback and direct path on one versioned logical storage format with exclusive ownership, compatibility validation, atomic generation publication, PostgreSQL-safe sync boundaries, and typed failure semantics.
• Unify direct /base materialization with the existing storage lease lifecycle, including deterministic pool, lock, and host-filesystem cleanup on success and failure.
• Add direct/fallback interoperability, corruption, atomicity, descriptor, spill, and lifecycle coverage plus bounded browser smoke and comparison instrumentation and updated architecture guidance.

Why / root cause

The previous OPFS provider hydrated PGDATA into a Wasmer in-memory Directory and persisted mutation snapshots. Even after the clean-break runtime moved PostgreSQL into the dedicated worker, storage still paid for that materialization and persistence bridge. The host lacked a synchronous caller-realm filesystem interface that WASIX could invoke directly.

This change supplies that narrow host bridge and serves requests from the same dedicated worker through pooled synchronous OPFS handles. Browsers that cannot provide the required primitives retain the existing portable path. The public storage descriptor and factory surface do not change.

This PR does not claim a measured win over PGlite. Its benchmark tooling records matched topology and durability metadata so a comparative result can be qualified separately.

Release Intent

• Package/API/runtime change: PR title uses feat:, fix:, perf:, refactor:, revert:, or a breaking !.
• Docs/CI/repository-only change: no release intended.
• Source/input/runtime asset change: source pins, generated metadata, and release metadata affectedness are current.

Verification

• pnpm doctor (not exposed at this repository root)
• pnpm fmt:check (not exposed at this repository root)
• pnpm check (not exposed at this repository root)
• pnpm test — 19 files, 133 tests
• pnpm release-check (not exposed at this repository root)
• Product-specific smoke/package/perf checks when product behavior or artifacts changed.

Additional qualification:

• bash src/bindings/wasix-ts/host/build-sdk.sh
• moon run liboliphaunt-wasix:runtime-portable
• moon run sdk-contracts:check oliphaunt-wasix-ts:package
• pnpm typecheck
• pnpm build && node tools/stage-host.mjs && pnpm package:check
• Browser smoke: answers=[42,43], OPFS reopen answers 1,2,3, pgTAP 1.3, expected startup SQLSTATE 3D000, directWorkers=0, opfsTransport=direct

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
oliphaunt-docs	Ready	Preview	Aug 18, 2026 12:31pm