docs(docs): V1-2.2 RUST.md §12, contract decisions, core pointers

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.
This commit is contained in:
bchanot committed 2026-10-29 13:14:23 +01:00
1 parent 8ae756534c
commit 741c25c464
4 files changed
+144 -5

No files matched your search

+5
View File
@@ -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.
+2 -2
View File
@@ -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
+116
View File
@@ -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:<id>`, `zone:<id>`, 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": <key>, …content}` read from the typed document (an omitted
marking is written `inherited`): `general` is the document without `views`, `annotations`, `finding_zones`; `view:<id>` is
`{views: [the views of that id], annotations: [those drawn in it, document order]}`; `zone:<id>` 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 `<kind>: <detail>`: `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
`<style>` element is active when its text holds such a value, cleanable otherwise.
2. The cleaning reads a picked file with one difference from the stored-drawing reader: an oversized `title` or `desc`
(over 4 KiB) is a removal (the cleaned text drops it) where the stored reader refuses the file (`too_complex`).
3. `clean_svg` answers `cleaning_unstable` if a cleaned text did not read back with no removal; the property test proves
it never happens on the corpus and 3 000 generated drawings, and the check stays so no upload rests on the test.
4. The document measure is exact for texts written as JavaScript writes numbers (every core output); a page that sends
another spelling (`1.50`, `1E2`) is stored as written and may measure a few bytes differently.
5. `EditCommand` and `NewElement` keep serde's tagged wire forms but are read through `serde_json::Value`, and
`read_document` reads from `&Value`: serde's tagged readers and the owned-`Value` reader each compiled a second copy of
the schema's reader into the module (measured: 635.7 KB gzip before, 582.7 KB after).
### 12.4 Proofs and tests
- `sheet_size` (6): 17 PostgreSQL vectors (`oracles/v1-2-2/size.json`, measured by PGlite 17.5 from
`oracles/v1-2-2/size.mjs`), the equine seed at 184 105 bytes (the real image's value, contract §12.3), the pgTAP 017
vectors (cap − 1, cap, cap + 1 in 1-, 3- and 4-byte characters, dense, `1e21`), 600 000 numbers in linear time.
- `sheet_review` (9): the equine counts of the contract (188 / 31 / 620 over 839 elements, 30 groups), digests stable
and local to their group, an omitted marking digesting as `inherited`, coverage, a derived version deleting a zone
with its removal group and change list, removal digests bound to their key, an inherited element alone keeping its
group uncoverable, added / changed / status-changed / removed-plus-added, a reorder changing the digest only.
- `sheet_verdict` (13): a clean sheet and the equine draft pass (fingerprint `12d78872…`, 30 groups, 184 105 bytes); the
shape the SQL reads; each rule and drawing fault alone; caps at cap − 1 / cap / cap + 1 (annotations, labels in
astral characters, depth, nodes, drawings, document bytes); code order; determinism; base and removal groups; a
document at every cap (64 views, 1 024 annotations, 8 192 nodes, depth 8) verified.
- `sheet_preview` (8): the equine draft previews with the bundle's index tables and canvases and its fingerprint; hash
mismatch refused in every mode; fingerprint, missing drawing and caps refused for published and deprecated, reported
for drafts; an invalid draft draws with its issues; five replacements, one drawing read; read-only published; no
report operation on a preview.
- `sheet_edit` (11): each marking rule of §6.6, the refusals, `dependents`, the facade, and 400 random commands on the
small sheet and on the equine draft (strict re-read, keys kept unless removed, nothing turned `inherited`).
- `svg_clean` (8): the 42 hostile files, each on the §9.2 line it belongs to; active names; a plain `<style>` cleaned and
named, four hostile ones refused; the product drawing clean with its sha256; the four committed exports; the owner's
folder (empty so far); the fixpoint on the corpus and on 3 000 generated drawings (123 clean, 2 697 cleanable, 180
reference cycles refused).
- Mutation run (10 mutants, each against its suite): caps off by one, digest without its key, no active class, hash
unchecked, an update keeping `reviewed`, fingerprint unchecked, `inherited` counted as read, redrawn views ignored,
numeric scale ignored, removal groups never made: 10 killed (the `inherited` one survived the first run; the test
that kills it was added).
- `packages/core-wasm/tests/preview.test.ts` (5) on the shipped module: the equine preview equals the `SheetHandle`'s index
and canvases, the closed refusals, a replacement redrawn, `sheet.edit` and `sheet.dependents`, `clean_svg` on 45 hostile
inputs and floods with no trap (slowest 0.4 ms).
### 12.5 Measurements
| Measure | Value |
|---|---|
| shipped module | 1 771 003 B raw, 582 722 B gzip -9 (script), 592 136 B by Node's gzip in `size.test.ts`; budget 600 000 (D-R13); 531 715 B before V1-2.2 |
| verdict at every cap, native | 107 ms release, 493 ms debug (document 1 165 850 bytes) |
| `clean_svg`, shipped module | 45 hostile inputs and floods, slowest 0.4 ms |
### 12.6 Residual risks and points for V1-2.3
- The module's margin under its budget is about 8 KB by the test's measure: the V1-2.5 and V1-2.6 pages must not grow the
core's browser surface without measuring.
- cairo writes colours as `rgb(…)`: the allowlist removes any function from presentation attributes, so its cleaned
exports lose their colours (named, visible in the preview). Allowing `rgb()` / `rgba()` with numeric arguments would be a
reader change for the owner to decide.
- Editor exports (Inkscape, Illustrator, Figma, Affinity) are pending from the owner: the classification of their real
output is untested until then.
- A verdict whose document does not read strictly carries no group and no drawing: M6's structure check
(`complete_sheet_verification`) must accept a failed verdict without them, or the round would wait for its attempt limit.
- `PreviewSheet` handles are not yet under `CoreRuntime`'s poison and recovery (§8.3): the first page that holds one adds
it.
+21 -3
View File
@@ -1041,7 +1041,8 @@ Four stages, each a superset of the previous:
| Rule | Submit | Approve | Publish | Code |
|---|---|---|---|---|
| Strict parse and the 19 error codes | yes | | | `verification.validation.*` |
| Strict parse of the document and, for a derived version, of its base (§6.5; owner decision 2026-10-29) | yes | | | `verification.integrity.document`, `verification.integrity.base` |
| The 19 error codes | yes | | | `verification.validation.rules` |
| Caps of §1, all of them | yes | | | `verification.validation.caps` |
| Every annotation has a geometry | yes | | | `verification.validation.no_geometry` |
| Every reachable drawing present, size and sha256 equal to its row, read without removal | yes | | | `verification.integrity.*` |
@@ -1058,7 +1059,7 @@ Four stages, each a superset of the previous:
| Species active and other than `other` | | | yes | `publish.species.inactive`, `publish.species.other` |
| Caller capability (E, V, P) and `aal2` | yes | yes | yes | `rights.capability`, `rights.mfa` |
- The rules of the first five lines come from the stored verdict. SQL checks
- The rules of the first six lines come from the stored verdict. SQL checks
relations, states, rights, separation, the verdict's structure (§6.4), and
the declared defensive check of statuses on the stored document (§12.2).
- Shown, never blocking: uncited elements, the two warning codes, the number
@@ -1304,6 +1305,9 @@ The page reads the file with the core SVG reader before anything is stored.
| Any other removal (editor metadata and namespaces, `data-*` attributes, `<style>` elements, `class` or `style` on the root, ids outside the grammar, unsupported elements such as `symbol`, oversized `title` or `desc`) | cleaning offered: « Nettoyer et utiliser cette version », after the composed preview of the cleaned drawing and one confirmation; a removed `<style>` element is named, since the `class` attributes it styled then render unstyled |
| No removal | used as is |
- An oversized `title` or `desc` is a removal for the cleaning only: the reader
of stored drawings refuses such a file whole (`too_complex`), so it reaches
Storage only cleaned (V1-2.2).
- The classification and the cleaning are core functions (V1-2.2), tested on
committed vector-tool exports (tool and version named in the fixture) and
on the hostile corpus; a property test proves that cleaned output reads back
@@ -1396,7 +1400,11 @@ A drawing never blocks authoring: only the round waits for its verdict.
`not_found_or_denied`, `drawing_missing`, `drawing_hash_mismatch`,
`fingerprint_mismatch`, `invalid_document`, `caps`, `core_unavailable`,
`unavailable`. A draft with integrity errors previews with its issues and no
fingerprint.
fingerprint. For a draft, a caps excess and a referenced drawing that was not
given are reported in the state, never a load failure; `caps` and
`drawing_missing` refuse a published or deprecated version only (owner
decision 2026-10-29). A hash mismatch and an unreadable document refuse every
mode.
- `LoadedSheet` (the report editor's sheet) keeps its mandatory migration map;
`archive::SheetStatus` is not extended; a deprecated version previews like a
published one with a « retirée » mark. The readers of user data
@@ -2272,6 +2280,16 @@ checkpoint `2af61e7`:
| M7 | The Git fixture is accepted for the V1-2.1 upgrade rehearsal (sha256 equal to the DEV metadata's; bytes, metadata and relations before and after); no DEV Storage read, so the live DEV object's integrity is not demonstrated | §12.3, §16.2 |
| Size | The SQL check follows the contract's measure, the UTF-8 bytes of the JSON text; the binary `jsonb` size is not the measure; the cap stays 2 MiB | §12.2, M5 |
### 17.4 V1-2.2 decisions (owner, 2026-10-29)
Asked before the code of V1-2.2, on the brief « Autorisation de démarrer V1-2.2 »:
| Item | Decision | Where |
|---|---|---|
| Vector-tool exports | The owner supplies the editors' exports (Inkscape, Illustrator, Figma, Affinity) under `crates/core/tests/fixtures/svg/exports/owner/`; the cairo and ImageMagick exports of the development machine are committed meanwhile, tool and version in the file name | §9.2, §15 |
| Strict-parse code | `verification.integrity.document` (and `.base` for the base), as §6.5 files it; the 19 rule errors are `verification.validation.rules` | §6.5, §6.7 |
| Draft load | caps excess and missing drawings reported for a draft, refused for a published or deprecated version | §10 |
---
## 18. Documents touched by V1-2.0