From d6b5edb626a09514465bd9d5e9268cbc646178ef Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 15 Oct 2026 00:07:20 +0200 Subject: [PATCH] =?UTF-8?q?docs(docs):=20R3=20in=20RUST.md=20=C2=A79,=20CL?= =?UTF-8?q?AUDE.md,=20CHANGELOG,=20PDF=20import=20gate=20note,=20packages?= =?UTF-8?q?=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 7 ++ CLAUDE.md | 21 ++-- docs/development/PDF_IMPORT_HARDENING.md | 5 +- docs/development/RUST.md | 148 +++++++++++++++++++++++ packages/README.md | 8 +- 5 files changed, 177 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a975904..0b0e9f3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ Versions follow [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Changed (Rust R3, anatomy core, 2026-10-15) + +- **The editor canvas draws what the Rust core composes** (`crates/core/src/anatomy`): one SVG reader for every drawing the product shows (bounds checked by a markup scanner before any XML parser, the engine's allowlist matched the same way, a reference graph refusing cycles and expansions over 50,000 elements, a serialiser that re-reads to the same tree), the annotation layer and the view composition, reached through the new `view.canvas` operation and memoised per view. The canvas keeps its in-place selection styling, click and tooltip delegation. The browser-side denylist and the app's dependency on the TypeScript renderer are gone; the PDF engine and the curation pipeline keep the TypeScript renderer until R4 and R5. +- **No visible change**, proven first with the TypeScript: canvas trees of both views and 28 selection states, layer trees with attribute order, 36 PDF highlight compositions, 36 hostile SVGs and 10 generated floods, the 4 product SVGs untouched; in Chromium 156 the live canvas trees equal the frozen ones and 30 screenshots (desktop and phone) are pixel-identical before and after. The Step 6 goldens are untouched. +- Declared differences, none on a product drawing: elements outside the SVG namespace removed, comments dropped, no `class`/`style` on the inline root, stricter ids, text only in `title`/`desc` (4 KiB each), floods and reference cycles refused, a product drawing the allowlist would alter refused at load instead of silently cut, a canvas that cannot be composed shows the existing degraded notice with a retry (`docs/development/RUST.md` §9.4). +- `docs/ANNOTATION-RENDERING.md` rewritten to describe the code exactly (no rendering change). Module 396 KB gzip (+56 KB, budget 600 KB). + ### Security (maintenance after R2, 2026-10-14) - **Worker TLS: rustls 0.23.45 → 0.23.46** (`Cargo.lock` only, through `ureq` 3.4.2): RUSTSEC-2026-0346 (session values' `Debug` printed TLS secrets), 0347 (ECH rejection), 0348 (Brotli certificate decompression), 0349 (unauthenticated ServerHello pinning the next key exchange group). None reached the worker as configured (ring provider without ML-KEM groups, no ECH, no `brotli` feature, sessions never printed); the bump removes them anyway. No API or feature change; the patch also fixes `StreamOwned` flushing and surfaces a connection's fatal error on the next write. `cargo deny check advisories` clean. diff --git a/CLAUDE.md b/CLAUDE.md index 24d7086c..1ac6949d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -219,7 +219,7 @@ faunosteo/ │ │ ├─ reportStore.ts ← Zustand store (Report v3, core-built reports, actions answer { ok }) + persistence.ts (raw texts, quarantine keys) │ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage) │ │ └─ practitionerCache.ts ← localStorage prefill -│ ├─ anatomy/drawing.ts ← sanitised asset + generated annotation layer → inline per view +│ ├─ anatomy/drawing.ts ← the core's composed view (`view.canvas`) → DOMParser → importNode (R3; no sanitiser here) │ ├─ components/ │ │ ├─ ui/{Button,ButtonLink,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip,Icon,FormField,Notice}.tsx │ │ ├─ canvas/{AnatomyCanvas,DetailModal}.tsx @@ -258,7 +258,7 @@ faunosteo/ ├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only): anatomical-sheet (document, integrity rules, sheet-index), report (v3, v2 migration, rebase), archive (sheet snapshot, envelope v1, branding, labels, layered reader) │ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules │ └─ tests/{fixtures/horse-slice.ts,*.test.ts} -├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, pure annotation-layer renderer + view composer (`./render`) +├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, frozen TS annotation-layer renderer + view composer (`./render`: PDF engine until R4, pipeline until R5; the app no longer depends on it) ├─ packages/pdf/ ← @faunosteo/pdf: browser-free PDF engine — src/{export,read,text,branding}.ts, attachment/, svg/{parse,sanitize,view}.ts, render/, i18n/; tests reproduce the Step 6 goldens │ ├─ src/legacy/{svg,catalog,regions,ids,report,importer}.ts, src/cli/import-equine.ts │ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft @@ -279,7 +279,7 @@ faunosteo/ ├─ packages/README.md ← shared packages index ├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + Node source, pkg/ shipped and pkg-proofs/ (built, git-ignored, BUILD_STAMP), ts-rs types (committed), frozen N-1 reader (tests/n-1), tests ├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root) -│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing); tests/{oracles,conformance,fixtures} frozen from the TypeScript; no I/O, no clock (lint-enforced) +│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing); tests/{oracles,conformance,fixtures} frozen from the TypeScript (oracles/r3, fixtures/svg/hostile); no I/O, no clock (lint-enforced) │ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, SheetHandle; trap exports in the proofs build only) │ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh ├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the real-stack avatar e2e @@ -311,7 +311,9 @@ Sheet loading (Rust core, RUST.md §8) document and migration map, index → index_data → SheetIndex (tables only) + ops (sheet-bound core calls) SVG interaction - → AnatomyCanvas builds the view: sanitised asset + renderAnnotationLayer() (markers from the document; TS until R3) + → AnatomyCanvas builds the view once per (sheet, view): index.canvasSvg(view) = core `view.canvas` (the drawing read + once at sheet load: prescan caps → roxmltree → allowlist → reference graph; framed + annotation layer) → DOMParser + → importNode; data-state restyled in place; a failed build shows the degraded notice with a retry → delegated click on [data-anno-id] → sheet.ops.zoneClick(observation, id) (one core call: decision + new observation) → open_view → DetailModal (same drawing, view_box crop, or the view's own asset) → open_vertebra_picker (initial selection from the core) / open_laterality_picker (sides present) → pickers @@ -395,8 +397,11 @@ Database (Supabase) - `docs/design/` holds the owner-validated mockups (Step 7 file = target for the whole SaaS shell: sidebar entries, dashboard tiles, Mon compte tabs, mobile tab bar). Any new screen follows them; elements they show that no step has built yet are listed in `docs/design/README.md` with their owning step. A redesign needs a new validated file there first. ### Annotation rendering -- docs/ANNOTATION-RENDERING.md is the source of truth: the drawing carries no annotation element, the app draws - the markers from the document (`@faunosteo/anatomy/render`), with the attributes listed there +- docs/ANNOTATION-RENDERING.md is the source of truth: the drawing carries no annotation element, the markers are + drawn from the document (Rust core for the canvas since R3, `crates/core/src/anatomy`; the frozen TS renderer + `@faunosteo/anatomy/render` for the PDF engine and the pipeline until R4/R5, same output), with the attributes listed there +- Every SVG the product draws goes through the core's one reader (`anatomy::svg::read_svg`): caps before any parse, + allowlist, reference graph; a product drawing with anything removed is refused at load, never repaired - Never rely on element id, className or a label for click targeting or behaviour — always `data-anno-id` and the annotation's fields (`laterality`, `vertebral_region_code`, `opens_view_id`) - Marker look (radii, opacities, strokes) is renderer style; colours are document data (`color` on categories @@ -512,8 +517,8 @@ Database (Supabase) Study and roadmap: `docs/development/RUST_ARCHITECTURE_REVIEW.md` (validated with the amendments of Annex C). Done: R0, R1 (worker), R2 (domain core used by the app, -`docs/development/RUST.md` §8). Next: R3 (anatomy core), R4 (PDF core), R5 -(pipeline); release 0.2.0 unaffected. +`docs/development/RUST.md` §8), R3 (anatomy core: SVG reader, layer, composition; editor canvas on it, +RUST.md §9; awaiting the owner's validation). Next: R4 (PDF core), R5 (pipeline); release 0.2.0 unaffected. - Any logic that can run in Rust with no significant loss (features, UX, graphics, data compatibility, security, reliability, useful performance, diff --git a/docs/development/PDF_IMPORT_HARDENING.md b/docs/development/PDF_IMPORT_HARDENING.md index 04da36b3..293236f9 100644 --- a/docs/development/PDF_IMPORT_HARDENING.md +++ b/docs/development/PDF_IMPORT_HARDENING.md @@ -109,6 +109,9 @@ hides its `/Keywords`, so a stripped attachment on such a file reads as observation) so a hostile report cannot freeze the editor before the export's own caps refuse it. - The remaining low findings of the Step 6 audits: `` nesting budget in - the sanitiser (today bounded by the rasterizer), the decoder memory + the sanitiser (today bounded by the rasterizer on the PDF path; since R3 the + Rust reader refuses reference cycles and expansions over 50,000 elements, + `docs/development/RUST.md` §9.2, and the engine gets it when R4 switches it to + that reader: still open for the PDF path), the decoder memory envelope of PNG logos (bounded by the 4096² cap, about 430 MB worst case for four logos). diff --git a/docs/development/RUST.md b/docs/development/RUST.md index 85f5412f..e92fabf5 100644 --- a/docs/development/RUST.md +++ b/docs/development/RUST.md @@ -684,3 +684,151 @@ application itself builds. is the Step 27 follow-up of R0). - The documented CSP refuses the footer's external credit logo (`img-src`), an older matter seen by the proof. + +## 9. R3: the anatomy core in Rust, drawn by the editor canvas (2026-10-15) + +Plan and contract: `.claude/tasks/plans/2026-10-14-rust-r3-anatomy-core.md` +(revision 2 after three plan challenges, 32 findings folded). Status: delivered +on `feature/rust-r3-anatomy-core`, awaiting the owner's validation; not merged. + +### 9.1 What runs in Rust, and who calls it + +| Former TypeScript | Rust (`crates/core/src/anatomy`) | Consumer | +|---|---|---| +| `apps/app/src/anatomy/drawing.ts` denylist + `DOMParser` parse of the asset (deleted) | `svg/{prescan,tree,sanitize,refs,number,serialize}.rs`, `svg::read_svg` | the sheet load (`LoadedSheet`, each drawing read once) | +| `packages/anatomy/src/render/layer.ts` (`renderAnnotationLayer`, `viewBoxOf`) | `layer.rs` | `view.canvas`; the highlight | +| the canvas composition of `drawing.ts` (fresh root, viewBox rules, layer last) | `compose.rs` `compose_canvas` | `view.canvas` → `SheetIndex.canvasSvg` → `AnatomyCanvas` | +| `packages/anatomy/src/render/compose.ts` (`composeViewSvg`, `highlightLayer`, halo) | `compose.rs` `compose_highlight` | none yet: proven against the engine (O3), wired at R4 in R4's snapshot-based call | +| `packages/pdf/src/svg/sanitize.ts` allowlist and value rules | `svg/sanitize.rs` (same lists, same rules, declared additions 9.4) | the canvas now; the engine keeps its TypeScript copy until R4 | + +One facade operation on the sheet handle: `view.canvas { viewId } → { svg }`, +failures `unknown_view`, `no_asset`, `svg_rejected` (reason in `detail`: +`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`, +`too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`, or +`removed ` when the allowlist would take something out of a product +drawing), `invalid_character`. The result is constant for a loaded sheet: +`SheetIndex` memoises it per view; `AnatomyCanvas` parses it with `DOMParser`, +imports it and restyles `data-state` in place as before. + +### 9.2 The SVG reader (`read_svg`) + +1. Bounds before any parser (`prescan.rs`, a markup state machine: comments, + CDATA, PIs and quoted values skipped by the grammar, no regex): 2 MiB, a + leading BOM refused, `` count cap 256. +4. The reference graph (`refs.rs`): tree edges plus every `href`/`xlink:href` + and `url(#id)` to the first element of that id; a cycle is refused, and so + is an expanded size over 50,000 elements (each reference adds its target's + expanded subtree, saturating, iterative, early exit). +5. The serialiser (`serialize.rs`): XML 1.0, `& < > "` and `\t \n \r` as + references in attributes, `& < >` and `\r` in text; a re-read gives the + same tree. A composed view over 4 MiB is refused. + +### 9.3 Proofs and tests (oracles frozen with the TypeScript first) + +- O1 (`apps/app/tests/fixtures/goldens/r3/canvas.*.json`, 47c5f49): the canvas + tree of each view and the layer of 14 state sets per view (the three + reference reports). Green on the Rust composition in cargo + (`tests/anatomy_compose.rs`), in the app suite on the mounted canvas + (`canvas.trees.test.tsx`) and in Chromium 156 on the live page + (`scripts/visual-canvas.mjs dom`): equal for both views. +- O2 (`oracles/r3/layer.json`): 8 layer trees with attribute order (draft + + an edge document: twin radius floor, `1e+21`, path geometry, circle trigger + without a name, colour fallback, laterality): exact, order included. +- O3 (`oracles/r3/highlight.json`): 36 highlighted compositions (every + observation and view of the three reports, an existing nested ``, a + detail view with its own asset and no viewBox): tree-equal. +- O4/O5 (`oracles/r3/sanitiser.json`): 36 hostile files + (`tests/fixtures/svg/hostile`) and 10 generated cases: equal to the + TypeScript verdict or a declared one (9.4); the 4 product SVGs (horse + drawing, partner logo, 2 public logos) untouched, tree-equal. Mutation + checks run on the oracle tests (a cap, the namespace rule, the twin floor, + the halo placement): each mutant failed the suite. +- Shipped wasm (`packages/core-wasm/tests/anatomy.test.ts`): the corpus plus + floods (99,000 nesting levels, 20,001 nodes, 150,000 `<` in a comment, 257 + attributes, 2 MiB + 1, a 12 × 20 `` chain, 1.9 MiB of `>`), each in a + fresh instance: a closed outcome, no trap, slowest 24.9 ms, largest linear + memory growth 10.1 MiB. +- Runtime: the `SheetHandle` constructor's closed refusal (`: ` + from a plain `Error`) is `invalid_sheet`; any other throw (RangeError, + InternalError, a trap) poisons the instance (`runtime.test.ts`). +- Visual, Chromium 156 (`scripts/visual-canvas.mjs`): 30 captures before + (TypeScript canvas) and after (Rust), desktop 1280 × 800 and phone + 390 × 844, no selection, each demo observation active, hover, main and + head: 30/30 pixel-identical. The method's own noise floor: two captures of + the same build 30/30 identical; its classifier flags a 10 × 10 change as a + regression and a one-pixel edge nudge as anti-aliasing. +- The Step 6 goldens (39) and the seed and review-drawing goldens are + untouched: the engine and the pipeline still run the TypeScript renderer. + +### 9.4 Behaviour differences (declared; none touches a product SVG) + +1. An element outside the SVG namespace is removed (``), and + `xlink:href` must be in the xlink namespace whatever its prefix. +2. Comments and processing instructions are dropped; non-whitespace text is + kept only in `title`/`desc`, each at most 4 KiB (longer: refused whole). +3. The root loses `class` and `style` (an inline SVG lives under the page's + CSS: `class="fixed inset-0 …"` would cover the application); an `id` + outside `[A-Za-z_][\w.:-]*` is removed. +4. A reference cycle, an expansion over 50,000 elements, and the floods of + 9.2 step 1 are refused; the TypeScript accepted them (size counted on the + raw text, refused subtrees included). +5. A product drawing the allowlist would alter is refused at sheet load for + the views on that asset (`svg_rejected`, `removed …`); the TypeScript canvas + dropped such parts silently. +6. A label or path the document holds with a code point XML 1.0 cannot carry + is refused (`invalid_character`); the DOM path drew it. +7. When the canvas cannot be composed, it shows the existing degraded notice + (`sheet.core_unavailable`) with "Réessayer" inside the canvas; before R3 a + failure there left it blank (an uncaught error). + +### 9.5 Measurements + +| Measure | Value | +|---|---| +| shipped module | 1,188,740 B raw, **395,771 B gzip -9** (+55.8 KB over R2; budget 600 KB) | +| sheet handle with the drawing read (Node) | 8 to 10 ms | +| `view.canvas` main, first (Node) | 1.2 to 1.4 ms; head warm median 0.85 ms; 143 KiB of SVG | +| Chromium, preview build, CPU × 4, medians of 3 | editor to canvas 503 ms (476 ms before R3); detail open 143 ms (125 ms before R3, runs 109 to 157); browser parse + import of the canvas text 21 ms (22 ms) | +| 50 detail open/close cycles, CPU × 4 | JS heap +0.72 MiB (+0.89 MiB before R3), DOM nodes +0 (+0) | + +### 9.6 TypeScript deleted, kept + +- Deleted: the canvas denylist `sanitizeSvg`, `parseDrawing`, the parse + cache, `assetOfView`, the states input of the canvas build, the + `assets` field of `SheetIndex`, the app's dependency on + `@faunosteo/anatomy`. +- Kept, with their consumers: `packages/anatomy/src/render/**` (PDF engine + until R4, curation pipeline until R5), `packages/pdf/src/svg/**` (engine + until R4), the R3 oracle generators (`packages/anatomy/tests/ + r3.layer-oracles.test.ts`, `packages/pdf/tests/r3.{highlight,sanitiser}- + oracles.test.ts`: they still pass on the TypeScript and keep the freeze + honest until R4/R5). + +### 9.7 Residual risks + +- The engine (PDF) still sanitises with the TypeScript allowlist and has no + reference budget: the `` expansion gate of `PDF_IMPORT_HARDENING.md` + §5 is met in the core, closed for the PDF path only when R4 switches it. +- roxmltree's recursion: safe behind the prescan depth cap; pin the release + with the iterative parser when it ships. +- Firefox and WebKit: not run here (no browser build); the owner's LAN run on + the phone covers WebKit. +- The degraded notice inside the canvas (9.4 item 7) and its wording ("le + moteur … n'a pas pu être chargé") are not tailored to a rejected drawing, + which no shipped sheet can produce today. +- A trigger without a name carries the opened view's French name in both + name attributes (unchanged since Step 5; owner question). diff --git a/packages/README.md b/packages/README.md index 17a0dae7..d72c7f40 100644 --- a/packages/README.md +++ b/packages/README.md @@ -9,7 +9,7 @@ Planned packages and the step that creates each one: | Package | Content | Created at | |---|---|---| | `@faunosteo/domain` | Zod schemas: anatomical sheet document + integrity rules (**created**, Step 4); report document, entitlement capabilities later | Step 4 (sheet model) | -| `@faunosteo/anatomy` | legacy importer (**created**, Step 4b), curation pipeline: changeset → working draft + report migration map (**created**, Steps 4c/5), pure annotation-layer renderer `@faunosteo/anatomy/render` shared with the app (**created**, Step 5) | Step 4b (importer) | +| `@faunosteo/anatomy` | legacy importer (**created**, Step 4b), curation pipeline: changeset → working draft + report migration map (**created**, Steps 4c/5), pure annotation-layer renderer `@faunosteo/anatomy/render` (**created**, Step 5; since R3 used by the PDF engine and the pipeline only, the app canvas draws the Rust core's composition) | Step 4b (importer) | | `@faunosteo/pdf` | browser-free PDF engine (**created**, Step 6): report archive export from explicit inputs (report, sheet snapshot, branding, labels, rasterizer), layered archive reading, SVG sanitiser, page renderers | Step 6 (PDF archives) | | `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) | | `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 | @@ -17,8 +17,10 @@ Planned packages and the step that creates each one: Since R2 the Rust core (`crates/core`) holds the business logic `domain` held for the application (`docs/development/RUST.md` §8); `domain` stays frozen -for the PDF engine, the pipeline and the compare CLI. `anatomy` and `pdf` -follow at R3 and R4 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Part +for the PDF engine, the pipeline and the compare CLI. Since R3 the core also +holds the SVG reader, the annotation layer and the view composition the editor +canvas draws (`RUST.md` §9); `anatomy/render` stays frozen for the engine and the +pipeline. `pdf` follows at R4 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Part VI); each TypeScript package is deleted in the phase that switches its last consumer (`domain` and `anatomy` at R5, `pdf` at R4). | `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web |