Files
faunosteo/.claude/tasks/contracts/2026-10-11-step-06-phase-1-domain.md

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

  1. packages/domain/src/anatomical-sheet/sheet-index.ts holds buildSheetIndex, pickLabel, isObservable, SheetIndex, ObservableAnnotation, SheetIndexSource = { ref: { documentSha256: string }; document: AnatomicalSheetDocument; assets: Readonly<Record<string, string>> } (generic so SheetIndex['sheet'] keeps the caller's type: buildSheetIndex<S extends SheetIndexSource>(sheet: S): SheetIndex<S>); pickLabel(text, locale: 'fr' | 'en'). apps/app/src/services/sheetIndex.ts becomes 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: passed
  2. packages/domain/src/archive/ with snapshot.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 that LoadedSheet satisfies it; snapshot ref = { ...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 .* passed
  3. buildSheetSnapshot(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 or unresolved): 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 have categories: []; assets = every asset reachable from a view (own svg_asset_id or parent chain), sha256 from assetHashes or null. On the draft with the fixture report apps/app/tests/fixtures/report-v2.full.json migrated: the document passes AnatomicalSheetDocumentSchema and validateSheetDocument returns no error issue; pretty JSON of the snapshot (with the SVG) is under 250,000 bytes (print the number in the test output).
  4. assertSnapshot order: iterative depth pre-check of finding_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) → validateSheetDocument has an error → integrity → a view that reaches no asset present in assets → integrity. Tests cover each reason and the happy path.
  5. 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 with envelopeVersion: 2 and report v3 → report returned, snapshotRejected 'unsupported_envelope'; envelope v1 with report version: 4 → throws UnsupportedReportVersionError with 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.
  6. 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.sheet replaced by index.sheet.ref; output passes ReportSchema.
  7. Bundle: apps/app/vite/sheet-bundle.ts payload gains assetHashes (from assets.json sha256 by svg_asset_id); apps/app/src/sheets/provider.ts BundledSheetData/LoadedSheet gain assetHashes: Readonly<Record<string, string>> and schemaVersion: number (from ref.schema_version); parseBundledSheet fills them; tests/unit/sheets.provider.test.ts asserts the hash of the horse asset equals the manifest value.
  8. Green everywhere: corepack pnpm -r typecheck && corepack pnpm -r lint && corepack pnpm -r test:run from 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/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.