# 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.