diff --git a/.claude/tasks/contracts/2026-10-15-rust-r3-verify.md b/.claude/tasks/contracts/2026-10-15-rust-r3-verify.md new file mode 100644 index 00000000..86e6de86 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-15-rust-r3-verify.md @@ -0,0 +1,48 @@ +# CONTRACT — Rust R3: anatomy core (SVG reader, layer, composition) and the editor canvas on it +- date: 2026-10-15 | flow: feature branch, plan + 3 challenges, verifier gate | branch: feature/rust-r3-anatomy-core +- status: dispatched after the code, test and doc commits +- spec: owner brief 2026-10-14 §2–§12 (R3); plan `.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md` rev 2 (§2 decisions C1–C8, §3 oracles O1–O6, §5 end criteria); `docs/development/RUST.md` §9 +- diff range: develop..HEAD (run every CHECK from the repository root; `. scripts/rust-env.sh` first for cargo) + +## REQUEST (IMMUTABLE) +Migrate the anatomy core to Rust (review R3 scope): SVG analysis, anatomical tree building and manipulation, allowlist SVG sanitisation, view serialisation, marker rendering, view composition, highlights, the editor canvas adapted to the Rust core's results, integrated in crates/core and the wasm facade. React and the DOM keep their UI duties; the TypeScript PDF engine stays until R4 and the curation pipeline keeps its parts until R5; no TypeScript still consumed by those later steps deleted. Not a functional or graphic redesign. Visual parity mandatory: freeze the reference renderings before modifying the current engine (three reference reports, Step 6 golden views, main and detail views, markers and annotations, selections and highlights, laterality, vertebral zones, dimensions and positions, click behaviour); compare SVG/DOM trees by structure and semantic properties, not arbitrary attribute order; add real-browser visual comparisons distinguishing anti-aliasing from real regressions; no intentional graphic difference without the owner's prior validation. SVG security: element and attribute allowlist; scripts, JavaScript events and dangerous external references refused; internal references controlled; DTD and forbidden entities refused; size, element count, depth, complexity and `` reference limits; malformed documents handled; ids needed by anatomical interactions kept; critical size and depth limits applied before any XML analysis that could consume excessive resources; no regex alone for structure; tested on hostile inputs; the allowlist must not silently remove a useful element of existing sheets (conflict → documented and owner asked). Preserve annotation ids, data-anno-id, zone references, SVG↔findings mapping, detail views, anatomical versions, archived snapshots, v2/v3 archives; never regenerate goldens to pass tests. Measure the module size (budget 600 KB gzip served; report a significant increase before keeping it), load time, memory, fluidity. Run native Rust tests, wasm facade tests, TS/Rust parity, frozen SVG oracles, hostile SVG and sanitisation security tests, annotation and interaction tests, browser rendering tests, report non-regression, PDF export/import tests, `pnpm check:all`. Do not merge R3 before the owner's validation; do not start R4; no production or release 0.2.0 change. + +## CLARIFICATIONS +- `apps/app/tests/unit/canvas.trees.test.ts` is renamed to `.tsx` (it now mounts the canvas): a rename, no test deleted. +- The sanitiser oracle (`oracles/r3/sanitiser.json`) was regenerated as corpus files were added; the TypeScript it runs (`packages/pdf/src`, `packages/anatomy/src`) is unchanged on the branch (criterion 4), so every regeneration is the same TypeScript's verdict. `highlight.json` gained `edgeDocument` only; its cases and sanitised trees are unchanged since d1aa35e (criterion 4). +- Visual screenshots are uncommitted by design (plan O6); their result is recorded in RUST.md §9.3. + +## ACCEPTANCE CRITERIA +1. The native Rust gate is green. + CHECK: bash scripts/rust-check.sh > /tmp/r3-verify-rust.log 2>&1; echo "exit $?" + EXPECT: exit 0 +2. The R3 cargo suites pass: sanitiser verdicts (O4/O5), layer (O2), compositions (O1 + O3), facade op. + CHECK: . scripts/rust-env.sh && cargo test -p faunosteo-core --test svg_sanitiser --test anatomy_layer --test anatomy_compose --test anatomy_canvas_op 2>&1 | grep "test result" | awk '{s+=$4; f+=$6} END {print s, f}' + EXPECT: 11 0 +3. The frozen R3 oracles of the canvas and the layer are unchanged since their freeze commits, and the highlight oracle's cases too. + CHECK: git diff --stat 47c5f49 -- apps/app/tests/fixtures/goldens/r3/ | wc -l; git diff --stat 969b872 -- crates/core/tests/oracles/r3/layer.json | wc -l; python3 -c "import json,subprocess;o=json.loads(subprocess.check_output(['git','show','d1aa35e:crates/core/tests/oracles/r3/highlight.json']));n=json.load(open('crates/core/tests/oracles/r3/highlight.json'));print(o['cases']==n['cases'] and o['sanitized']==n['sanitized'])" + EXPECT: 0 / 0 / True +4. The TypeScript renderer and engine are unchanged, and so are the Step 6 and R2 goldens and the seed (no golden regenerated). + CHECK: git diff --stat develop -- packages/pdf/src packages/anatomy/src | wc -l; git diff --stat develop -- apps/app/tests/fixtures/goldens/step6 apps/app/tests/fixtures/goldens/r2 supabase/seed | wc -l + EXPECT: 0 / 0 +5. One sanitiser for the canvas: the app has no denylist, no parse of its own and no dependency on the TypeScript renderer. + CHECK: grep -rnE "sanitizeSvg|parseDrawing|@faunosteo/anatomy" apps/app/src | wc -l; grep -c "@faunosteo/anatomy" apps/app/package.json + EXPECT: 0 / 0 +6. The size and depth bounds run before any parser. + CHECK: grep -n "prescan(text, &SVG_CAPS)?;" crates/core/src/anatomy/svg/tree.rs; grep -n "roxmltree::Document::parse_with_options" crates/core/src/anatomy/svg/tree.rs + EXPECT: the prescan line number is lower than the parse line number +7. The rendering contract was rewritten before the canvas switched. + CHECK: git merge-base --is-ancestor 4e01710 09a6cf7 && echo "doc first" + EXPECT: doc first +8. The Node gate is green on the rebuilt module, with the new suites. + CHECK: bash scripts/wasm-build.sh > /tmp/r3-verify-wasm.log 2>&1; grep "bytes raw" /tmp/r3-verify-wasm.log; ./node_modules/.bin/pnpm check > /tmp/r3-verify-check.log 2>&1; echo "exit $?"; grep -E "(apps/app|packages/core-wasm|packages/pdf|packages/anatomy) test:run: Tests" /tmp/r3-verify-check.log + EXPECT: gzip under 600000 bytes / exit 0 / app 352, core-wasm 29, pdf 140, anatomy 131, all passed +9. The hostile corpus runs through the shipped wasm under the stated budgets, and the canvas composes within its own. + CHECK: grep -E "R3 hostile corpus|R3 sheet handle" /tmp/r3-verify-check.log + EXPECT: a hostile-corpus line with 44 cases, slowest under 150 ms, largest growth under 32 MiB; a sheet-handle line with a warm head median under 15 ms +10. The hostile corpus covers the owner's classes (scripts, events, external and data references, DTD/entities, depth, element count, `` count, cycles and expansion, malformed, namespaces, CSS, size). + CHECK: ls crates/core/tests/fixtures/svg/hostile | wc -l; ls crates/core/tests/fixtures/svg/hostile | tr '\n' ' ' + EXPECT: 36 files including script, events, script-urls, external-use, data-and-images, external-urls, doctype-entities, malformed, namespaces, css, use-self-cycle, use-mutual-cycle, root-class-style, long-title +11. The docs record the phase: RUST.md §9 (proofs, measurements, differences, risks), CHANGELOG, CLAUDE.md map. + CHECK: grep -c "^## 9. R3" docs/development/RUST.md; grep -c "Rust R3, anatomy core" CHANGELOG.md; grep -c "anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose}" CLAUDE.md + EXPECT: 1 / 1 / 1