Files
faunosteo/.claude/tasks/contracts/2026-10-15-rust-r3-verify.md

51 lines
7.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 `<use>` 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).
- Pass 2 (after the security audit, PASS + 1 MEDIUM + 2 LOW): the prescan searches each closer after its whole opener (`<!-->` desync), `href` locality on ASCII-trimmed text only, root `transform`/`filter`/`mask`/`clip-path` removed; 5 corpus files added (41), the wasm corpus has 49 cases; counts below updated.
- Pass 3 (security pass 2 on the fix: PASS + LOW): `url(` skips CSS whitespace only; corpus 42 files, wasm corpus 50 cases.
- 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 50 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, `<use>` 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: 42 files including url-unicode-space, comment-desync-depth, comment-desync-attributes, href-unicode-space, root-presentation, and 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