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:
1 parent
5fec0654d3
commit
2a38fa37b5
39 files changed
+1913
-1
No files matched your search
@@ -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: '^_' },
|
||||
],
|
||||
},
|
||||
},
|
||||
)
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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',
|
||||
)
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -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',
|
||||
)
|
||||
}
|
||||
@@ -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' })
|
||||
})
|
||||
})
|
||||
@@ -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)
|
||||
})
|
||||
})
|
||||
@@ -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"]
|
||||
}
|
||||
@@ -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";
|
||||
@@ -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, };
|
||||
@@ -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, };
|
||||
@@ -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, };
|
||||
@@ -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'
|
||||
@@ -0,0 +1,9 @@
|
||||
import { defineConfig } from 'vitest/config'
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'node',
|
||||
globals: true,
|
||||
include: ['tests/**/*.test.ts'],
|
||||
},
|
||||
})
|
||||
Reference in new issue
Block a user