v1 refuses a non-hex or historical value (NotCanonical); the switch patch now builds report-compare and refuses unknown block keys; RUST.md 11.19 states the measured rehearsal (4 + 3 expected failures) instead of a green claim.
10 KiB
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 plan2026-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)
- Canonicaliser.
crates/core/src/domain/sheet/fingerprint.rs(no feature: the core and the tools share it): JCS overserde_json::Value(keys sorted by UTF-16 code units, ES number printing through the core'sjs_number(F1-fixedzmij), 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 oforacles/r5/fingerprints.jsonrfc8785_vectors(RFC appendix inputs) and the 44,322-row V8 number oracleoracles/r5/numbers.jsonthrough the canonical number printer; UTF-16 key order cases (astral vs BMP,évsé). - Independent differential.
scripts/r5-fingerprints.mjs(its own Node JCS, RFC vectors first) is the reference, never the Rust: a new--jsonfield per document, then a Rust test reads a frozen outputoracles/r5/fingerprint-differential.jsonwritten once byMAKE_R5_ORACLES=1over 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. - Validation before hashing.
sheet_fingerprint(document_text) -> Result<Fingerprint, FingerprintError>: strict parse, R2 shape,validate_sheet_documentwith 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. - Versioned convention.
const FINGERPRINT_CONVENTION: &str = "sha256-rfc8785-validated-v1";v1freezes 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. - 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-switchsheet-ref.json, never from an archive, a PDF, a bundle or the database.sheet-ref.jsongains an additivefingerprintblock (convention,aliases: [...]) for visibility; at sheet load the core checks that every listed alias is in the registry for thatsheet_idand canonical value, else the sheet is refused. - Old archives. An archive stamped
27c7…on sheet503dc301…is "same document" as the loaded sheet whose canonical value is12d7…: no rebase, no message, labels and snapshots kept. The exported envelope is never rewritten. - 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. - Seed and sheet-ref. Regenerated once by
import-equine --outinto an empty folder, copied overdraft/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.sqlcarries no fingerprint; checked).--checkthen 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. .prettierignore.supabase/seed/anatomical-sheets/equine/{legacy-import,draft}/(the Rust-written paths, narrow), with a reproducible check:prettier --checkon the repo passes andgit diffafterpnpm formatis empty on those paths.- 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-compareon the fixtures,check:all. - 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). - Rollback before merge. Everything stays on the branch: revert the R5.6 commits (
git revert, never a reset of pushed history); the seed returns to27c7…from git; no database, Storage or asset change exists to undo; an archive exported during the R5.6 tests with12d7…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
- 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). - The TypeScript writer.
pnpm import:equineand its golden test inpackages/anatomywould write and expect27c7…after the switch. Recommendation: the Rust tool becomes the only writer of the seed at R5.6,pnpm import:equinerefuses to write (message pointing atr5:import-equine) and its golden test is pinned to the pre-switch commit as historical evidence, both deleted at R5.7. - Where the alias authority lives. Recommendation as step 5 (core registry authoritative,
sheet-ref.jsonblock for visibility, mismatch refused). Alternative:sheet-ref.jsonalone (simpler, but then the bundle is the authority, which the owner excluded). - The app side.
apps/app/src/sheets/provider.tsreadsref.document_sha256only; 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:
-
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". -
The two
curation_draftcases move to a declared rule forsheet-ref.jsonandreport-migration-map.json(fingerprint field and block only), the R5.1 oracles untouched. -
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.
-
M2 remainder: refuse a
sheet-ref.jsonwithout 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).