chore(workspace): Rust workspace R0 — builder image, core crate (JS-compatible JSON, report contracts, facade), wasm facade, core-wasm package with proofs

This commit is contained in:
bchanot committed 2026-10-13 00:01:25 +02:00
1 parent 5fec0654d3
commit 2a38fa37b5
39 files changed
+1913 -1

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
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/**'] },
{
files: ['**/*.ts'],
extends: [...tseslint.configs.recommended],
languageOptions: {
globals: { ...globals.node, ...globals.es2022 },
},
rules: {
'@typescript-eslint/no-explicit-any': 'warn',
'@typescript-eslint/no-unused-vars': [
'error',
{ argsIgnorePattern: '^_' },
],
},
},
)
+28
View File
@@ -0,0 +1,28 @@
{
"name": "@faunosteo/core-wasm",
"version": "0.1.0",
"private": true,
"description": "Faunosteo core compiled to WebAssembly: loader, generated TypeScript types of the contracts, and the R0 proofs (panic, serialisation, size)",
"license": "MIT",
"type": "module",
"exports": {
".": "./src/index.ts",
"./types": "./types/index.ts"
},
"scripts": {
"typecheck": "tsc -p tsconfig.json --noEmit",
"test": "vitest",
"test:run": "vitest run",
"lint": "eslint . --max-warnings 0",
"build": "tsc -p tsconfig.json --noEmit"
},
"devDependencies": {
"@faunosteo/domain": "workspace:*",
"@types/node": "^20.19.41",
"eslint": "^9.17.0",
"globals": "^15.14.0",
"typescript": "^5.7.2",
"typescript-eslint": "^8.19.0",
"vitest": "^3.2.7"
}
}
+72
View File
@@ -0,0 +1,72 @@
/**
* Loader of the Faunosteo core module (wasm-bindgen `--target web` output under `pkg/`,
* built by `pnpm wasm:build`, git-ignored).
*
* 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.
*/
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)
}
+56
View File
@@ -0,0 +1,56 @@
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { callCore, loadCore } from '../src/index'
import { coreBuilt } from './helpers/core'
const CORE_MANIFEST = new URL(
'../../../crates/core/Cargo.toml',
import.meta.url,
)
const WORKSPACE_MANIFEST = new URL('../../../Cargo.toml', import.meta.url)
describe.skipIf(!coreBuilt)('core facade (wasm)', () => {
it('reports the workspace version of the core', async () => {
const core = await loadCore()
const workspace = readFileSync(fileURLToPath(WORKSPACE_MANIFEST), 'utf8')
const version = /\[workspace\.package\][^[]*?version = "([^"]+)"/s.exec(
workspace,
)?.[1]
expect(version).toBeDefined()
expect(readFileSync(fileURLToPath(CORE_MANIFEST), 'utf8')).toContain(
'version.workspace = true',
)
expect(core.core_version()).toBe(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({
ok: false,
kind: 'unknown_op',
})
expect(callCore(core, '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',
)
}
})
})
+13
View File
@@ -0,0 +1,13 @@
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',
)
}
+52
View File
@@ -0,0 +1,52 @@
/**
* R0 proof: on wasm32 a Rust panic is a trap (`WebAssembly.RuntimeError`), the shadow
* stack overflow is a trap too (no silent corruption), and a trapped instance must never be
* reused: review III.3 rule 5 (poison and re-instantiate) rests on these three facts.
*
* Observed at R0 (Node 24, wasm-bindgen 0.2.129):
* - after a plain panic the same instance still answers calls, which is the dangerous case:
* the shadow stack pointer was never unwound, so later frames run in a shifted stack;
* - after a stack-exhaustion trap the next call on the same instance fails in the allocator
* (`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'
describe.skipIf(!coreBuilt)('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)
})
it('traps on shadow stack exhaustion instead of returning garbage', async () => {
const core = await loadCore()
expect(core.recurse_for_test(100)).toBe(100)
// 2 000 000 frames of at least 128 bytes exceed the 1 MiB shadow stack by far.
expect(() => core.recurse_for_test(2_000_000)).toThrow(
WebAssembly.RuntimeError,
)
})
it('leaves a stack-trapped instance unusable and recovers with a fresh instance', async () => {
const poisoned = await loadCore()
expect(() => poisoned.recurse_for_test(2_000_000)).toThrow(
WebAssembly.RuntimeError,
)
expect(() => poisoned.core_version()).toThrow(WebAssembly.RuntimeError)
const fresh = await loadCore()
expect(fresh.core_version()).toMatch(/^\d+\.\d+\.\d+$/)
expect(JSON.parse(fresh.call('pretty_json', '[1.0]'))).toEqual({
ok: true,
value: '[\n 1\n]',
})
})
it('may keep answering after a plain panic, which is why no instance is reused after any trap', async () => {
const poisoned = await loadCore()
expect(() => poisoned.panic_for_test()).toThrow(WebAssembly.RuntimeError)
// Not asserted either way: the instance's stack pointer is undefined from here on.
const fresh = await loadCore()
expect(fresh.core_version()).toMatch(/^\d+\.\d+\.\d+$/)
})
})
@@ -0,0 +1,115 @@
/**
* R0 proof: the core's JSON output is byte-identical to `JSON.stringify(v, null, 2)` on the
* real documents, optional fields stay absent and nullable fields stay `null`, and the
* current Zod readers accept what the core writes (review I.2, D-R11).
*/
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { ReportZoneSchema, SheetRefSchema } from '@faunosteo/domain'
import type { ReportZone, SheetRef } from '../types/index'
import { callCore, loadCore, type CoreModule } from '../src/index'
import { coreBuilt } from './helpers/core'
const FIXTURES = [
'apps/app/tests/fixtures/report-v3.demo.json',
'apps/app/tests/fixtures/report-v2.full.json',
'supabase/seed/anatomical-sheets/equine/draft/document.json',
'supabase/seed/anatomical-sheets/equine/draft/report-migration-map.json',
]
const NUMBER_CASES = [
1523, 1715.4285714285713, 0.85, 1e21, 1e-7, 0.000001, -0,
123456789012345680000, 5e-324, 1.7976931348623157e308, 100, -2.5, 0.1,
1.5e300, 12345678901234567890,
]
function repoFile(relative: string): string {
return readFileSync(
fileURLToPath(new URL(`../../../${relative}`, import.meta.url)),
'utf8',
)
}
function prettyByCore(core: CoreModule, text: string): string {
const outcome = callCore<string>(core, 'pretty_json', text)
if (!outcome.ok) throw new Error(`${outcome.kind}: ${outcome.detail ?? ''}`)
return outcome.value
}
describe.skipIf(!coreBuilt)('serialisation contract (wasm)', () => {
it.each(FIXTURES)(
'%s: core pretty output equals JSON.stringify(…, null, 2)',
async (relative) => {
const core = await loadCore()
const text = repoFile(relative)
const expected = JSON.stringify(JSON.parse(text), null, 2)
expect(prettyByCore(core, text)).toBe(expected)
},
)
it('prints every number as JavaScript does', async () => {
const core = await loadCore()
const text = JSON.stringify(NUMBER_CASES)
expect(prettyByCore(core, text)).toBe(
JSON.stringify(JSON.parse(text), null, 2),
)
})
it('writes optional fields absent and nullable fields null, readable by the Zod schemas', async () => {
const core = await loadCore()
const bare = callCore<ReportZone>(
core,
'report_zone',
JSON.stringify({ annotationId: 'hip', viewId: 'main' }),
)
expect(bare).toEqual({
ok: true,
value: { annotationId: 'hip', viewId: 'main' },
})
if (!bare.ok) return
expect(Object.keys(bare.value)).toEqual(['annotationId', 'viewId'])
expect(ReportZoneSchema.parse(bare.value)).toEqual(bare.value)
const full = callCore<ReportZone>(
core,
'report_zone',
JSON.stringify({
viewId: 'main',
annotationId: 'hip',
side: 'left',
unresolved: true,
extra: 1,
}),
)
expect(full).toEqual({
ok: true,
value: {
annotationId: 'hip',
viewId: 'main',
side: 'left',
unresolved: true,
},
})
const sheet = callCore<SheetRef>(
core,
'sheet_ref',
JSON.stringify({
sheetId: 'faunosteo-cheval',
versionId: null,
documentSha256: 'a'.repeat(64),
}),
)
expect(sheet.ok && sheet.value.versionId).toBeNull()
if (sheet.ok) expect(SheetRefSchema.parse(sheet.value)).toEqual(sheet.value)
const refused = callCore(
core,
'report_zone',
JSON.stringify({ annotationId: 'a', viewId: 'v', unresolved: false }),
)
expect(refused).toMatchObject({ ok: false, kind: 'invalid_shape' })
})
})
+26
View File
@@ -0,0 +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).
*/
import { readFileSync } from 'node:fs'
import { gzipSync } from 'node:zlib'
import { coreWasmPath, loadCore } from '../src/index'
import { coreBuilt } from './helpers/core'
/** 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)', () => {
it('stays under the compressed budget and reports its numbers', async () => {
const bytes = readFileSync(coreWasmPath())
const gzip = gzipSync(bytes, { level: 9 }).length
const started = performance.now()
await loadCore()
const instantiateMs = performance.now() - started
console.info(
`[core-wasm] faunosteo_wasm_bg.wasm: ${bytes.length} bytes raw, ${gzip} bytes gzip-9, instantiate ${instantiateMs.toFixed(1)} ms`,
)
expect(gzip).toBeLessThanOrEqual(COMPRESSED_BUDGET_BYTES)
})
})
+21
View File
@@ -0,0 +1,21 @@
{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noImplicitReturns": true,
"skipLibCheck": true,
"esModuleInterop": true,
"resolveJsonModule": true,
"isolatedModules": true,
"types": ["node", "vitest/globals"],
"noEmit": true
},
"include": ["src", "tests", "types"],
"exclude": ["node_modules", "pkg"]
}
+6
View File
@@ -0,0 +1,6 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* Side of a bilateral zone.
*/
export type LateralSide = "left" | "right";
+17
View File
@@ -0,0 +1,17 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { LateralSide } from "./LateralSide";
import type { Vertebra } from "./Vertebra";
/**
* A zone of an observation. Unknown keys are ignored on input, as the Zod schema strips
* them; optional fields are written only when set.
*/
export type ReportZone = { annotationId: string, viewId: string, side?: LateralSide, vertebrae?: Array<Vertebra>,
/**
* Annotation name at selection time (or legacy name at migration).
*/
labelFrSnapshot?: string, labelEnSnapshot?: string,
/**
* Set by the migration when the legacy id has no canonical annotation.
*/
unresolved?: true, };
+14
View File
@@ -0,0 +1,14 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* Reference of the anatomical sheet a report was written against (`Report.sheet`).
*/
export type SheetRef = { sheetId: string,
/**
* Database version id once the sheet lives in the database; `null` for a bundled draft.
*/
versionId: string | null,
/**
* sha256 of the document file the report was written against.
*/
documentSha256: string, };
+6
View File
@@ -0,0 +1,6 @@
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* One vertebra of a spine zone: the region code and the 1-based index in that region.
*/
export type Vertebra = { region: string, index: number, };
+6
View File
@@ -0,0 +1,6 @@
// Types of the core contracts, generated by ts-rs from crates/core (`pnpm rust:check`
// regenerates them; CI fails when the committed files drift from the Rust structs).
export type { LateralSide } from './LateralSide'
export type { ReportZone } from './ReportZone'
export type { SheetRef } from './SheetRef'
export type { Vertebra } from './Vertebra'
+9
View File
@@ -0,0 +1,9 @@
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
environment: 'node',
globals: true,
include: ['tests/**/*.test.ts'],
},
})