Files
faunosteo/.claude/audits/R5_DOCUMENT_SHA256_CENSUS.md

205 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# R5 census: sheet fingerprint `documentSha256`
Date 2026-10-22, branch feature/rust-r5-pipeline-core (cut at 9c0117a). Read-only census by an analyzer agent, saved by the orchestrator. Facts only, no recommendation.
Names covered: `documentSha256` (camelCase contracts), `document_sha256` (sheet-ref.json, bundle payload, Rust fields), `SheetRef` / `SheetSnapshotRef` / `BundledRef`, `sheet-ref.json`.
## Summary
1. There is exactly one producer: `sheetRef()` in packages/anatomy/src/curation/pipeline.ts:159-165. It computes sha256 over `formatJson(document)`, which is the Prettier 3.8.3 json printer run over `JSON.stringify(v,null,2)`.
2. Nothing in Rust, SQL, apps/app, packages/supabase or scripts computes a document fingerprint. In crates/core, `sha2` is a dev-dependency only.
3. SQL has no fingerprint column, CHECK, trigger or RPC. Measured on PGlite (PG 17.5), `jsonb::text` of the draft hashes to eaf891f4…, not 27c7383c…. jsonb reorders keys (length, then bytes) and keeps numeric scale (`1.50`, `1.0`).
4. One real value exists: 27c7383c445c73dc2001ebf4794a3ea63d416910bbbaa0d7848dd720de7c2660. It equals sha256(draft/document.json, 302,794 B), has been unchanged since 0a17e39 (2026-10-10), and belongs to sheetId 503dc301-… (uuid derived from `faunosteo:sheet:equine:v1`) with versionId null.
5. That value sits in sheet-ref.json, in report-migration-map.json, in 8 app JSON fixtures, in 6 Rust oracle files, and inside the attachments of 99 of the 216 committed PDFs.
6. The rebase decides on the fingerprint alone (rebase.rs:40). The envelope invariant (read.rs:116-119) and the export (input.rs:206-207) compare sheetId and fingerprint. versionId is never compared anywhere.
7. Mismatch on import or draft restore: the report is rebased. `report.sheet` takes the loaded ref, unknown zones and findings get `unresolved: true`, labels are filled only where absent, nothing is deleted. Messages: `home.import.rebased`, `editor.draft_rebased`.
8. Same fingerprint with a different sheetId: no rebase, so the report keeps the foreign sheetId and a later export is refused with `sheet_mismatch`, shown as the generic `editor.export_failed`.
9. Both v2 imports and new reports get their stamp from the copies the pipeline writes (map.sheet, sheet-ref.json). No runtime check verifies that those copies agree or match document.json.
10. `BundledRef.document_sha256` is loaded without any format check (loaded.rs:29-36). Report and snapshot refs are checked against `^[0-9a-f]{64}$`.
11. The hashed bytes depend on Prettier's layout. The file differs from `JSON.stringify(v,null,2)+LF` from line 17 on, because Prettier collapses short arrays. It also differs from the parsed form: Zod or serde fill defaults, 173,136 vs 245,636 UTF-16 units compact.
12. Draft data: 208 numbers (29 non-integer, none negative, no exponent, no `-0`, all already in ECMAScript `Number#toString` form). No escape of any kind, no astral character, no empty container. Every key is ASCII, and key order is schema order, not sorted.
13. The docs disagree with each other. BDR-045 / Annex C says "existing fingerprints untouched". RUST.md:2092 and TODO:307 still say "will change once".
14. Doc errors: RUST_ARCHITECTURE_REVIEW.md:145 says "lean document" (the fingerprint covers the full document) and cites the deleted `packages/pdf export.ts:88`. STEP6:89 says "every run changes" the fingerprint, but the pipeline is deterministic and the golden test pins it.
15. Open: which form gets canonicalised (input file or parsed), what "compatibility" with 27c7… means concretely, who computes the fingerprint for database-served sheets (Step 13), and whether versionId or sheetId should take part in the rebase decision.
## 1. Producers (who computes a fingerprint)
| Layer | Site | What it does |
|---|---|---|
| TS pipeline | packages/anatomy/src/curation/pipeline.ts:158-165 `sheetRef()` | `documentSha256: sha256Hex(documentJson)`, with `sheetId: draft.sheetId` and `versionId: null` |
| | pipeline.ts:185-186 | `documentJson = await formatJson(draft.document)`. The same text is written as `document.json` (:203) and embedded verbatim in the seed SQL (:216-221, seed.ts:21-25 and :73-80 dollar-quoted `::jsonb`) |
| | pipeline.ts:205-211 | writes `sheet-ref.json` `{sheet_id, version_id, document_sha256, schema_version, species_id}` |
| | pipeline.ts:187-194 → curation/migration-map.ts:24 | the same `ref` object becomes `report-migration-map.json` `.sheet` |
| | packages/anatomy/src/legacy/ids.ts:15-17 | `sha256Hex = createHash('sha256').update(data).digest('hex')` (node:crypto, UTF-8 of the string) |
| | packages/anatomy/src/format.ts:9-26 | `formatJson(v) = prettier.format(JSON.stringify(v,null,2), {parser:'json', printWidth:80, …})`. Prettier `^3.4.2` (packages/anatomy/package.json:31), locked 3.8.3 (pnpm-lock.yaml:1894) |
| TS legacy importer | legacy/artifacts.ts:17 | writes legacy-import/document.json through `formatJson`. It produces no fingerprint and no sheet-ref |
| TS app | none | apps/app/vite/sheet-bundle.ts:44-75 `JSON.parse`s document.json and re-serialises the payload (`JSON.stringify(payload)`, :99). The browser never holds the hashed bytes. provider.ts:46-57 copies `ref` |
| TS packages | none | packages/domain, packages/supabase and packages/core-wasm/src have no document hash |
| Rust | none | crates/core: `sha2` is a `[dev-dependencies]` entry (Cargo.toml:41-44, oracle digests). crates/worker: sha2 hashes WebP output only (job.rs:8, :210, :264). crates/wasm: nothing |
| SQL | none | no column, CHECK, trigger or RPC hashes `content`. sha256 columns exist only for assets: `anatomical_sheet_assets.sha256` (20261008110000_anatomical_sheets.sql:154-164) and `public.assets.sha256` (20261013100000_files_foundation.sql:74-75) |
| Scripts | none | scripts/browser/lib/core-module.mjs:45 and scripts/r4-j2-kit.mjs:51 pass `sheet-ref.json` through. wasm-stamp.mjs and r4-afm-data.mjs hash other inputs |
On the SQL side, `anatomical_sheet_versions.content` is `jsonb` (anatomical_sheets.sql:105-108, 2 MiB cap). Its schema version is pinned by CHECK (`document_schema_version = 2`, 20261010100000_sheet_document_schema_v2.sql:11-12). Measured on PGlite 0.3.16 (PostgreSQL 17.5, in-memory), one run:
```
jsonb_text_sha: eaf891f46d3149ecc8734c51ccca57a5459c9c1e5d81776445b25bba351d5d54 (file: 27c7383c…)
jsonb_text_bytes: 184105 stable re-cast: true
head: {"name": {"en": "Horse", "fr": "Cheval"}, "views": [{"id": "main", "kind": "main", ...
numeric samples [1.50, 1e2, -0, 743.0451049804688, 1.0] -> [1.50, 100, 0, 743.0451049804688, 1.0]
key order {"fr","en","schema_version","id"} -> {"en","fr","id","schema_version"} duplicate key -> last wins
```
jsonb::text orders keys by length then bytes and uses `", "` / `": "` separators. It keeps numeric scale (`1.50`, `1.0`), unlike JS and JCS. `1e2` becomes `100` and `-0` becomes `0`.
## 2. Consumers (read / compare)
| Site | file:line | Behaviour |
|---|---|---|
| Contract `SheetRef` | crates/core/src/domain/report/v3.rs:51-71 | `{sheetId, versionId\|null, documentSha256}`. `deserialize_with = "sha256"` → `js::is_sha256_hex` (js.rs:186-188, `^[0-9a-f]{64}$`). No `deny_unknown_fields` |
| Contract `SheetSnapshotRef` | archive/snapshot.rs:39-55 | adds schemaVersion and speciesId, `deny_unknown_fields`, same sha256 check |
| Bundle load | domain/sheet/loaded.rs:29-36, :104-111 | `BundledRef.document_sha256: String` copied into `LoadedSheet.reference` without format check or recomputation |
| Index to TS | sheet/index_data.rs:25, :112 | exposes `ref` (`SheetIndexData.ref`) → apps/app/src/services/sheetIndex.ts:28, :63-66 |
| New report | ops.rs:53-60, :117-125 → editor/report_ops.rs:56 | stamps the `SheetRef` it receives (validated). App: NewReportRoute.tsx:77 `sheet.sheet.ref` (from provider.ts `availabilityOf`, raw bundle) → reportStore.ts:354-366 → reportOps.ts:21-29 `report.new` |
| v2 migration | domain/report/read.rs:91 | `sheet: map.sheet.clone()`: a migrated v2 report takes the migration map's ref |
| Rebase | domain/report/rebase.rs:40-47 | only `report.sheet.document_sha256 == sheet.reference.document_sha256`: equal → report returned untouched, `rebased:false` |
| | rebase.rs:48-62 | otherwise `rebased.sheet = sheet.reference.clone()` (sheetId, versionId and sha all replaced), observations rebased, `reparse` through the v3 schema |
| Envelope invariant | domain/archive/read.rs:94-119 | `snapshot.ref.sheet_id == report.sheet.sheet_id && snapshot.ref.document_sha256 == report.sheet.document_sha256`. If false: `SnapshotRejection::SheetMismatch`, envelope dropped, report kept (:86-89) |
| Session entries | domain/session.rs:76-101 (draft), :111-135 (import) | read, then rebase with the archived snapshot. A rebase failure becomes `RestoreFailure::Rebase` → `rebase_failed` (ops.rs:327) or `ImportFailure::Invalid` → `invalid` (ops.rs:351-357) |
| Snapshot build | archive/snapshot_rules.rs:54-66 | copies the loaded ref into `sheetSnapshot.ref`. The snapshot `document` is the lean document, so the ref names the full document, not the archived one |
| Export check | pdf/write/input.rs:204-210 | `sheet_id !=` or `document_sha256 !=` → `ExportErrorKind::SheetMismatch` (`sheet_mismatch`, :50, :66) |
| Export envelope | pdf/write/export.rs:26-37 | writes `report` (with its `sheet`) and `sheetSnapshot` (with `ref`) as given, `JSON.stringify(…,null,2)` form. `export_from_envelope` (:116-137) re-exports from the envelope's own report and snapshot. The PDF layout draws no ref |
| PDF import | pdf/import.rs:22-30, facade.rs:66-77 | byte scan → `import_archive` (same rebase) |
| Rescue copy | facade.rs:80-100 | `restore_draft` semantics with no archive |
| `sheet_ref` op | facade.rs:43 | echo of the contract (tests) |
| report-compare | bin/report_compare.rs:32-66 | loads `sheet-ref.json` as-is. compare/mod.rs:133 reads the archive with no rebase. compare/lines.rs:347-367: sheetId and sha equal → `sheet … (draft, matches the bundled sheet)`, else `sheet … !! written on another sheet document (sha <12 hex>…)`. Exit code unaffected (exit 2 only on unreadable entries, run.rs:252) |
| App, import messages | apps/app/src/app/routes/HomeRoute.tsx:41-100, :205-229 | see §4 |
| App, draft restore | state/reportStore.ts:262-293; EditorRoute.tsx:58-67, :104-139 | see §4 |
| App, error mapping | core/worker/outcome.ts:65-67 | `invalid` (rebase refused) → `ImportError('generic')`. EditorRoute.tsx:262: every export failure, `sheet_mismatch` included → `editor.export_failed` |
| packages/domain (frozen; only packages/anatomy imports it, type-only for SheetRef) | report/v3.ts:31-38; rebase.ts:114-135; archive/envelope.ts:96-101; archive/snapshot.ts:24, :60-68, :262-276; report/migration-map.ts:17; report/migrate.ts:121; anatomical-sheet/sheet-index.ts:23 | same semantics as the Rust (rebase on sha only, invariant on sheetId+sha) |
| N-1 reader | packages/core-wasm/tests/n-1/domain/** | byte-identical to packages/domain/src (`diff -r` empty). Used by pdf-export.test.ts:16, :192 and measure.test.ts:14 |
| packages/supabase | none | publish gate anatomical-sheets.ts:74-98 checks shape and integrity only. scripts/upload-sheet-assets.ts:58-59 hashes asset bytes |
| SQL RPCs | anatomical_sheets.sql:735-762 `create_sheet_draft` copies `content` verbatim from a non-draft version (same document, new `gen_random_uuid` id). :764-805 `publish_sheet_version` runs `sheet_document_issues` and `unknown_assets`, no hash. No reports table exists |
## 3. Stored values
Only one non-synthetic fingerprint has ever been committed. `git log` on sheet-ref.json shows one commit, 0a17e39 (2026-10-10), and document.json has not changed since that commit.
| Value | Where (file:line) | Identifies |
|---|---|---|
| `27c7383c445c73dc2001ebf4794a3ea63d416910bbbaa0d7848dd720de7c2660` | supabase/seed/anatomical-sheets/equine/draft/sheet-ref.json:4; draft/report-migration-map.json:6 | sha256 of the committed draft/document.json bytes (302,794 B, verified with `sha256sum`). sheetId `503dc301-a8b1-50d4-9e44-0919b2fc2916` = `deterministicUuid('faunosteo:sheet:equine:v1')` (verified; importer.ts:329), versionId null, curated draft schema v2 |
| same | apps/app/tests/fixtures/report-v3.demo.json:24; r4/reports/L.json:24; r4/reports/CAP.json:24; pdf/r3/store-path.report.json:22 | Report v3 fixtures stamped on the bundled draft |
| same | apps/app/tests/fixtures/goldens/r2/envelope.demo.fr.nologos.json:29,279; envelope.v2full…:29,160; envelope.v2unresolved…:24,763 | report.sheet + sheetSnapshot.ref of frozen envelopes |
| same | crates/core/tests/oracles/editor.json (18 lines, 1669…2475); migration-map.draft.json:1; report-v3.demo.json:1 | R2 oracles frozen from the TS |
| same | oracles/r4/compare/compare.json:9; oracles/r4/tolerance.json:6 | sheet pins, asserted equal to the loaded ref (pdf_compare.rs:266-270) |
| same | oracles/r4/text.json:17807-17808 | an AFM width sample string, not a fingerprint use |
| same | attachments of 99 committed PDFs (pdf/r3 13, r3/real 1, r4/read 21, r4/tolerance 50, step6 3, fixtures root 1, compare scenarios 10). Visible uncompressed in r4/read/scan.{crlf-unspaced-type-params,indirect-length,wrong-direct-length}.pdf | exported archives of the draft |
| `fff…f` (64) | 1 PDF in r4/read; archive_rules.rs:777; domain archive.envelope.test.ts:189; r2-characterisation.test.ts:676; anatomy curation.migration-map.test.ts:15 | synthetic: snapshot of another sheet |
| `bbb…b` | 1 PDF in compare scenarios; report_rules.rs:397; reportStore.test.ts:201; HomeRoute.archive.test.tsx:69; domain tests | synthetic "other sheet" |
| `aaa…a`, `ccc…c`, `eee…e`, `000…0` | oracles/characterisation.json, oracles/verdicts.json (≈600 `a`), Rust tests (`"0".repeat(64)` in sheet_index.rs:120, editor_rules.rs:43, sheet_contract.rs:35, anatomy_canvas_op.rs:21, pdf_layout.rs:295), app tests (`'c'.repeat(64)` in heldSession/quarantine/rescueCopy, `'0'` in EditorRoute.test.tsx:223) | synthetic. Part of the `c` values are asset hashes |
| `91e459f4c0ac8043831242c9fccde01f75f1023464db909f1c29571aa8a414c2` | not stored: sha256 of legacy-import/document.json, computed for this census | legacy baseline has no sheet-ref |
| `eaf891f4…5d54` | not stored: sha256 of the draft's `jsonb::text` (PGlite) | §1 |
The other 64-hex values in the repo (89 files) are unrelated to the fingerprint: asset hashes (draft horse.svg `0ea5202f…` in draft/assets.json and equine_draft.sql:18, two legacy-import asset hashes), PDF and PNG digests in oracles, R4 golden digests, wasm and build digests under scripts/browser/results, and AFM data headers.
The PDF scan was a regex over raw bytes plus zlib inflation of every `stream`. 116 PDFs carry no fingerprint: r4/read hostile and v2 cases (110), 3 compare scenarios, 2 legacy v2 PDFs and 1 tolerance case.
## 4. Semantics on mismatch
Import (PDF or attachment JSON), session.rs:111-135, in this order.
1. The report is read first. A v3 report is kept as written. A v2 report is migrated and stamped with `map.sheet` (read.rs:91), which is 27c7…/503dc301 today.
2. Envelope v1: the snapshot passes the strict gate, then the invariant. The snapshot ref and the report ref of the same file must agree on sheetId and fingerprint (read.rs:116-119). If they don't, the envelope is dropped (`snapshotRejected: 'sheet_mismatch'`) and the report is kept. Message: `home.import.snapshot_rejected` (fr.ts:46-47, en.ts:44-45) with `home.import.snapshot_reason.sheet_mismatch` ("fiche différente de celle du bilan", fr.ts:53-54; "sheet differs from the report's", en.ts:51-52). Headline `home.import.degraded`.
3. Rebase onto the loaded sheet (rebase.rs). If the fingerprint is equal, nothing changes. If it differs, `report.sheet` becomes the loaded ref.
- A zone becomes `unresolved: true` when its `annotationId` or `viewId` is unknown (:85-101). Its label snapshots are filled from the archived snapshot only when absent (`??=`, :103-112).
- A finding becomes `unresolved: true` when `(findingZoneId, path)` is unknown (:137-153).
- Already-flagged items are left alone and not re-counted. Ids, paths, severity, comments and labels are all kept. "unresolved" means "the loaded sheet cannot place this item", not "deleted".
- The app shows `home.import.rebased` with the count: "Bilan ouvert sur la fiche actuelle, différente de celle de l'archive. Éléments non retrouvés : {count} (conservés avec leurs libellés)." (fr.ts:55-56, en.ts:53-54).
- The headline is `home.import.complete` (fr.ts:39, en.ts:37) when 0 items are lost, else `home.import.degraded` (fr.ts:40-41, en.ts:38-39) (HomeRoute.tsx:70-84). An accepted envelope adds `home.import.archive_ok` (fr.ts:44-45).
- The imported envelope is kept unchanged (`osteo:archive`) with its original refs. Only the working report is rebased.
4. A sheetId that differs while the fingerprint is equal triggers no rebase, because rebase.rs:40 ignores sheetId. The foreign sheetId stays, and a later export is refused (`sheet_mismatch`, input.rs:206) as the generic `editor.export_failed` (EditorRoute.tsx:262). A different sheetId with a different fingerprint is rebased and the sheetId replaced.
Draft restore (reportStore.ts:262-293 → core `draft.restore`) uses the same rebase. When the draft was rebased, items were flagged and the practitioner has not confirmed replacement, the raw draft goes to `osteo:quarantine:draft-pre-rebase`, or is held if that slot cannot be written. The editor then shows `editor.draft_rebased` (fr.ts:89-90; en.ts:83-84). A rescue copy (HomeRoute.tsx:222-229) gets the same message. If the rebased report fails the schema (a defect of the loaded ref, such as a malformed bundle sha), the result is `rebase_failed`: the draft stays where it is and the app answers `core_unavailable` (reportStore.ts:266-271).
Export: the snapshot ref and the report ref must agree on sheetId and fingerprint. After any rebase both equal the loaded ref. The envelope carries the fingerprint twice (`report.sheet` and `sheetSnapshot.ref`, docs/PDF-FORMAT.md:60-70, :121-122), and the visible PDF text carries none. report-compare prints a header line only (§2) and never rebases.
## 5. Document data shape (script output)
```
== draft/document.json bytes 302794 sha256 27c7383c…2660 BOM False CR False tabs False trailing LF True lines 8284
top-level keys: schema_version species_id name description scope_disclaimer attribution vertebral_config references categories views annotations finding_zones
numbers: {'int': 179, 'float': 29} (no negative, no exponent, no -0) float paths: geometry.points 28, geometry.cx 1
float examples 743.0451049804688 1418.5 556.2 … max 16 significant digits; ending .0: 0; int range 2..1780
raw escapes in file: \u 0 \n 0 \" 0 \\ 0 \/ 0 \t 0
non-ASCII code points 1831, distinct 18: é 1354, è 139, à 106, ï 58, ° 45, ê 37, ç 22, â 19, « 15, » 15, – U+2013 6, ô 5 …; astral 0
strings 3724, non-ASCII 788, control chars 0; max string length 521 code points ($.scope_disclaimer.fr)
non-ASCII keys 0; duplicate-key objects 0; objects 1951, arrays 370
objects with >=2 keys: sorted (UTF-16) 560, not sorted 1390 (e.g. $ top level; every {fr, en}); single-key 1
empty objects 0; empty arrays 0; nulls 66 (doi 27, vertebral_region_code 22, url 13, license, view_box, svg_asset_id, name); booleans true 55, false 0
max depth 10 at $.finding_zones[0].categories[0].children[0].children[0].name.fr
== legacy-import/document.json bytes 224109 sha256 91e459f4…14c2 same top-level keys, LF, no BOM
numbers int 159, float 36 (max 17 significant digits, 1424.2662353515625); no negative/exponent/-0; escapes 0; astral 0
non-ASCII 1164 code points, 11 distinct (adds — U+2014 ×4, É ×2); strings 2889 (650 non-ASCII); max length 253
objects 1808 (586 sorted, 1158 not, 64 single-key); empty arrays 1 ($.references); nulls 30; max depth 10
```
Node checks:
```
draft: file === JSON.stringify(v,null,2)+LF: false; first diff line 17 '"authors": ["Faunosteo"],' (Prettier collapses short arrays, e.g. "[1655, 545]"); 8284 vs 8695 lines
draft: number tokens 208, not in ECMAScript Number#toString form 0, unsafe integers 0 (legacy: 195 / 0 / 0)
draft: compact UTF-8 bytes 174,974; JSON.stringify(raw) 173,136 UTF-16 units vs JSON.stringify(Zod.parse(raw)) 245,636 (first diff: count_range:null default added)
legacy: same pattern, 110,854 vs 190,448
```
What these checks show:
- The hashed bytes are the input form: defaults are omitted (no empty arrays, no `count_range`). The parsed form adds those defaults, so its bytes differ.
- Key order is construction or schema order, not sorted.
- Numbers already print as ECMAScript does, and no string needs escaping.
- The layout comes from Prettier's line fitting (printWidth 80), which is not `JSON.stringify` layout.
## 6. Documentation statements
| file:line | Statement (quoted or condensed) |
|---|---|
| docs/development/RUST_ARCHITECTURE_REVIEW.md:55-60 | "`documentSha256` is today the sha256 of the Prettier-formatted document text. It is computed once by the pipeline and only compared at runtime; a different hash sends an old archive through the rebase path … The study therefore does not chain the pipeline to Prettier (D-R5)" |
| …REVIEW.md:145 | "sha256 of the Prettier-formatted lean document text … (`rebase.ts:119`, `envelope.ts:100`, pdf `export.ts:88`)". "lean" is inaccurate (the full curated document is hashed), and `packages/pdf` was deleted at R4.8 |
| …REVIEW.md:584 | `serde_jcs` listed under "Rejected" (Part V) |
| …REVIEW.md:636, :655 | R5 row: "seed golden regenerated once (decided)". Compatibility: "regenerated seed (new `documentSha256`) … rebase tests both ways on the two seeds" |
| …REVIEW.md:837 (Part X), :873 (Annex A) | D-R5 rev 2: "`documentSha256` = sha256 of the bytes the Rust pipeline emits; generated dirs leave Prettier's scope; the one-time hash change makes older archives … rebase … 0 unresolved items". Alternatives named: keep Prettier, or canonical JSON (RFC 8785, `serde_jcs`) |
| …REVIEW.md:974 (Annex C, owner amendment) | "Preference for a deterministic fingerprint over a canonical JSON representation independent of the formatter … study RFC 8785 (JCS) or a strictly defined alternative … Explicit compatibility with the fingerprints and archives already produced. Existing fingerprints are not changed now: the decision is prepared for R5" |
| docs/development/RUST.md:2092-2094 | "`documentSha256` will change once (D-R5) and every older archive will rebase on import" |
| RUST.md:1902 | report-compare loads `sheet-ref.json` |
| docs/PDF-FORMAT.md:66, :106 | snapshot `ref.documentSha256`; "sha256 of the full catalog document (provenance pointer)" |
| PDF-FORMAT.md:121-122 | "Invariant: `report.sheet.documentSha256 === sheetSnapshot.ref.documentSha256` (and the sheet ids match). The export refuses to write a file that breaks it." |
| PDF-FORMAT.md:175, :195-200 | closed reason `sheet_mismatch`; "When the archive's sheet differs from the loaded one, the report is rebased …" |
| docs/development/ANATOMICAL_SHEET_MODEL.md:317 | `sheet-ref.json` "(sheet id, null version id, sha256 of the document)" |
| docs/development/STEP5_MIGRATION_ANALYSIS.md:74, :94-95, :137 | "`documentSha256` the hash of `draft/document.json`" |
| docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md:88-89 | pre-Step-6 state: "Nothing compares `report.sheet` with the loaded sheet … Every `pnpm import:equine` run changes the draft's `documentSha256`" (the second sentence conflicts with the deterministic golden) |
| STEP6:124, :160-161, :290-293, :775-776 | ref = "full catalog document's hash, kept as a pointer, not as a hash of the snapshot"; invariant; rebase trigger; export `sheet_mismatch` |
| .claude/memory/decisions.md:327 (BDR-038) | Report v3 `sheet {sheetId, versionId\|null, documentSha256}` |
| decisions.md:336 (BDR-039) | the snapshot hash check was rejected as "self-referential; sha copied … as provenance pointer" (about assets) |
| decisions.md:361 (BDR-043) | alternative rejected: "Prettier-chained sheet identity (hash only compared at runtime → one-time rebase accepted)" |
| decisions.md:371 (BDR-045) | "D-R5 fingerprint → canonical JSON (RFC 8785 JCS or strictly defined alternative) independent of formatter, explicit compat with old fingerprints/archives, existing fingerprints untouched, decision prepared for R5" |
| .claude/memory/learnings.md:363 (LRN-048) | "`documentSha256` = sha256 of Prettier-formatted text (only compared at runtime → mismatch = rebase, not loss)" |
| .claude/tasks/TODO.md:307 | "seed golden regenerated once (new `documentSha256`, D-R5)" |
| CLAUDE.md:277 | `draft/` holds `sheet-ref` |
## 7. Risks and open questions (analyzer)
Risks:
- Any change to the emitted bytes with identical content (Rust emitter, Prettier bump, printWidth) changes the value. Every archive and draft carrying 27c7… then rebases with a visible message, normally with 0 unresolved items. That covers 99 committed PDFs, 8 JSON fixtures and 6 Rust oracle files, which would need decisions.
- map.sheet and sheet-ref.json are two copies with no runtime equality check. If they diverge, every v2 import is stamped with one and rebased onto the other (low: one pipeline value plus the golden).
- The bundle fingerprint is not format-checked at load. A malformed value surfaces later as `rebase_failed`, generic `invalid` or a refused `report.new` (low).
- versionId is never compared, and create_sheet_draft copies content verbatim. Once sheets come from the database (Step 13), versions with identical content would share a fingerprint and skip the rebase (medium).
- If a fingerprint has to be computed from database `content`, the jsonb text differs from the file (key order, numeric scale). The current value cannot be reproduced from jsonb (medium at Step 13).
- Stale or contradictory docs (REVIEW:145 "lean" and deleted citation, RUST.md:2092 and TODO:307 vs BDR-045, STEP6:89) could steer the R5 plan.
Open questions:
- Which statement is in force for R5? BDR-045 / Annex C ("existing fingerprints untouched, explicit compatibility") or RUST.md:2092 / TODO:307 ("will change once")?
- What does "compatibility with fingerprints already produced" mean concretely: keep 27c7… for the current draft, an old→new equivalence, or a one-time rebase with a message?
- Which form gets canonicalised: the input file form (defaults omitted) or the parsed form (defaults filled)? They differ by about 72k UTF-16 units.
- For database-served sheets, who computes and stores the fingerprint (pipeline or operator, Rust service, SQL)? No column exists.
- Should sheetId or versionId join the rebase decision (today it uses the fingerprint only), given that the export and the envelope check sheetId too?