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

+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.