Files
faunosteo/.claude/tasks/contracts/2026-10-11-step-06-verify.md
T

9.0 KiB

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 | grep -E "Tests|✓|passed" | tail -3; grep -cE "^\s*[?'(five assets|3 MiB|depth 9|1,?025|cycle|dangling|sheet_mismatch)|reason: '" packages/pdf/tests/security.test.ts EXPECT: 20 passed ; the rejection table lists the 7 cases (count ≥ 7 rows carrying a reason:), each asserted to keep outcome.report (one shared assertion over the parametrised table is accepted)
  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 -rnE "\bfetch(|\bwindow.|globalThis.document|\bnew Image(|navigator." packages/pdf/src | wc -l; grep -rln "from '@xmldom/xmldom'" packages/pdf/src | wc -l; grep -rnE "DOMParser|XMLSerializer" packages/pdf/src -l | xargs grep -L "@xmldom/xmldom" | wc -l; grep -rln "fetch(" apps/app/src/pdf; grep -n "environment" packages/pdf/vitest.config.ts; grep -c "no-restricted-globals" packages/pdf/eslint.config.js EXPECT: 0 ; >= 1 ; 0 (every file using DOMParser/XMLSerializer imports them from xmldom) ; apps/app/src/pdf/branding.ts only ; node ; >= 1
  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. EVIDENCE: 2026-10-11 orchestrator: root typecheck/lint/test:run (154+21+130+53+222 = 580 tests) and build rc 0 at 9bd5173; docker build -t faunosteo-step6 . exit 0 (log in the session scratchpad, image tagged). MET.
  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

CLARIFICATIONS

  • 2026-10-11 (orchestrator, after verifier pass 1 ECARTS(31): oracle defects + scope): CHECKs of criteria 6 and 7 rewritten above (the behaviour was met, the oracles counted the wrong thing). FILE SCOPE widened below to the structurally necessary files. Deleted tests authorised: apps/app/tests/unit/pdf.attachment.test.ts → replaced by packages/pdf/tests/read.test.ts (roundtrip, no_attachment, oversized) and apps/app/tests/unit/pdf.import.test.ts; pdf.attachment.inflate.test.ts → packages/pdf/tests/security.test.ts (inflate bomb); pdf.svgToPng.test.ts → apps/app/tests/unit/pdf.browserRasterizer.test.ts. The spec (Part II §18, Phase 4 contract criterion 1) planned the removal of the legacy modules with their tests.

FILE SCOPE

packages/pdf/, packages/domain/ (src/archive, src/report/rebase.ts, src/anatomical-sheet/sheet-index.ts, barrels, package.json, tests), packages/anatomy/src/render/{compose,index}.ts, packages/anatomy/src/curation/app-review.ts, packages/anatomy/tests/render.compose.test.ts, apps/app/package.json, apps/app/src/services/sheetIndex.ts, .claude/** (memory, TODO, contracts), 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.