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

+1
View File
@@ -20,5 +20,6 @@ docs/
logos/
target/
packages/core-wasm/pkg/
packages/core-wasm/pkg-proofs/
docker/dev-gateway/htpasswd
docker/dev-gateway/mailpit-password
+1
View File
@@ -63,6 +63,7 @@ supabase/.temp/
# Rust workspace (R0): build output and the generated browser module
target/
packages/core-wasm/pkg/
packages/core-wasm/pkg-proofs/
# DEV gateway credentials (generated by scripts/dev-gateway.sh)
docker/dev-gateway/htpasswd
+90 -32
View File
@@ -1,18 +1,39 @@
//! The call surface the wasm facade and the tools expose (review III.3): one operation
//! name, one JSON text in, one JSON text out, closed outcome kinds, never a panic on
//! content. The envelope is `{"ok":true,"value":…}` or `{"ok":false,"kind":…,"detail":…}`.
//! content. The envelope is `{"ok":true,"value":…}` or `{"ok":false,"kind":…,"detail":…}`,
//! plus `"found":<number>` when a failure names a document version.
use serde::Serialize;
use serde::de::DeserializeOwned;
use serde_json::{Value, json};
use serde_json::{Map, Value};
use crate::domain::js::parse_json;
use crate::domain::sheet::{BundledSheetData, LoadError, LoadedSheet};
use crate::domain::{ReportZone, SheetRef};
use crate::json::pretty_js_round_trip;
use crate::json::{pretty_js_round_trip, to_js_compact};
/// Runs the operation `op` on the JSON text `input` and returns the outcome envelope.
///
/// Operations of R0: `core_version`, `pretty_json` (JavaScript pretty form of any JSON
/// text), `sheet_ref` and `report_zone` (parse and re-emit a contract type).
/// A closed failure of an operation.
#[derive(Debug, Clone, PartialEq)]
pub struct Failure {
pub kind: &'static str,
pub detail: String,
/// The document version a reader refused, as the JavaScript number it was.
pub found: Option<f64>,
}
impl Failure {
pub fn new(kind: &'static str, detail: impl std::fmt::Display) -> Self {
Self {
kind,
detail: detail.to_string(),
found: None,
}
}
}
type Outcome = Result<Value, Failure>;
/// Runs the free operation `op` on the JSON text `input` and returns the outcome envelope.
pub fn call(op: &str, input: &str) -> String {
let outcome = match op {
"core_version" => Ok(Value::String(crate::CORE_VERSION.to_owned())),
@@ -21,47 +42,72 @@ pub fn call(op: &str, input: &str) -> String {
.map_err(|error| Failure::new("invalid_json", error)),
"sheet_ref" => echo::<SheetRef>(input),
"report_zone" => echo::<ReportZone>(input),
_ => Err(Failure::new(
"unknown_op",
format!("no operation named {op}"),
)),
_ => Err(unknown(op)),
};
render(outcome)
}
fn echo<T: DeserializeOwned + Serialize>(input: &str) -> Result<Value, Failure> {
let parsed: T =
serde_json::from_str(input).map_err(|error| Failure::new("invalid_shape", error))?;
serde_json::to_value(parsed).map_err(|error| Failure::new("internal", error))
/// Reads the bundled sheet payload (`BundledSheetData` JSON) into a loaded, indexed sheet.
pub fn load_sheet(bundle: &str) -> Result<LoadedSheet, Failure> {
let data: BundledSheetData = parse_input(bundle)?;
LoadedSheet::from_bundle(data).map_err(|error| match error {
LoadError::Shape(error) => Failure::new("invalid_sheet", error),
LoadError::NoMainView => Failure::new("invalid_sheet", "the sheet has no main view"),
})
}
struct Failure {
kind: &'static str,
detail: String,
/// Runs the operation `op` that needs the session's sheet.
pub fn call_with_sheet(sheet: &LoadedSheet, op: &str, _input: &str) -> String {
let outcome = match op {
"sheet.ref" => to_value(&sheet.reference),
_ => Err(unknown(op)),
};
render(outcome)
}
impl Failure {
fn new(kind: &'static str, detail: impl std::fmt::Display) -> Self {
Self {
kind,
detail: detail.to_string(),
fn unknown(op: &str) -> Failure {
Failure::new("unknown_op", format!("no operation named {op}"))
}
/// Parses the JSON text of an operation input into its contract type.
pub(crate) fn parse_input<T: DeserializeOwned>(input: &str) -> Result<T, Failure> {
let value = parse_json(input).map_err(|error| Failure::new("invalid_json", error))?;
serde_json::from_value(value).map_err(|error| Failure::new("invalid_shape", error))
}
pub(crate) fn to_value<T: Serialize>(value: &T) -> Outcome {
serde_json::to_value(value).map_err(|error| Failure::new("internal", error))
}
fn echo<T: DeserializeOwned + Serialize>(input: &str) -> Outcome {
let parsed: T = parse_input(input)?;
to_value(&parsed)
}
fn render(outcome: Outcome) -> String {
let mut envelope = Map::new();
match outcome {
Ok(value) => {
envelope.insert("ok".to_owned(), Value::Bool(true));
envelope.insert("value".to_owned(), value);
}
Err(failure) => {
envelope.insert("ok".to_owned(), Value::Bool(false));
envelope.insert("kind".to_owned(), Value::from(failure.kind));
envelope.insert("detail".to_owned(), Value::from(failure.detail));
if let Some(found) = failure.found.and_then(serde_json::Number::from_f64) {
envelope.insert("found".to_owned(), Value::Number(found));
}
}
}
}
fn render(outcome: Result<Value, Failure>) -> String {
let envelope = match outcome {
Ok(value) => json!({ "ok": true, "value": value }),
Err(failure) => json!({ "ok": false, "kind": failure.kind, "detail": failure.detail }),
};
serde_json::to_string(&envelope).unwrap_or_else(|_| {
to_js_compact(&Value::Object(envelope)).unwrap_or_else(|_| {
r#"{"ok":false,"kind":"internal","detail":"outcome serialisation failed"}"#.to_owned()
})
}
#[cfg(test)]
mod tests {
use super::call;
use super::{Failure, call, render};
#[test]
fn unknown_operation_is_a_closed_kind() {
@@ -87,4 +133,16 @@ mod tests {
r#"{"ok":true,"value":{"annotationId":"a","viewId":"v","side":"left"}}"#
);
}
#[test]
fn a_found_version_is_printed_as_a_javascript_number() {
let failure = Failure {
found: Some(4.0),
..Failure::new("incompatible_version", "v4")
};
assert_eq!(
render(Err(failure)),
r#"{"ok":false,"kind":"incompatible_version","detail":"v4","found":4}"#
);
}
}
+37
View File
@@ -176,6 +176,34 @@ pub fn to_js_pretty<T: Serialize + ?Sized>(value: &T) -> Result<String, serde_js
String::from_utf8(buffer).map_err(<serde_json::Error as serde::ser::Error>::custom)
}
/// `serde_json`'s compact formatter with JavaScript float printing (`JSON.stringify(value)`).
#[derive(Default)]
pub struct JsCompactFormatter;
impl Formatter for JsCompactFormatter {
fn write_f32<W>(&mut self, writer: &mut W, value: f32) -> io::Result<()>
where
W: ?Sized + io::Write,
{
writer.write_all(js_number(f64::from(value)).as_bytes())
}
fn write_f64<W>(&mut self, writer: &mut W, value: f64) -> io::Result<()>
where
W: ?Sized + io::Write,
{
writer.write_all(js_number(value).as_bytes())
}
}
/// Serialises `value` as `JSON.stringify(value)` would.
pub fn to_js_compact<T: Serialize + ?Sized>(value: &T) -> Result<String, serde_json::Error> {
let mut buffer = Vec::new();
let mut serializer = serde_json::Serializer::with_formatter(&mut buffer, JsCompactFormatter);
value.serialize(&mut serializer)?;
String::from_utf8(buffer).map_err(<serde_json::Error as serde::ser::Error>::custom)
}
/// Parses JSON text and re-emits it in the JavaScript pretty form, keeping the key order.
pub fn pretty_js_round_trip(text: &str) -> Result<String, serde_json::Error> {
let value: serde_json::Value = serde_json::from_str(text)?;
@@ -215,6 +243,15 @@ mod tests {
assert_eq!(js_number(f64::INFINITY), "null");
}
#[test]
fn compact_output_prints_floats_as_javascript() {
let value = serde_json::json!({"a": [1.0, 0.5, 1e21], "b": "\u{1}"});
assert_eq!(
to_js_compact(&value).ok().as_deref(),
Some(r#"{"a":[1,0.5,1e+21],"b":"\u0001"}"#)
);
}
#[test]
fn pretty_output_matches_the_javascript_shape() {
let text = r#"{"b":[1,2.0,{"c":[]}],"a":{},"d":"é\u0001","e":-0.0}"#;
+29 -3
View File
@@ -1,8 +1,10 @@
//! wasm-bindgen facade over `faunosteo-core` (review III.3): JSON strings in and out, closed
//! outcome kinds. Built by `scripts/wasm-build.sh` into `packages/core-wasm/pkg`; loaded
//! lazily by the application from R2 on (never at R0).
//! outcome kinds. Built by `scripts/wasm-build.sh` into `packages/core-wasm/pkg` (shipped)
//! and `packages/core-wasm/pkg-proofs` (with the trap exports, tests only); loaded lazily by
//! the application behind the sheet and import paths (`packages/core-wasm/src/runtime.ts`).
use wasm_bindgen::prelude::wasm_bindgen;
use faunosteo_core::domain::sheet::LoadedSheet;
use wasm_bindgen::prelude::{JsError, wasm_bindgen};
/// Version of the core compiled into this module.
#[wasm_bindgen]
@@ -17,6 +19,30 @@ pub fn call(op: &str, input: &str) -> String {
faunosteo_core::facade::call(op, input)
}
/// The session's anatomical sheet, held in the module's memory and built once from the
/// bundled payload, so the per-action calls carry only the observation or the report.
#[wasm_bindgen]
pub struct SheetHandle {
sheet: LoadedSheet,
}
#[wasm_bindgen]
impl SheetHandle {
/// Loads the bundled sheet payload; throws an `Error` whose message is
/// `invalid_sheet: <detail>` when the payload, the document or the map is refused.
#[wasm_bindgen(constructor)]
pub fn new(bundle: &str) -> Result<SheetHandle, JsError> {
faunosteo_core::facade::load_sheet(bundle)
.map(|sheet| SheetHandle { sheet })
.map_err(|failure| JsError::new(&format!("{}: {}", failure.kind, failure.detail)))
}
/// Runs one operation on this sheet; same envelope as `call`.
pub fn call(&self, op: &str, input: &str) -> String {
faunosteo_core::facade::call_with_sheet(&self.sheet, op, input)
}
}
/// R0 proof: on wasm32 a panic is a trap (panic = abort), reaching JavaScript as a
/// `WebAssembly.RuntimeError`; the caller re-instantiates the module.
#[cfg(feature = "proofs")]
+2 -2
View File
@@ -2,8 +2,8 @@ import globals from 'globals'
import tseslint from 'typescript-eslint'
export default tseslint.config(
// pkg/ is the wasm-bindgen output, types/ the ts-rs output: generated, never linted.
{ ignores: ['node_modules/**', 'pkg/**', 'types/**'] },
// pkg/ and pkg-proofs/ are the wasm-bindgen outputs, types/ the ts-rs output: generated, never linted.
{ ignores: ['node_modules/**', 'pkg/**', 'pkg-proofs/**', 'types/**'] },
{
files: ['**/*.ts'],
extends: [...tseslint.configs.recommended],
+4 -1
View File
@@ -7,8 +7,11 @@
"type": "module",
"exports": {
".": "./src/index.ts",
"./node": "./src/node.ts",
"./types": "./types/index.ts",
"./n-1": "./tests/n-1/index.ts"
"./n-1": "./tests/n-1/index.ts",
"./vitest-global-setup": "./tests/global-setup.ts",
"./pkg/*": "./pkg/*"
},
"scripts": {
"typecheck": "tsc -p tsconfig.json --noEmit",
+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'
+68
View File
@@ -0,0 +1,68 @@
/**
* Node source of the core module (vitest suites, scripts): the glue and the `.wasm` read
* from `pkg/` (the shipped build) or `pkg-proofs/` (with the R0 trap exports). Never
* imported by the application bundle.
*/
import { existsSync } from 'node:fs'
import { readFile } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'
import { CoreRuntime, type CoreSource, type GlueModule } from './runtime'
export type CoreBuild = 'pkg' | 'pkg-proofs'
const glueUrl = (build: CoreBuild) =>
new URL(`../${build}/faunosteo_wasm.js`, import.meta.url)
const wasmUrl = (build: CoreBuild) =>
new URL(`../${build}/faunosteo_wasm_bg.wasm`, import.meta.url)
/** Path of a built module on disk (size measurements). */
export function coreWasmPath(build: CoreBuild = 'pkg'): string {
return fileURLToPath(wasmUrl(build))
}
/** True when `pnpm wasm:build` has produced the module. */
export function isCoreBuilt(build: CoreBuild = 'pkg'): boolean {
return existsSync(coreWasmPath(build))
}
/** Each import gets its own query string, hence its own module record and instance. */
let imports = 0
export function nodeCoreSource(build: CoreBuild = 'pkg'): CoreSource {
return {
compile: async () =>
WebAssembly.compile(await readFile(coreWasmPath(build))),
importGlue: async () => {
imports += 1
return (await import(
`${glueUrl(build).href}?instance=${imports}`
)) as GlueModule
},
}
}
/** A runtime over the Node source, loaded. */
export async function nodeCoreRuntime(
build: CoreBuild = 'pkg',
): Promise<CoreRuntime> {
const runtime = new CoreRuntime(nodeCoreSource(build))
if (!(await runtime.ready())) {
throw new Error(`core module ${build} failed to load`)
}
return runtime
}
/** The functions of the proofs build (R0 trap proofs). */
export interface ProofModule extends GlueModule {
panic_for_test(): void
recurse_for_test(depth: number): number
}
/** A fresh, initialised glue of the proofs build, outside any runtime (R0 proofs). */
export async function loadProofModule(): Promise<ProofModule> {
const source = nodeCoreSource('pkg-proofs')
const glue = (await source.importGlue(0)) as ProofModule
await glue.default({ module_or_path: await source.compile() })
return glue
}
+29
View File
@@ -0,0 +1,29 @@
/**
* Outcome envelope of every core call (closed kinds, never an exception for content):
* `{ ok: true, value }` or `{ ok: false, kind, detail?, found? }`. Two kinds come from the
* runtime itself: `core_unavailable` (the module is not loaded, failed to load or is being
* re-created after a trap) and `internal` (the call trapped; the instance was dropped).
*/
export type CoreOutcome<T> =
| { ok: true; value: T }
| { ok: false; kind: string; detail?: string; found?: number }
export type CoreFailure = Extract<CoreOutcome<never>, { ok: false }>
export const CORE_UNAVAILABLE: CoreFailure = {
ok: false,
kind: 'core_unavailable',
}
export function failure(kind: string, detail?: string): CoreFailure {
return detail === undefined ? { ok: false, kind } : { ok: false, kind, detail }
}
/** Parses the JSON text a core call returned. */
export function parseOutcome<T>(text: string): CoreOutcome<T> {
try {
return JSON.parse(text) as CoreOutcome<T>
} catch {
return failure('internal', 'unreadable outcome')
}
}
+220
View File
@@ -0,0 +1,220 @@
import {
CORE_UNAVAILABLE,
failure,
parseOutcome,
type CoreOutcome,
} from './outcome'
/**
* Browser and Node runtime of the core module (RUST_ARCHITECTURE_REVIEW III.3 rules 5 and
* 6, R2 plan P9 rev 2). The module is loaded on first need only; calls are synchronous once
* it is ready. A `WebAssembly.RuntimeError` (a Rust panic or a stack overflow) poisons the
* instance: the failing call answers `internal`, no further call reaches that instance, and
* a fresh one is created from the compiled module kept in memory and a glue module record
* imported in advance (a trap needs no network). Calls made while it is re-created answer
* `core_unavailable`; after `maxRecoveries` traps the page stays unavailable until reload.
*/
/** What the wasm-bindgen glue (`--target web`) exports. */
export interface GlueModule {
default(input: { module_or_path: WebAssembly.Module }): Promise<unknown>
core_version(): string
call(op: string, input: string): string
SheetHandle: new (bundle: string) => GlueSheetHandle
}
export interface GlueSheetHandle {
call(op: string, input: string): string
}
/** Where the module comes from: the browser (Vite asset URLs) or Node (files). */
export interface CoreSource {
/** Compiles the `.wasm` once; the runtime keeps the result for every instance. */
compile(): Promise<WebAssembly.Module>
/**
* Imports a NEW glue module record: the glue keeps its instance in a module variable and
* the ESM cache returns the same record for the same URL, so each `instance` number must
* give a distinct URL (cache-busting query).
*/
importGlue(instance: number): Promise<GlueModule>
}
export type CoreStatus =
| 'idle'
| 'loading'
| 'ready'
| 'recovering'
| 'unavailable'
export interface CoreRuntimeOptions {
/** Re-creations after a trap allowed for the page's lifetime. */
maxRecoveries?: number
}
export class CoreRuntime {
private state: CoreStatus = 'idle'
private glue: GlueModule | null = null
private compiled: Promise<WebAssembly.Module> | null = null
private spare: Promise<GlueModule | null> | null = null
private pending: Promise<boolean> | null = null
private imports = 0
private recoveries = 0
private readonly maxRecoveries: number
/** Increments with every instance; sheet handles of an older generation are dropped. */
generation = 0
constructor(
private readonly source: CoreSource,
options: CoreRuntimeOptions = {},
) {
this.maxRecoveries = options.maxRecoveries ?? 3
}
get status(): CoreStatus {
return this.state
}
/** Loads the module on first use; true when calls can be made. */
ready(): Promise<boolean> {
if (this.state === 'ready') return Promise.resolve(true)
if (this.state === 'unavailable') return Promise.resolve(false)
this.pending ??= this.load()
return this.pending
}
/** After a load failure: forgets it and loads again (traps already spent stay spent). */
retry(): Promise<boolean> {
if (this.state !== 'unavailable') return this.ready()
if (this.recoveries >= this.maxRecoveries) return Promise.resolve(false)
this.state = 'idle'
this.compiled = null
this.pending = null
return this.ready()
}
/** Runs a free operation. */
call<T>(op: string, input: string): CoreOutcome<T> {
return this.invoke((glue) => parseOutcome<T>(glue.call(op, input)))
}
/** A session bound to one sheet payload; the handle is rebuilt per instance. */
sheet(bundleText: string): SheetSession {
return new SheetSession(this, bundleText)
}
/**
* Runs `fn` on the live instance. Any exception from the module poisons the instance:
* the result is `internal`, and the next calls wait for a fresh one.
*/
invoke<T>(fn: (glue: GlueModule) => CoreOutcome<T>): CoreOutcome<T> {
const glue = this.glue
if (this.state !== 'ready' || !glue) return CORE_UNAVAILABLE
try {
return fn(glue)
} catch (error) {
this.poison()
return failure('internal', error instanceof Error ? error.name : 'error')
}
}
private async load(): Promise<boolean> {
this.state = 'loading'
try {
await this.instantiate(await this.source.importGlue(this.nextImport()))
return true
} catch {
this.state = 'unavailable'
this.pending = null
return false
}
}
private async instantiate(glue: GlueModule): Promise<void> {
this.compiled ??= this.source.compile()
await glue.default({ module_or_path: await this.compiled })
this.glue = glue
this.generation += 1
this.state = 'ready'
this.spare = this.source
.importGlue(this.nextImport())
.catch(() => null)
}
private nextImport(): number {
this.imports += 1
return this.imports
}
private poison(): void {
this.glue = null
if (this.recoveries >= this.maxRecoveries) {
this.state = 'unavailable'
return
}
this.recoveries += 1
this.state = 'recovering'
this.pending = this.recover()
}
private async recover(): Promise<boolean> {
try {
const spare = await this.spare
await this.instantiate(
spare ?? (await this.source.importGlue(this.nextImport())),
)
return true
} catch {
this.state = 'unavailable'
return false
} finally {
this.pending = null
}
}
}
/** The calls that need the session's sheet (`SheetHandle` in the module's memory). */
export class SheetSession {
private handle: GlueSheetHandle | null = null
private handleGeneration = -1
constructor(
private readonly runtime: CoreRuntime,
/** The bundled sheet payload, kept to rebuild the handle on a new instance. */
readonly bundleText: string,
) {}
/** Builds the handle now: `invalid_sheet` when the payload is refused. */
open(): CoreOutcome<null> {
const handle = this.current()
return handle.ok ? { ok: true, value: null } : handle
}
call<T>(op: string, input: string): CoreOutcome<T> {
const handle = this.current()
if (!handle.ok) return handle
return this.runtime.invoke(() =>
parseOutcome<T>(handle.value.call(op, input)),
)
}
/** The handle of the live instance; a handle of a dropped instance is never called. */
private current(): CoreOutcome<GlueSheetHandle> {
if (this.handle && this.handleGeneration === this.runtime.generation) {
return this.runtime.status === 'ready'
? { ok: true, value: this.handle }
: CORE_UNAVAILABLE
}
this.handle = null
return this.runtime.invoke((glue) => {
try {
this.handle = new glue.SheetHandle(this.bundleText)
} catch (error) {
if (error instanceof WebAssembly.RuntimeError) throw error
const message = error instanceof Error ? error.message : ''
return failure('invalid_sheet', message.replace(/^invalid_sheet: /, ''))
}
this.handleGeneration = this.runtime.generation
return { ok: true, value: this.handle }
})
}
}
+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
}
+1
View File
@@ -5,5 +5,6 @@ export default defineConfig({
environment: 'node',
globals: true,
include: ['tests/**/*.test.ts'],
globalSetup: ['tests/global-setup.ts'],
},
})
+24 -9
View File
@@ -21,14 +21,29 @@ if [ "$lock_version" != "$cli_version" ]; then
exit 1
fi
# `proofs`: the R0 trap exports; dropped when R2 builds the module the application ships.
cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown --locked --features proofs
# Two modules from the same sources: pkg/ is the one the application ships (no trap export),
# pkg-proofs/ adds the R0 trap exports for the poison-and-reinstantiate tests only (R2 plan P10).
build_module() {
local out="$1"
shift
cargo build -p faunosteo-wasm --release --target wasm32-unknown-unknown --locked "$@"
rm -rf "$out"
wasm-bindgen --target web --out-dir "$out" --out-name faunosteo_wasm \
target/wasm32-unknown-unknown/release/faunosteo_wasm.wasm
}
out=packages/core-wasm/pkg
rm -rf packages/core-wasm/pkg
wasm-bindgen --target web --out-dir "$out" --out-name faunosteo_wasm \
target/wasm32-unknown-unknown/release/faunosteo_wasm.wasm
stamp="$(node scripts/wasm-stamp.mjs)"
build_module packages/core-wasm/pkg-proofs --features proofs
echo "$stamp" > packages/core-wasm/pkg-proofs/BUILD_STAMP
build_module packages/core-wasm/pkg
echo "$stamp" > packages/core-wasm/pkg/BUILD_STAMP
raw=$(wc -c < "$out/faunosteo_wasm_bg.wasm")
gz=$(gzip -9 -c "$out/faunosteo_wasm_bg.wasm" | wc -c)
echo "faunosteo_wasm_bg.wasm: ${raw} bytes raw, ${gz} bytes gzip -9"
# The shipped module must not carry a proof export.
if grep -Eq 'panic_for_test|recurse_for_test' packages/core-wasm/pkg/faunosteo_wasm.d.ts; then
echo "packages/core-wasm/pkg exports a proof function: refusing to ship it" >&2
exit 1
fi
raw=$(wc -c < packages/core-wasm/pkg/faunosteo_wasm_bg.wasm)
gz=$(gzip -9 -c packages/core-wasm/pkg/faunosteo_wasm_bg.wasm | wc -c)
echo "faunosteo_wasm_bg.wasm (shipped): ${raw} bytes raw, ${gz} bytes gzip -9"
+41
View File
@@ -0,0 +1,41 @@
// Build stamp of the browser module: sha256 over the sources that compile into it (the core
// library, the wasm facade, the workspace manifests and lock, the cargo config). Written into
// pkg/ and pkg-proofs/ by scripts/wasm-build.sh; packages/core-wasm/tests/global-setup.ts
// recomputes it and refuses to run the suites on a missing or stale module.
// Usage: node scripts/wasm-stamp.mjs → prints the stamp.
import { createHash } from 'node:crypto'
import { readdirSync, readFileSync, statSync } from 'node:fs'
import { join, relative, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
const ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)))
const INPUTS = [
'Cargo.toml',
'Cargo.lock',
'.cargo/config.toml',
'crates/core/Cargo.toml',
'crates/core/src',
'crates/wasm/Cargo.toml',
'crates/wasm/src',
]
function files(path) {
const absolute = join(ROOT, path)
if (!statSync(absolute).isDirectory()) return [path]
return readdirSync(absolute).flatMap((name) => files(join(path, name)))
}
export function wasmStamp() {
const hash = createHash('sha256')
const all = INPUTS.flatMap(files).map((f) => relative(ROOT, join(ROOT, f)))
for (const file of all.sort()) {
hash.update(`${file}\0`)
hash.update(readFileSync(join(ROOT, file)))
hash.update('\0')
}
return hash.digest('hex')
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
process.stdout.write(`${wasmStamp()}\n`)
}