fix(evidence): close canonical contract gaps

harness/tht/corpus/models.py

@@ -1,13 +1,16 @@
 """Immutable records emitted by the Evidence preprocessing pipeline."""
 
+import hashlib
 import re
+from collections.abc import Mapping
 from datetime import UTC, datetime
+from typing import Self
 
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator
 
 from tht.ports.evidence import (
+    canonical_provenance_uri,
     normalize_aware_datetime,
-    validate_canonical_uri,
     validate_namespaced_value,
     validate_safe_metadata,
 )
@@ -29,11 +32,24 @@ def _validate_hash(value: str) -> str:
     return value
 
 
+def _require_content_hash(content: str, content_hash: str) -> None:
+    expected = f"sha256:{hashlib.sha256(content.encode('utf-8')).hexdigest()}"
+    if content_hash != expected:
+        raise ValueError("content_hash must match the exact canonical UTF-8 content")
+
+
 class _CanonicalValue(BaseModel):
     model_config = ConfigDict(
         frozen=True, extra="forbid", validate_default=True, revalidate_instances="always"
     )
 
+    def model_copy(self, *, update: Mapping[str, object] | None = None, deep: bool = False) -> Self:
+        """Copy through full field and model validation, including manifest invariants."""
+        data = self.model_dump(round_trip=True)
+        if update:
+            data.update(update)
+        return type(self).model_validate(data)
+
 
 class _WithMetadata(_CanonicalValue):
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -41,6 +57,7 @@ class _WithMetadata(_CanonicalValue):
 
 
 class CanonicalDocument(_WithMetadata):
+    """Normalized text whose hash covers the exact stored UTF-8 content bytes."""
     document_id: str
     source_id: str
     source_uri: str
@@ -54,13 +71,19 @@ class CanonicalDocument(_WithMetadata):
 
     _document_id = field_validator("document_id")(_validate_namespaced_id)
     _source_id = field_validator("source_id")(_validate_namespaced_id)
-    _source_uri = field_validator("source_uri")(validate_canonical_uri)
+    _source_uri = field_validator("source_uri")(canonical_provenance_uri)
     _source_fingerprint = field_validator("source_fingerprint")(validate_namespaced_value)
     _content_hash = field_validator("content_hash")(_validate_hash)
     _modified_at = field_validator("modified_at")(normalize_aware_datetime)
 
+    @model_validator(mode="after")
+    def content_hash_matches(self) -> "CanonicalDocument":
+        _require_content_hash(self.content, self.content_hash)
+        return self
+
 
 class CanonicalChunk(_WithMetadata):
+    """Chunk text whose hash covers the exact stored UTF-8 content bytes."""
     chunk_id: str
     document_id: str
     ordinal: int = Field(ge=0)
@@ -72,7 +95,12 @@ class CanonicalChunk(_WithMetadata):
     _chunk_id = field_validator("chunk_id")(_validate_namespaced_id)
     _document_id = field_validator("document_id")(_validate_namespaced_id)
     _content_hash = field_validator("content_hash")(_validate_hash)
-    _source_uri = field_validator("source_uri")(validate_canonical_uri)
+    _source_uri = field_validator("source_uri")(canonical_provenance_uri)
+
+    @model_validator(mode="after")
+    def content_hash_matches(self) -> "CanonicalChunk":
+        _require_content_hash(self.content, self.content_hash)
+        return self
 
 
 class CorpusManifest(_WithMetadata):