From 93e4e81bda0d9681b2ecb4626f4105398590810f Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 16:24:19 +0100 Subject: [PATCH] docs(docs): V1-2.2 owner arbitrations in the contract and RUST.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contract §6.5, §6.7, §8.1, §9.2, §9.3, §10, §13, §15 and §17.4 for the SVG references, the stored form, colours and removals; RUST.md §12.7 records what was built, the declared oracle changes and the size audit. --- docs/development/RUST.md | 74 ++++++++++---- docs/development/V1-2_ANATOMICAL_SHEETS.md | 111 ++++++++++++++++----- 2 files changed, 141 insertions(+), 44 deletions(-) diff --git a/docs/development/RUST.md b/docs/development/RUST.md index 0c7fb791..a1f81c27 100644 --- a/docs/development/RUST.md +++ b/docs/development/RUST.md @@ -896,8 +896,8 @@ imports it and restyles `data-state` in place as before. fuzzed, 9.3); pin the release with the iterative parser when it ships. - References are checked inside one drawing; in the page `#id` resolves against the whole document (the detail modal imports a second copy of the drawing, - as before R3). Drawings with their own assets (Step 13) should get ids - scoped per view before external uploads are drawn. + as before R3). Closed at V1-2.2 (§12.7): a reference must name an id its + drawing defines, and the canvas scopes ids per view. - Firefox and WebKit: not run here (no browser build); the owner's LAN run on the phone covers WebKit. - The worker's TLS path has not run against a real HTTPS endpoint (every run @@ -3870,7 +3870,7 @@ marking is written `inherited`): `general` is the document without `views`, `ann ### 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 +`invalid_target`, `id_changed`, `invalid_position`, `too_deep`, `has_dependents` (§12.7), `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`, @@ -3897,8 +3897,8 @@ trapping test stub (`apps/app/tests/helpers/core.ts`) lists the two new glue mem 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`); its subtree is still classified, so active content inside it refuses the file. -3. `clean_svg` answers `cleaning_unstable` if a cleaned text did not read back with no removal and serialise to - itself (what the admin confirms is what every reader draws); the property test proves +3. `clean_svg` answers `cleaning_unstable` if the stored text (§12.7) did not read back with no removal and give + itself again (what the admin confirms is what every reader draws); 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. @@ -3969,26 +3969,62 @@ with a PI shown `rejected` by the preview as the verdict refuses it. - The module's margin under its budget is about 3.3 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. +- cairo colours: closed at the checkpoint (§12.7), strict numeric `rgb()` / `rgba()` kept. +- Editor exports: Inkscape 1.4.3 covered at the checkpoint (§12.7); Illustrator, Figma and Affinity pending from the + owner, their real output untested until then (A6 open). - 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. -- Dangling `#id` references are clean and pass the verdict: once a view is inlined into the page, such an id resolves - against the page, so a detail drawing with 256 `` can instantiate the main drawing's group - (security audit, MEDIUM, probe on the shipped module) or show page icons. §9.7's « ids scoped per view » becomes - necessary before V1-2.6 draws two uploaded drawings in one page; refusing references to ids a drawing does not - define is the alternative. Owner decision. -- A clean file is uploaded as its original bytes (contract §9.2 « used as is »): an HTML-only comment form - (`…-->`) or an XML declaration naming another encoding stays in the stored object, inert for every current - reader (the bucket serves `image/svg+xml`, the app parses core serialisations). Uploading the core's serialisation - in the clean case too would remove it; that changes §9.2 and is the owner's call. +- Dangling `#id` references and original bytes uploaded as they are: both closed at the checkpoint (§12.7). - `validate_sheet_document`'s `view.parent.cycle` rule (R2 code) walks each view's parent chain: quadratic on a long chain (8 000 chained views, 2.4 s per `preview.state` in the module; the server cap of 2 MiB allows that order). Left as it was in this step; memoising the chain is the fix, with the conformance fixtures as its oracle. - The glue copies a drawing's bytes into linear memory before the 2 MiB check (transient, bounded by the bucket). +### 12.7 Owner arbitrations at the checkpoint (2026-10-29) + +Brief « V1-2.2 : arbitrages du propriétaire et finalisation » on `17d9199`; the owner chose, for each open point, the +option recorded in contract §17.4. All of it is in the core and the facade; no SQL, no screen, no DEV operation. + +| Point | Built | Where | +|---|---|---| +| Dangling references | `SvgRejection::DanglingReference` (`dangling_reference`): `refs::check_targets` after the reference graph, in `read_svg` (stored drawings, verdict, preview, PDF snapshot gate) and in `clean_svg` after active content is classified | `anatomy/svg/{refs,mod,clean,tree}.rs` | +| Views isolated | `compose_canvas` scopes the drawing's ids and local references (`fv..`, `compose::id_scope`, `sanitize::scope_url_targets` rewrites exactly the targets `url_targets` reads); `compose_highlight` (PDF) unchanged | `anatomy/compose.rs` | +| Stored form | `serialize::stored_form` = `` + LF + `serialize`; `SvgCleaning.cleaned` renamed `stored`, filled for clean and cleanable; verdict `DrawingResult::SvgNotCanonical` → `verification.integrity.svg_not_canonical`; preview `rejected` `not_canonical`; upload tool `verify_asset` refuses another form | `anatomy/svg/{serialize,clean}.rs`, `domain/sheet/{verdict,preview}.rs`, `curation/upload.rs` | +| Colours | `sanitize::without_colour_functions`: lowercase `rgb(` 3 / `rgba(` 4 components, all bare ≤ 255 or all `%` ≤ 100, alpha ≤ 1 or ≤ 100 %, nothing glued before; applied inside `calls_only_local_url` only, so active values are classified as before | `anatomy/svg/sanitize.rs` | +| Removals | `EditError::HasDependents` (`has_dependents`) when `dependents(key)` holds anything but descendants | `domain/sheet/edit.rs` | +| Module size | `scripts/wasm-build.sh` passes `--remove-name-section` to wasm-bindgen | `scripts/wasm-build.sh` | + +Declared oracle changes (frozen files untouched, the change applied in the test): `oracles/r3/sanitiser.json` +`dangling-references.svg` → `dangling_reference`, `css.svg` keeps `fill:rgb(1,2,3)` (5 removals instead of 6); the R3 +canvas goldens (`canvas.{main,head}.json`) get their ids scoped (`with_ids_scoped_per_view` in Rust, +`withIdsScopedPerView` in the app's `canvas.trees.test.tsx`). The equine drawing is already in the stored form: its +sha256 `0ea5202f…`, the fingerprint and every R4 digest are unchanged. + +Tests: `svg_scope` (6: valid reference, absent reference refused by reader, cleaning, preview and verdict, two views with +the same ids resolving each in its own view when both canvases are inlined, a cross-view attempt, three references to +one id, deterministic and repeated composition); `svg_clean` (13: cairo export clean with its five colours, shapes and +references; seven dangerous constructs next to a colour refused as active, five other functions removed; the three +Inkscape exports; clean files uploaded in the stored form; generated drawings now also refused for dangling references); +`sheet_verdict` and `sheet_preview` (a drawing outside the stored form fails / shows rejected); `sheet_edit` (removal +refused while named, through the facade too; the property test checks that a removal never adds a referential issue and +that `has_dependents` is answered only when something names the element); `sheet_review` (zones removed after their +annotations are unlinked); `curation_upload`; `packages/core-wasm/tests/preview.test.ts` on the shipped module. + +Inkscape: not installed and inkscape.org unreachable that day (504, then a timeout); the Ubuntu archive package +`inkscape_1.4.3-0ubuntu2_amd64.deb` (sha256 equal to the signed archive index) and 22 library packages were fetched with +`apt-get download`, unpacked with `dpkg-deb -x` into the session scratch folder and run from there (no install, no sudo). +`crates/core/tests/fixtures/svg/exports/generate-inkscape.sh` writes the three exports from `inkscape-source.svg`. + +Size (V1-2.2 final, by Node's gzip in `size.test.ts`): see §12.5. Contributors measured on a build keeping the name +section: code 1 283 513 B in 1 808 functions (gzip ≈ 462 KB) and data 219 920 B (gzip ≈ 90 KB); by crate, raw code: +`faunosteo_core` 46 % (`domain::sheet` 204 KB, of which `schema` 68 KB and `edit` 42 KB; `pdf::write` 91 KB; +`domain::report` 51 KB; `domain::archive` 41 KB; `anatomy::svg` 39 KB), `core` (fmt, float printing, slices) 18 %, +`serde_json` 12 %, `roxmltree` 3.6 %, `url` + `idna` 4.7 % (Zod's `.url()` check, `js::is_url`), `serde` 3 %, +`miniz_oxide` 2.7 % (PDF import). Options for later steps, none applied: `opt-level = "z"` for every crate (measured: +−1.6 KB gzip, not worth the speed), a lighter URL check than the WHATWG parser (`url` + `idna`: 61 KB raw, about 23 KB +gzip, but `is_url` must keep matching `new URL()`), the PDF writer, reader and inflater in a second lazily loaded module +(about 55 to 60 KB gzip by the attribution above, estimated; the editor pages never export), `wasm-opt -Oz` in the build +(not installed here; to be measured). No security check, validation or feature is removed for size. + diff --git a/docs/development/V1-2_ANATOMICAL_SHEETS.md b/docs/development/V1-2_ANATOMICAL_SHEETS.md index 60929577..65ab6345 100644 --- a/docs/development/V1-2_ANATOMICAL_SHEETS.md +++ b/docs/development/V1-2_ANATOMICAL_SHEETS.md @@ -940,7 +940,7 @@ did not pass; the closed codes keep the categories apart. | Category | Example | Outcome | Retry | Exit | |---|---|---|---|---| | Business validation | integrity error, caps exceeded, annotation without geometry | `verification_failed`, outcome `failed`, codes `verification.validation.*` and the issues | no | fix the draft, submit again | -| Integrity | strict parse refused, drawing missing, size or sha256 mismatch, SVG refused or needing a removal, `object_conflict` | `verification_failed`, outcome `failed`, codes `verification.integrity.*` | no | fix or upload again; `object_conflict` follows §9.3 | +| Integrity | strict parse refused, drawing missing, size or sha256 mismatch, SVG refused, needing a removal or outside the stored form (§9.2), `object_conflict` | `verification_failed`, outcome `failed`, codes `verification.integrity.*` | no | fix or upload again; `object_conflict` follows §9.3 | | Transient worker error | database or Storage unreachable, worker restart | stays `verifying`, code recorded | yes, up to the limit | automatic | | Timeout or resource limit | child over its wall-clock or memory limit | stays `verifying`, code recorded | yes, up to the limit | reduce the document or the drawing if it repeats | | Interruption | worker crash, lease expired | claimable again; counts as an attempt | yes, up to the limit | automatic | @@ -1045,7 +1045,7 @@ Four stages, each a superset of the previous: | 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.*` | +| Every reachable drawing present, size and sha256 equal to its row, read without removal, in the stored form of §9.2 | yes | | | `verification.integrity.*` | | Fingerprint computed | yes | | | `verification.integrity.fingerprint` | | Verdict passed, on the current revision | | yes | yes | `verdict.missing`, `verdict.failed`, `verdict.stale` | | No `to_confirm` element (D2) | | yes | yes | `publish.to_confirm.open` | @@ -1197,19 +1197,29 @@ supplied; they are not invented. drawn with its issues. - Every change is a Rust core command (`sheet.edit`, V1-2.2): generic primitives (insert, update, remove, reorder) over element keys, applying the - status rules of §6.6 and refusing only what would break strict parsing; - referential gaps are left to the validation panel. A `dependents(key)` + status rules of §6.6 and refusing what would break strict parsing or leave + an element named by another behind (owner decision 2026-10-29, below); + other referential gaps are left to the validation panel. A `dependents(key)` query feeds the delete confirmations. TypeScript holds no schema of its own and no Zod copy; it reads the ts-rs types. -- As built in V1-2.2 (implementation reading, for the owner's confirmation): the - wire ops are `insert`, `update`, `remove`, `move` (the reorder), `set_status` - and `mark_reviewed`; besides what breaks strict parsing they refuse what would - leave an element unaddressable or outside the editor's offer - (`duplicate_key`, `unknown_key`, `invalid_target`, `id_changed`, - `invalid_position`, `too_deep` beyond 8 finding levels); removing a view or a category leaves the - annotations that name it in place, dangling for the validation panel, which - `dependents` lists before the confirmation (§6.6 « with descendants » read - as the finding tree's children). +- As built in V1-2.2, strict validation of the commands confirmed by the owner + (2026-10-29): the wire ops are `insert`, `update`, `remove`, `move` (the + reorder), `set_status` and `mark_reviewed`; besides what breaks strict + parsing they refuse what would leave an element unaddressable or outside the + editor's offer (`duplicate_key`, `unknown_key`, `invalid_target`, + `id_changed`, `invalid_position`, `too_deep` beyond 8 finding levels). +- Removal, owner decision 2026-10-29 (atomic refusal): `remove` takes the + element with its descendants (a zone with its categories and nodes, a + category or node with its children: §6.6 « with descendants ») and is + refused as a whole, the document unchanged, with `has_dependents` while + anything else names the element: a view with annotations drawn in it, + detail views under it or a link that opens it; an annotation category or a + vertebral region used by an annotation; a finding zone linked from an + annotation; a reference cited by a category or a node. The page shows the + `dependents` list; the editor detaches or deletes those first. No cascade + deletion is offered in level 1. An `insert` or `update` that names an + element absent from the document stays allowed (left to the validation + panel), as does a document saved with gaps: the verdict refuses them. - Ids are generated by the page (`-<10 lowercase base32 characters>`, alphabet `a-z2-7`, inside the stable-id rule), passed to the core, never derived from labels, never editable, never reused. @@ -1309,13 +1319,14 @@ The page reads the file with the core SVG reader before anything is stored. | Reader outcome | Treatment | |---|---| -| Hard rejection (`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`, `too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`) | refused, with the reason in FR or EN; no cleaning offered | +| Hard rejection (`too_large`, `doctype`, `malformed`, `not_svg`, `too_many_elements`, `too_deep`, `too_many_uses`, `too_complex`, `reference_cycle`, `dangling_reference`) | refused, with the reason in FR or EN; no cleaning offered | | Any removal of active or external content: `script`, `foreignObject`, event-handler attributes, `image`, animation elements, a reference that does not point inside the document (`href` or `url(…)` not starting with `#`), `@import` or `javascript:` values | refused (`svg_active_content`): such a file is hostile or incompatible; no cleaning offered | | Any other removal (editor metadata and namespaces, `data-*` attributes, `