fix(domain): refuse three non-canonical v3 shapes, R5.5 LOW fixes, R5.6 plan

check_v3_shape at read_report_document v3 and parse_envelope (sheet, practitioner
as non-objects, severity as non-string); Protocol errors final; DEV address must be
an own unicast address. SQL confirm function and DEV keys characterised, no change.
This commit is contained in:
bchanot committed 2026-10-24 03:34:38 +02:00
1 parent 13db5539a3
commit d502dfa923
11 files changed
+369 -37

No files matched your search

@@ -0,0 +1,85 @@
# 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.