feat(evidence): define source and corpus contracts

2026-07-12 03:02:10 +02:00
parent 532073d550
commit d702aad93d
6 changed files with 357 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Evidence / Preprocessing Task 1 Report
+
+## Outcome
+
+Implemented the additive Evidence source port and canonical corpus records. Existing evidence,
+search, vector, and session runtime code is unchanged.
+
+## Contract
+
+- `EvidenceSource` is a runtime-checkable protocol with `discover` and `acquire` operations.
+- `SourceObject` and `AcquiredDocument` are frozen, reject extra fields, use independent metadata
+  defaults, and restrict metadata to Pydantic `JsonValue` values.
+- `CanonicalDocument`, `CanonicalChunk`, and `CorpusManifest` are frozen and reject extra fields.
+- Provenance includes stable source IDs, canonical URIs, fingerprints, modification time, and
+  content hashes.
+- Pipeline versions are recorded on documents, chunks, and manifests. Manifests also carry schema
+  version, optional publish ID/vector generation, and paired embedding model/dimension fields.
+- Credential-like metadata keys are rejected recursively. Credentials are not model fields and
+  therefore cannot enter serialized canonical artifacts through extras.
+
+## TDD evidence
+
+The initial focused run failed during collection because `tht.ports.evidence` and `tht.corpus`
+did not exist. After implementation, the focused suite passed.
+
+## Verification
+
+- Focused models/protocol tests: 13 passed.
+- Harness excluding Docker-backed L0 and the network-dependent wheel packaging test: 444 passed,
+  5 deselected.
+- Focused Ruff: passed.
+- Full-repository Ruff remains blocked by 34 pre-existing findings outside the task files.
+- An unrestricted `pytest -q` attempt reached 453 passed and 5 deselected, but reported 47 Docker
+  setup errors plus 4 Docker parity failures because the sandbox cannot access the Docker socket;
+  the wheel packaging test also failed because its isolated `uv build` needs unavailable network.
+
+## Concerns / follow-up
+
+- Pydantic's `frozen=True` prevents model field reassignment but does not recursively freeze list
+  and dict contents. `default_factory` prevents shared mutable defaults. Later pipeline stages should
+  treat these value objects as immutable and construct replacements rather than mutate collections.
+- The adapter and normalization tasks should preserve the credential-free boundary by passing only
+  these records beyond acquisition.