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:
1 parent
8ae756534c
commit
741c25c464
4 files changed
+144
-5
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user