ThothII/.superpowers/sdd/evidence-task-1-report.md

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.