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

+19 -23
View File
@@ -1,18 +1,18 @@
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { callCore, loadCore } from '../src/index'
import { coreBuilt } from './helpers/core'
import { nodeCoreRuntime, nodeCoreSource } from '../src/node'
const CORE_MANIFEST = new URL(
'../../../crates/core/Cargo.toml',
import.meta.url,
)
const WORKSPACE_MANIFEST = new URL('../../../Cargo.toml', import.meta.url)
const SHIPPED_DTS = new URL('../pkg/faunosteo_wasm.d.ts', import.meta.url)
describe.skipIf(!coreBuilt)('core facade (wasm)', () => {
describe('core facade (shipped wasm build)', () => {
it('reports the workspace version of the core', async () => {
const core = await loadCore()
const core = await nodeCoreRuntime()
const workspace = readFileSync(fileURLToPath(WORKSPACE_MANIFEST), 'utf8')
const version = /\[workspace\.package\][^[]*?version = "([^"]+)"/s.exec(
workspace,
@@ -21,36 +21,32 @@ describe.skipIf(!coreBuilt)('core facade (wasm)', () => {
expect(readFileSync(fileURLToPath(CORE_MANIFEST), 'utf8')).toContain(
'version.workspace = true',
)
expect(core.core_version()).toBe(version)
expect(core.call('core_version', '')).toEqual({ ok: true, value: version })
})
it('answers with a closed outcome envelope', async () => {
const core = await loadCore()
expect(callCore(core, 'core_version', '')).toEqual({
ok: true,
value: core.core_version(),
})
expect(callCore(core, 'nope', '{}')).toMatchObject({
const core = await nodeCoreRuntime()
expect(core.call('nope', '{}')).toMatchObject({
ok: false,
kind: 'unknown_op',
})
expect(callCore(core, 'pretty_json', '{ not json')).toMatchObject({
expect(core.call('pretty_json', '{ not json')).toMatchObject({
ok: false,
kind: 'invalid_json',
})
})
it('exposes exactly the documented functions', async () => {
const core = await loadCore()
for (const name of [
'core_version',
'call',
'panic_for_test',
'recurse_for_test',
]) {
expect(typeof (core as unknown as Record<string, unknown>)[name]).toBe(
'function',
)
it('ships no trap export (the proofs live in pkg-proofs only)', async () => {
const glue = (await nodeCoreSource('pkg').importGlue(0)) as unknown as Record<
string,
unknown
>
for (const name of ['core_version', 'call', 'SheetHandle']) {
expect(typeof glue[name]).toBe('function')
}
expect(glue.panic_for_test).toBeUndefined()
expect(glue.recurse_for_test).toBeUndefined()
const dts = readFileSync(fileURLToPath(SHIPPED_DTS), 'utf8')
expect(dts).not.toMatch(/panic_for_test|recurse_for_test/)
})
})
+25
View File
@@ -0,0 +1,25 @@
/**
* Vitest global setup of every suite that runs the core: refuses to run on a missing or
* stale module instead of skipping (R2 plan rev 2). The stamp is the hash of the Rust
* sources the module is compiled from (scripts/wasm-stamp.mjs), written by
* `pnpm wasm:build` into both builds.
*/
import { existsSync, readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { wasmStamp } from '../../../scripts/wasm-stamp.mjs'
export default function checkCoreBuilds(): void {
const expected = wasmStamp()
for (const build of ['pkg', 'pkg-proofs']) {
const file = fileURLToPath(
new URL(`../${build}/BUILD_STAMP`, import.meta.url),
)
const found = existsSync(file) ? readFileSync(file, 'utf8').trim() : null
if (found !== expected) {
throw new Error(
`packages/core-wasm/${build} is ${found ? 'stale' : 'missing'}: run \`pnpm wasm:build\``,
)
}
}
}
-13
View File
@@ -1,13 +0,0 @@
import { isCoreBuilt } from '../../src/index'
/**
* The proofs need the built module. On a host without Docker they are skipped with a
* visible notice instead of failing `pnpm check`; CI always builds the module first.
*/
export const coreBuilt = isCoreBuilt()
if (!coreBuilt) {
console.warn(
'[core-wasm] pkg/ missing: run `pnpm wasm:build` (Docker builder); proofs skipped',
)
}
+2 -3
View File
@@ -10,10 +10,9 @@
* (`memory access out of bounds`), deterministically;
* - a genuinely new instance (new module record, new memory) recovers in full.
*/
import { loadCore } from '../src/index'
import { coreBuilt } from './helpers/core'
import { loadProofModule as loadCore } from '../src/node'
describe.skipIf(!coreBuilt)('panics and stack exhaustion (wasm)', () => {
describe('panics and stack exhaustion (wasm)', () => {
it('turns a panic into a WebAssembly.RuntimeError', async () => {
const core = await loadCore()
expect(() => core.panic_for_test()).toThrow(WebAssembly.RuntimeError)
+147
View File
@@ -0,0 +1,147 @@
/**
* The core runtime (R2 plan P9 rev 2) on the proofs build, whose trap exports make the
* failure paths real: lazy load, poison on a trap, re-instantiation from the kept compiled
* module and the pre-imported glue record (no network), handles rebuilt per instance and
* never called on a dropped one, the recovery cap, load failure and retry.
*/
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { CoreRuntime, type CoreSource, type GlueModule } from '../src/index'
import { nodeCoreSource, type ProofModule } from '../src/node'
const SEED = '../../../supabase/seed/anatomical-sheets/equine/draft/'
function seedJson(name: string): unknown {
const path = fileURLToPath(new URL(`${SEED}${name}`, import.meta.url))
return JSON.parse(readFileSync(path, 'utf8'))
}
const BUNDLE = JSON.stringify({
status: 'draft',
ref: {
sheet_id: 'sheet',
version_id: null,
document_sha256: '0'.repeat(64),
schema_version: 2,
species_id: 'equine',
},
document: seedJson('document.json'),
migrationMap: seedJson('report-migration-map.json'),
assets: {},
assetHashes: {},
})
/** Counts glue imports; imports after `offlineAfter` fail like a lost network. */
function countingSource(offlineAfter = Infinity) {
const inner = nodeCoreSource('pkg-proofs')
const source = {
imports: 0,
compile: () => inner.compile(),
importGlue: async (n: number): Promise<GlueModule> => {
source.imports += 1
if (source.imports > offlineAfter) throw new TypeError('offline')
return inner.importGlue(n)
},
}
return source
}
/** Traps the live instance through the proofs build (stack exhaustion). */
function trap(runtime: CoreRuntime) {
return runtime.invoke((glue) => {
;(glue as ProofModule).recurse_for_test(2_000_000)
return { ok: true, value: null }
})
}
describe('core runtime', () => {
it('loads on first need only', async () => {
const source = countingSource()
const runtime = new CoreRuntime(source)
expect(runtime.status).toBe('idle')
expect(runtime.call('core_version', '')).toMatchObject({
ok: false,
kind: 'core_unavailable',
})
expect(source.imports).toBe(0)
expect(await runtime.ready()).toBe(true)
expect(runtime.call('core_version', '')).toMatchObject({ ok: true })
})
it('poisons on a trap and recovers offline from the spare glue record', async () => {
const source = countingSource(2)
const runtime = new CoreRuntime(source)
await runtime.ready()
expect(trap(runtime)).toMatchObject({ ok: false, kind: 'internal' })
expect(runtime.status).toBe('recovering')
expect(runtime.call('core_version', '')).toMatchObject({
kind: 'core_unavailable',
})
expect(await runtime.ready()).toBe(true)
expect(runtime.generation).toBe(2)
expect(runtime.call('core_version', '')).toMatchObject({ ok: true })
})
it('rebuilds a sheet handle on the new instance and never calls the dropped one', async () => {
const runtime = new CoreRuntime(countingSource())
await runtime.ready()
const sheet = runtime.sheet(BUNDLE)
expect(sheet.call('sheet.ref', '')).toMatchObject({
ok: true,
value: { sheetId: 'sheet', versionId: null },
})
trap(runtime)
expect(sheet.call('sheet.ref', '')).toMatchObject({
kind: 'core_unavailable',
})
await runtime.ready()
// A call through the stack-trapped instance would fail in its allocator and poison
// again: one generation more and a ready runtime prove the handle was rebuilt.
expect(sheet.call('sheet.ref', '')).toMatchObject({ ok: true })
expect(runtime.generation).toBe(2)
expect(runtime.status).toBe('ready')
})
it('stops recovering after the cap', async () => {
const runtime = new CoreRuntime(countingSource(), { maxRecoveries: 1 })
await runtime.ready()
trap(runtime)
expect(await runtime.ready()).toBe(true)
trap(runtime)
expect(runtime.status).toBe('unavailable')
expect(await runtime.retry()).toBe(false)
expect(runtime.call('core_version', '')).toMatchObject({
kind: 'core_unavailable',
})
})
it('reports a load failure and loads again on retry', async () => {
const inner = nodeCoreSource('pkg')
let failNext = true
const source: CoreSource = {
compile: () => {
if (failNext) {
failNext = false
return Promise.reject(new WebAssembly.CompileError('blocked'))
}
return inner.compile()
},
importGlue: (n) => inner.importGlue(n),
}
const runtime = new CoreRuntime(source)
expect(await runtime.ready()).toBe(false)
expect(runtime.status).toBe('unavailable')
expect(await runtime.retry()).toBe(true)
expect(runtime.call('core_version', '')).toMatchObject({ ok: true })
})
it('refuses an invalid sheet payload without poisoning the instance', async () => {
const runtime = new CoreRuntime(nodeCoreSource('pkg'))
await runtime.ready()
const outcome = runtime.sheet('{"status":"draft"}').open()
expect(outcome).toMatchObject({ ok: false, kind: 'invalid_sheet' })
expect(runtime.status).toBe('ready')
expect(runtime.sheet(BUNDLE).open()).toEqual({ ok: true, value: null })
})
})
+12 -16
View File
@@ -9,8 +9,8 @@ import { fileURLToPath } from 'node:url'
import { ReportZoneSchema, SheetRefSchema } from './n-1/domain'
import type { ReportZone, SheetRef } from '../types/index'
import { callCore, loadCore, type CoreModule } from '../src/index'
import { coreBuilt } from './helpers/core'
import type { CoreRuntime } from '../src/index'
import { nodeCoreRuntime } from '../src/node'
const FIXTURES = [
'apps/app/tests/fixtures/report-v3.demo.json',
@@ -32,17 +32,17 @@ function repoFile(relative: string): string {
)
}
function prettyByCore(core: CoreModule, text: string): string {
const outcome = callCore<string>(core, 'pretty_json', text)
function prettyByCore(core: CoreRuntime, text: string): string {
const outcome = core.call<string>('pretty_json', text)
if (!outcome.ok) throw new Error(`${outcome.kind}: ${outcome.detail ?? ''}`)
return outcome.value
}
describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
describe('serialisation contract (wasm)', () => {
it.each(FIXTURES)(
'%s: core pretty output equals JSON.stringify(…, null, 2)',
async (relative) => {
const core = await loadCore()
const core = await nodeCoreRuntime()
const text = repoFile(relative)
const expected = JSON.stringify(JSON.parse(text), null, 2)
expect(prettyByCore(core, text)).toBe(expected)
@@ -50,7 +50,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
)
it('prints every number as JavaScript does', async () => {
const core = await loadCore()
const core = await nodeCoreRuntime()
const text = JSON.stringify(NUMBER_CASES)
expect(prettyByCore(core, text)).toBe(
JSON.stringify(JSON.parse(text), null, 2),
@@ -58,9 +58,8 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
})
it('writes optional fields absent and nullable fields null, readable by the Zod schemas', async () => {
const core = await loadCore()
const bare = callCore<ReportZone>(
core,
const core = await nodeCoreRuntime()
const bare = core.call<ReportZone>(
'report_zone',
JSON.stringify({ annotationId: 'hip', viewId: 'main' }),
)
@@ -72,8 +71,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
expect(Object.keys(bare.value)).toEqual(['annotationId', 'viewId'])
expect(ReportZoneSchema.parse(bare.value)).toEqual(bare.value)
const full = callCore<ReportZone>(
core,
const full = core.call<ReportZone>(
'report_zone',
JSON.stringify({
viewId: 'main',
@@ -93,8 +91,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
},
})
const sheet = callCore<SheetRef>(
core,
const sheet = core.call<SheetRef>(
'sheet_ref',
JSON.stringify({
sheetId: 'faunosteo-cheval',
@@ -105,8 +102,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
expect(sheet.ok && sheet.value.versionId).toBeNull()
if (sheet.ok) expect(SheetRefSchema.parse(sheet.value)).toEqual(sheet.value)
const refused = callCore(
core,
const refused = core.call(
'report_zone',
JSON.stringify({ annotationId: 'a', viewId: 'v', unresolved: false }),
)
+10 -9
View File
@@ -1,25 +1,26 @@
/**
* R0 measurement: served size of the module and instantiate time (D-R13 budget, enforced
* from R2 on the real core; R0 records the skeleton's numbers).
* D-R13 budget: the served module (gzip) stays under 600 KB; the numbers are printed for
* RUST.md (raw and compressed size, compile + instantiate time on Node).
*/
import { readFileSync } from 'node:fs'
import { gzipSync } from 'node:zlib'
import { coreWasmPath, loadCore } from '../src/index'
import { coreBuilt } from './helpers/core'
import { CoreRuntime } from '../src/index'
import { coreWasmPath, nodeCoreSource } from '../src/node'
/** D-R13: the served module (compressed) stays under this many bytes. */
const COMPRESSED_BUDGET_BYTES = 600_000
describe.skipIf(!coreBuilt)('module size and instantiate time (wasm)', () => {
describe('module size and instantiate time (shipped wasm build)', () => {
it('stays under the compressed budget and reports its numbers', async () => {
const bytes = readFileSync(coreWasmPath())
const bytes = readFileSync(coreWasmPath('pkg'))
const gzip = gzipSync(bytes, { level: 9 }).length
const started = performance.now()
await loadCore()
const instantiateMs = performance.now() - started
const runtime = new CoreRuntime(nodeCoreSource('pkg'))
expect(await runtime.ready()).toBe(true)
const readyMs = performance.now() - started
console.info(
`[core-wasm] faunosteo_wasm_bg.wasm: ${bytes.length} bytes raw, ${gzip} bytes gzip-9, instantiate ${instantiateMs.toFixed(1)} ms`,
`[core-wasm] faunosteo_wasm_bg.wasm: ${bytes.length} bytes raw, ${gzip} bytes gzip-9, compile + instantiate ${readyMs.toFixed(1)} ms`,
)
expect(gzip).toBeLessThanOrEqual(COMPRESSED_BUDGET_BYTES)
})
+3
View File
@@ -0,0 +1,3 @@
declare module '*/scripts/wasm-stamp.mjs' {
export function wasmStamp(): string
}