Files
faunosteo/.claude/tasks/plans/2026-10-24-rust-r5-6-fingerprint-switch.md
bchanot 943a25a98f fix(domain): R5.6 prep gates, strict declared block, patch builds, docs corrected
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.
2026-10-24 14:57:44 +02:00

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 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<Fingerprint, FingerprintError>: 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).