From 81342009fe7800ac8f2e372ca53e21147b55169e Mon Sep 17 00:00:00 2001 From: bchanot Date: Sat, 10 Oct 2026 23:17:23 +0200 Subject: [PATCH] docs: step 6 autonomous PDF archives analysis and plan (snapshot content, envelope v1, compatibility, limits, tests) --- .claude/memory/journal.md | 4 + .claude/tasks/TODO.md | 9 + .../development/STEP6_PDF_ARCHIVE_ANALYSIS.md | 619 ++++++++++++++++++ 3 files changed, 632 insertions(+) create mode 100644 docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index e10c4477..13d40d7b 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -195,3 +195,7 @@ Step 4 validated + finished into develop. User decisions on the 7 open points - Step 5 addendum (2026-10-10, user testing manually): per-leaf migration tests (612 leaves, anatomy + app + PDF roundtrip), `pnpm report:compare` archive check tool (privacy default, escaping), stale `scaffold:species` script removed, attachment read/parse split. Gates: verifier 2→1→CONFORME, security PASS ×2 (2 MEDIUM + 4 LOW fixed by executors). EVAL-012, LRN-044. Branch 14 commits ahead, not merged; awaiting user validation; no Step 6. - Step 5 user validation (2026-10-10): all paths OK. One defect: findings picker text blurry on screen. Root cause (headless Chromium measure): permanent `will-change: transform, opacity` on the picker list + fractional offset inside height-animated card → composited text resampled; PDF unaffected. Hotfix 1f0b710: prop dropped, regression test (app 182). Security PASS, docs NONE. Full check green. User signal → finish Step 5; carpus + moved points noted, 28 annotations NOT a final catalog (enrichment with the osteopath + future editor later). Step 6 to present, not started. + +## 2026-10-10 (session — Step 5 closed, Step 6 analysis) + +Step 5 validated + closed by user; LRN-045 (permanent will-change blurs text) written on develop. Step 6 analysis on chore/step-06-pdf-archive-analysis: 3 analyzers (PDF pipeline, data model, app/tests) → facts: export reads live SheetIndex (labels, views, asset, all annotations of view), 4 fetched logos + 3 hard-coded URLs, DOM in drawing/highlight/raster, attachment = bare v3 Flate'd by pdf-lib, getAttachments dead on pdf-lib 1.17.1, no report↔sheet check anywhere. Measured: lean snapshot envelope 172 KB raw / 51 KB stored (3 obs), 228 / 54 worst; SVG = 90% of stored. Plan: snapshot = lean AnatomicalSheetDocument + assets inline (reuses index/renderer/integrity rules), packages/pdf engine (xmldom compose promoted from app-review.ts, Rasterizer + Branding inputs, no DOM lib), envelope v1 layered reading (report never lost), rebase on import/restore keeps report.sheet == snapshot.ref, export-side caps. 3 plan-challengers GO WITH FIXES (16+19+13 findings folded in). docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md; TODO 6.0–6.7. Awaiting user decisions D1/D4/D6/D7/D8/D10/D12/D13; no implementation. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 75eae18f..47da331a 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -100,6 +100,15 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] 5.10 final controls on the last lot: stale root script scaffold:species removed; verifier ×3 (2→1→CONFORME) + security ×2 PASS on criteria 16-18; EVAL-012 - [x] 5.11 user validation defect: findings picker text blurry on screen → permanent `will-change` on the list dropped (hotfix 1f0b710, regression test); PDF never affected - [ ] 5.12 follow-up (not Step 5): equine sheet anatomical enrichment with the osteopath + future sheet editor (Step 17); the 28 draft annotations (carpus added, points moved) are NOT a final catalog +- [ ] Step 6 — autonomous PDF archives (analysis + plan 2026-10-10 on chore/step-06-pdf-archive-analysis: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md, challenged on 3 lenses GO WITH FIXES; AWAITING USER VALIDATION of D1/D4/D6/D7/D8/D10/D12/D13 before implementation on feature/step-06-pdf-archives) + - [x] 6.0 analysis: 3 analyzers (pipeline, model, app/tests) + size measurements (envelope 172 KB raw / 51 KB stored for 3 obs, 228 / 54 worst case) + 3 plan-challengers → plan rewritten + - [ ] 6.1 Phase 0 freeze with current code: demo report fixture, migrated-v2-with-unresolved builder, G3 bare v3 PDF, G1 text goldens (logos absent + present), G2 structural facts/placements/links, T12 HomeRoute + T13 EditorRoute characterisation + - [ ] 6.2 Phase 1 domain: sheet-index moved, archive/snapshot (buildSheetSnapshot, assertSnapshot, caps), archive/envelope (schema v1, layered readArchiveDocument, SnapshotRejection), report/rebase (rebaseReportOnSheet), bundle carries asset sha + status/name, tests + - [ ] 6.3 Phase 2 anatomy: render/compose.ts promoted from curation/app-review.ts, highlight on the layer tree, review drawing golden unchanged + - [ ] 6.4 Phase 3 packages/pdf: scaffold (no DOM lib, restricted globals, vitest node, Dockerfile, CI, README), svg/sanitize allowlist + horse.svg zero-removal, render moved, Branding/Rasterizer/exportedAt/safeText/dict, exportReportArchive (T3 both logo modes), readReportArchive (filename-first, layered, attachment_stripped; T4-T6, T8), T1/T7/T9/T10 resvg/T11, xmldom bundle size ≤ 50 KB gz + - [ ] 6.5 Phase 4 app: browserRasterizer, branding.ts, export/import on the engine, rebase on import + draft restore, 2 new messages, old render/attachment/highlight code + pdf.* keys removed, report:compare on engine API, T2/T14/T15, suite migrated 1:1 + - [ ] 6.6 Phase 5 docs + gates: PDF-FORMAT.md real, CLAUDE.md map, WORKSPACE.md rule, DEPLOY.md rollback note, CHANGELOG, BDR-014 note; pnpm check, docker build, verifier + security gates, EVAL; manual validation list + - [ ] 6.7 follow-ups recorded for Step 13: catalog asset cap aligned with the archive cap (2 MiB), allowlist sanitiser at upload, app canvas sanitiser (EVAL-011) - [ ] 5 follow-up: allowlist SVG sanitiser before Storage-served assets (Step 13); orphan findings UX (D5) at the report UX step; report:compare residuals (ZodError reason genericised, v3 lines computed once, long template lines); 16 MiB attachment cap without direct test --- diff --git a/docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md b/docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md new file mode 100644 index 00000000..e6722ce0 --- /dev/null +++ b/docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md @@ -0,0 +1,619 @@ +# Step 6 — Autonomous PDF archives: analysis and plan + +Status 2026-10-10: analysis and plan, challenged on three lenses (correctness, +robustness, simplicity: GO WITH FIXES each, fixes folded in below), awaiting +user validation. No implementation. + +Scope authorised by the user on 2026-10-10: the PDF import system, the +attachment and the modules around them may change (this lifts the CLAUDE.md +"ask before" gate for this step). Goal: a Faunosteo PDF must stay readable and +re-renderable when the anatomical sheet it was built on no longer exists in +the catalog. Business behaviour of the PDF is preserved; no graphic redesign. + +Sources: three read-only analyses of the current code (PDF pipeline, data +model, app wiring and tests), size measurements on the equine draft, three +plan challenges. Facts carry a `path:line` reference; measurements were taken +on `develop @ 072d761`. + +--- + +## 1. What the current pipeline depends on + +### 1.1 Inputs read at export time + +`exportReportToPdf(report, sheet: SheetIndex, { locale })` +(`apps/app/src/pdf/export.ts:27`) reads two sources. + +From the **live sheet**, through the `SheetIndex` built from the bundled draft: + +| Data | Used for | Where | +|---|---|---| +| `annotation.name {fr,en}` (trigger: the opened view's name) | zone text | `render/observationPage.ts:355-356`, `services/sheetIndex.ts:108-111` | +| `finding_zones[].name`, looked up by id whatever the `unresolved` flag | finding group heading | `observationPage.ts:383-390` | +| `view.kind`, `view.name` | "general" label, halo, upper-cased detail caption | `:329-340` | +| `view.view_box`, `view.svg_asset_id`, parent chain | crop and asset choice | `anatomy/drawing.ts:61-85` | +| asset SVG text | the drawing | `drawing.ts:52` | +| `document.views` (names title the nameless triggers), `categories[].color`, every annotation of the view | marker layer, then highlight | `packages/anatomy/src/render/layer.ts:114-255` | + +From the **report**: identities, dates, zones `(annotationId, viewId, side, +vertebrae)`, finding leaf snapshots (always the text source, BDR-010) and the +vet flag `(!)` (`observationPage.ts:413-414`), free text, severity, +conclusion. Zone snapshots are a fallback only (`:357-361`). + +From the **i18n dict**: `pdf.*`, `severity.*`, `lateral.*`, +`footer.powered_by`, `footer.in_partnership`. + +Never read: the finding tree nodes (`nodeAt`), `vertebral_config`, +`report.sheet`, `finding.path`. + +### 1.2 Browser and network dependencies + +| Dependency | Where | Behind an interface | +|---|---|---| +| `fetch` of 4 logos on root-relative URLs | `render/logo.ts:6`, `export.ts:63` | no | +| `DOMParser`, `document.createElementNS/importNode` | `drawing.ts:37,78,88,95` | no | +| `querySelectorAll`, `el.remove()`, `XMLSerializer` | `observationPage.ts:159-229` | no | +| `DOMParser`, `Blob`, `URL.createObjectURL`, `Image`, canvas, `toBlob`/`toDataURL`, `atob` | `svgToPng.ts:17-101` | no | +| `DecompressionStream` (read side, guarded) | `attachment.ts:127` | no | +| `new Date()` (non-deterministic bytes) | `export.ts:38`, `attachment.ts:35` | no | + +Hard-coded branding: 4 logo paths under `public/`, link URLs at +`header.ts:63` and `footer.ts:53,92,107,116`, attachment description, +highlight colour `#b85a3f`. No `useConfig`/`appConfig` on the PDF path. +Logos degrade one by one (own try/catch, `export.ts:47-68`); a single view +raster failure sinks the whole export (`Promise.all`, `observationPage.ts:334`). + +Node 24 provides `CompressionStream`, `DecompressionStream`, `TextEncoder`, +`crypto.subtle`, `Blob`, `structuredClone`; it has no `DOMParser`, +`XMLSerializer`, `Image` or `document`. pdf-lib 1.17.1 is DOM-free and already +runs in Node for `pnpm report:compare`. `@faunosteo/anatomy/render` is DOM-free +(`LayerElement` tree + `serializeLayer`), and the curation pipeline already +composes a view drawing with `@xmldom/xmldom` in Node +(`renderAppReviewDrawing`, `packages/anatomy/src/curation/app-review.ts:20-36`: +parse asset, set `viewBox`, drop width/height, append the layer, serialise). + +### 1.3 The attachment today + +- One embedded file `osteo-report.json`, the bare Report v3 (pretty JSON), + Flate-compressed by pdf-lib itself (`FileEmbedder` → `context.flateStream`, + pako). Full fixture: 3,947 B raw, 1,177 B stored. +- Carries `sheet {sheetId, versionId|null, documentSha256}` and nothing else of + the sheet. No locale, no labels beyond the zone and leaf snapshots. +- Read path: `importReportFromPdf` (50 MiB cap) → `readAttachedDocument` + (16 MiB cap, raw object traversal: the `getAttachments` branch never runs on + pdf-lib 1.17.1, so the filename is never checked and the first + `EmbeddedFile` wins) → `readReportDocument` (v3 parsed, v2 migrated with the + bundled map, else `incompatible_version`). Any other failure becomes + `no_attachment` ("not generated by Faunosteo"). +- Nothing compares `report.sheet` with the loaded sheet, on import or on + export. Every `pnpm import:equine` run changes the draft's `documentSha256`. + +### 1.4 What the report already preserves + +Report v3 (`packages/domain/src/report/v3.ts`) embeds: zone names FR/EN +(optional), leaf finding names FR/EN (required), the vet flag, vertebra codes +and indexes, the side, `unresolved: true` on items the v2 migration could not +place (their legacy ids are kept; the 29 unresolved legacy leaves all sit in +zones that still exist: frontal, sphenoid, ssb). It does **not** embed +finding-zone names, ancestor and category names, region names, view names, +colours, geometry, view boxes or assets. + +--- + +## 2. Snapshot: exact content + +### 2.1 Requirement + +Re-read and re-render an old bilan (FR and EN, text and drawings) without the +current catalog, and keep every historical datum including unresolved items. +A sheet id or a dependency on the current catalog is not enough. + +### 2.2 Shape: a lean sheet document, not a new schema + +The snapshot has the shape the renderer and the sheet index already consume +(`LoadedSheet` minus the migration map): `{ status, ref, document, assets }`. +`document` is a valid `AnatomicalSheetDocument` (schema v2, strict, unchanged) +with the bibliography emptied and the finding trees pruned to what the report +uses. So `renderAnnotationLayer`, `buildSheetIndex`, `pickLabel` and +`validateSheetDocument` apply to it with no change, and the full set of sheet +integrity rules (unique ids, acyclic view chain, one main view, categories and +regions present) protects it. + +| Part | Content | Why | +|---|---|---| +| `ref` | `sheet_id`, `version_id`, `document_sha256`, `schema_version`, `species_id`, `name {fr,en}`, `status` | provenance (`document_sha256` is the full catalog document's hash, kept as a pointer, not as a hash of the snapshot) | +| `document.views` | all views | captions, crops, trigger titles (a nameless trigger is titled from the view it opens, `layer.ts:240-248`) | +| `document.annotations` | all annotations, `review_status` kept (schema default) | geometry, colours, zone names, anatomical relations (`finding_zone_id`, `vertebral_region_code`, `opens_view_id`, `laterality`) | +| `document.categories`, `vertebral_config` | all | marker colours, region names and counts | +| `document.finding_zones` | every zone `{id, name}`; for a zone referenced by any finding of the report, resolved or `unresolved`, its categories pruned to the referenced paths (`{id, kind, name}` and every node on the path `{id, name, requires_vet_referral}`, `description: {}`, `reference_ids: []`); other zones keep `categories: []` | group headings by id; the labels of every ancestor on a used path are preserved (+4 KB raw, +0.4 KB stored over empty trees) | +| `document.references` | `[]` | bibliography is not bilan data (15 KB) | +| `document.name`, `description`, `scope_disclaimer`, `attribution` | kept as is (1.4 KB) | sheet identity and legal scope of the historical sheet | +| `assets` | `[{ svg_asset_id, sha256, svg }]` for every asset reachable from a view | the drawing; `sha256` is the catalog's content address copied from the seed manifest (`assets.json`), carried by the bundle from now on, a provenance pointer and not a tamper check | + +The SVG text goes **inline as a JSON string** (SVG is UTF-8 text: no base64 +penalty, one attachment, one size cap, one parse). Separate embedded files +were rejected: the raw-object reader takes the first `EmbeddedFile`, and +several attachments multiply the stripping risk. + +Rejected alternative: a dedicated `SheetSnapshotSchema`. It would force a +rewrite of every sheet lookup in the render path, leave `renderAnnotationLayer` +without a valid input, and lose the sheet integrity rules. + +### 2.3 Envelope (attachment v1) + +```json +{ + "format": "faunosteo-report-archive", + "envelope_version": 1, + "exported_at": "2026-10-10T18:00:00.000Z", + "locale": "fr", + "report": { "version": 3, "...": "Report v3 unchanged" }, + "sheet_snapshot": { + "status": "draft", + "ref": { "sheet_id": "…", "version_id": null, "document_sha256": "…", "schema_version": 2, "species_id": "equine", "name": { "fr": "…", "en": "…" } }, + "document": { "schema_version": 2, "...": "lean AnatomicalSheetDocument" }, + "assets": [ { "svg_asset_id": "…", "sha256": "…", "svg": "" } ] + } +} +``` + +Report v3 is wrapped, not changed: no report version bump. Invariant written +and checked: `report.sheet.documentSha256 === sheet_snapshot.ref.document_sha256` +(see §3.5 for how the app keeps it true). Filename stays `osteo-report.json` +(CLAUDE.md); description becomes `Faunosteo report archive v1`; the PDF Info +dictionary gains `Keywords: faunosteo-archive/1` so a PDF whose attachment was +stripped by a viewer can still be recognised. Pretty-printed as today (an +extracted archive stays human-readable). `locale` and `exported_at` make the +attachment differ between locale variants: BDR-014's "byte-identical JSON" +note is superseded on that point, the report inside stays identical. + +### 2.4 Measured sizes (equine draft, pretty JSON, deflate 6 ≈ pdf-lib Flate) + +| Envelope | Raw | Stored | +|---|---|---| +| 3-observation fixture, lean document + SVG | 172 KB | 51 KB | +| Worst case 27 zones × 3 findings, both views | 228 KB | 54 KB | +| Lean document alone, 3 observations | 29 KB | 4 KB | +| Full document (bibliography included) + SVG, alternative | 464 KB | 79 KB | +| SVG alone, as a JSON string | 138 KB | 47 KB | + +The drawing is 90% of the stored size. The 250 KB target holds on the raw +size (worst case 228 KB) and with a 4× margin on the stored size. Data +conservation wins over size: nothing in §2.2 is dropped to fit. + +--- + +## 3. Target architecture + +### 3.1 One sheet input for the engine: the snapshot + +``` +app export : LoadedSheet + Report ──buildSheetSnapshot()──▶ SheetSnapshot ─┐ +archive re-export: envelope.sheet_snapshot ─────────────────────────────────────┤ + ▼ +exportReportArchive({ report, sheet, branding, locale, rasterizer, exportedAt }) ─▶ { pdf, warnings } +``` + +The engine builds its `SheetIndex` from the snapshot and never sees a live +sheet. The app builds the snapshot from the loaded sheet at export; an archive +re-export passes `envelope.sheet_snapshot` as is. The attachment embeds exactly +what the engine consumed. + +Label policy, identical to today's output: + +- zone name = snapshot annotation name by id (trigger: the opened view's + name), else the report's zone snapshot in the requested locale, else the id; + `unresolved` is never consulted; +- finding group heading = snapshot finding-zone name by id, else the id + upper-cased (as today); +- finding text and the `(!)` marker always come from the report (BDR-010); +- views: unique view ids of the observation present in the snapshot, main + first; an unknown view prints no image, as today. + +### 3.2 Packages and moved code + +| Package | Content | +|---|---| +| `packages/domain` | `archive/envelope.ts`: `ReportArchiveEnvelopeSchema` (v1, metadata tolerant to unknown keys, `report` and `sheet_snapshot` at fixed keys), snapshot caps, `readArchiveDocument(data, map)` with layered reading (§4), `ArchiveReadError`; `archive/snapshot.ts`: `buildSheetSnapshot(loadedSheet, report)` (pure: prune trees, empty references, pick assets), `assertSnapshot(snapshot)` (schema, caps, `validateSheetDocument` with no error, every view reaches an asset present in `assets`); `anatomical-sheet/sheet-index.ts`: `buildSheetIndex`, `pickLabel`, `isObservable` moved from `apps/app/src/services/sheetIndex.ts` (the app re-exports them); `report/rebase.ts`: `rebaseReportOnSheet(report, index, archivedSnapshot?)` (§3.5) | +| `packages/anatomy` | `render/compose.ts`: `composeViewSvg({ assetRoot, document, viewId, highlight })` promoted from `curation/app-review.ts` (xmldom), highlight applied on the `LayerElement` tree before it becomes DOM (fill `#b85a3f`, opacity 0.85, `osteo-halo` filter on the main view, unselected markers dropped, no `data-*`, `` kept); the curation review drawing calls it with no highlight | +| `packages/pdf` (new, `@faunosteo/pdf`) | the engine: `exportReportArchive`, `readReportArchive`; `render/*` moved as is (metadata, fonts, pages, header, footer, text, link annotations, constants); `svg/sanitize.ts` (allowlist, xmldom, §6); `svg/view.ts` (parse → sanitise → compose → serialise, raster size from the view box); `attachment/{write,read,inflate}.ts`; `text.ts` (`safeText`, §6); `dates.ts` (`formatDate` copy, never throws on a free string); `i18n/{fr,en}.ts` (verbatim copies of today's `pdf.*`, `severity.*`, `lateral.*`, `footer.powered_by`, `footer.in_partnership`); types `Branding`, `Rasterizer`, `ExportInput`, `ExportResult`. `tsconfig`: `lib: ["ES2022"]`, `types: ["node"]`; ESLint on `src/**`: `no-restricted-globals` (`fetch`, `window`, `document`, `Image`, `DOMParser`, `XMLSerializer`, `navigator`, `Buffer`, `process`, `require`) and `no-restricted-imports` (`@/*`, `react`, `node:*`); vitest `environment: node` | +| `apps/app/src/pdf` (shrinks) | `export.ts` (snapshot + branding + browser rasterizer → engine; download unchanged), `import.ts` (engine read → `ImportError` kinds, BDR-015), `browserRasterizer.ts` (today's `svgToPng`), `branding.ts` | +| `apps/app/scripts` | `report:compare` moved onto the engine read API (unchanged options) | + +Dependencies added: + +- `@xmldom/xmldom` 0.9.x as a runtime dependency of `packages/pdf` and + `packages/anatomy` (`compose.ts`), pinned: parse, sanitise, compose and + serialise without a browser, in the browser too (one code path). Already in + the workspace as a devDependency of `packages/anatomy` (0.9.12). Unminified + 276 KB / 71 KB gzipped, 43 KB of which is the HTML entity table; expected + 35–45 KB gzipped in the app bundle, measured in Phase 3 with a stated + ceiling of 50 KB, else the browser keeps the native DOM for composition. + Parsed with an `onError` that throws on `error` and `fatalError` and never + logs raw input. Watched by `pnpm audit --prod`. +- `@resvg/resvg-js` as a **devDependency** of `packages/pdf` (D6): real + rasterisation in Node for one end-to-end test. Native prebuilt binaries + (lockfile must carry `linux-x64-musl` for the Docker builder stage, where + the unfiltered install pulls it; the runtime image is nginx and unaffected). + +No text-extraction dependency: drawn-text goldens reuse the +`PDFPage.prototype.drawText` spy pattern (LRN-033). + +### 3.3 Browser-free guarantees + +1. Compile-time: `packages/pdf` has no `DOM` lib, so `document`, `Image`, + `DOMParser` do not type-check. +2. Lint-time: restricted globals and imports on `src/**` (tests may read + fixtures with `node:fs`). +3. Test-time: the engine suite runs under vitest `environment: node` with no + Vite sheet plugin, so nothing can reach the bundled sheet. +4. Rasterisation is an adapter: + `type Rasterizer = (svg: string, size: { widthPx: number; heightPx: number }) => Promise`. + The engine computes the size (width 1200 px, height from the view box, + aspect clamped to [0.2, 2.0]) and degrades per view: a failed raster gives + a page without that image and a `warnings` entry, never a failed export. + Logos degrade one by one as today. + +### 3.4 Branding as explicit input + +```ts +interface Credit { logoPng: Uint8Array | null; url: string; fallbackText: string } +interface Branding { + siteUrl: string; + headerLogoPng: Uint8Array | null; + footerLogoPng: Uint8Array | null; + poweredBy: Credit | null; // today: ZenQuality, 70×16 pt + partner: Credit | null; // today: Paws in Harmony, aspect-derived width +} +``` + +The app assembles it once per export in `branding.ts`: PNG bytes from +bundled assets (`?url` import + fetch inside the app, allowed there), the Paws +SVG rasterised with the browser rasterizer before the engine runs, URLs and +fallback handles as app constants (none of them is an identity string of +`ConfigProvider`; the PDF prints no site name). Branding is **not** embedded in +the archive: brand assets are the publisher's, not bilan data, and a re-export +uses the branding it is given. + +### 3.5 Import flow and the sheet invariant + +`readReportArchive(pdfBytes, migrationMap)` returns +`{ report, snapshot | null, origin: 'envelope_v1' | 'bare_v3' | 'v2', migrated, unresolvedZones, unresolvedFindings, snapshotRejected?: SnapshotRejection }` +with `SnapshotRejection = 'unsupported_envelope' | 'schema' | 'caps' | 'integrity' | 'sheet_mismatch'` +(a closed enum: no received value is echoed). Attachment selection: the +Filespec whose `/F` starts with `osteo-report` first, then the first +`EmbeddedFile` (today's behaviour as fallback); the dead `getAttachments` +branch is removed. A PDF stamped `faunosteo-archive/1` with no attachment +gives the new `ImportError` kind `attachment_stripped` (message: the viewer or +optimiser removed the data; re-export from the original). + +**Invariant and rebase.** The editor always works on the loaded sheet. When a +report arrives whose `report.sheet.documentSha256` differs from the loaded +ref (import of any archive, or a session draft restored after the bundle +changed), the app calls `rebaseReportOnSheet(report, index, archivedSnapshot?)`: + +- a zone whose `annotationId` is absent from the loaded sheet, or whose + `viewId` is unknown, gets `unresolved: true`; its label snapshots are filled + from the archived snapshot when present (labels survive the rebase); +- a finding whose `(findingZoneId, path)` has no node in the loaded sheet gets + `unresolved: true` (same semantics as the v2 migration); +- `report.sheet` becomes the loaded ref; counts are returned and the existing + partial-import alert pattern shows them (new key `home.import.rebased`, + wording to validate: "Bilan établi sur une autre version de la fiche. + Éléments non retrouvés : {count} (conservés avec leurs libellés)."). + +Export then refuses when the invariant does not hold (`ArchiveExportError +'sheet_mismatch'`), which cannot happen through the app once rebase runs on +every entry path. An envelope whose two references disagree is imported with +`snapshotRejected: 'sheet_mismatch'`. + +The imported snapshot is not kept in the session (D8): once rebased, the +report lives on the current sheet, the original PDF remains the historical +rendering, and autonomy is exercised by the engine API and the tests. + +--- + +## 4. v2 / v3 archive compatibility + +Layered reading, so the report is never lost because of its wrapper: + +1. Locate the report: `data.report` when `data.envelope_version` is numeric, + else `data` itself (bare). +2. Parse the report with `readReportDocument` (v3 parsed, v2 migrated with the + bundled map, any other `version` → `incompatible_version` with the report + version found). `foundVersion` always names a **report** version, so the + existing UI message stays true. +3. Parse the envelope metadata tolerantly (unknown keys ignored within v1). + `envelope_version` other than 1 → `snapshotRejected: 'unsupported_envelope'`, + report kept. Then parse `sheet_snapshot` strictly (document schema v2, + caps, integrity, assets reachable, `sheet_mismatch`); any failure → + `snapshotRejected` with its reason, report kept. + +| Archive | Produced by | Import | Re-export | +|---|---|---|---| +| v2 bare report | app before Step 5 | migrated with the map; unresolved items flagged, snapshots and legacy ids kept; then rebased (no-op when the map's sheet is the loaded one) | envelope v1 on the current sheet snapshot; unresolved items print from their snapshots | +| v3 bare report | Step 5 develop | parsed, `snapshot: null`, rebased if the draft changed since | as above | +| envelope v1 | Step 6 | report parsed first, snapshot validated or rejected with a reason, rebased if the sheet changed | from the embedded snapshot, no sheet needed | +| envelope v≥2 | future | report imported if its version is known, `snapshotRejected: 'unsupported_envelope'` | — | +| report v≠2,3 | future | `incompatible_version` with that version | — | + +Durability rule: archive readers never drop a schema version. Sheet document +schema v2 stays readable in `packages/domain` for as long as envelope v1 +archives exist, exactly as Report v2 stays readable today. Forward rule: +additive optional fields keep `envelope_version: 1` (readers ignore unknown +metadata keys); a breaking change bumps it and the reader keeps every older +version. A rollback to a pre-Step-6 app reads an envelope as `no_attachment`; +DEPLOY.md records that limit. + +A v2 archive has no legacy sheet snapshot. Its own pages are the historical +rendering; the attachment serves data recovery. Building a "legacy snapshot" +from `legacy-import/` for a faithful re-render of v2 bilans is possible (the +baseline document and the two legacy SVGs are in the repo) but not proposed: +no external users, BDR-038 rejected v3→v2 work, and the printed PDF already +holds the picture. D4 covers keeping the original v2 JSON. + +Fixtures: the two frozen v2 PDFs stay; Phase 0 freezes, with the current code +(LRN-043): a **v3 bare golden** PDF, a **demo report** `report-v3.demo.json` +(6 observations: main and head views, vertebrae, bilateral sides, a +vet-referral leaf, a leaf label with an en dash, free text, next appointment) +and a **migrated v2 report with unresolved items** (sphenoid / ssb leaves +reached only through unresolved paths). + +--- + +## 5. Re-export without current resources + +`exportReportArchive({ report: envelope.report, sheet: envelope.sheet_snapshot, branding, locale, rasterizer, exportedAt })` +is the whole answer: no sheet provider, no Vite, no browser, no network. The +labels, drawings, colours, crops and relations come from the snapshot; the +finding texts from the report; the only external inputs are the branding and +the locale. Test T1 (§7) performs exactly this call in a Node environment +where no sheet exists. A future server worker runs the same call. + +An operator CLI (`report:reexport`) is **not** planned in this step (D12): the +test proves the property, and a CLI is a public command name plus a file +writer over untrusted content (output names must derive from the input file +name, `wx` open, LRN-044 escaping, resvg under memory and time limits). + +--- + +## 6. Size and security limits + +Write side (new): `buildSheetSnapshot` output goes through `assertSnapshot` +(schema, caps, integrity, assets present, sanitiser acceptance of every asset, +sheet invariant) and the serialised envelope must stay under the 16 MiB +attachment cap; otherwise the export fails with a typed `ArchiveExportError` +(`snapshot_invalid | snapshot_too_large | sheet_mismatch | too_many_pages`) +and an alert, never a file that cannot be read back. The equine draft is 60× +under every cap. Step 13 must align the catalog's asset cap with the archive +cap (BDR-032 allows 20 MiB assets today). + +Caps (checked on both sides, Zod and counters): + +| Item | Cap | +|---|---| +| PDF file | 50 MiB (existing) | +| attachment, raw and inflated | 16 MiB (existing, bomb guard) | +| assets | ≤ 4 per snapshot, ≤ 2 MiB each, ≤ 6 MiB total | +| document | ≤ 64 views, ≤ 1,024 annotations, ≤ 8,192 finding nodes, depth ≤ 8 (pre-checked before the recursive schema), labels ≤ 512 chars | +| report at export | ≤ 500 observations, ≤ 8 views per observation (`too_many_pages`) | +| sanitiser | ≤ 20,000 elements, nesting ≤ 64, ≤ 256 ``, filter `stdDeviation` ≤ 50 | +| raster | width 1200 px, aspect clamped to [0.2, 2.0] (an untrusted root `viewBox` cannot request a 120-million-pixel canvas) | + +SVG sanitiser (`packages/pdf/src/svg/sanitize.ts`, xmldom, used at export on +the bundled asset and at re-export on the archived one; the app canvas is out +of scope, EVAL-011 keeps it for Step 13): + +- the text is refused if it contains ``), + `font-*`; no `on*`; `href`/`xlink:href` and `url(…)` values must be + `#fragment`; `style` attributes may not contain `url(` other than `#`, + `expression(` or `@import`; +- returns the list of removals; the engine logs nothing from it and the test + on `horse.svg` asserts an empty list and a byte-identical serialisation. + +Other guards: strict document schema, `Object.hasOwn` on records, depth +pre-check, no new PII in the envelope (export date, locale). WinAnsi: one text +ingress `safeText()` used by measurement and drawing, testing each code point +with `Encodings.WinAnsi.canEncodeUnicodeCodePoint` (en and em dashes are +encodable and must survive), replacing the rest by `?` and stripping control +characters; a canary test covers `⚠`, `→`, an emoji, `\t`, U+2028 (restores +the lost EVAL-003 test). `formatDate` never throws: a non `YYYY-MM-DD` string +is printed as is. + +--- + +## 7. Tests that prove autonomy + +Phase 0 goldens and characterisation tests, frozen with the current code +before any change: + +- G1 drawn-text sequence per page, FR and EN, for: the v2 full fixture, the + demo report, the migrated v2 report with unresolved items. Two harness + modes: logos absent (fetch 404, as today) and logos present (fetch stub + returning the real PNG bytes from `public/`, Paws raster stubbed). +- G2 per view, structural: `viewBox`, highlighted ids with + `fill`/`fill-opacity`/`filter`, hidden marker count, halo filter on the main + view only, no `data-*` left; plus image placements `(page, x, y, w, h)` and + link annotations `(page, Rect, URI)`. +- G3 `report-v3.bare.pdf` exported by Step 5 code (import fixture only). +- T12 `HomeRoute` import: v2 alert with count, error kinds to messages, + navigation. T13 `EditorRoute` export: call arguments, download name. + Both written now on the current routes and kept green unchanged. + +Engine (`packages/pdf`, node environment): + +- T1 **No-sheet re-export**: export the demo report through the app path → + read the envelope → `exportReportArchive` from the envelope alone → same G1 + text, same G2 facts, same envelope minus `exported_at` (the written snapshot + is `assertSnapshot`'s parsed output, so key order is stable). +- T3 G1/G2 equality between the new engine and the Phase 0 goldens in both + logo modes: proof of "no visible change". +- T4 roundtrip envelope → import → `toEqual` report and snapshot. +- T5 v2 fixtures import (29 unresolved on the 612-leaf report, zones `[]` + everywhere, so an empty-views observation must export) → re-export → + import again equals; G3 imports with `snapshot: null`. +- T6 versions: envelope v2 with report v3 → report imported, + `snapshotRejected: 'unsupported_envelope'`; envelope v1 with report v4 → + `incompatible_version` 4; bare v7 → `incompatible_version` 7. +- T7 size: demo envelope stored < 250 KB, raw size printed. +- T8 security: 5 assets, a 3 MiB asset, depth 9, 1,025 annotations, a + view chain cycle, a dangling `svg_asset_id`, `sheet_mismatch` → the report + imports and `snapshotRejected` names the reason; hostile SVG (`