chore(memory): step 6 whole-step verification contract

This commit is contained in:
bchanot committed 2026-10-11 13:12:37 +02:00
1 parent 9e681232cf
commit 20dafc0b00
1 file changed
+47
@@ -0,0 +1,47 @@
# CONTRACT — step-06 autonomous PDF archives (whole step, for the fresh verifier)
- date: 2026-10-11 | flow: ship-feature | branch: feature/step-06-pdf-archives
- status: active
- spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md (Part II binding), docs/PDF-FORMAT.md; phase contracts 2026-10-11-step-06-phase-{0,1,2,3,4}-*.md
## REQUEST (verbatim user requirements, 2026-10-11 — IMMUTABLE)
Un PDF Faunosteo doit rester lisible, interprétable et réexportable dans le futur, même si : la fiche anatomique originale a disparu ; le catalogue de constats a changé ; les identifiants ou les traductions ont évolué ; le logo Faunosteo a changé ; les ressources du site ne sont plus disponibles ; le bilan contient des éléments hérités ou non résolus. L'export ne doit nécessiter aucun chargement réseau. Preuve automatisée des scénarios : (1) exporter un bilan v3, supprimer l'accès à sa fiche actuelle, puis l'importer et le réexporter depuis son instantané ; (2) modifier le catalogue anatomique courant sans affecter l'interprétation des anciennes archives ; (3) modifier le branding courant sans altérer les ressources historiques d'une archive réexportée ; (4) importer un PDF v2, migrer son bilan et conserver ses éventuels éléments non résolus ; (5) comparer le contenu et le rendu des PDF FR/EN aux références enregistrées avant la refactorisation ; (6) rejeter proprement les instantanés dangereux, invalides ou excessivement volumineux, sans perdre les données récupérables du bilan ; (7) vérifier qu'aucun chargement réseau n'est nécessaire à la génération ; (8) tester la rasterisation réelle des SVG. Aucun changement graphique des pages. Instantané importé conservé en session, rebase explicite sur copie de travail. Messages FR/EN explicites, jamais une importation dégradée présentée comme parfaite.
## ACCEPTANCE CRITERIA
1. Scenario 1 (no-sheet re-export) is a test in packages/pdf that re-exports from the envelope alone and compares text/images/views facts.
CHECK: grep -ln "exportFromEnvelope" packages/pdf/tests/*.test.ts | wc -l; cd packages/pdf && corepack pnpm vitest run tests/reexport.test.ts 2>&1 | tail -2
EXPECT: >= 1 ; passed
2. Scenario 2 (catalog changed) is a test in apps/app that mutates the loaded sheet (labels + geometry) and proves the envelope re-export ignores it.
CHECK: grep -n "mutat\|renamed\|changed sheet\|exportFromEnvelope" apps/app/tests/unit/pdf.export.app.test.ts | head -3; cd apps/app && corepack pnpm vitest run tests/unit/pdf.export.app.test.ts 2>&1 | tail -2
EXPECT: matches ; passed
3. Scenario 3 (branding changed) — the envelope carries `branding` and `labels`, and `exportFromEnvelope` uses them, not the caller's current branding: a test exports with branding A, re-exports the envelope while branding B is the app's current one, and the images/links/text of the re-export equal the first export.
CHECK: grep -rn "branding" packages/pdf/tests/reexport.test.ts apps/app/tests/unit/pdf.export.app.test.ts | grep -i "differ\|current\|B\b\|other" | head -3
EXPECT: at least one assertion that the re-export does not use the current branding (if absent → ECART)
4. Scenario 4 (v2 import with unresolved items kept): v2 fixtures and the 612-leaf report import, unresolved items survive export → import.
CHECK: cd packages/pdf && corepack pnpm vitest run tests/read.test.ts 2>&1 | tail -2; cd ../../apps/app && corepack pnpm vitest run tests/unit/migration.leaves.test.ts 2>&1 | tail -2
EXPECT: passed ; passed
5. Scenario 5 (goldens): the 39 Phase 0 goldens are unchanged in git since commit 8b86b92 and reproduced by the engine (packages/pdf/tests/goldens.test.ts) and by the app path (apps/app/tests/unit/pdf.goldens.test.ts).
CHECK: git diff --stat 8b86b92 HEAD -- apps/app/tests/fixtures/goldens | tail -1; cd packages/pdf && corepack pnpm vitest run tests/goldens.test.ts 2>&1 | tail -2; cd ../../apps/app && corepack pnpm vitest run tests/unit/pdf.goldens.test.ts 2>&1 | tail -2
EXPECT: empty diff ; passed ; passed
6. Scenario 6 (hostile/oversized snapshots rejected, report kept): security tests cover caps, cycles, dangling asset, sheet_mismatch, hostile SVG, entity, use bomb, viewBox bomb, inflate bomb, __proto__; every rejection keeps `report`.
CHECK: cd packages/pdf && corepack pnpm vitest run tests/security.test.ts 2>&1 | tail -2; grep -c "snapshotRejected" packages/pdf/tests/security.test.ts
EXPECT: passed ; >= 6
7. Scenario 7 (no network): packages/pdf has no `fetch`/DOM usage (lint rule + grep) and its suite runs in vitest `node` environment; the only `fetch(` under apps/app/src/pdf is in branding.ts.
CHECK: grep -rn "fetch(\|window\.\|document\.\|new Image\|DOMParser\|XMLSerializer" packages/pdf/src | grep -v "xmldom" | wc -l; grep -rln "fetch(" apps/app/src/pdf; grep -n "environment" packages/pdf/vitest.config.ts
EXPECT: 0 ; apps/app/src/pdf/branding.ts only ; node
8. Scenario 8 (real raster): resvg-based test renders main and head views with dimension and highlight-colour assertions.
CHECK: cd packages/pdf && corepack pnpm vitest run tests/raster.test.ts 2>&1 | tail -2
EXPECT: passed
9. Pages unchanged: no edit to render constants/layout beyond the move (compare `packages/pdf/src/render/*.ts` against `git show 8b86b92:apps/app/src/pdf/render/*.ts` — differences limited to imports, labels source, SheetIndex source, rasterizer call, safeText); goldens green (criterion 5).
10. Session: store holds `archive`, persisted under `osteo:archive` only on hydrateImport/hydrateReport/initReport/reset; `rebaseReportOnSheet` runs on import and draft restore; tests exist.
CHECK: grep -n "osteo:archive\|hydrateImport\|rebaseReportOnSheet" apps/app/src/state/*.ts apps/app/src/app/routes/HomeRoute.tsx apps/app/src/app/routes/EditorRoute.tsx | wc -l
EXPECT: >= 5
11. Messages: fr.ts and en.ts carry `home.import.archive_ok`, `home.import.snapshot_rejected`, five `home.import.snapshot_reason.*`, `home.import.rebased`, `home.import.error_attachment_stripped`; HomeRoute composes them; i18n parity test green; `pdf.*` keys gone from the app dicts.
CHECK: grep -c "home.import.snapshot_reason\." apps/app/src/i18n/fr.ts apps/app/src/i18n/en.ts; grep -c "'pdf\." apps/app/src/i18n/fr.ts
EXPECT: 5 5 ; 0
12. Whole workspace green and buildable: `corepack pnpm typecheck && corepack pnpm lint && corepack pnpm test:run && corepack pnpm build` from the root; `docker build -t faunosteo-step6 .` succeeds.
13. Docs: docs/PDF-FORMAT.md describes envelope v1, snapshot content, layered reading, rebase, caps, sizes; CLAUDE.md folder map lists packages/pdf and the new apps/app/src/pdf files; CHANGELOG has the Step 6 entry; DEPLOY.md has the rollback note.
CHECK: grep -c "envelopeVersion\|snapshotRejected\|rebase" docs/PDF-FORMAT.md; grep -n "packages/pdf" CLAUDE.md | head -2
EXPECT: >= 3 ; present
## FILE SCOPE
packages/pdf/**, packages/domain/src/{archive,report/rebase.ts,anatomical-sheet/sheet-index.ts}, packages/anatomy/src/render/compose.ts, apps/app/src/pdf/**, apps/app/src/state/**, apps/app/src/app/routes/{HomeRoute,EditorRoute}.tsx, apps/app/src/i18n/{fr,en}.ts, apps/app/src/sheets/provider.ts, apps/app/vite/sheet-bundle.ts, apps/app/scripts/**, apps/app/tests/**, docs/**, CLAUDE.md, README.md, CHANGELOG.md, DEPLOY.md, Dockerfile, packages/README.md, pnpm-lock.yaml.