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

109 lines
10 KiB
Markdown

# 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).