docs(docs): RUST.md §11.14-11.15 (R5.4 review files, declared R3 trigger-name difference, checkpoint), CHANGELOG, CLAUDE.md

This commit is contained in:
bchanot committed 2026-10-23 11:21:50 +02:00
1 parent fef21d67ef
commit b27121ff08
3 files changed
+88 -5

No files matched your search

+4
View File
@@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Changed (2026-10-23, Rust R5.4: the review files in Rust)
- The review drawings (`review/annotations-*.svg`, `review/app-*.svg`), `CHANGELOG.md` and `REVIEW-REPORT.md` of the draft are produced by the Rust pipeline: the two reports and three drawings byte for byte with the committed files; `review/app-main.svg` carries the head trigger's English name ("Head (left lateral view)"), the name the editor canvas shows since R3, where the committed file repeats the French one. `pnpm r5:import-equine --check` now compares the whole draft (12 files) and fails on any file missing or different without a declared rule; `--out` writes the 18 files. The seed, `horse.svg`, `pnpm import:equine` and `documentSha256` are unchanged (`docs/development/RUST.md` §11.14).
### Changed (2026-10-22, Rust R5.3: the curated draft in Rust)
- The draft side of the anatomical pipeline runs in Rust behind the core's `curation` feature (`crates/core/src/curation/draft`): the authored changeset and references files parsed strictly, the six ops of a change applied on the plain JSON document with their records, the review rule of levels B and C, the shape and integrity gate of the R2 core, the report migration map, the document statistics and the seed SQL. `pnpm r5:import-equine --check` reproduces `legacy-import/` and the R5.3 files of `draft/` (`document.json`, `assets.json`, `sheet-ref.json`, `report-migration-map.json`, `equine_draft.sql`, the frozen `assets/horse.svg`) byte for byte, 12 files, 0 differences; `pnpm r5:import-equine --out <dir>` writes both folders into an empty folder and never deletes anything. The review drawings, `CHANGELOG.md` and `REVIEW-REPORT.md` of the draft stay with the TypeScript until R5.4; `pnpm import:equine` and the seed are unchanged; `documentSha256` stays `27c7383c…2660` until R5.6 (`docs/development/RUST.md` §11.12).
+2 -2
View File
@@ -119,7 +119,7 @@ pnpm db:types:check # CI diff
pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments)
pnpm preview:draft # same, then serves it
pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings): the TypeScript writer of the seed until the R5 switch
pnpm r5:import-equine --check | --out <dir> # the Rust pipeline (R5.2 importer, R5.3 draft): compare with the committed folders, or write <dir>/{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles)
pnpm r5:import-equine --check | --out <dir> # the Rust pipeline (R5.2 importer, R5.3 draft, R5.4 review files): compare the 18 generated files with the committed folders (bytes; app drawings under the declared R3 rule), or write <dir>/{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles)
pnpm report:compare <pdf|dir>... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md); the core's `report-compare` binary since R4.7 (scripts/report-compare.sh, first run compiles)
# Rust (docs/development/RUST.md) — native toolchain (user-level rustup, channel of rust-toolchain.toml) first
@@ -280,7 +280,7 @@ 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,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL), bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`, the two files 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)
│ ├─ 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,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL, CHANGELOG, REVIEW-REPORT, review drawings), bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`, the two files 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)
│ └─ 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}.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`)
+82 -3
View File
@@ -2885,7 +2885,7 @@ until the switch; no fingerprint change; the cleaned `horse.svg` is read as froz
re-cleaned; the review drawings and the two Markdown reports are R5.4. Contract
`.claude/tasks/contracts/2026-10-22-rust-r5-draft.md`.
`crates/core/src/curation/draft` (2,912 lines, feature `curation`):
`crates/core/src/curation/draft` (2,908 lines at the R5.3 close, feature `curation`):
| Module | Ports |
|---|---|
@@ -2923,7 +2923,9 @@ Parity, every expectation written by the TypeScript (`tests/curation_draft.rs`,
rename, re-homing, two chained changes, the two migration-map debt cases below, the three
`JSON.parse` cases of the aligned paragraph) byte for
byte on the formatted document, the records, the stats, the migration map and the seed
SQL; 63 refusals (23 schema, `null` on `scope`, `position` and `field` and the shape
SQL; 63 refusals (23 schema, among them `schema-set-without-value`, which the TypeScript
refused at the gate and the port at parse, the declared family below; `null` on `scope`,
`position` and `field` and the shape
family below included, 40 applier, integrity and shape gates included) refused alike, with
the same reason: the same message for an op or change refusal (change id and op index
included), the same stage for a schema or gate refusal; 7 references files refused alike;
@@ -2940,12 +2942,13 @@ reproduced byte for byte):
| a lone surrogate escape (`"\ud800"`) in any string of the two files | `JSON.parse` kept it | refused (the core's L1 rule: no lone surrogate is ever read) |
| nesting deeper than 128 levels (an `add` of a 70-level finding chain) | accepted | refused at parse (serde_json's depth limit, kept as a resource bound) |
| a number beyond the double range (`1e400`) in a value a later op overwrites or removes | `JSON.parse` read Infinity, the value was discarded, the change accepted (a surviving value is refused by both at the gate) | refused at parse (serde_json's range check) |
| a `set` field path ending in an inherited `Object.prototype` member (`name.constructor`, `name.toString`, `name.valueOf`…) | `readField` returned the inherited function and the record's `structuredClone` threw (`… could not be cloned`): change refused at the op | the member is an ordinary missing key: written, `before` recorded as null. Kept alone, the shape gate refuses it (every object of the sheet contract is strict). Replaced by a later op of the run (a `set name` on the same item), the change is accepted: the document is byte for byte the one the later op alone gives, one extra record traces the overwritten write. Nothing is bypassed: the settable table checks the first segment on both sides (`constructor` as a field: `unknown field`), no value is read through a prototype, the integrity gate runs on the final document (test `an_inherited_member_name_is_a_plain_key_and_bypasses_nothing`, four member names; `__proto__` has its own row). Accepted by the owner 2026-10-23 |
| a `set` field path ending in an inherited `Object.prototype` member (`name.constructor`, `name.toString`, `name.valueOf`…) | `readField` returned the inherited function and the record's `structuredClone` threw (`… could not be cloned`): change refused at the op | the member is an ordinary missing key: written, `before` recorded as null. Kept alone, the shape gate refuses it (every object of the sheet contract is strict). Replaced by a later op of the run (a `set name` on the same item), or removed with its item, the change is accepted: the document is byte for byte the one the later op alone gives, one extra record traces the overwritten write. Nothing is bypassed: the settable table checks the first segment on both sides (`constructor` as a field: `unknown field`), no value is read through a prototype, the integrity gate runs on the final document (test `an_inherited_member_name_is_a_plain_key_and_bypasses_nothing`, four member names; `__proto__` has its own row). Accepted by the owner 2026-10-23 |
| a `set` field path holding a `__proto__` segment (`name.__proto__`, `name.__proto__.x`) | no key was ever written: at the end of the path the setter ignored a primitive or set the holder's prototype (change accepted, records with `before: {}`); in the middle, `Object.prototype` itself was polluted and every later object failed the strict gate (change refused) | refused at the op (`reserved key "__proto__"`), with or without a later overwrite: no faithful reading exists (fifth final round; declared case `declared-proto-segment-overwritten`, test `a_proto_segment_is_refused_at_the_op`) |
| an authored key starting with NUL (`"\u0000touched"`) in a value, or a field path segment starting with NUL (`name.\u0000touched`) | refused at the strict document gate when the key reaches the document, accepted when a later op overwrites or removes it | refused (`reserved key`): at parse for a value, at the op for a field path; the prefix is reserved for the applier's transient touch marks, which the cleanup strips at every depth, so a written key would be lost while a record claims it (found by the final gates, test `a_reserved_or_unbounded_field_path_is_refused_without_writing`) |
| a null, a string, a number or a boolean among the `children` or `categories` of an added item | a TypeError where a walk met it (`descendants`, the review marking: refused), silently skipped by a rename's citation walk (accepted when a later op removed the item), refused by the gate when it stayed | refused at the add (`… entry that is not an object`), whatever follows (three cases frozen from the TypeScript, one declared: `declared-children-string-renamed-then-removed`) |
| a `children` or `categories` of an added item that is present but not a list (an object, a string, `null`) | replaced by `[]` when a later op added under the item (`childrenOf`): the author's value lost without a word; accepted as well when a later op removed the item | refused at the add (`… that is not a list`); `children_path` never replaces a present value (declared case `declared-children-object-then-added-to`) |
| a `set` whose path goes through a non-object (a string, a number, a boolean, an array, `null`: `name.fr.x`): `writeField` replaces it by an object | `before` recorded as undefined (null), the replaced string in no record; refused by the gate unless a later op overwrites the field | the same (kept, recorded here) |
| a document of more than 200,000 values after an op (the equine document holds 6,374) | accepted when valid | refused at the op: a resource bound checked with the depth (test `the_document_cannot_hold_more_values_than_the_bound`) |
| a field path of more than 8 segments (the deepest settable path has 2) | accepted, the gate refused the stray keys | refused at the op: a resource bound (20,000 segments overflowed the stack before it) |
| a document nested more than 64 levels after an op (the equine document has 10), by repeated `add` or `move`, or a deep value | accepted when valid | refused at the op: a resource bound checked after every op with an iterative walk (test `the_document_cannot_be_nested_past_the_bound_by_repeated_adds`) |
@@ -3091,3 +3094,79 @@ compared as parsed trees against the xmldom files (declaration, prefixes and whi
declared), on the R3 layer and compose; `CHANGELOG.md` and `REVIEW-REPORT.md` byte for byte
through `markdown.rs` (the pre-Prettier digests of the ledger as the intermediate check);
the pending list of `--check` removed so the draft folder is compared whole.
### 11.14 R5.4: the review files in Rust and the whole-draft check (2026-10-23)
Owner go « Validation R5.3 et autorisation conditionnelle R5.4 » (2026-10-23), conditional on a
fresh verification of the final R5.3 state: met on c6e0d85 (CONFORME 13/13, security PASS with
LOWs only, §11.12). Contract `.claude/tasks/contracts/2026-10-23-rust-r5-review.md`.
`crates/core/src/curation/draft` gains 1,177 lines (4,204 in all):
| Module | Ports |
|---|---|
| `labels.rs` | the French labels of kinds, levels and priorities (`labels.ts`) |
| `stats.rs` `stat_rows` | `statRows`: labelled rows, fixed order, counters in their key order |
| `changelog.rs` | `compactValue` (labels as `fr / en`, other values as `JSON.stringify`, cut to 120 UTF-16 units with `…`, a cut inside a surrogate pair giving U+FFFD as the file write did), `recordSubject`, the comparison, migration and per-level tables, the intro |
| `review_report.rs` | the ten sections of `review-report.ts`: initial quality, errors, corrections, additions, restructures, uncertain items, translations, clinical vigilance (changed vet flags, flags per zone), bibliography (URL and DOI, citation counts), professional decisions (priority then id by UTF-16 units, stable) |
| `drawing.rs` | the frozen `horse.svg` read by the core's one SVG reader (refused if anything is removed), its prolog (the XML declaration and its line break) kept verbatim in front of every drawing |
| `overlay.rs` | `renderReviewOverlay`: the view's frame, the markers (unchanged, moved, added, removed, the previous position of a moved one), shapes, titles, labels, the legend, the font size from the frame width; numbers printed as `String(number)` |
| `app_review.rs` | `renderAppReviewDrawing` on the R3 layer (`render_layer`, `view_box_of`) the editor canvas uses |
| `svg_compare.rs` | how a produced drawing is compared with the committed xmldom file: bytes, else parsed trees after the one declared rule |
| `pipeline.rs` | `render_draft_artifacts` complete, in the TypeScript order: document, assets, sheet-ref, migration map, the overlays and the application's drawings per view, CHANGELOG, REVIEW-REPORT, seed SQL |
| `bin/import_equine.rs` | `--check` compares the 6 + 12 files with explicit criteria (byte identity; the application's drawings may fall back on parsed trees under the declared rule, printed as `declared:`); a file missing, not produced or different fails; the pending list and its `shortcut:` are gone; `--out` writes the 18 files |
Parity, every expectation written by the TypeScript (`tests/curation_review.rs`, 6 tests):
- `CHANGELOG.md` (1,114,533 bytes) and `REVIEW-REPORT.md` of the committed draft byte for byte;
their raw texts equal the ledger's pre-Prettier digests, the aligned texts its digests;
- `review/annotations-main.svg`, `review/annotations-head.svg` and `review/app-head.svg` byte for
byte with the xmldom files;
- `review/app-main.svg`: the one declared difference, measured to the byte (test
`app_main_differs_only_by_the_r3_trigger_names`): the head trigger, which has no name of its
own, carries `data-anno-name-en="Head (left lateral view)"` and the title `Tête (vue latérale
gauche) / Head (left lateral view)`, where the TypeScript renderer wrote the French name
twice; this is the R3 owner decision of 2026-10-15, the name the editor canvas already shows
(a tooltip and a data attribute: no shape, colour, position or frame changes);
- four synthetic cases written by the TypeScript on the mini sheet and a small drawing
(`oracles/r5/review-synthetic.json`, generator
`packages/anatomy/tests/r5.review-synthetic-oracles.test.ts`): pipes and line breaks in
cells, a value over 120 units, accents and guillemets, a vet flag change, a translation, a
level C question per priority, a restructure, a removal, references with URL and DOI, a
moved, an added and a polygon marker, a path marker on a detail view framed by its view box,
a sheet with nothing but a level A change: raw and aligned Markdown byte for byte, the
overlays byte for byte, the application's drawings byte for byte or under the declared rule;
an emoji in a cell gives the same raw text and the declared refusal at the alignment (R5.2);
- two runs byte-equal; an undeclared difference (a colour, a coordinate) refused with and
without the rule.
`pnpm r5:import-equine --check`: `legacy-import: 6 files, 0 differences`; `draft: declared:
review/app-main.svg (trees equal under the R3 trigger-name rule)`; `draft: 12 files, 0
differences`. `--out` then `diff -r`: legacy identical; draft identical but `app-main.svg`.
R5.3 carry-over (final gate LOWs, not applied to the verified state): an existing destination
folder is itself identity-checked against the seed's folders; a failed seed walk reads `the seed
folder cannot be read` instead of `inside the seed folder`; the cite check against the item's
existing citations is hashed; the stale test comment fixed; the §11.12 nits (the inherited row
covers a later removal; the 200,000-value row; the line count at the close; the
set-without-value case counted among the schema refusals).
Tests: `cargo test -p faunosteo-core --features curation` (review 6, draft 16, importer 5,
binary 3, formatting 6, plus the crate's suites); anatomy 143 (the generator added).
### 11.15 Checkpoint R5.4
Graphic differences for the owner's validation: none in shapes, colours, positions or frames;
one text difference in `app-main.svg` (the trigger's English name and tooltip), already decided
at R3 and identical to the editor canvas.
Residual risks: the Markdown alignment refuses an emoji (declared since R5.2); the comparison of
the application's drawings accepts exactly the trigger-name rule and nothing else; the frozen
`horse.svg` is read, never regenerated, so a future change of the drawing needs its own
decision; the residual risks of §11.13 stand.
Conditions for R5.5: the owner's validation of this checkpoint; the upload tool (`ureq`, the
service key from the environment, bucket `anatomical-sheet-assets`, key `<sha256>.svg`,
`upsert: false`, bytes verified against `assets.json`, RPC `confirm_sheet_asset_upload`) run
against the local stack only, with its runbook.