From 343d6f4c1ff70df4b33e2958b7c705d32f338af1 Mon Sep 17 00:00:00 2001 From: bchanot Date: Wed, 14 Oct 2026 00:12:04 +0200 Subject: [PATCH] =?UTF-8?q?feat(workspace):=20R2.4=20core=20runtime=20?= =?UTF-8?q?=E2=80=94=20lazy=20load,=20poison=20on=20trap,=20offline=20re-i?= =?UTF-8?q?nstantiation,=20per-generation=20sheet=20handles?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .dockerignore | 1 + .gitignore | 1 + crates/core/src/facade.rs | 122 +++++++--- crates/core/src/json.rs | 37 +++ crates/wasm/src/lib.rs | 32 ++- packages/core-wasm/eslint.config.js | 4 +- packages/core-wasm/package.json | 5 +- packages/core-wasm/src/index.ts | 87 ++----- packages/core-wasm/src/node.ts | 68 ++++++ packages/core-wasm/src/outcome.ts | 29 +++ packages/core-wasm/src/runtime.ts | 220 ++++++++++++++++++ packages/core-wasm/tests/facade.test.ts | 42 ++-- packages/core-wasm/tests/global-setup.ts | 25 ++ packages/core-wasm/tests/helpers/core.ts | 13 -- packages/core-wasm/tests/panic.test.ts | 5 +- packages/core-wasm/tests/runtime.test.ts | 147 ++++++++++++ .../core-wasm/tests/serialisation.test.ts | 28 +-- packages/core-wasm/tests/size.test.ts | 19 +- packages/core-wasm/tests/wasm-stamp.d.ts | 3 + packages/core-wasm/vitest.config.ts | 1 + scripts/wasm-build.sh | 33 ++- scripts/wasm-stamp.mjs | 41 ++++ 22 files changed, 783 insertions(+), 180 deletions(-) create mode 100644 packages/core-wasm/src/node.ts create mode 100644 packages/core-wasm/src/outcome.ts create mode 100644 packages/core-wasm/src/runtime.ts create mode 100644 packages/core-wasm/tests/global-setup.ts delete mode 100644 packages/core-wasm/tests/helpers/core.ts create mode 100644 packages/core-wasm/tests/runtime.test.ts create mode 100644 packages/core-wasm/tests/wasm-stamp.d.ts create mode 100644 scripts/wasm-stamp.mjs diff --git a/.dockerignore b/.dockerignore index e32191b5..9465d471 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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 diff --git a/.gitignore b/.gitignore index 837d4870..050024ff 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/crates/core/src/facade.rs b/crates/core/src/facade.rs index a63b34cd..e9a1d0fa 100644 --- a/crates/core/src/facade.rs +++ b/crates/core/src/facade.rs @@ -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":` 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, +} + +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; + +/// 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::(input), "report_zone" => echo::(input), - _ => Err(Failure::new( - "unknown_op", - format!("no operation named {op}"), - )), + _ => Err(unknown(op)), }; render(outcome) } -fn echo(input: &str) -> Result { - 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 { + 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(input: &str) -> Result { + 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(value: &T) -> Outcome { + serde_json::to_value(value).map_err(|error| Failure::new("internal", error)) +} + +fn echo(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) -> 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}"# + ); + } } diff --git a/crates/core/src/json.rs b/crates/core/src/json.rs index 5e4d1459..3feb664e 100644 --- a/crates/core/src/json.rs +++ b/crates/core/src/json.rs @@ -176,6 +176,34 @@ pub fn to_js_pretty(value: &T) -> Result::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(&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(&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(value: &T) -> Result { + 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(::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 { 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}"#; diff --git a/crates/wasm/src/lib.rs b/crates/wasm/src/lib.rs index af347b06..3e311652 100644 --- a/crates/wasm/src/lib.rs +++ b/crates/wasm/src/lib.rs @@ -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: ` when the payload, the document or the map is refused. + #[wasm_bindgen(constructor)] + pub fn new(bundle: &str) -> Result { + 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")] diff --git a/packages/core-wasm/eslint.config.js b/packages/core-wasm/eslint.config.js index 08c2e32f..bf84073f 100644 --- a/packages/core-wasm/eslint.config.js +++ b/packages/core-wasm/eslint.config.js @@ -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], diff --git a/packages/core-wasm/package.json b/packages/core-wasm/package.json index bdbb5c3e..28c1df67 100644 --- a/packages/core-wasm/package.json +++ b/packages/core-wasm/package.json @@ -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", diff --git a/packages/core-wasm/src/index.ts b/packages/core-wasm/src/index.ts index bd134e96..1b62a47f 100644 --- a/packages/core-wasm/src/index.ts +++ b/packages/core-wasm/src/index.ts @@ -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 = - | { 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 -} - -/** 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 { - 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( - core: CoreModule, - op: string, - input: string, -): CoreOutcome { - return JSON.parse(core.call(op, input)) as CoreOutcome -} - -/** 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' diff --git a/packages/core-wasm/src/node.ts b/packages/core-wasm/src/node.ts new file mode 100644 index 00000000..1087623e --- /dev/null +++ b/packages/core-wasm/src/node.ts @@ -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 { + 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 { + const source = nodeCoreSource('pkg-proofs') + const glue = (await source.importGlue(0)) as ProofModule + await glue.default({ module_or_path: await source.compile() }) + return glue +} diff --git a/packages/core-wasm/src/outcome.ts b/packages/core-wasm/src/outcome.ts new file mode 100644 index 00000000..af3f2510 --- /dev/null +++ b/packages/core-wasm/src/outcome.ts @@ -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 = + | { ok: true; value: T } + | { ok: false; kind: string; detail?: string; found?: number } + +export type CoreFailure = Extract, { 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(text: string): CoreOutcome { + try { + return JSON.parse(text) as CoreOutcome + } catch { + return failure('internal', 'unreadable outcome') + } +} diff --git a/packages/core-wasm/src/runtime.ts b/packages/core-wasm/src/runtime.ts new file mode 100644 index 00000000..2034df5c --- /dev/null +++ b/packages/core-wasm/src/runtime.ts @@ -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 + 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 + /** + * 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 +} + +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 | null = null + private spare: Promise | null = null + private pending: Promise | 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 { + 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 { + 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(op: string, input: string): CoreOutcome { + return this.invoke((glue) => parseOutcome(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(fn: (glue: GlueModule) => CoreOutcome): CoreOutcome { + 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 { + 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 { + 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 { + 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 { + const handle = this.current() + return handle.ok ? { ok: true, value: null } : handle + } + + call(op: string, input: string): CoreOutcome { + const handle = this.current() + if (!handle.ok) return handle + return this.runtime.invoke(() => + parseOutcome(handle.value.call(op, input)), + ) + } + + /** The handle of the live instance; a handle of a dropped instance is never called. */ + private current(): CoreOutcome { + 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 } + }) + } +} diff --git a/packages/core-wasm/tests/facade.test.ts b/packages/core-wasm/tests/facade.test.ts index 271b43a2..186ed660 100644 --- a/packages/core-wasm/tests/facade.test.ts +++ b/packages/core-wasm/tests/facade.test.ts @@ -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)[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/) }) }) diff --git a/packages/core-wasm/tests/global-setup.ts b/packages/core-wasm/tests/global-setup.ts new file mode 100644 index 00000000..704012c8 --- /dev/null +++ b/packages/core-wasm/tests/global-setup.ts @@ -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\``, + ) + } + } +} diff --git a/packages/core-wasm/tests/helpers/core.ts b/packages/core-wasm/tests/helpers/core.ts deleted file mode 100644 index 4a8d57c2..00000000 --- a/packages/core-wasm/tests/helpers/core.ts +++ /dev/null @@ -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', - ) -} diff --git a/packages/core-wasm/tests/panic.test.ts b/packages/core-wasm/tests/panic.test.ts index 113fe2cc..af3e6132 100644 --- a/packages/core-wasm/tests/panic.test.ts +++ b/packages/core-wasm/tests/panic.test.ts @@ -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) diff --git a/packages/core-wasm/tests/runtime.test.ts b/packages/core-wasm/tests/runtime.test.ts new file mode 100644 index 00000000..e16fd099 --- /dev/null +++ b/packages/core-wasm/tests/runtime.test.ts @@ -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 => { + 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 }) + }) +}) diff --git a/packages/core-wasm/tests/serialisation.test.ts b/packages/core-wasm/tests/serialisation.test.ts index 6f854091..387feff5 100644 --- a/packages/core-wasm/tests/serialisation.test.ts +++ b/packages/core-wasm/tests/serialisation.test.ts @@ -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(core, 'pretty_json', text) +function prettyByCore(core: CoreRuntime, text: string): string { + const outcome = core.call('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( - core, + const core = await nodeCoreRuntime() + const bare = core.call( '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( - core, + const full = core.call( 'report_zone', JSON.stringify({ viewId: 'main', @@ -93,8 +91,7 @@ describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => { }, }) - const sheet = callCore( - core, + const sheet = core.call( '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 }), ) diff --git a/packages/core-wasm/tests/size.test.ts b/packages/core-wasm/tests/size.test.ts index 1dc8671a..982f06c1 100644 --- a/packages/core-wasm/tests/size.test.ts +++ b/packages/core-wasm/tests/size.test.ts @@ -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) }) diff --git a/packages/core-wasm/tests/wasm-stamp.d.ts b/packages/core-wasm/tests/wasm-stamp.d.ts new file mode 100644 index 00000000..185ae3b6 --- /dev/null +++ b/packages/core-wasm/tests/wasm-stamp.d.ts @@ -0,0 +1,3 @@ +declare module '*/scripts/wasm-stamp.mjs' { + export function wasmStamp(): string +} diff --git a/packages/core-wasm/vitest.config.ts b/packages/core-wasm/vitest.config.ts index f6374039..cfd8f913 100644 --- a/packages/core-wasm/vitest.config.ts +++ b/packages/core-wasm/vitest.config.ts @@ -5,5 +5,6 @@ export default defineConfig({ environment: 'node', globals: true, include: ['tests/**/*.test.ts'], + globalSetup: ['tests/global-setup.ts'], }, }) diff --git a/scripts/wasm-build.sh b/scripts/wasm-build.sh index 98e308b9..c5514b62 100755 --- a/scripts/wasm-build.sh +++ b/scripts/wasm-build.sh @@ -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" diff --git a/scripts/wasm-stamp.mjs b/scripts/wasm-stamp.mjs new file mode 100644 index 00000000..0cd52ace --- /dev/null +++ b/scripts/wasm-stamp.mjs @@ -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`) +}