docs: step 6 implementation contract (types, envelope v1, read, rebase, session, messages, goldens) + BDR-039

This commit is contained in:
bchanot committed 2026-10-11 11:59:08 +02:00
1 parent 72f19521d3
commit 4c6c5151f8
3 files changed
+408

No files matched your search

+8
View File
@@ -327,3 +327,11 @@ Status: closed.
Sheet source: `SheetProvider` interface; Step 5 implementation = Vite virtual module `virtual:faunosteo-sheet` built from the seed draft (`vite/sheet-bundle.ts`), mode `SHEET_BUNDLE=draft|none`, default draft for dev server, none for builds/CI/Docker (`--build-arg SHEET_BUNDLE=draft` = explicit preview) → unvalidated draft never ships by accident (D2). Markers: pure renderer `@faunosteo/anatomy/render` (element tree, no DOM) reproduces legacy look (hitbox r + twin r−12, opacities 0.65/0.5, spine 0.3, trigger 0.06 dashed); colours = document data (`categories[].color`, additive `annotations[].color` for the head shades, schema_version stays 2 for additive optional fields); same renderer feeds `draft/review/app-<view>.svg` for visual checks. Report v3 in packages/domain: `(annotationId, viewId)` zones with label snapshots, `(findingZoneId, path)` findings, severity codes, `sheet {sheetId, versionId|null, documentSha256}`, `unresolved: true` for what migration cannot place, `localAnnotations: []` reserved. Migration map generated by the pipeline from applier records (replay renames/moves/removals + unique re-homing): 792 nodes → 571/180/7/34. Interaction = pure service + reducers (BDR-019 kept); store = v3 + persistence adapter (v2 draft migrated on restore). D4 applied: registry, matchers, SVG parser, editors, pathology-editor, public species assets deleted; legacy sources moved to `supabase/seed/.../legacy-sources/` (importer input).
Alt rejected: copying the draft into apps/app (duplication, drift); runtime fetch of `/sheets/*.json` (still public, no gain); UUID annotation ids (BDR-031); converting v3→v2 for attachments (lossy); per-view colour table in the app (horse knowledge in generic code).
Status: closed; awaiting user validation of Step 5.
---
## BDR-039 | 2026-10-11 | Step 6: autonomous PDF archives — lean-document snapshot, envelope v1, archived branding + labels, explicit rebase
User-validated design (docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II). Attachment = envelope v1 `{format, envelopeVersion, exportedAt, locale, report v3, sheetSnapshot, branding, labels}` in one `osteo-report.json`, SVG inline as text. Snapshot = `{status, ref, document, assets}` where document = valid lean `AnatomicalSheetDocument` (all views/annotations/categories/regions, finding zones kept by id, trees pruned to used paths with ancestor labels, references emptied) → reuses sheet index, layer renderer, 21 integrity rules; no dedicated schema. Branding (logos base64/svg, credits, URLs) + label dict (fr+en) archived so future logo/wording changes never alter a re-render (user D7 adjustment). Engine `packages/pdf`: explicit inputs `{report, sheet, branding, labels, locale, rasterizer, exportedAt}`, no DOM lib, xmldom composition promoted from curation app-review, Rasterizer adapter (browser Image/canvas; resvg devDep for tests), per-view/per-logo degradation, export-side validation (caps, integrity, sheet invariant). Read = layered: report first (v3/v2 existing dispatch), envelope metadata tolerant, snapshot strict → `snapshotRejected` enum, report never lost; `attachment_stripped` via Info.Keywords stamp. Session: imported archive kept immutable (`osteo:archive`), working copy rebased explicitly on the loaded sheet (`rebaseReportOnSheet`, unresolved flags + labels from archived snapshot) (user D8 adjustment); re-export of the kept archive = technical support only, UX submitted after step. No CLI, no page change, no original v2 JSON re-embedded.
Alt rejected: dedicated SheetSnapshotSchema (rewrites lookups, loses integrity rules); separate embedded files per asset (first-EmbeddedFile reader, stripping risk); pruning views/annotations (saves ~0 KB, breaks trigger titles); snapshot discarded on import (user: keep for faithful re-read); crypto hash check of assets (self-referential; sha copied from catalog manifest as provenance pointer instead).
Status: open (implementation in progress on feature/step-06-pdf-archives).