feat(workspace): R2.4 core runtime — lazy load, poison on trap, offline re-instantiation, per-generation sheet handles

packages/core-wasm: browser-safe CoreRuntime (synchronous calls once ready;
a WebAssembly.RuntimeError poisons the instance, the call answers internal,
a fresh instance comes from the kept compiled module and a glue record
imported in advance; at most 3 recoveries per page; retry after a load
failure), SheetSession (handle rebuilt per instance generation, never
called on a dropped one; invalid_sheet without poisoning), Node source.
crates/wasm: SheetHandle (sheet held in the module memory). Two builds:
pkg/ shipped without trap exports (checked), pkg-proofs/ for the trap
tests; BUILD_STAMP (hash of the Rust sources) refused when missing or
stale by the vitest global setup instead of skipping. Failure envelope
carries a numeric found version; compact JS-number output.
This commit is contained in:
bchanot committed 2026-10-14 00:12:04 +02:00
1 parent 22fea8736d
commit 343d6f4c1f
22 files changed
+783 -180

No files matched your search

+18 -69
View File
@@ -1,72 +1,21 @@
/**
* Loader of the Faunosteo core module (wasm-bindgen `--target web` output under `pkg/`,
* built by `pnpm wasm:build`, git-ignored).
* @faunosteo/core-wasm: the Faunosteo core (Rust) compiled to WebAssembly.
*
* The module is never imported statically: `pkg/` may be absent on a host without Docker,
* and the application loads the core lazily behind the paths that need it (review III.3).
* No file of this package is reachable from the application before R2.
* Browser-safe entry: the runtime and the outcome types. The application gives the runtime
* a source built from Vite asset URLs (`apps/app/src/core/`), so the module is fetched on
* first need only; Node code (tests, scripts) uses `@faunosteo/core-wasm/node`.
*/
import { existsSync } from 'node:fs'
import { readFile } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'
/** The functions the module exports (mirror of `pkg/faunosteo_wasm.d.ts`). */
export interface CoreModule {
core_version(): string
call(op: string, input: string): string
panic_for_test(): void
recurse_for_test(depth: number): number
}
/** Outcome envelope of every `call` (closed kinds, never an exception for content). */
export type CoreOutcome<T = unknown> =
| { ok: true; value: T }
| { ok: false; kind: string; detail?: string }
const PKG_JS = new URL('../pkg/faunosteo_wasm.js', import.meta.url)
const PKG_WASM = new URL('../pkg/faunosteo_wasm_bg.wasm', import.meta.url)
interface PkgModule extends CoreModule {
default(input: { module_or_path: BufferSource }): Promise<unknown>
}
/** True when `pnpm wasm:build` has produced the module. */
export function isCoreBuilt(): boolean {
return existsSync(fileURLToPath(PKG_WASM))
}
let instances = 0
/**
* Instantiates a fresh module (Node: bytes from disk). Each call is a new instance.
*
* The wasm-bindgen glue keeps its instance in a module-level variable and the ESM cache
* returns the same module for the same URL, so a second plain `import()` would hand back
* the previous (possibly trapped) instance: R0 proved that an instance is unusable after a
* trap (`memory access out of bounds` in the allocator on the next call). A cache-busting
* query gives a new module record, hence a new instance. The browser loader of R2 must do
* the same (static glue URL imported with a query, or a Worker recreated on trap).
*/
export async function loadCore(): Promise<CoreModule> {
instances += 1
const pkg = (await import(
`${PKG_JS.href}?instance=${instances}`
)) as PkgModule
const bytes = await readFile(PKG_WASM)
await pkg.default({ module_or_path: bytes })
return pkg
}
/** Runs one operation and parses its envelope. */
export function callCore<T = unknown>(
core: CoreModule,
op: string,
input: string,
): CoreOutcome<T> {
return JSON.parse(core.call(op, input)) as CoreOutcome<T>
}
/** Path of the built module on disk (size measurements). */
export function coreWasmPath(): string {
return fileURLToPath(PKG_WASM)
}
export {
CoreRuntime,
SheetSession,
type CoreSource,
type CoreStatus,
type GlueModule,
type GlueSheetHandle,
} from './runtime'
export {
CORE_UNAVAILABLE,
parseOutcome,
type CoreFailure,
type CoreOutcome,
} from './outcome'