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

+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)
})
})