docs(docs): R3 in RUST.md §9, CLAUDE.md, CHANGELOG, PDF import gate note, packages README

This commit is contained in:
bchanot committed 2026-10-15 00:07:20 +02:00
1 parent 967c71c31e
commit d6b5edb626
5 files changed
+177 -12

No files matched your search

+7
View File
@@ -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.
+13 -8
View File
@@ -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 <svg> 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,
+4 -1
View File
@@ -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: `<use>` 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).
+148
View File
@@ -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 <names>` 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, `<!DOCTYPE`/`<!ENTITY` anywhere, depth 64, 20,000
elements, 256 attributes per element and 100,000 in all, 16 namespace
declarations, 100,000 raw `<` and 200,000 raw `=`. Reason: roxmltree 0.21.1
builds its tree recursively (measured: a 1 MiB stack overflows between
1,000 and 3,000 nesting levels; the iterative fix is unreleased), and it
pre-allocates on the raw `<`/`=` counts, checks duplicate attributes
quadratically and copies inherited namespaces per declaring element.
2. roxmltree 0.21.1 (DTD refused, node limit 200,000 as a backstop) into the
core's own tree, names as written (the allowlist matches qualified names
like the engine).
3. The allowlist (`sanitize.rs`): the engine's 28 elements, 74 attributes, 27
presentation attributes and value rules (no backslash, every `url(` local,
`href` to `#id` only, `style` without forbidden tokens or functions, the
`stdDeviation` clamp with JavaScript `Number()` reproduced by hand), and the
`<use>` 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 `<defs>`, 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 `<use>` 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 (`<kind>: <detail>`
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 (`<path xmlns="…">`), 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 `<use>` 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).
+5 -3
View File
@@ -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 |