chore(memory): R5 plan, pipeline inventory and documentSha256 census audits, TODO R5.1, journal, LRN-070, EVAL-026
This commit is contained in:
1 parent
60cc0f5fa8
commit
64d4595e73
7 files changed
+669
-1
No files matched your search
@@ -0,0 +1,204 @@
|
||||
# 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?
|
||||
Reference in new issue
Block a user