# PLAN: Rust R5.6, the sheet fingerprint switch to `sha256-rfc8785-validated-v1` (prepared, NOT started) - date: 2026-10-24 | branch `feature/rust-r5-pipeline-core` | parent plan `2026-10-22-rust-r5-pipeline-core.md` §B.3.5, §B.5 row R5.6 - brief: owner 2026-10-24 « Clôture R5.5, corrections ciblées et préparation R5.6 » §6 (convention confirmed, file scope approved: `report/rebase.rs`, `archive/read.rs`, `session.rs`, `pdf/write/input.rs`; switch NOT authorised yet) - decisions on record: BDR-068 (D-R5 = B), owner 2026-10-24 (one alias, `27c7383c…2660`; Report v3 unchanged) ## A. What changes, what does not The value: `sha256(JCS(validated document))`, where the validated document is the R2 typed reading (`AnatomicalSheetDocument` + `validate_sheet_document`, no issue) serialised back, and JCS is RFC 8785. Frozen study value for the current draft: `12d788727c1e532641bd5b3a7ecf39dbdd25e70350f8a76be5ca917b262874e2` (`oracles/r5/fingerprints.json`, `b_rfc8785_validated`). `27c7383c…2660` (sha256 of the Prettier file bytes) becomes the one alias of that content. Unchanged: Report v3 shape (`sheet.documentSha256`, 64 hex), the N-1 reader, every PDF fixture, golden and R2-R4 oracle (they keep `27c7…`, valid through the alias), `horse.svg` bytes and asset ids (no re-upload), the document content, the integrity rules, the migration behaviour for a real content change. No view, zone, region, category or reference is renamed. ## B. Steps (one subtask = one commit, gates at the end) 1. **Canonicaliser.** `crates/core/src/domain/sheet/fingerprint.rs` (no feature: the core and the tools share it): JCS over `serde_json::Value` (keys sorted by UTF-16 code units, ES number printing through the core's `js_number` (F1-fixed `zmij`), string escaping of RFC 8785 §3.2.2.2, no whitespace), then sha256. Refuses non-finite numbers and lone surrogates (the core's parser already does). Tests: every vector of `oracles/r5/fingerprints.json` `rfc8785_vectors` (RFC appendix inputs) and the 44,322-row V8 number oracle `oracles/r5/numbers.json` through the canonical number printer; UTF-16 key order cases (astral vs BMP, `é` vs `é`). 2. **Independent differential.** `scripts/r5-fingerprints.mjs` (its own Node JCS, RFC vectors first) is the reference, never the Rust: a new `--json` field per document, then a Rust test reads a frozen output `oracles/r5/fingerprint-differential.json` written once by `MAKE_R5_ORACLES=1` over the draft, the legacy document and N synthetic documents (numbers at the ES formatting edges, Unicode keys, deep nesting). Added, never an existing oracle rewritten. 3. **Validation before hashing.** `sheet_fingerprint(document_text) -> Result`: strict parse, R2 shape, `validate_sheet_document` with zero issues, then JCS of the typed reading. A document with an issue has no fingerprint (closed error), so an invalid sheet can never be stamped official. 4. **Versioned convention.** `const FINGERPRINT_CONVENTION: &str = "sha256-rfc8785-validated-v1"`; `v1` freezes steps 1 and 3. No default anywhere: a sheet reference without a known convention name is refused at sheet load (`invalid_sheet`), and the pre-switch reference (no convention field) is read as the legacy convention only for the frozen registry of step 5. 5. **Trusted alias registry.** A compiled-in table in the core, the only authority: `(sheet_id 503dc301-…, convention "prettier-file-bytes-v0", alias 27c7383c…2660, canonical 12d78872…74e2)`, built from the frozen oracle (P4) and the committed pre-switch `sheet-ref.json`, never from an archive, a PDF, a bundle or the database. `sheet-ref.json` gains an additive `fingerprint` block (`convention`, `aliases: [...]`) for visibility; at sheet load the core checks that every listed alias is in the registry for that `sheet_id` and canonical value, else the sheet is refused. 6. **Old archives.** An archive stamped `27c7…` on sheet `503dc301…` is "same document" as the loaded sheet whose canonical value is `12d7…`: no rebase, no message, labels and snapshots kept. The exported envelope is never rewritten. 7. **The four gated readers** (owner approved scope; one membership test each, `same_document(report_sha, loaded_ref)`): `report/rebase.rs:40` (skip the rebase on current value or registered alias), `session.rs` (draft restore and import go through the rebase: no own comparison expected, verified), `archive/read.rs:118` (`snapshot_matches`: report vs archived snapshot, both archived; equality kept, alias accepted only when the pair is the registered one), `pdf/write/input.rs:207` (the export's sheet match: a report stamped with an alias exports against the current sheet). Nothing else in them moves. 8. **Seed and sheet-ref.** Regenerated once by `import-equine --out` into an empty folder, copied over `draft/` by the owner's go after review of the diff: `sheet-ref.json` (value + block), `report-migration-map.json` (`sheet.documentSha256`, so a migrated v2 report is stamped with the canonical value), nothing else (`equine_draft.sql` carries no fingerprint; checked). `--check` then compares with the regenerated folder; the R5 oracles (TypeScript output) stay as frozen, and the two files' difference from them is a declared rule (fingerprint field and block only), never an oracle regeneration. 9. **`.prettierignore`.** `supabase/seed/anatomical-sheets/equine/{legacy-import,draft}/` (the Rust-written paths, narrow), with a reproducible check: `prettier --check` on the repo passes and `git diff` after `pnpm format` is empty on those paths. 10. **Non-regression.** Every R2-R4 suite, the 99 PDF fixtures (import, compare), the envelope goldens, the N-1 reader, the 612-leaf migration, the app suite on the bundled sheet (wasm rebuilt), `report-compare` on the fixtures, `check:all`. 11. **Refusals.** A sheet-ref alias absent from the registry, an alias bound to another `sheet_id`, an alias whose canonical value is not the loaded one, a malformed hex value, an unknown convention: each a closed refusal with a test; a report stamped with an unknown fingerprint rebases as today (never treated as the official sheet). 12. **Rollback before merge.** Everything stays on the branch: revert the R5.6 commits (`git revert`, never a reset of pushed history); the seed returns to `27c7…` from git; no database, Storage or asset change exists to undo; an archive exported during the R5.6 tests with `12d7…` would rebase after a rollback (DEV only, labels kept). Rollback trigger: any authentic archive (fixtures, goldens, owner devices) opening with a message or a rebase it did not have before. ## C. Decisions still needed before the switch 1. **The fifth comparison.** `crates/core/src/pdf/compare/lines.rs:350` (`report-compare`, the archive check tool) compares fingerprints too and is not in the approved list. Without the membership test, it reports alias-stamped archives as "other sheet". Recommendation: include it (same one-line test). 2. **The TypeScript writer.** `pnpm import:equine` and its golden test in `packages/anatomy` would write and expect `27c7…` after the switch. Recommendation: the Rust tool becomes the only writer of the seed at R5.6, `pnpm import:equine` refuses to write (message pointing at `r5:import-equine`) and its golden test is pinned to the pre-switch commit as historical evidence, both deleted at R5.7. 3. **Where the alias authority lives.** Recommendation as step 5 (core registry authoritative, `sheet-ref.json` block for visibility, mismatch refused). Alternative: `sheet-ref.json` alone (simpler, but then the bundle is the authority, which the owner excluded). 4. **The app side.** `apps/app/src/sheets/provider.ts` reads `ref.document_sha256` only; the additive block needs no TS change. Confirm no TS display of the fingerprint should show the convention. ## D. Out of scope The migration-map cascade debt (§11.12) stays open: no rename in this switch. Step 13 (`anatomical_sheet_versions` storing a fingerprint) is later. No merge, no release, no deploy. ## E. Owner arbitration 2026-10-24 and preparation state Decided: convention confirmed; compiled registry the only authority, bound to sheet + content; five consumers (adds `pdf/compare/lines.rs`); Rust the only generator, `pnpm import:equine` → Rust, TypeScript kept as `import:equine:legacy` until R5.7; no visible change, no migration message. Prepared (RUST.md §11.19): module + tests committed inert; the switch as `.claude/tasks/plans/r5-6-switch.patch` (applies cleanly; on the current seed 4 `curation` tests fail as expected, with the seed switched 3 more: RUST.md §11.19; the earlier "rehearsed green" covered the five consumers only). Still to decide at the switch signal: 1. `loaded.rs` + `facade.rs` (sheet load refuses a contradicting block): outside the five approved files, not in CLAUDE.md's gated list (bundled sheet, not user data). Needed for "a contradiction is refused". 2. The two `curation_draft` cases move to a declared rule for `sheet-ref.json` and `report-migration-map.json` (fingerprint field and block only), the R5.1 oracles untouched. 3. M1 (security): the export's snapshot reference on an alias match: the report's own stamp (recommended), re-stamp at rebase, or accept with an N-1 test. 4. M2 remainder: refuse a `sheet-ref.json` without a fingerprint block after the switch (every test sheet then needs one). Switch procedure (on the signal): apply the patch; move the fingerprint after the drawings bound and keep the drawings-bound fixture valid; declared rules for the O7 oracle and the switched-seed preconditions; declared rule in `curation_draft`; `pnpm import:equine` → `scripts/import-equine.sh`, TS as `import:equine:legacy`; `import-equine --out` into an empty folder, diff reviewed (only the two files of §11.19), copied over `draft/`; `--check` 0 differences; `pnpm rust:check`, `pnpm check:all`, security, fresh verifier; owner device check (an old PDF opens with no message). Rollback: `git revert` of the switch commits (seed back to `27c7…`, nothing outside git to undo); an archive exported meanwhile with `12d7…` would then rebase (DEV only).