docs(docs): RUST.md §11.9 to §11.11 (F1 fix and audit, R5.2 importer parity, declared differences, checkpoint), CHANGELOG

This commit is contained in:
bchanot committed 2026-10-22 21:14:46 +02:00
1 parent 03bdb5eaa0
commit 82f166450c
2 files changed
+118

No files matched your search

+5
View File
@@ -6,6 +6,11 @@ Versions follow [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Changed (2026-10-22, Rust R5.1b and R5.2)
- The core prints an exact decimal tie as JavaScript does (`840.1692504882812`, round half to even), its digits now from `zmij`, the formatter serde_json already used; no historical output carried such a value, so no oracle, golden or PDF digest changed (`docs/development/RUST.md` §11.9).
- The legacy importer runs in Rust behind the core's `curation` feature: `import-equine --check` reproduces the committed `legacy-import/` folder byte for byte, and `--out <dir>` writes it into an empty folder. The TypeScript pipeline, `pnpm import:equine` and the seed are unchanged; `documentSha256` stays as it is until R5.6 (§11.10).
### Changed (2026-10-22, Rust R5.1: the TypeScript pipeline frozen, not yet ported)
- `packages/anatomy` and `packages/domain` are unchanged; their outputs are recorded as oracles under `crates/core/tests/oracles/r5/` (intermediate values, ids and slugs, the fingerprint of every generated JSON file under today's rule and the candidate rules of D-R5), generated by `packages/anatomy/tests/r5.pipeline-oracles.test.ts` with `MAKE_R5_ORACLES=1`. Study scripts `scripts/r5-fingerprints.mjs` and `packages/supabase/scripts/r5-jsonb-fingerprint.mjs` (read-only). `documentSha256` and the generated seed are untouched; the D-R5 decision is the owner's (`docs/development/RUST.md` §11). Known defect recorded, not fixed: the core's JavaScript number printing rounds an exact decimal tie upward where JavaScript rounds to even (no value of the curated draft is affected).
+113
View File
@@ -2763,3 +2763,116 @@ regenerated once by the Rust tool, `.prettierignore`, CHANGELOG). R5.7
consumer census, fixtures moved, `packages/anatomy` and `packages/domain`
deleted, xmldom and Prettier out of the anatomy lockfile, docs and ledger.
R5.6 needs the D-R5 decision; R5.2 needs R5.1b.
### 11.9 R5.1b: F1 fixed (2026-10-22)
The owner's decisions of 2026-10-22 (« Validation R5.1, décision D-R5 et lancement du
portage Rust »): D-R5 = option B, convention `sha256-rfc8785-validated-v1` (applied at R5.6
only), aliases of the historical fingerprints established from trusted frozen documents
only, F1 fixed first, byte-exact reproduction of the TypeScript artifacts by default, the
historical SVG bytes kept, `.prettierignore` on the Rust-written paths, `ureq` preferred
for the upload tool at R5.5.
`js_number` (`crates/core/src/json.rs`) now takes its shortest digits from `zmij` 1.0.23,
the formatter serde_json 1.0.154 already used (a dependency edge, no new crate): among the
shortest candidates it picks the closest and, on an exact decimal tie, the even one, which is
ECMAScript's rule. The decimal layout (ECMAScript `Number::toString` steps 6 to 10) is
unchanged.
Independent reference: `crates/core/tests/oracles/r5/numbers.json`, 44,322 rows written by
V8 (`scripts/r5-number-oracle.mjs`, `String(value)`), each value given by its IEEE bits:
edge values (zero, subnormals, extremes, the 1e21 and 1e-7 thresholds, powers of ten and two,
integers around 2^53), the tie values of the study, 12,000 float32-exact values (where ties
occur), 10,000 random doubles, each negated. `tests/json_numbers.rs` compares every row and
characterises 840.1692504882812. Before the fix: 1,552 mismatches; after: none. The R2
helper `zod_oracle` now first checks the oracle's own bytes against the core's compact
printing, so a number the core prints differently from V8 fails there instead of on both
sides of the comparison: on the old printer it fails the legacy baseline oracle.
Consumers audited (`grep js_number crates/core/src`): the R3 canvas layer and sanitiser
(`anatomy/layer.rs`, `svg/number.rs`, `svg/sanitize.rs`), the R2 editor and sheet rules
(`domain/editor/zone.rs`, `domain/js.rs`, `domain/sheet/validate.rs`), the R4 writer
(`pdf/write/{content,views,layout/observation}.rs`) and `report-compare`
(`pdf/compare`). Result on the historical corpora: `pnpm rust:check` (every cargo suite,
the R4 serialiser digests included), `pnpm wasm:build` and `pnpm check` (app 434, core-wasm
58, domain 262) green with no oracle, golden or digest changed: no historical output
carries a tie value, so no contract moved and the porting went on as the brief allows.
Effect on user data: an archive whose report holds a tie value now re-prints it as the
JavaScript application wrote it (`…812`), where the R2 to R4 core would have printed
`…813`; the value itself was never altered (the two texts parse to the same double).
### 11.10 R5.2: the legacy importer in Rust (2026-10-22)
`crates/core/src/curation` behind the feature `curation` (never enabled by the wasm module
or the worker; `scripts/rust-check.sh` runs clippy and the suites with it), 3,187 lines:
| Module | Ports |
|---|---|
| `text.rs` | Prettier's `getStringWidth` (the East Asian wide table transcribed row for row from `prettier@3.8.3`), the NFD fold of `slugify` and the region roots (`icu_normalizer`, already locked through `url`), UTF-16 ordering, `Object.keys` order (array indices first), `Math.round` |
| `ids.rs` | `sha256Hex`, `deterministicUuid`, the asset and sheet ids |
| `prettier_json.rs` | `formatJson`: Prettier's JSON layout over `JSON.stringify(v, null, 2)` (expanded objects, collapsed short arrays, filled number arrays, Prettier's exponent form `1e21`) |
| `markdown.rs` | `cell`, `table`, `code` and Prettier's table alignment (the only change it makes to the reports) |
| `legacy/*` | `svg`, `vertebrae`, `regions`, `categories`, `catalog`, `catalog_checks`, `annotations`, `authored_labels`, `importer`, `report` (IMPORT-REPORT), `render_artifacts` |
| `bin/import_equine.rs` | `import-equine --check` (compare with the committed `legacy-import/`, write nothing) and `--out <dir>` (write into an absent or empty folder; nothing is ever deleted) |
Parity, every expectation written by the TypeScript tools:
- the four text files of `legacy-import/` byte for byte and the two SVG copies
(`tests/curation_legacy.rs`); `import-equine --check`: 6 files, 0 differences; `--out`
then `diff -r` against the committed folder: identical;
- every intermediate value of the frozen run (`oracles/r5/pipeline.json`, section
`legacy`: stats, anomalies in order, rows, inferences, zone stats, digests, view boxes);
the raw report's sha256 equals the ledger's pre-Prettier digest; two runs byte-equal;
- 10 synthetic cases run through the TypeScript importer (`oracles/r5/legacy-synthetic.json`,
generator `packages/anatomy/tests/r5.legacy-synthetic-oracles.test.ts`): a generic sheet
(integer-like zone keys, non-stable node ids slugified, missing FR and EN names, unknown
laterality and special, a `rect`, odd polygon points, `0x10` and `1e1` coordinates, the
tie value, `-0`, a duplicate formula key, a hyphen range) and a minimal one with a BOM,
both byte for byte with every result part; 8 refusals (schema, zones missing, catalog
with a BOM, region missing, no formula, inline sources, key ≠ id, a truthy non-boolean
referral) refused alike;
- the generic format probes (`oracles/r5/{prettier-json,markdown-tables,js-semantics}.json`,
generator `packages/anatomy/tests/r5.format-oracles.test.ts`): 968 JSON layouts across
depths, key widths and the 80-column boundary, 10 tables, 22 extra slug edges (İ, Kelvin,
final sigma, ß, ligatures, fullwidth, Hangul, the 64-character cut), 7 uuid names, 39
`Number()` texts, 12 point lists, 18 `Math.round` values (bits kept, −0 included), 8
spaces, 3 key orders; the 7 generated JSON files of the seed (draft included) print byte
for byte.
Differences declared (the port refuses where JavaScript accepted; none is reachable by the
committed sources, since the equine folder is reproduced byte for byte):
| Input | TypeScript | Rust |
|---|---|---|
| a text holding an emoji, in a table cell or a JSON string | Prettier measures it with its RGI emoji table | refused (`UnsupportedWidth`): the table is not reproduced (the only emoji of the sources, in `Horse.svg`, never reaches a generated text) |
| a malformed SVG, a DTD, a text over the core's SVG caps | xmldom parsed leniently | refused (the core's prescan, then roxmltree) |
| a catalog node whose `id` is not a string, a `children`, `categories` or `sources` that is not an array | coerced or crashed | refused with the node named |
| a category or label named like an `Object.prototype` member (`constructor`, `toString`) | the prototype answered the lookup | a plain table lookup |
Kept as the TypeScript: invalid UTF-8 in the catalog and vertebrae texts becomes U+FFFD
(`Buffer.toString`), a BOM there is kept (and `JSON.parse` refuses it); invalid UTF-8 in an
SVG is refused and one BOM removed (`TextDecoder` fatal); a missing coordinate reads 0
(`Number(null)`); NaN and the infinities become `null` in the document and `NaN` /
`Infinity` in the report rows.
Tests: `cargo test -p faunosteo-core --features curation` (formatting 6, importer 5, plus
the crate's suites); the TypeScript keeps its 131 frozen cases and gains the 4 generators of
R5.2 (anatomy 141). `packages/anatomy`, `packages/domain` and `pnpm import:equine` stay:
the TypeScript still writes both folders until the switch.
### 11.11 Checkpoint R5.2
Residual risks: the emoji refusal (a label with an emoji would stop the pipeline, visibly);
Prettier's markdown changes other than table alignment are not reproduced (none occurs in
the three reports; a future content with emphasis or escapes could differ, and the R5.4
byte comparison of CHANGELOG and REVIEW-REPORT will show it); the NFD and lowercase tables
follow `icu_normalizer` 2.3 and Rust 1.99 (Unicode 16 or 17) where Node uses ICU 78.3:
equal on every frozen label and edge, a character added by a later Unicode version could
differ; the binary has no pnpm script yet (a public name, the owner's call).
Conditions for R5.3: the owner's validation of this checkpoint; the draft side reads the
same inputs (`curation/changes.json`, `references.json`) and its oracles are frozen
(`pipeline.json` draft section: 46 changes, 825 records, migration stats; the draft folder
byte for byte except `sheet-ref.json`'s fingerprint, which stays `27c7383c…2660` until
R5.6); the cleaned `horse.svg` is kept as frozen bytes (owner decision), so R5.3 reads it
instead of re-cleaning the legacy drawing; the review drawings (xmldom bytes) wait for R5.4.