6.7 KiB
CONTRACT — step-06 phase 1 domain
- date: 2026-10-11 | flow: ship-feature (executor) | branch: feature/step-06-pdf-archives
- status: active
- spec: docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md Part II §13 (types), §14 "Read" steps 1-3 and "Bundle", §15 caps table (snapshot + branding rows), §2.2 (lean document content)
REQUEST (IMMUTABLE)
Give the domain package the archive contracts (sheet snapshot, envelope v1, branding, labels), the layered reader, the report rebase, and move the sheet index into the domain; make the bundle carry the asset hashes. Pure TypeScript + Zod, no DOM, no pdf-lib. The app keeps compiling and its suite stays green through re-export shims; no app behaviour changes in this phase.
ACCEPTANCE CRITERIA
packages/domain/src/anatomical-sheet/sheet-index.tsholdsbuildSheetIndex,pickLabel,isObservable,SheetIndex,ObservableAnnotation,SheetIndexSource = { ref: { documentSha256: string }; document: AnatomicalSheetDocument; assets: Readonly<Record<string, string>> }(generic soSheetIndex['sheet']keeps the caller's type:buildSheetIndex<S extends SheetIndexSource>(sheet: S): SheetIndex<S>);pickLabel(text, locale: 'fr' | 'en').apps/app/src/services/sheetIndex.tsbecomes a re-export of it (no other app file edited for this move). CHECK: cd apps/app && corepack pnpm typecheck && corepack pnpm vitest run tests/unit/sheets.provider.test.ts 2>&1 | tail -2 EXPECT: passedpackages/domain/src/archive/withsnapshot.ts(SheetSnapshotRef,SheetSnapshotAsset,SheetSnapshot,SheetSnapshotSchema,SnapshotSource,buildSheetSnapshot,assertSnapshot,SnapshotError,SnapshotRejection,snapshotIndexSource(snapshot): SheetIndexSource),branding.ts(ImageAsset,Credit,Branding,BrandingSchema),labels.ts(PDF_LABEL_KEYS,PdfLabels,PdfLabelSet,PdfLabelSetSchema),envelope.ts(ENVELOPE_FORMAT,ENVELOPE_VERSION,ReportArchiveEnvelope,ReportArchiveEnvelopeSchema,ArchiveOrigin,ArchiveReadOutcome,readArchiveDocument),index.ts; exported as@faunosteo/domain/archive(package.json exports) and from the root index. Types and behaviour exactly as spec §13/§14;SnapshotSource = { status; ref: SheetRef; speciesId; schemaVersion; document; assets; assetHashes? }so thatLoadedSheetsatisfies it; snapshotref={ ...sheet.ref, schemaVersion, speciesId }. CHECK: cd packages/domain && corepack pnpm vitest run tests/archive.snapshot.test.ts tests/archive.envelope.test.ts tests/archive.branding-labels.test.ts 2>&1 | tail -3 EXPECT: Tests .* passedbuildSheetSnapshot(sheet, report)is pure and deterministic: document = all views, annotations, categories, vertebral_config, name/description/scope_disclaimer/attribution/species_id/schema_version kept;references: []; every finding zone kept as{ id, name, categories }where categories are pruned to the paths referenced by the report's findings (resolved orunresolved): category{ id, kind, name, description: {}, reference_ids: [], review_status, children }, node{ id, name, description: {}, requires_vet_referral, reference_ids: [], review_status, children }; zones not referenced havecategories: []; assets = every asset reachable from a view (ownsvg_asset_idor parent chain),sha256fromassetHashesor null. On the draft with the fixture reportapps/app/tests/fixtures/report-v2.full.jsonmigrated: the document passesAnatomicalSheetDocumentSchemaandvalidateSheetDocumentreturns noerrorissue; pretty JSON of the snapshot (with the SVG) is under 250,000 bytes (print the number in the test output).assertSnapshotorder: iterative depth pre-check offinding_zones[].categories[].children(> 8 →caps) →SheetSnapshotSchema.parse(strict wrapper; failure →schema) → counters (views ≤ 64, annotations ≤ 1024, nodes ≤ 8192, any LocalizedText value > 512 chars, assets ≤ 4 / ≤ 2 MiB each / ≤ 6 MiB total →caps) →validateSheetDocumenthas anerror→integrity→ a view that reaches no asset present inassets→integrity. Tests cover each reason and the happy path.readArchiveDocument(data, map)implements spec §14 "Read" steps 1-3 exactly, with these cases tested: bare v3 →origin 'bare_v3',archive null, counts 0; bare v2 (fixture) →'v2',migrated true, counts from the migration; envelope v1 valid →'envelope_v1',archive= validated envelope,migrated false; envelope withenvelopeVersion: 2and report v3 → report returned,snapshotRejected 'unsupported_envelope'; envelope v1 with reportversion: 4→ throwsUnsupportedReportVersionErrorwith foundVersion 4; envelope v1 with unknown extra metadata key → accepted; envelope v1 with broken branding →'schema'; snapshot over caps →'caps'; snapshot ref sheetId/documentSha256 ≠ report.sheet →'sheet_mismatch';__proto__keys harmless; non-object → throws.packages/domain/src/report/rebase.ts:rebaseReportOnSheet(report, index, archived)as spec §13; tests: same sha → untouched,rebased false; different sha → unknown annotation →unresolved: true+ labels from the archived snapshot's annotation name (both locales) when the zone had none; unknown viewId → unresolved; finding with no node → unresolved; already-unresolved items stay; resolved items untouched;report.sheetreplaced byindex.sheet.ref; output passesReportSchema.- Bundle:
apps/app/vite/sheet-bundle.tspayload gainsassetHashes(fromassets.jsonsha256bysvg_asset_id);apps/app/src/sheets/provider.tsBundledSheetData/LoadedSheetgainassetHashes: Readonly<Record<string, string>>andschemaVersion: number(fromref.schema_version);parseBundledSheetfills them;tests/unit/sheets.provider.test.tsasserts the hash of the horse asset equals the manifest value. - Green everywhere:
corepack pnpm -r typecheck && corepack pnpm -r lint && corepack pnpm -r test:runfrom the repo root (domain, anatomy, supabase, app). The Phase 0 golden tests and route characterisation tests under apps/app/tests must pass unchanged. CHECK: cd /home/bchanot/Documents/faunosteo && corepack pnpm typecheck 2>&1 | tail -2 && corepack pnpm test:run 2>&1 | grep -E "Tests|Test Files" | tail -8 EXPECT: all passed
FILE SCOPE
packages/domain/** (src/anatomical-sheet/sheet-index.ts new, src/archive/* new, src/report/rebase.ts new, index files, package.json exports, tests/archive.*.test.ts, tests/report.rebase.test.ts, tests/sheet-index.test.ts), apps/app/src/services/sheetIndex.ts (re-export only), apps/app/vite/sheet-bundle.ts, apps/app/src/sheets/provider.ts, apps/app/src/sheets/virtual-sheet.d.ts if needed, apps/app/tests/unit/sheets.provider.test.ts. Nothing under apps/app/src/pdf, packages/anatomy, packages/pdf.