Files
faunosteo/.claude/tasks/contracts/2026-10-22-rust-r5-f1-importer.md

9.1 KiB

Contract: R5.1b (F1 fix) and R5.2 (legacy importer in Rust, import-equine)

Base: 64d4595 on feature/rust-r5-pipeline-core (« chore(memory): R5 plan, pipeline inventory and documentSha256 census audits, TODO R5.1, journal, LRN-070, EVAL-026 »). Range: 64d4595..HEAD; <base> below is 64d4595. Date: 2026-10-22.

REQUEST (verbatim excerpts, owner, « Validation R5.1, décision D-R5 et lancement du portage Rust »)

« Je valide la correction du défaut d'arrondi de js_number dans le cœur Rust. La nouvelle implémentation doit reproduire les règles ECMAScript, notamment les égalités décimales exactes et les cas limites identifiés. Utiliser une implémentation éprouvée déjà présente dans l'écosystème du projet lorsque c'est approprié […]. Ajouter : un test caractérisant précisément le cas 840.1692504882812 ; des vecteurs couvrant les égalités d'arrondi ; des tests différentiels Rust / ECMAScript et des cas limites ; une référence indépendante pour éviter qu'une implémentation calcule elle-même son attendu. Auditer les consommateurs de js_number dans R2, R3 et R4. Conserver les oracles et goldens gelés. Si une divergence apparaît sur les corpus historiques, […] arrêter le portage avant toute modification de golden ou de contrat. »

« Par défaut, chaque fichier produit par Rust doit correspondre à l'ancien pipeline octet pour octet. Les différences éventuellement nécessaires doivent être déclarées individuellement […]. Ne pas modifier silencieusement les données métier pour satisfaire un oracle. »

« Je décide de conserver les octets de horse.svg et des autres assets historiques […]. » « Ne pas ajouter reqwest par défaut […]. Ce choix sera implémenté à R5.5, pas pendant R5.2. »

« Vérifier les cas limites de deterministicUuid, slugify, UTF-16, Math.round et Number(''). Ne pas se contenter de tests sur les données équines actuelles lorsque le contrat est générique et multi-espèces. »

« Conserver les tests TypeScript et les oracles gelés durant le portage. Ne pas modifier documentSha256, le seed officiel ou les contrats des bilans avant R5.6 […]. Ne supprime pas encore packages/anatomy ou packages/domain. »

FILE SCOPE

  • R5.1b: crates/core/src/json.rs, Cargo.toml and crates/core/Cargo.toml (zmij), Cargo.lock (one dependency edge), crates/core/tests/json_numbers.rs, crates/core/tests/common/mod.rs (zod_oracle raw-text check, repo_path), crates/core/tests/oracles/r5/numbers.json, scripts/r5-number-oracle.mjs
  • R5.2: crates/core/src/curation/** (new), crates/core/src/lib.rs (module behind curation), crates/core/src/bin/import_equine.rs (new), Cargo.toml and crates/core/Cargo.toml (feature curation, icu_normalizer, optional sha2, bin, two test targets), Cargo.lock (one dependency edge), crates/core/tests/{curation_format,curation_legacy}.rs, crates/core/tests/oracles/r5/{prettier-json,markdown-tables,js-semantics,legacy-synthetic}.json, packages/anatomy/tests/{r5.format-oracles,r5.legacy-synthetic-oracles}.test.ts, scripts/rust-check.sh (the curation lines)
  • Docs and memory: docs/development/RUST.md §11.9 to §11.11, CHANGELOG.md (Unreleased), this contract, .claude/tasks/TODO.md, .claude/tasks/plans/2026-10-22-rust-r5-pipeline-core.md (owner decisions), .claude/memory/{decisions,journal,learnings,evals}.md

Out of scope: supabase/seed/** (no generated or authored file changes), apps/**, packages/**/src, packages/core-wasm/**, the existing oracles (crates/core/tests/oracles/*.json, oracles/r3/**, oracles/r4/**, and the R5.1 files oracles/r5/{pipeline,ids,fingerprints}.json), apps/app/tests/fixtures/** (goldens, R4 digests), the gated readers (crates/core/src/domain/{archive/read,report/rebase,report/read,session}.rs, crates/core/src/pdf/{read,json_js,import}.rs), crates/worker/**, pnpm-lock.yaml; any deletion.

ACCEPTANCE CRITERIA

  1. F1 fixed with an existing implementation: js_number's digits come from zmij (already in Cargo.lock through serde_json 1.0.154 before the base: git show <base>:Cargo.lock | grep -A2 'name = "zmij"'); git diff <base> -- Cargo.lock adds dependency edges only ("zmij" and "icu_normalizer" under faunosteo-core), no new [[package]].
  2. Independent reference: crates/core/tests/oracles/r5/numbers.json was written by Node (scripts/r5-number-oracle.mjs, String(value), values as IEEE bits) and holds ≥ 40,000 rows including the bits 408a415aa0000000 → 840.1692504882812; crates/core/tests/json_numbers.rs compares js_number(f64::from_bits(..)) to every row and has a dedicated test for 840.1692504882812 (both signs) and the two other tie values of the study.
  3. Red before, green after: on the base's json.rs the number suite fails (orchestrator run: « 1552 mismatches, first: 408a415aa0000000: 840.1692504882813 vs V8 840.1692504882812 ») and the strengthened zod_oracle fails the_legacy_import_baseline_prints_as_zod_outputs_it; after the fix both pass. The verifier checks by reading that zod_oracle compares the oracle's raw bytes with to_js_compact(oracle) + "\n" before using to_js_pretty.
  4. R2 to R4 preserved: git diff --stat <base> -- crates/core/tests/oracles/*.json crates/core/tests/oracles/r3 crates/core/tests/oracles/r4 apps/app/tests/fixtures crates/core/tests/conformance crates/core/tests/fixtures is empty; the check:all log (path in the brief) shows the cargo suites (pdf_serialize, pdf_layout, anatomy_, sheet_, report_, archive_) and the app 434 / core-wasm 58 / domain 262 cases green.
  5. Formatting parity, generic: crates/core/tests/curation_format.rs passes: the 968 Prettier JSON probes match except case 19 (emoji, refused with UnsupportedWidth), the 10 table probes match except case 5 (emoji, refused), the 7 generated JSON files of the seed print byte for byte, slugs (ids.json 801 rows + 22 edges) and uuids (6 + 7) match, Number() (39 texts), points (12), Math.round (18, bits kept), trim (8) and Object.keys order (3) match. The probes were written by Prettier and Node (r5.format-oracles.test.ts), not by Rust.
  6. Importer parity: crates/core/tests/curation_legacy.rs passes: the 4 text files of legacy-import/ byte for byte and the 2 SVG copies; every key of pipeline.json's legacy section (sheetId, viewBoxes, stats, sourceDigests, assets, anomalies, issues, regionInferences, zoneStats, annotationRows) equal in the JavaScript compact form; the raw report's sha256 equals the ledger's before_prettier_sha256; two runs byte-equal; the 10 synthetic cases of legacy-synthetic.json (2 accepted: files byte for byte and every result part; 8 refused by the TypeScript: refused by Rust too).
  7. Binary: cargo run -p faunosteo-core --features curation --bin import-equine -- --check prints legacy-import: 6 files, 0 differences and exits 0; --out refuses a non-empty folder (exit 2, nothing written); the binary never deletes a file (read crates/core/src/bin/import_equine.rs: no remove_* call).
  8. Declared differences only: every behaviour where the port refuses what JavaScript accepted is listed in RUST.md §11.10 (emoji widths; malformed SVG, DTD or caps; non-string ids, non-array children / categories / sources; prototype-named keys) and none of them is reachable by the committed sources (criterion 6 proves the equine folder).
  9. Gating: the curation code compiles only with feature curation (#[cfg(feature = "curation")] on the module; the bin and the two suites required-features); crates/wasm/Cargo.toml and crates/worker/Cargo.toml do not enable it; scripts/rust-check.sh runs clippy and tests with --features curation.
  10. Scope held: git diff --stat <base> -- supabase apps packages/core-wasm packages/domain packages/anatomy/src packages/supabase crates/worker pnpm-lock.yaml is empty; packages/anatomy and packages/domain still exist; no reqwest anywhere in Cargo.lock; no deletion (git diff --diff-filter=D --name-only <base> empty); documentSha256 and sheet-ref.json unchanged.
  11. Suites: pnpm check:all exit 0 on the final code state (log ending == all checks passed); pnpm rust:check exit 0 with the curation lines; git status --short empty at the end.
  12. Docs: RUST.md §11.9 (F1: fix, oracle, consumers audited with the result on R2 to R4), §11.10 (R5.2: modules, parity proofs, declared differences, binary), §11.11 (checkpoint R5.2, conditions for R5.3); CHANGELOG Unreleased lines for F1 and the importer; the owner's decisions recorded (BDR) with D-R5 = sha256-rfc8785-validated-v1 not yet applied.

CLARIFICATIONS

Q: emoji in a table cell or a JSON string: reproduce Prettier's RGI emoji table? / A: no: the table is not reproduced; a text holding an emoji candidate is refused (UnsupportedWidth), declared, and absent from every committed source (the only emoji of the sources, in Horse.svg, never reaches a generated text). [owner brief « Les différences éventuellement nécessaires doivent être déclarées individuellement »] Q: the binary's command name and a pnpm script? / A: no new pnpm script at R5.2 (a public name is the owner's to choose); the bin is reached through cargo. [CLAUDE.md « a name that becomes public → ask »]