Sprint 1: complete domain models — canonical document, geometry, provenance, readiness

Define all Pydantic v2 domain models for the canonical-first architecture:

- status.py: 12 enums (GeometryStatus, EvidenceType, BlockRole, NonTextKind,
InputType, ReadinessLevel, MissingCapability, OverlayLevel, etc.)
- geometry.py: Point, BBox, Baseline, ClipRect, Geometry (bbox + polygon +
status), GeometryContext — bbox convention is [x, y, width, height]
- provenance.py: Provenance with conditional validation (provider_native
cannot have derived_from)
- readiness.py: AltoReadiness, PageXmlReadiness, ExportEligibility,
DocumentReadiness with consistency validators
- canonical_document.py: Source, Hyphenation, Word, TextLine, TextRegion,
NonTextRegion, Page, Audit, CanonicalDocument — full hierarchy with
metadata field at every level for future extensibility
- raw_payload.py: RawProviderPayload (opaque container for provider output)
- viewer_projection.py: OverlayItem, InspectionData, ViewerProjection
- __init__.py: public API re-exporting all models

All models are frozen (immutable). 117 tests covering validation, rejection
of invalid data, conditional logic, JSON round-trips, and JSON Schema
generation. The spec example from the architecture document validates.

https://claude.ai/code/session_01Cuzvc9Pjfo5u46eT3ta2Cg

src/app/domain/models/__init__.py

@@ -0,0 +1,97 @@
+"""Domain models — public API.
+
+Import from here rather than from individual modules:
+
+    from src.app.domain.models import CanonicalDocument, Word, Page, Geometry
+"""
+
+from src.app.domain.models.canonical_document import (
+    Audit,
+    CanonicalDocument,
+    Hyphenation,
+    NonTextRegion,
+    Page,
+    Source,
+    TextLine,
+    TextRegion,
+    Word,
+)
+from src.app.domain.models.geometry import (
+    BBox,
+    Baseline,
+    ClipRect,
+    Geometry,
+    GeometryContext,
+    Point,
+    PolygonPoints,
+)
+from src.app.domain.models.provenance import Provenance
+from src.app.domain.models.raw_payload import RawProviderPayload
+from src.app.domain.models.readiness import (
+    AltoReadiness,
+    DocumentReadiness,
+    ExportEligibility,
+    PageXmlReadiness,
+)
+from src.app.domain.models.status import (
+    BlockRole,
+    CoordinateOrigin,
+    EvidenceType,
+    GeometryStatus,
+    InputType,
+    MissingCapability,
+    NonTextKind,
+    OverlayLevel,
+    ReadinessLevel,
+    Unit,
+)
+from src.app.domain.models.viewer_projection import (
+    InspectionData,
+    OverlayItem,
+    ViewerProjection,
+)
+
+__all__ = [
+    # Enums
+    "BlockRole",
+    "CoordinateOrigin",
+    "EvidenceType",
+    "GeometryStatus",
+    "InputType",
+    "MissingCapability",
+    "NonTextKind",
+    "OverlayLevel",
+    "ReadinessLevel",
+    "Unit",
+    # Geometry
+    "BBox",
+    "Baseline",
+    "ClipRect",
+    "Geometry",
+    "GeometryContext",
+    "Point",
+    "PolygonPoints",
+    # Provenance
+    "Provenance",
+    # Readiness
+    "AltoReadiness",
+    "DocumentReadiness",
+    "ExportEligibility",
+    "PageXmlReadiness",
+    # Canonical document
+    "Audit",
+    "CanonicalDocument",
+    "Hyphenation",
+    "NonTextRegion",
+    "Page",
+    "Source",
+    "TextLine",
+    "TextRegion",
+    "Word",
+    # Raw payload
+    "RawProviderPayload",
+    # Viewer
+    "InspectionData",
+    "OverlayItem",
+    "ViewerProjection",
+]

src/app/domain/models/canonical_document.py

@@ -0,0 +1,275 @@
+"""CanonicalDocument — the business truth of the system.
+
+This is the central model.  Everything flows through it:
+  Provider output → Adapter → CanonicalDocument → Validators → Serializers
+
+The hierarchy is:  Document → Page → TextRegion (block) → TextLine → Word
+                                    → NonTextRegion
+
+Every node carries geometry + provenance.  No exceptions.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from src.app.domain.models.geometry import Geometry
+from src.app.domain.models.provenance import Provenance
+from src.app.domain.models.readiness import (
+    AltoReadiness,
+    DocumentReadiness,
+    ExportEligibility,
+    PageXmlReadiness,
+)
+from src.app.domain.models.status import (
+    BlockRole,
+    CoordinateOrigin,
+    InputType,
+    NonTextKind,
+    ReadinessLevel,
+    Unit,
+)
+
+
+# -- Source ------------------------------------------------------------------
+
+
+class Source(BaseModel):
+    """Metadata about the original input document."""
+
+    model_config = ConfigDict(frozen=True)
+
+    input_type: InputType
+    filename: str | None = None
+    mime_type: str | None = None
+    checksum: str | None = None
+
+
+# -- Hyphenation -------------------------------------------------------------
+
+
+class Hyphenation(BaseModel):
+    """Word-level hyphenation info for split words across lines."""
+
+    model_config = ConfigDict(frozen=True)
+
+    is_hyphenated: bool
+    part: int | None = None
+    full_form: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_consistency(self) -> Hyphenation:
+        if not self.is_hyphenated:
+            if self.part is not None or self.full_form is not None:
+                raise ValueError(
+                    "When is_hyphenated is False, part and full_form must be None"
+                )
+        else:
+            if self.part not in (1, 2):
+                raise ValueError(f"Hyphenation part must be 1 or 2, got {self.part}")
+            if not self.full_form:
+                raise ValueError("Hyphenation full_form is required when is_hyphenated is True")
+        return self
+
+
+# -- Word --------------------------------------------------------------------
+
+
+class Word(BaseModel):
+    """A single word — the leaf level of the canonical hierarchy.
+
+    This is the primary unit for ALTO export (maps to <String>).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    text: str = Field(min_length=1)
+    normalized_text: str | None = None
+    geometry: Geometry
+    lang: str | None = Field(default=None, pattern=r"^[a-z]{3}$")
+    confidence: float | None = Field(default=None, ge=0, le=1)
+    style_refs: list[str] = Field(default_factory=list)
+    hyphenation: Hyphenation | None = None
+    provenance: Provenance
+    metadata: dict[str, Any] | None = None
+
+
+# -- TextLine ----------------------------------------------------------------
+
+
+class TextLine(BaseModel):
+    """A line of text — contains an ordered list of Words.
+
+    Maps to <TextLine> in ALTO and PAGE XML.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    geometry: Geometry
+    confidence: float | None = Field(default=None, ge=0, le=1)
+    lang: str | None = Field(default=None, pattern=r"^[a-z]{3}$")
+    provenance: Provenance
+    words: list[Word] = Field(min_length=1)
+    metadata: dict[str, Any] | None = None
+
+    @property
+    def text(self) -> str:
+        """Concatenated text of all words in this line."""
+        return " ".join(w.text for w in self.words)
+
+
+# -- TextRegion (block) ------------------------------------------------------
+
+
+class TextRegion(BaseModel):
+    """A text block / region — contains an ordered list of TextLines.
+
+    Maps to <TextBlock> in ALTO and <TextRegion> in PAGE XML.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    role: BlockRole | None = None
+    geometry: Geometry
+    confidence: float | None = Field(default=None, ge=0, le=1)
+    lang: str | None = Field(default=None, pattern=r"^[a-z]{3}$")
+    provenance: Provenance
+    lines: list[TextLine] = Field(min_length=1)
+    metadata: dict[str, Any] | None = None
+
+    @property
+    def text(self) -> str:
+        """Concatenated text of all lines in this region."""
+        return "\n".join(line.text for line in self.lines)
+
+
+# -- NonTextRegion -----------------------------------------------------------
+
+
+class NonTextRegion(BaseModel):
+    """A non-textual region (illustration, table, separator, etc.)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    kind: NonTextKind
+    geometry: Geometry
+    confidence: float | None = Field(default=None, ge=0, le=1)
+    provenance: Provenance
+    metadata: dict[str, Any] | None = None
+
+
+# -- Page --------------------------------------------------------------------
+
+
+class Page(BaseModel):
+    """A single page in the document.
+
+    Contains text regions (blocks), non-text regions, reading order,
+    and per-page readiness assessments.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    page_index: int = Field(ge=0)
+    width: float = Field(gt=0)
+    height: float = Field(gt=0)
+    unit: Unit = Unit.PX
+    rotation: float = 0.0
+    coordinate_origin: CoordinateOrigin = CoordinateOrigin.TOP_LEFT
+
+    alto_readiness: AltoReadiness = Field(
+        default_factory=lambda: AltoReadiness(level=ReadinessLevel.NONE, missing=["word_text"])
+    )
+    page_readiness: PageXmlReadiness = Field(
+        default_factory=lambda: PageXmlReadiness(level=ReadinessLevel.NONE, missing=["word_text"])
+    )
+
+    reading_order: list[str] = Field(default_factory=list)
+
+    text_regions: list[TextRegion] = Field(default_factory=list)
+    non_text_regions: list[NonTextRegion] = Field(default_factory=list)
+
+    warnings: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] | None = None
+
+    @property
+    def text(self) -> str:
+        """Concatenated text of all text regions."""
+        return "\n\n".join(r.text for r in self.text_regions)
+
+
+# -- Audit -------------------------------------------------------------------
+
+
+class Audit(BaseModel):
+    """Audit trail for the document processing pipeline."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: str | None = None
+    runtime_type: str | None = None
+    adapter_version: str | None = None
+    enrichers_applied: list[str] = Field(default_factory=list)
+    validators_run: list[str] = Field(default_factory=list)
+    processing_duration_ms: float | None = None
+    warnings: list[str] = Field(default_factory=list)
+
+
+# -- CanonicalDocument -------------------------------------------------------
+
+
+class CanonicalDocument(BaseModel):
+    """The canonical document — business truth of the system.
+
+    This is the single representation that all validators, enrichers,
+    and serializers operate on.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    schema_version: str = Field(default="1.0.0", pattern=r"^\d+\.\d+\.\d+$")
+    document_id: str = Field(min_length=1)
+    source: Source
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    pages: list[Page] = Field(min_length=1)
+
+    audit: Audit = Field(default_factory=Audit)
+    global_readiness: DocumentReadiness = Field(default_factory=DocumentReadiness)
+    export_eligibility: ExportEligibility = Field(default_factory=ExportEligibility)
+
+    metadata: dict[str, Any] | None = None
+
+    @property
+    def text(self) -> str:
+        """Concatenated text of all pages."""
+        return "\n\n---\n\n".join(p.text for p in self.pages)
+
+    @property
+    def all_text_region_ids(self) -> set[str]:
+        """All text region IDs across all pages."""
+        return {r.id for p in self.pages for r in p.text_regions}
+
+    @property
+    def all_ids(self) -> set[str]:
+        """Every node ID in the document (pages, regions, lines, words)."""
+        ids: set[str] = set()
+        for page in self.pages:
+            ids.add(page.id)
+            for region in page.text_regions:
+                ids.add(region.id)
+                for line in region.lines:
+                    ids.add(line.id)
+                    for word in line.words:
+                        ids.add(word.id)
+            for ntr in page.non_text_regions:
+                ids.add(ntr.id)
+        return ids

src/app/domain/models/geometry.py

@@ -0,0 +1,128 @@
+"""Geometry primitives and context for the canonical model.
+
+Convention (non-negotiable, see AGENTS.md):
+  - bbox: [x, y, width, height]  — x = left edge, y = top edge
+  - coordinate origin: top_left
+  - unit: px
+  - polygon: list of (x, y) pairs, or None
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from src.app.domain.models.status import CoordinateOrigin, GeometryStatus, Unit
+
+
+# -- Primitives --------------------------------------------------------------
+
+
+class Point(BaseModel):
+    """A 2D point in image space."""
+
+    model_config = ConfigDict(frozen=True)
+
+    x: float = Field(ge=0)
+    y: float = Field(ge=0)
+
+
+class BBox(BaseModel):
+    """Axis-aligned bounding box: [x, y, width, height].
+
+    x, y = top-left corner.  width, height > 0.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    x: float = Field(ge=0)
+    y: float = Field(ge=0)
+    width: float = Field(gt=0)
+    height: float = Field(gt=0)
+
+    @property
+    def x2(self) -> float:
+        return self.x + self.width
+
+    @property
+    def y2(self) -> float:
+        return self.y + self.height
+
+    def as_tuple(self) -> tuple[float, float, float, float]:
+        return (self.x, self.y, self.width, self.height)
+
+
+PolygonPoints = list[tuple[float, float]]
+"""Ordered list of (x, y) vertex pairs forming a closed polygon."""
+
+
+class Baseline(BaseModel):
+    """A baseline defined by two endpoints."""
+
+    model_config = ConfigDict(frozen=True)
+
+    start: Point
+    end: Point
+
+
+class ClipRect(BaseModel):
+    """Clipping rectangle — same semantics as BBox but used for clipping ops."""
+
+    model_config = ConfigDict(frozen=True)
+
+    x: float = Field(ge=0)
+    y: float = Field(ge=0)
+    width: float = Field(gt=0)
+    height: float = Field(gt=0)
+
+
+# -- Geometry (the canonical geometry object on every node) ------------------
+
+
+class Geometry(BaseModel):
+    """Standardised geometry attached to every canonical node.
+
+    bbox is always required (at least for ALTO export).
+    polygon is optional — preserved when the provider supplies it.
+    status indicates how the geometry was obtained.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    bbox: Annotated[
+        tuple[float, float, float, float],
+        Field(description="(x, y, width, height)"),
+    ]
+    polygon: PolygonPoints | None = None
+    status: GeometryStatus
+
+    @model_validator(mode="after")
+    def _validate_bbox_dimensions(self) -> Geometry:
+        _x, _y, w, h = self.bbox
+        if w <= 0 or h <= 0:
+            raise ValueError(f"bbox width and height must be > 0, got w={w}, h={h}")
+        if _x < 0 or _y < 0:
+            raise ValueError(f"bbox x and y must be >= 0, got x={_x}, y={_y}")
+        return self
+
+
+# -- GeometryContext (describes the coordinate space of a provider output) ---
+
+
+class GeometryContext(BaseModel):
+    """Describes the geometric context of a provider's output.
+
+    Used by adapters to normalise provider coordinates into canonical space.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    source_width: int = Field(gt=0)
+    source_height: int = Field(gt=0)
+    provided_width: int | None = Field(default=None, gt=0)
+    provided_height: int | None = Field(default=None, gt=0)
+    resize_factor: float | None = Field(default=None, gt=0)
+    rotation: float = 0.0
+    coordinate_origin: CoordinateOrigin = CoordinateOrigin.TOP_LEFT
+    unit: Unit = Unit.PX

src/app/domain/models/provenance.py

@@ -0,0 +1,33 @@
+"""Provenance model — tracks how every piece of data was produced.
+
+Every node in the CanonicalDocument must carry a Provenance.  This is
+the foundation of the system's explainability and auditability.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from src.app.domain.models.status import EvidenceType
+
+
+class Provenance(BaseModel):
+    """Tracks the origin and derivation chain of a canonical node."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider: str = Field(min_length=1)
+    adapter: str = Field(min_length=1)
+    source_ref: str = Field(min_length=1)
+    evidence_type: EvidenceType
+    derived_from: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_derivation_consistency(self) -> Provenance:
+        """provider_native data cannot have derivation parents."""
+        if self.evidence_type == EvidenceType.PROVIDER_NATIVE and self.derived_from:
+            raise ValueError(
+                "provider_native evidence must have an empty derived_from list, "
+                f"got {self.derived_from}"
+            )
+        return self

src/app/domain/models/raw_payload.py

@@ -0,0 +1,34 @@
+"""RawProviderPayload — the source truth.
+
+This is an opaque wrapper around whatever the provider returned.
+It is stored for audit, debug, comparison, and reproducibility.
+It is never used for export or rendering.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RawProviderPayload(BaseModel):
+    """Opaque container for the raw output of a provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_id: str = Field(min_length=1)
+    adapter_id: str = Field(min_length=1)
+    runtime_type: str = Field(min_length=1)
+    model_id: str | None = None
+
+    payload: dict[str, Any] | list[Any]
+    """The raw JSON-serialisable output from the provider."""
+
+    received_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    image_width: int | None = Field(default=None, gt=0)
+    image_height: int | None = Field(default=None, gt=0)
+
+    metadata: dict[str, Any] | None = None

src/app/domain/models/readiness.py

@@ -0,0 +1,68 @@
+"""Readiness and export eligibility models.
+
+These models answer: "can we export this document, and how completely?"
+They are computed by validators, never set manually.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from src.app.domain.models.status import MissingCapability, ReadinessLevel
+
+
+class AltoReadiness(BaseModel):
+    """ALTO export readiness for a single page."""
+
+    model_config = ConfigDict(frozen=True)
+
+    level: ReadinessLevel
+    missing: list[MissingCapability] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_consistency(self) -> AltoReadiness:
+        if self.level == ReadinessLevel.FULL and self.missing:
+            raise ValueError(
+                f"level is 'full' but missing capabilities listed: {self.missing}"
+            )
+        if self.level == ReadinessLevel.NONE and not self.missing:
+            raise ValueError("level is 'none' but no missing capabilities listed")
+        return self
+
+
+class PageXmlReadiness(BaseModel):
+    """PAGE XML export readiness for a single page."""
+
+    model_config = ConfigDict(frozen=True)
+
+    level: ReadinessLevel
+    missing: list[MissingCapability] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _validate_consistency(self) -> PageXmlReadiness:
+        if self.level == ReadinessLevel.FULL and self.missing:
+            raise ValueError(
+                f"level is 'full' but missing capabilities listed: {self.missing}"
+            )
+        if self.level == ReadinessLevel.NONE and not self.missing:
+            raise ValueError("level is 'none' but no missing capabilities listed")
+        return self
+
+
+class ExportEligibility(BaseModel):
+    """Aggregated export eligibility for the whole document."""
+
+    model_config = ConfigDict(frozen=True)
+
+    alto_export: ReadinessLevel = ReadinessLevel.NONE
+    page_export: ReadinessLevel = ReadinessLevel.NONE
+    viewer_render: ReadinessLevel = ReadinessLevel.NONE
+
+
+class DocumentReadiness(BaseModel):
+    """Global readiness summary for the document."""
+
+    model_config = ConfigDict(frozen=True)
+
+    level: ReadinessLevel = ReadinessLevel.NONE
+    page_readiness: list[ReadinessLevel] = Field(default_factory=list)

src/app/domain/models/status.py

@@ -0,0 +1,126 @@
+"""Domain enums — single source of truth for all status and classification values.
+
+These enums are used across the canonical document, provenance, readiness,
+and viewer projection models. They carry no logic — only values.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+# -- Geometry ----------------------------------------------------------------
+
+
+class GeometryStatus(str, Enum):
+    """How a piece of geometry was obtained."""
+
+    EXACT = "exact"
+    INFERRED = "inferred"
+    REPAIRED = "repaired"
+    UNKNOWN = "unknown"
+
+
+class CoordinateOrigin(str, Enum):
+    """Origin of the coordinate system.  Always top_left in canonical model."""
+
+    TOP_LEFT = "top_left"
+
+
+class Unit(str, Enum):
+    """Measurement unit.  Always px in canonical model."""
+
+    PX = "px"
+
+
+# -- Provenance --------------------------------------------------------------
+
+
+class EvidenceType(str, Enum):
+    """How a piece of data was produced."""
+
+    PROVIDER_NATIVE = "provider_native"
+    DERIVED = "derived"
+    REPAIRED = "repaired"
+    MANUAL = "manual"
+
+
+# -- Document structure ------------------------------------------------------
+
+
+class BlockRole(str, Enum):
+    """Semantic role of a text block within the page."""
+
+    BODY = "body"
+    HEADING = "heading"
+    FOOTNOTE = "footnote"
+    CAPTION = "caption"
+    MARGIN = "margin"
+    PAGE_NUMBER = "page_number"
+    HEADER = "header"
+    FOOTER = "footer"
+    OTHER = "other"
+
+
+class NonTextKind(str, Enum):
+    """Type of non-textual region."""
+
+    ILLUSTRATION = "illustration"
+    TABLE = "table"
+    SEPARATOR = "separator"
+    ORNAMENT = "ornament"
+    GRAPHIC = "graphic"
+    OTHER = "other"
+
+
+# -- Source ------------------------------------------------------------------
+
+
+class InputType(str, Enum):
+    """Type of the original input document."""
+
+    IMAGE = "image"
+    PDF = "pdf"
+    OCR_JSON = "ocr_json"
+    MARKDOWN = "markdown"
+    HTML = "html"
+    XML = "xml"
+    TEXT = "text"
+    OTHER = "other"
+
+
+# -- Readiness ---------------------------------------------------------------
+
+
+class ReadinessLevel(str, Enum):
+    """How ready a document / page / element is for export."""
+
+    FULL = "full"
+    PARTIAL = "partial"
+    DEGRADED = "degraded"
+    NONE = "none"
+
+
+class MissingCapability(str, Enum):
+    """Specific capabilities that may be missing for export readiness."""
+
+    PAGE_DIMENSIONS = "page_dimensions"
+    BLOCK_GEOMETRY = "block_geometry"
+    LINE_GEOMETRY = "line_geometry"
+    WORD_GEOMETRY = "word_geometry"
+    WORD_TEXT = "word_text"
+    READING_ORDER = "reading_order"
+    LANGUAGE = "language"
+    CONFIDENCE = "confidence"
+
+
+# -- Overlay (viewer) --------------------------------------------------------
+
+
+class OverlayLevel(str, Enum):
+    """Granularity level for viewer overlays."""
+
+    BLOCK = "block"
+    LINE = "line"
+    WORD = "word"
+    NON_TEXT = "non_text"

src/app/domain/models/viewer_projection.py

@@ -0,0 +1,79 @@
+"""ViewerProjection — the rendering truth.
+
+This is the lightweight structure consumed by the front-end viewer.
+It is derived from the CanonicalDocument by the projection builder.
+It never parses XML.  It never calls providers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.app.domain.models.readiness import ExportEligibility
+from src.app.domain.models.status import (
+    EvidenceType,
+    GeometryStatus,
+    OverlayLevel,
+    ReadinessLevel,
+)
+
+
+class OverlayItem(BaseModel):
+    """A single visual overlay on the page image."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    level: OverlayLevel
+    bbox: tuple[float, float, float, float] = Field(
+        description="(x, y, width, height)"
+    )
+    polygon: list[tuple[float, float]] | None = None
+    label: str | None = None
+    text: str | None = None
+    confidence: float | None = Field(default=None, ge=0, le=1)
+    provenance_type: EvidenceType | None = None
+    geometry_status: GeometryStatus | None = None
+    click_payload: dict[str, Any] | None = None
+
+
+class InspectionData(BaseModel):
+    """Detailed data for the inspection panel — shown on click."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(min_length=1)
+    level: OverlayLevel
+    text: str | None = None
+    bbox: tuple[float, float, float, float]
+    polygon: list[tuple[float, float]] | None = None
+    confidence: float | None = None
+    lang: str | None = None
+    provenance_type: EvidenceType | None = None
+    provenance_provider: str | None = None
+    geometry_status: GeometryStatus | None = None
+    readiness: ReadinessLevel | None = None
+    role: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class ViewerProjection(BaseModel):
+    """Complete projection for the viewer — one per page."""
+
+    model_config = ConfigDict(frozen=True)
+
+    image_ref: str
+    image_width: int = Field(gt=0)
+    image_height: int = Field(gt=0)
+
+    block_overlays: list[OverlayItem] = Field(default_factory=list)
+    line_overlays: list[OverlayItem] = Field(default_factory=list)
+    word_overlays: list[OverlayItem] = Field(default_factory=list)
+    non_text_overlays: list[OverlayItem] = Field(default_factory=list)
+
+    inspection_index: dict[str, InspectionData] = Field(default_factory=dict)
+
+    validation_flags: list[str] = Field(default_factory=list)
+    export_status: ExportEligibility = Field(default_factory=ExportEligibility)

tests/unit/test_canonical_document.py

@@ -0,0 +1,627 @@
+"""Tests for the CanonicalDocument model — the heart of the system."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from pydantic import ValidationError
+
+from src.app.domain.models import (
+    AltoReadiness,
+    Audit,
+    BlockRole,
+    CanonicalDocument,
+    EvidenceType,
+    ExportEligibility,
+    Geometry,
+    GeometryStatus,
+    Hyphenation,
+    InputType,
+    MissingCapability,
+    NonTextKind,
+    NonTextRegion,
+    Page,
+    PageXmlReadiness,
+    Provenance,
+    ReadinessLevel,
+    Source,
+    TextLine,
+    TextRegion,
+    Word,
+)
+
+
+# -- Helpers (reusable fixture builders) -------------------------------------
+
+
+def _prov(ref: str = "$.test", evidence: EvidenceType = EvidenceType.PROVIDER_NATIVE) -> Provenance:
+    return Provenance(
+        provider="test-provider",
+        adapter="adapter.test.v1",
+        source_ref=ref,
+        evidence_type=evidence,
+    )
+
+
+def _geo(
+    x: float = 100,
+    y: float = 200,
+    w: float = 300,
+    h: float = 50,
+    status: GeometryStatus = GeometryStatus.EXACT,
+) -> Geometry:
+    return Geometry(bbox=(x, y, w, h), status=status)
+
+
+def _word(
+    id: str = "w1",
+    text: str = "Bonjour",
+    x: float = 100,
+    y: float = 200,
+    w: float = 90,
+    h: float = 40,
+) -> Word:
+    return Word(
+        id=id,
+        text=text,
+        geometry=_geo(x, y, w, h),
+        lang="fra",
+        confidence=0.96,
+        provenance=_prov(f"$.words.{id}"),
+    )
+
+
+def _line(id: str = "tl1", words: list[Word] | None = None) -> TextLine:
+    return TextLine(
+        id=id,
+        geometry=_geo(100, 200, 1100, 42),
+        lang="fra",
+        provenance=_prov(f"$.lines.{id}"),
+        words=words or [_word()],
+    )
+
+
+def _region(id: str = "tb1", lines: list[TextLine] | None = None) -> TextRegion:
+    return TextRegion(
+        id=id,
+        role=BlockRole.BODY,
+        geometry=_geo(100, 200, 1200, 900),
+        lang="fra",
+        provenance=_prov(f"$.blocks.{id}"),
+        lines=lines or [_line()],
+    )
+
+
+def _page(
+    id: str = "p1",
+    text_regions: list[TextRegion] | None = None,
+) -> Page:
+    return Page(
+        id=id,
+        page_index=0,
+        width=2480,
+        height=3508,
+        alto_readiness=AltoReadiness(level=ReadinessLevel.FULL),
+        page_readiness=PageXmlReadiness(level=ReadinessLevel.FULL),
+        reading_order=["tb1"],
+        text_regions=text_regions or [_region()],
+    )
+
+
+def _doc(pages: list[Page] | None = None) -> CanonicalDocument:
+    return CanonicalDocument(
+        document_id="doc_test_001",
+        source=Source(input_type=InputType.IMAGE, filename="test.png"),
+        pages=pages or [_page()],
+    )
+
+
+# -- Source ------------------------------------------------------------------
+
+
+class TestSource:
+    def test_minimal(self) -> None:
+        s = Source(input_type=InputType.IMAGE)
+        assert s.filename is None
+        assert s.checksum is None
+
+    def test_full(self) -> None:
+        s = Source(
+            input_type=InputType.IMAGE,
+            filename="page.tif",
+            mime_type="image/tiff",
+            checksum="abc123",
+        )
+        assert s.filename == "page.tif"
+
+
+# -- Hyphenation -------------------------------------------------------------
+
+
+class TestHyphenation:
+    def test_not_hyphenated(self) -> None:
+        h = Hyphenation(is_hyphenated=False)
+        assert h.part is None
+        assert h.full_form is None
+
+    def test_part_1(self) -> None:
+        h = Hyphenation(is_hyphenated=True, part=1, full_form="patrimoine")
+        assert h.part == 1
+
+    def test_part_2(self) -> None:
+        h = Hyphenation(is_hyphenated=True, part=2, full_form="patrimoine")
+        assert h.part == 2
+
+    def test_false_with_part_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="is_hyphenated is False"):
+            Hyphenation(is_hyphenated=False, part=1, full_form="test")
+
+    def test_true_without_part_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="part must be 1 or 2"):
+            Hyphenation(is_hyphenated=True, part=None, full_form="test")
+
+    def test_true_without_full_form_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="full_form is required"):
+            Hyphenation(is_hyphenated=True, part=1, full_form=None)
+
+    def test_invalid_part_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="part must be 1 or 2"):
+            Hyphenation(is_hyphenated=True, part=3, full_form="test")
+
+
+# -- Word --------------------------------------------------------------------
+
+
+class TestWord:
+    def test_valid(self) -> None:
+        w = _word()
+        assert w.text == "Bonjour"
+        assert w.confidence == 0.96
+
+    def test_empty_text_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Word(
+                id="w1",
+                text="",
+                geometry=_geo(),
+                provenance=_prov(),
+            )
+
+    def test_empty_id_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Word(
+                id="",
+                text="hello",
+                geometry=_geo(),
+                provenance=_prov(),
+            )
+
+    def test_confidence_out_of_range_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Word(
+                id="w1",
+                text="hello",
+                geometry=_geo(),
+                confidence=1.5,
+                provenance=_prov(),
+            )
+
+    def test_invalid_lang_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Word(
+                id="w1",
+                text="hello",
+                geometry=_geo(),
+                lang="french",  # must be 3-letter ISO
+                provenance=_prov(),
+            )
+
+    def test_valid_lang(self) -> None:
+        w = Word(
+            id="w1",
+            text="hello",
+            geometry=_geo(),
+            lang="eng",
+            provenance=_prov(),
+        )
+        assert w.lang == "eng"
+
+    def test_null_confidence_ok(self) -> None:
+        w = Word(
+            id="w1",
+            text="hello",
+            geometry=_geo(),
+            confidence=None,
+            provenance=_prov(),
+        )
+        assert w.confidence is None
+
+    def test_with_hyphenation(self) -> None:
+        w = Word(
+            id="w1",
+            text="patri-",
+            geometry=_geo(),
+            provenance=_prov(),
+            hyphenation=Hyphenation(is_hyphenated=True, part=1, full_form="patrimoine"),
+        )
+        assert w.hyphenation is not None
+        assert w.hyphenation.full_form == "patrimoine"
+
+    def test_with_metadata(self) -> None:
+        w = Word(
+            id="w1",
+            text="hello",
+            geometry=_geo(),
+            provenance=_prov(),
+            metadata={"custom_field": "value"},
+        )
+        assert w.metadata == {"custom_field": "value"}
+
+
+# -- TextLine ----------------------------------------------------------------
+
+
+class TestTextLine:
+    def test_valid(self) -> None:
+        line = _line()
+        assert line.text == "Bonjour"
+
+    def test_empty_words_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            TextLine(
+                id="tl1",
+                geometry=_geo(),
+                provenance=_prov(),
+                words=[],
+            )
+
+    def test_multiple_words(self) -> None:
+        line = _line(words=[_word("w1", "Hello"), _word("w2", "world")])
+        assert line.text == "Hello world"
+
+
+# -- TextRegion --------------------------------------------------------------
+
+
+class TestTextRegion:
+    def test_valid(self) -> None:
+        r = _region()
+        assert r.role == BlockRole.BODY
+        assert "Bonjour" in r.text
+
+    def test_empty_lines_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            TextRegion(
+                id="tb1",
+                geometry=_geo(),
+                provenance=_prov(),
+                lines=[],
+            )
+
+    def test_multiple_lines(self) -> None:
+        r = _region(
+            lines=[
+                _line("tl1", [_word("w1", "First")]),
+                _line("tl2", [_word("w2", "Second")]),
+            ]
+        )
+        assert r.text == "First\nSecond"
+
+    def test_null_role(self) -> None:
+        r = TextRegion(
+            id="tb1",
+            role=None,
+            geometry=_geo(),
+            provenance=_prov(),
+            lines=[_line()],
+        )
+        assert r.role is None
+
+
+# -- NonTextRegion -----------------------------------------------------------
+
+
+class TestNonTextRegion:
+    def test_valid(self) -> None:
+        ntr = NonTextRegion(
+            id="ntr1",
+            kind=NonTextKind.ILLUSTRATION,
+            geometry=_geo(),
+            provenance=_prov(),
+        )
+        assert ntr.kind == NonTextKind.ILLUSTRATION
+
+    def test_all_kinds(self) -> None:
+        for kind in NonTextKind:
+            ntr = NonTextRegion(
+                id=f"ntr_{kind.value}",
+                kind=kind,
+                geometry=_geo(),
+                provenance=_prov(),
+            )
+            assert ntr.kind == kind
+
+
+# -- Page --------------------------------------------------------------------
+
+
+class TestPage:
+    def test_valid(self) -> None:
+        p = _page()
+        assert p.width == 2480
+        assert p.height == 3508
+        assert "Bonjour" in p.text
+
+    def test_zero_width_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Page(
+                id="p1",
+                page_index=0,
+                width=0,
+                height=100,
+            )
+
+    def test_negative_index_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Page(
+                id="p1",
+                page_index=-1,
+                width=100,
+                height=100,
+            )
+
+    def test_empty_page_ok(self) -> None:
+        """A page with no regions is valid (e.g. blank page)."""
+        p = Page(
+            id="p1",
+            page_index=0,
+            width=2480,
+            height=3508,
+        )
+        assert p.text_regions == []
+        assert p.text == ""
+
+    def test_with_non_text_region(self) -> None:
+        ntr = NonTextRegion(
+            id="ntr1",
+            kind=NonTextKind.SEPARATOR,
+            geometry=_geo(),
+            provenance=_prov(),
+        )
+        p = Page(
+            id="p1",
+            page_index=0,
+            width=2480,
+            height=3508,
+            non_text_regions=[ntr],
+        )
+        assert len(p.non_text_regions) == 1
+
+
+# -- CanonicalDocument -------------------------------------------------------
+
+
+class TestCanonicalDocument:
+    def test_valid_minimal(self) -> None:
+        doc = _doc()
+        assert doc.document_id == "doc_test_001"
+        assert doc.schema_version == "1.0.0"
+        assert len(doc.pages) == 1
+
+    def test_empty_pages_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            CanonicalDocument(
+                document_id="doc1",
+                source=Source(input_type=InputType.IMAGE),
+                pages=[],
+            )
+
+    def test_text_property(self) -> None:
+        doc = _doc()
+        assert "Bonjour" in doc.text
+
+    def test_all_ids(self) -> None:
+        doc = _doc()
+        ids = doc.all_ids
+        assert "p1" in ids
+        assert "tb1" in ids
+        assert "tl1" in ids
+        assert "w1" in ids
+
+    def test_all_text_region_ids(self) -> None:
+        doc = _doc()
+        assert doc.all_text_region_ids == {"tb1"}
+
+    def test_invalid_schema_version_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            CanonicalDocument(
+                schema_version="v1",
+                document_id="doc1",
+                source=Source(input_type=InputType.IMAGE),
+                pages=[_page()],
+            )
+
+    def test_empty_document_id_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            CanonicalDocument(
+                document_id="",
+                source=Source(input_type=InputType.IMAGE),
+                pages=[_page()],
+            )
+
+    def test_default_audit(self) -> None:
+        doc = _doc()
+        assert doc.audit.enrichers_applied == []
+        assert doc.audit.validators_run == []
+
+    def test_with_audit(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc1",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[_page()],
+            audit=Audit(
+                provider_id="paddle",
+                runtime_type="local",
+                enrichers_applied=["polygon_to_bbox", "lang_propagation"],
+            ),
+        )
+        assert len(doc.audit.enrichers_applied) == 2
+
+    def test_default_export_eligibility(self) -> None:
+        doc = _doc()
+        assert doc.export_eligibility.alto_export == ReadinessLevel.NONE
+
+    def test_with_metadata(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc1",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[_page()],
+            metadata={"project": "test", "version": 2},
+        )
+        assert doc.metadata["project"] == "test"
+
+    def test_json_roundtrip(self) -> None:
+        """Full serialization → deserialization cycle."""
+        doc = _doc()
+        json_str = doc.model_dump_json()
+        parsed = json.loads(json_str)
+        doc2 = CanonicalDocument.model_validate(parsed)
+        assert doc2.document_id == doc.document_id
+        assert len(doc2.pages) == len(doc.pages)
+        assert doc2.pages[0].text_regions[0].lines[0].words[0].text == "Bonjour"
+
+    def test_json_schema_generation(self) -> None:
+        """Verify we can generate a JSON Schema from the Pydantic model."""
+        schema = CanonicalDocument.model_json_schema()
+        assert schema["title"] == "CanonicalDocument"
+        assert "pages" in schema["properties"]
+        # Verify nested definitions exist
+        assert "$defs" in schema
+        defs = schema["$defs"]
+        assert "Word" in defs
+        assert "TextLine" in defs
+        assert "TextRegion" in defs
+        assert "Page" in defs
+        assert "Geometry" in defs
+        assert "Provenance" in defs
+
+
+# -- Full example from spec --------------------------------------------------
+
+
+class TestSpecExample:
+    """Validate the example from the architecture document §14."""
+
+    def test_spec_example_validates(self) -> None:
+        doc = CanonicalDocument(
+            schema_version="1.0.0",
+            document_id="doc_0001",
+            source=Source(
+                input_type=InputType.IMAGE,
+                filename="page_001.tif",
+                mime_type="image/tiff",
+                checksum=None,
+            ),
+            pages=[
+                Page(
+                    id="p1",
+                    page_index=0,
+                    width=2480,
+                    height=3508,
+                    alto_readiness=AltoReadiness(level=ReadinessLevel.FULL),
+                    page_readiness=PageXmlReadiness(level=ReadinessLevel.FULL),
+                    reading_order=["tb1"],
+                    text_regions=[
+                        TextRegion(
+                            id="tb1",
+                            role=BlockRole.BODY,
+                            geometry=Geometry(
+                                bbox=(100, 200, 1200, 900),
+                                polygon=None,
+                                status=GeometryStatus.EXACT,
+                            ),
+                            confidence=None,
+                            lang="fra",
+                            provenance=Provenance(
+                                provider="paddleocr-vl",
+                                adapter="adapter.paddle.v1",
+                                source_ref="$.pages[0].blocks[0]",
+                                evidence_type=EvidenceType.PROVIDER_NATIVE,
+                                derived_from=[],
+                            ),
+                            lines=[
+                                TextLine(
+                                    id="tl1",
+                                    geometry=Geometry(
+                                        bbox=(110, 220, 1180, 42),
+                                        polygon=None,
+                                        status=GeometryStatus.EXACT,
+                                    ),
+                                    confidence=None,
+                                    lang="fra",
+                                    provenance=Provenance(
+                                        provider="paddleocr-vl",
+                                        adapter="adapter.paddle.v1",
+                                        source_ref="$.pages[0].blocks[0].lines[0]",
+                                        evidence_type=EvidenceType.PROVIDER_NATIVE,
+                                        derived_from=[],
+                                    ),
+                                    words=[
+                                        Word(
+                                            id="w1",
+                                            text="Bonjour",
+                                            normalized_text=None,
+                                            geometry=Geometry(
+                                                bbox=(110, 220, 90, 40),
+                                                polygon=None,
+                                                status=GeometryStatus.EXACT,
+                                            ),
+                                            lang="fra",
+                                            confidence=0.96,
+                                            style_refs=[],
+                                            hyphenation=None,
+                                            provenance=Provenance(
+                                                provider="paddleocr-vl",
+                                                adapter="adapter.paddle.v1",
+                                                source_ref="$.pages[0].blocks[0].lines[0].words[0]",
+                                                evidence_type=EvidenceType.PROVIDER_NATIVE,
+                                                derived_from=[],
+                                            ),
+                                        ),
+                                    ],
+                                ),
+                            ],
+                        ),
+                    ],
+                    non_text_regions=[],
+                ),
+            ],
+        )
+        assert doc.document_id == "doc_0001"
+        assert doc.pages[0].text_regions[0].lines[0].words[0].text == "Bonjour"
+        assert doc.pages[0].text_regions[0].lines[0].words[0].confidence == 0.96
+
+    def test_hyphenation_example(self) -> None:
+        """Validate the hyphenation example from §8."""
+        w1 = Word(
+            id="w18",
+            text="patri-",
+            geometry=_geo(500, 800, 95, 30),
+            confidence=0.89,
+            lang="fra",
+            provenance=_prov("$.blocks[2].lines[5].words[7]"),
+            hyphenation=Hyphenation(is_hyphenated=True, part=1, full_form="patrimoine"),
+        )
+        w2 = Word(
+            id="w19",
+            text="moine",
+            geometry=_geo(120, 840, 70, 30),
+            confidence=0.90,
+            lang="fra",
+            provenance=_prov("$.blocks[2].lines[6].words[0]"),
+            hyphenation=Hyphenation(is_hyphenated=True, part=2, full_form="patrimoine"),
+        )
+        assert w1.hyphenation.full_form == w2.hyphenation.full_form == "patrimoine"
+        assert w1.hyphenation.part == 1
+        assert w2.hyphenation.part == 2

tests/unit/test_geometry.py

@@ -0,0 +1,143 @@
+"""Tests for geometry primitives and Geometry model."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from src.app.domain.models import (
+    BBox,
+    Baseline,
+    ClipRect,
+    Geometry,
+    GeometryContext,
+    GeometryStatus,
+    Point,
+)
+
+
+class TestPoint:
+    def test_valid(self) -> None:
+        p = Point(x=10.0, y=20.0)
+        assert p.x == 10.0
+        assert p.y == 20.0
+
+    def test_origin(self) -> None:
+        p = Point(x=0, y=0)
+        assert p.x == 0.0
+
+    def test_negative_x_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Point(x=-1, y=0)
+
+    def test_negative_y_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Point(x=0, y=-1)
+
+    def test_frozen(self) -> None:
+        p = Point(x=1, y=2)
+        with pytest.raises(ValidationError):
+            p.x = 5  # type: ignore[misc]
+
+
+class TestBBox:
+    def test_valid(self) -> None:
+        b = BBox(x=10, y=20, width=100, height=50)
+        assert b.x2 == 110.0
+        assert b.y2 == 70.0
+
+    def test_as_tuple(self) -> None:
+        b = BBox(x=10, y=20, width=100, height=50)
+        assert b.as_tuple() == (10.0, 20.0, 100.0, 50.0)
+
+    def test_zero_width_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            BBox(x=0, y=0, width=0, height=10)
+
+    def test_zero_height_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            BBox(x=0, y=0, width=10, height=0)
+
+    def test_negative_x_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            BBox(x=-1, y=0, width=10, height=10)
+
+
+class TestBaseline:
+    def test_valid(self) -> None:
+        bl = Baseline(start=Point(x=0, y=100), end=Point(x=200, y=100))
+        assert bl.start.x == 0
+        assert bl.end.x == 200
+
+
+class TestClipRect:
+    def test_valid(self) -> None:
+        cr = ClipRect(x=0, y=0, width=100, height=100)
+        assert cr.width == 100
+
+    def test_zero_dimension_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            ClipRect(x=0, y=0, width=0, height=100)
+
+
+class TestGeometry:
+    def test_valid_exact(self) -> None:
+        g = Geometry(bbox=(100, 200, 300, 50), status=GeometryStatus.EXACT)
+        assert g.bbox == (100, 200, 300, 50)
+        assert g.polygon is None
+
+    def test_valid_with_polygon(self) -> None:
+        g = Geometry(
+            bbox=(100, 200, 300, 50),
+            polygon=[(100, 200), (400, 200), (400, 250), (100, 250)],
+            status=GeometryStatus.EXACT,
+        )
+        assert len(g.polygon) == 4
+
+    def test_zero_width_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="width and height must be > 0"):
+            Geometry(bbox=(100, 200, 0, 50), status=GeometryStatus.EXACT)
+
+    def test_zero_height_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="width and height must be > 0"):
+            Geometry(bbox=(100, 200, 300, 0), status=GeometryStatus.EXACT)
+
+    def test_negative_x_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="x and y must be >= 0"):
+            Geometry(bbox=(-1, 200, 300, 50), status=GeometryStatus.EXACT)
+
+    def test_negative_y_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="x and y must be >= 0"):
+            Geometry(bbox=(100, -1, 300, 50), status=GeometryStatus.EXACT)
+
+    def test_all_statuses_accepted(self) -> None:
+        for status in GeometryStatus:
+            g = Geometry(bbox=(10, 10, 10, 10), status=status)
+            assert g.status == status
+
+    def test_frozen(self) -> None:
+        g = Geometry(bbox=(10, 20, 30, 40), status=GeometryStatus.EXACT)
+        with pytest.raises(ValidationError):
+            g.status = GeometryStatus.INFERRED  # type: ignore[misc]
+
+
+class TestGeometryContext:
+    def test_valid_minimal(self) -> None:
+        gc = GeometryContext(source_width=2480, source_height=3508)
+        assert gc.source_width == 2480
+        assert gc.resize_factor is None
+
+    def test_valid_full(self) -> None:
+        gc = GeometryContext(
+            source_width=2480,
+            source_height=3508,
+            provided_width=1240,
+            provided_height=1754,
+            resize_factor=0.5,
+            rotation=90.0,
+        )
+        assert gc.resize_factor == 0.5
+
+    def test_zero_source_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            GeometryContext(source_width=0, source_height=100)

tests/unit/test_provenance.py

@@ -0,0 +1,106 @@
+"""Tests for the Provenance model."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from src.app.domain.models import EvidenceType, Provenance
+
+
+class TestProvenance:
+    def test_valid_native(self) -> None:
+        p = Provenance(
+            provider="paddleocr-vl",
+            adapter="adapter.paddle.v1",
+            source_ref="$.pages[0].blocks[0]",
+            evidence_type=EvidenceType.PROVIDER_NATIVE,
+        )
+        assert p.derived_from == []
+
+    def test_valid_derived(self) -> None:
+        p = Provenance(
+            provider="enricher.polygon_to_bbox",
+            adapter="enricher.v1",
+            source_ref="tl1",
+            evidence_type=EvidenceType.DERIVED,
+            derived_from=["tl1"],
+        )
+        assert p.derived_from == ["tl1"]
+
+    def test_native_with_derived_from_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="provider_native.*empty derived_from"):
+            Provenance(
+                provider="paddle",
+                adapter="adapter.v1",
+                source_ref="$.x",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+                derived_from=["some_id"],
+            )
+
+    def test_empty_provider_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Provenance(
+                provider="",
+                adapter="adapter.v1",
+                source_ref="$.x",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+            )
+
+    def test_empty_adapter_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Provenance(
+                provider="paddle",
+                adapter="",
+                source_ref="$.x",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+            )
+
+    def test_empty_source_ref_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            Provenance(
+                provider="paddle",
+                adapter="adapter.v1",
+                source_ref="",
+                evidence_type=EvidenceType.PROVIDER_NATIVE,
+            )
+
+    def test_repaired_evidence_type(self) -> None:
+        p = Provenance(
+            provider="bbox_repair",
+            adapter="enricher.v1",
+            source_ref="w1",
+            evidence_type=EvidenceType.REPAIRED,
+            derived_from=["w1"],
+        )
+        assert p.evidence_type == EvidenceType.REPAIRED
+
+    def test_manual_evidence_type(self) -> None:
+        p = Provenance(
+            provider="manual",
+            adapter="manual.v1",
+            source_ref="user_correction",
+            evidence_type=EvidenceType.MANUAL,
+        )
+        assert p.evidence_type == EvidenceType.MANUAL
+
+    def test_frozen(self) -> None:
+        p = Provenance(
+            provider="paddle",
+            adapter="v1",
+            source_ref="$.x",
+            evidence_type=EvidenceType.PROVIDER_NATIVE,
+        )
+        with pytest.raises(ValidationError):
+            p.provider = "other"  # type: ignore[misc]
+
+    def test_json_roundtrip(self) -> None:
+        p = Provenance(
+            provider="paddleocr-vl",
+            adapter="adapter.paddle.v1",
+            source_ref="$.pages[0]",
+            evidence_type=EvidenceType.PROVIDER_NATIVE,
+        )
+        data = p.model_dump()
+        p2 = Provenance.model_validate(data)
+        assert p == p2

tests/unit/test_raw_payload.py

@@ -0,0 +1,82 @@
+"""Tests for the RawProviderPayload model."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from src.app.domain.models import RawProviderPayload
+
+
+class TestRawProviderPayload:
+    def test_valid_dict_payload(self) -> None:
+        rp = RawProviderPayload(
+            provider_id="paddleocr",
+            adapter_id="adapter.paddle.v1",
+            runtime_type="local",
+            payload={"pages": [{"blocks": []}]},
+        )
+        assert rp.provider_id == "paddleocr"
+
+    def test_valid_list_payload(self) -> None:
+        rp = RawProviderPayload(
+            provider_id="paddleocr",
+            adapter_id="adapter.paddle.v1",
+            runtime_type="local",
+            payload=[[[100, 200], [300, 200], [300, 250], [100, 250]], ["text", 0.95]],
+        )
+        assert isinstance(rp.payload, list)
+
+    def test_empty_provider_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            RawProviderPayload(
+                provider_id="",
+                adapter_id="v1",
+                runtime_type="local",
+                payload={},
+            )
+
+    def test_with_image_dimensions(self) -> None:
+        rp = RawProviderPayload(
+            provider_id="paddle",
+            adapter_id="v1",
+            runtime_type="local",
+            payload={},
+            image_width=2480,
+            image_height=3508,
+        )
+        assert rp.image_width == 2480
+
+    def test_zero_dimension_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            RawProviderPayload(
+                provider_id="paddle",
+                adapter_id="v1",
+                runtime_type="local",
+                payload={},
+                image_width=0,
+                image_height=100,
+            )
+
+    def test_with_metadata(self) -> None:
+        rp = RawProviderPayload(
+            provider_id="paddle",
+            adapter_id="v1",
+            runtime_type="local",
+            payload={"data": "test"},
+            metadata={"processing_time_ms": 1234},
+        )
+        assert rp.metadata["processing_time_ms"] == 1234
+
+    def test_json_roundtrip(self) -> None:
+        rp = RawProviderPayload(
+            provider_id="paddle",
+            adapter_id="v1",
+            runtime_type="local",
+            model_id="PP-OCRv4",
+            payload={"blocks": [{"text": "hello"}]},
+        )
+        data = rp.model_dump(mode="json")
+        rp2 = RawProviderPayload.model_validate(data)
+        assert rp2.provider_id == rp.provider_id
+        assert rp2.model_id == "PP-OCRv4"

tests/unit/test_readiness.py

@@ -0,0 +1,95 @@
+"""Tests for readiness and export eligibility models."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from src.app.domain.models import (
+    AltoReadiness,
+    DocumentReadiness,
+    ExportEligibility,
+    MissingCapability,
+    PageXmlReadiness,
+    ReadinessLevel,
+)
+
+
+class TestAltoReadiness:
+    def test_full_no_missing(self) -> None:
+        r = AltoReadiness(level=ReadinessLevel.FULL)
+        assert r.missing == []
+
+    def test_partial_with_missing(self) -> None:
+        r = AltoReadiness(
+            level=ReadinessLevel.PARTIAL,
+            missing=[MissingCapability.WORD_GEOMETRY, MissingCapability.CONFIDENCE],
+        )
+        assert len(r.missing) == 2
+
+    def test_none_with_missing(self) -> None:
+        r = AltoReadiness(
+            level=ReadinessLevel.NONE,
+            missing=[MissingCapability.PAGE_DIMENSIONS],
+        )
+        assert r.level == ReadinessLevel.NONE
+
+    def test_full_with_missing_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="full.*missing"):
+            AltoReadiness(
+                level=ReadinessLevel.FULL,
+                missing=[MissingCapability.WORD_GEOMETRY],
+            )
+
+    def test_none_without_missing_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="none.*no missing"):
+            AltoReadiness(level=ReadinessLevel.NONE, missing=[])
+
+
+class TestPageXmlReadiness:
+    def test_full_no_missing(self) -> None:
+        r = PageXmlReadiness(level=ReadinessLevel.FULL)
+        assert r.missing == []
+
+    def test_full_with_missing_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="full.*missing"):
+            PageXmlReadiness(
+                level=ReadinessLevel.FULL,
+                missing=[MissingCapability.LINE_GEOMETRY],
+            )
+
+    def test_none_without_missing_rejected(self) -> None:
+        with pytest.raises(ValidationError, match="none.*no missing"):
+            PageXmlReadiness(level=ReadinessLevel.NONE, missing=[])
+
+
+class TestExportEligibility:
+    def test_defaults_to_none(self) -> None:
+        e = ExportEligibility()
+        assert e.alto_export == ReadinessLevel.NONE
+        assert e.page_export == ReadinessLevel.NONE
+        assert e.viewer_render == ReadinessLevel.NONE
+
+    def test_independent_levels(self) -> None:
+        e = ExportEligibility(
+            alto_export=ReadinessLevel.FULL,
+            page_export=ReadinessLevel.PARTIAL,
+            viewer_render=ReadinessLevel.DEGRADED,
+        )
+        assert e.alto_export == ReadinessLevel.FULL
+        assert e.page_export == ReadinessLevel.PARTIAL
+        assert e.viewer_render == ReadinessLevel.DEGRADED
+
+
+class TestDocumentReadiness:
+    def test_defaults(self) -> None:
+        dr = DocumentReadiness()
+        assert dr.level == ReadinessLevel.NONE
+        assert dr.page_readiness == []
+
+    def test_with_pages(self) -> None:
+        dr = DocumentReadiness(
+            level=ReadinessLevel.PARTIAL,
+            page_readiness=[ReadinessLevel.FULL, ReadinessLevel.PARTIAL],
+        )
+        assert len(dr.page_readiness) == 2

tests/unit/test_viewer_projection.py

@@ -0,0 +1,156 @@
+"""Tests for the ViewerProjection model."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from src.app.domain.models import (
+    EvidenceType,
+    ExportEligibility,
+    GeometryStatus,
+    OverlayLevel,
+    ReadinessLevel,
+)
+from src.app.domain.models.viewer_projection import (
+    InspectionData,
+    OverlayItem,
+    ViewerProjection,
+)
+
+
+class TestOverlayItem:
+    def test_valid_word_overlay(self) -> None:
+        o = OverlayItem(
+            id="w1",
+            level=OverlayLevel.WORD,
+            bbox=(110, 220, 90, 40),
+            text="Bonjour",
+            confidence=0.96,
+            provenance_type=EvidenceType.PROVIDER_NATIVE,
+            geometry_status=GeometryStatus.EXACT,
+        )
+        assert o.level == OverlayLevel.WORD
+        assert o.text == "Bonjour"
+
+    def test_valid_block_overlay(self) -> None:
+        o = OverlayItem(
+            id="tb1",
+            level=OverlayLevel.BLOCK,
+            bbox=(100, 200, 1200, 900),
+            label="body",
+        )
+        assert o.level == OverlayLevel.BLOCK
+
+    def test_with_polygon(self) -> None:
+        o = OverlayItem(
+            id="w1",
+            level=OverlayLevel.WORD,
+            bbox=(100, 200, 50, 30),
+            polygon=[(100, 200), (150, 200), (150, 230), (100, 230)],
+        )
+        assert len(o.polygon) == 4
+
+    def test_empty_id_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            OverlayItem(id="", level=OverlayLevel.WORD, bbox=(0, 0, 10, 10))
+
+    def test_confidence_out_of_range(self) -> None:
+        with pytest.raises(ValidationError):
+            OverlayItem(
+                id="w1",
+                level=OverlayLevel.WORD,
+                bbox=(0, 0, 10, 10),
+                confidence=2.0,
+            )
+
+
+class TestInspectionData:
+    def test_valid(self) -> None:
+        insp = InspectionData(
+            id="w1",
+            level=OverlayLevel.WORD,
+            text="Bonjour",
+            bbox=(110, 220, 90, 40),
+            confidence=0.96,
+            lang="fra",
+            provenance_type=EvidenceType.PROVIDER_NATIVE,
+            provenance_provider="paddleocr",
+            geometry_status=GeometryStatus.EXACT,
+            readiness=ReadinessLevel.FULL,
+        )
+        assert insp.lang == "fra"
+
+
+class TestViewerProjection:
+    def test_valid_minimal(self) -> None:
+        vp = ViewerProjection(
+            image_ref="test.png",
+            image_width=2480,
+            image_height=3508,
+        )
+        assert vp.block_overlays == []
+        assert vp.word_overlays == []
+
+    def test_valid_with_overlays(self) -> None:
+        block = OverlayItem(
+            id="tb1",
+            level=OverlayLevel.BLOCK,
+            bbox=(100, 200, 1200, 900),
+            label="body",
+        )
+        word = OverlayItem(
+            id="w1",
+            level=OverlayLevel.WORD,
+            bbox=(110, 220, 90, 40),
+            text="Bonjour",
+        )
+        vp = ViewerProjection(
+            image_ref="test.png",
+            image_width=2480,
+            image_height=3508,
+            block_overlays=[block],
+            word_overlays=[word],
+            inspection_index={
+                "w1": InspectionData(
+                    id="w1",
+                    level=OverlayLevel.WORD,
+                    text="Bonjour",
+                    bbox=(110, 220, 90, 40),
+                )
+            },
+        )
+        assert len(vp.block_overlays) == 1
+        assert len(vp.word_overlays) == 1
+        assert "w1" in vp.inspection_index
+
+    def test_zero_dimensions_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            ViewerProjection(
+                image_ref="test.png",
+                image_width=0,
+                image_height=100,
+            )
+
+    def test_default_export_status(self) -> None:
+        vp = ViewerProjection(
+            image_ref="test.png",
+            image_width=100,
+            image_height=100,
+        )
+        assert vp.export_status.alto_export == ReadinessLevel.NONE
+
+    def test_json_roundtrip(self) -> None:
+        vp = ViewerProjection(
+            image_ref="test.png",
+            image_width=2480,
+            image_height=3508,
+            export_status=ExportEligibility(
+                alto_export=ReadinessLevel.FULL,
+                page_export=ReadinessLevel.PARTIAL,
+                viewer_render=ReadinessLevel.FULL,
+            ),
+        )
+        data = vp.model_dump(mode="json")
+        vp2 = ViewerProjection.model_validate(data)
+        assert vp2.export_status.alto_export == ReadinessLevel.FULL