From 741c25c4646638b9ac698eecfa337c65042ba419 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:14:23 +0100 Subject: [PATCH] =?UTF-8?q?docs(docs):=20V1-2.2=20RUST.md=20=C2=A712,=20co?= =?UTF-8?q?ntract=20decisions,=20core=20pointers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RUST.md §12 records the authoring core, its proofs, measures and residual risks. The contract records the owner's V1-2.2 answers (§17.4): editor exports supplied by the owner, the strict-parse code, the draft load rule; CLAUDE.md and the sheet-model rule point to it. --- .claude/rules/sheet-model.md | 5 + CLAUDE.md | 4 +- docs/development/RUST.md | 116 +++++++++++++++++++++ docs/development/V1-2_ANATOMICAL_SHEETS.md | 24 ++++- 4 files changed, 144 insertions(+), 5 deletions(-) diff --git a/.claude/rules/sheet-model.md b/.claude/rules/sheet-model.md index a8598a82..6ceff042 100644 --- a/.claude/rules/sheet-model.md +++ b/.claude/rules/sheet-model.md @@ -26,3 +26,8 @@ paths: ["crates/core/src/domain/sheet/**", "docs/development/ANATOMICAL_SHEET_MO editors upload from the application after the core's cleaning, and the worker verifies every submitted revision (M6). - Omitted `review_status` means `inherited` (`#[serde(default)]`): any check on statuses treats an absent value as `inherited`. +- Since V1-2.2 the core also holds the review model (`review.rs`: groups, digests, `coverable`, change list), the server + verdict (`verdict.rs`, the shape the M5 SQL reads; never exported to the browser), the document measure (`size.rs`: + PostgreSQL's `jsonb` text, never `JSON.stringify`), `PreviewSheet` and the editor's commands (`edit.rs`, the §6.6 + marking rules). A change to the SVG reader, the rules, the caps, the fingerprint or the digests is a core change + (contract §6.4: the release withdraws open rounds). RUST.md §12. diff --git a/CLAUDE.md b/CLAUDE.md index 35fd63bc..9fe3bb0f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -284,8 +284,8 @@ faunosteo/ ├─ packages/README.md ← shared packages index ├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + CoreExportSession (R4.6) + 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), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), pdf/{read,json_js,import,write,compare} (R4: reader, writer and session, the archive check tool behind feature `cli`), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing), curation/{text,ids,prettier_json,markdown,report_guard,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL, CHANGELOG, REVIEW-REPORT, review drawings), curation/upload.rs (R5.5, feature `upload`: the upload rules, pure) + bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`) + bin/upload_sheet_assets/ (`pnpm assets:upload`, ureq; the three tools allowed std::fs); tests/{oracles,conformance,fixtures,pdf/LEDGER.tsv} frozen from the TypeScript (oracles/r3, oracles/r4, 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) +│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules; sheet/{size,keys,caps,review,report,verdict,preview,edit} since V1-2.2: server document measure, review groups and digests, the server verdict, PreviewSheet, the editor's commands, RUST.md §12), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize,clean},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), pdf/{read,json_js,import,write,compare} (R4: reader, writer and session, the archive check tool behind feature `cli`), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing), curation/{text,ids,prettier_json,markdown,report_guard,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL, CHANGELOG, REVIEW-REPORT, review drawings), curation/upload.rs (R5.5, feature `upload`: the upload rules, pure) + bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`) + bin/upload_sheet_assets/ (`pnpm assets:upload`, ureq; the three tools allowed std::fs); tests/{oracles,conformance,fixtures,pdf/LEDGER.tsv} frozen from the TypeScript (oracles/r3, oracles/r4, fixtures/svg/hostile); no I/O, no clock (lint-enforced) +│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, SheetHandle, PreviewBuilder → PreviewSheet, clean_svg; 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,report-compare,import-equine,upload-sheet-assets,sheet-assets-e2e,floor-clarification-check}.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, the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`) ├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin diff --git a/docs/development/RUST.md b/docs/development/RUST.md index db4cee89..e0ffae18 100644 --- a/docs/development/RUST.md +++ b/docs/development/RUST.md @@ -3832,3 +3832,119 @@ back must recognise both conventions before any public exposure; tested by `r5_6 checks before public exposure (`confirm_sheet_asset_upload`); the accepted LOW items of §11.16 to §11.22. Once the generators are gone, a change of `curation/changes.json` cannot re-freeze `pipeline.json` or the synthetic oracles: the Rust tests that pin the real draft (46 changes, 825 records, the 612 fates, the fingerprints) then need an owner decision on a new baseline. + +## 12. V1-2.2: the sheet authoring core (2026-10-29) + +Owner brief « Autorisation de démarrer V1-2.2 » (V1-2.1 VERIFIED at ac71c5b), contract +`docs/development/V1-2_ANATOMICAL_SHEETS.md` §16.3. No SQL, no screen, no DEV operation. Owner answers taken before the +code (2026-10-29): the editors' exports come from the owner (cairo and ImageMagick exports committed meanwhile); a +document that does not read strictly fails as `verification.integrity.document` (§6.5); a draft preview reports caps and +missing drawings, a published or deprecated one refuses them. + +### 12.1 What runs in Rust, and who calls it + +| Module (`crates/core/src`) | What | Consumer | +|---|---|---| +| `domain/sheet/size.rs` | the server's document measure, `octet_length(content::text)`: `jsonb` text form (`": "`, `", "`, PostgreSQL's string escapes, numbers as `numeric` prints them, never an exponent), lengths summed in one walk | the verdict, `preview.state` (the validation panel's « taille ») | +| `domain/sheet/keys.rs` | `ElementKey` (sheet, reference, region, annotation category, view, annotation, zone, finding path), the marked elements in document order | edit commands, change list, groups | +| `domain/sheet/caps.rs` | `CapsReport`: every `SnapshotCaps` limit plus the 2 MiB document cap, the exceeded names | verdict, preview | +| `domain/sheet/review.rs` | completeness (markings, vet referrals, uncited categories and nodes), review groups (`general`, `view:`, `zone:`, removal groups) with digests and `coverable`, the change list against a base | verdict, preview | +| `domain/sheet/report.rs` | `SheetReport`: measure, issues (the 21 rules plus `annotation.geometry.missing`), caps, completeness, groups | verdict, preview | +| `domain/sheet/verdict.rs` | `compute_verdict`: pure, bound to sheet, version, revision and review; closed codes; the shape the M5 SQL reads | the worker's keyless child (V1-2.3); not exported to the browser (O15) | +| `domain/sheet/preview.rs` | `PreviewSheet`: drawings hashed against their rows and read once per sha256, draft / published / deprecated, `replace_document`, `add_drawing`, `state` | wasm `PreviewBuilder` → `PreviewSheet` (V1-2.5 catalogue, V1-2.6 editor) | +| `domain/sheet/edit.rs` | `apply_edit` (insert, update, remove, move, set_status, mark_reviewed) with the §6.6 marking rules; `dependents` | free ops `sheet.edit`, `sheet.dependents` | +| `anatomy/svg/clean.rs`, `sanitize.rs` | `clean_svg(bytes)`: clean / cleanable / rejected; the sanitiser's walk also names the removals that carried active or external content (`active`) | wasm `clean_svg` (V1-2.6 upload) | + +**Digests.** SHA-256 of the RFC 8785 text of `{"group": , …content}` read from the typed document (an omitted +marking is written `inherited`): `general` is the document without `views`, `annotations`, `finding_zones`; `view:` is +`{views: [the views of that id], annotations: [those drawn in it, document order]}`; `zone:` is +`{finding_zones: [the zones of that id]}`; a removal group is `{removed: true}`. A group is coverable when it holds no +`to_confirm` and no `inherited` element; a removal group always is. A core change of these rules is a « core change » of +§6.4 (rounds withdrawn). + +**Verdict codes,** first one recorded as the round's `failure_code`: `verification.integrity.document`, `.base`, +`verification.validation.rules`, `.no_geometry`, `.caps`, `verification.integrity.drawing_missing`, `.size_mismatch`, +`.object_conflict` (bytes not hashing to the row, which is the object key), `.svg_rejected`, `.svg_removal`, +`.fingerprint`. Drawing results: `ok`, `missing`, `size_mismatch`, `hash_mismatch`, `svg_rejected`, `svg_removal`. + +### 12.2 Facade + +Free (`call`): `sheet.edit` `{document, command}` → `{document}`, failures `unknown_key`, `duplicate_key`, +`invalid_target`, `id_changed`, `invalid_position`, `too_deep`, `too_large` (input over 8 MiB + 2 MiB or the OD-3 value +budget); `sheet.dependents` `{document, key}` → `{dependents: [{element, relation}]}`. Wasm classes: `PreviewBuilder` +(`add_drawing(assetId, sha256, bytes)`, `build(PreviewInput JSON)` throwing `: `: `invalid_document`, +`drawing_missing`, `drawing_hash_mismatch`, `fingerprint_mismatch`, `caps`), `PreviewSheet` (`call`: `preview.state`, +`view.canvas`; `replace_document`, `add_drawing`: `{"ok":true}` or `invalid_document`, `drawing_hash_mismatch`, +`read_only`); the function `clean_svg(bytes)` (`SvgCleaning`). `view.canvas` is one composition for `LoadedSheet` and +`PreviewSheet` (`ops::canvas_of`). The runtime (`CoreRuntime`) does not manage preview handles yet: their poison and +recovery come with their first page (V1-2.5). ts-rs: 31 new type files, `types/index.ts` 126 entries. + +### 12.3 Behaviour (declared) + +1. The sanitiser keeps, removes and refuses exactly as before (R3 oracles O4/O5 green); its walk also lists, in + `active`, each removal that carried a script, an embedded document or image (`image`, `feImage`, `foreignObject`, + `iframe`, `object`, `embed`, media), animation, a link (`a`), an event handler (`on*`), a reference outside the + document (`href`, `url(…)`), `@import`, `javascript:`, `expression(`, `image-set(`, `behavior:`, or a backslash. A + `