Core concepts · 29 / 42
Evidence references
Learn how the Northsun repository models tenant-scoped provenance, lineage, source priority, hashes, and temporal metadata.
evidence_refs is a repository substrate table in Northsun for provenance: it records where a source came from, a content hash, source priority, lineage, and temporal metadata. It is not a direct public REST resource, and its presence does not mean every current caller-memory response exposes evidence references.
What the table records
| Column | Purpose |
|---|---|
id | Evidence reference identifier. |
tenant_id | Tenant scope and RLS boundary. |
source_type | Free-text source classification such as user_confirmed or document_extracted. |
source_uri | Pointer back to the source record. |
content_hash | Tenant-scoped SHA-256 idempotency key. |
parent_ref_id | Immediate lineage parent. |
source_priority | Non-negative evidence-level ranking supplied by the producer. |
event_time | When the source event occurred. |
ingestion_time | When the system processed it. |
t_valid, t_invalid | Source scalars for the evidence validity window. |
superseded_by | Link to a later evidence reference. |
A corrective migration adds stored generated ranges:
valid_range = [t_valid, t_invalid or infinity)tx_range = [ingestion_time, infinity)
The scalar columns remain the source of truth. Unlike locked_facts, evidence_refs does not have the same transaction-time overlap exclusion, so the two tables should not be described as having identical temporal semantics.
Namespace-agnostic by design
Evidence records do not carry namespace or fact_key. Addressing belongs to locked_facts, where a fact is identified by tenant, entity, and key. Keeping evidence address-agnostic lets more than one fact cite the same source without turning the source record into a domain-specific fact store.
Evidence is not automatic authority
A content hash proves whether referenced content changed; it does not prove that the content was true. source_type and source_priority provide inputs to later precedence decisions, but the table alone does not resolve every conflict or certify a source.
Similarly, an evidence migration does not prove that an agent received the evidence or acted on it. A customer-visible governed-context claim needs a serving-path receipt showing what was returned and how it was used.
Public API boundary
The frozen caller-memory API does not include /v1/evidence/*. Do not build against evidence endpoints shown in older plans or migration comments. Use the API reference for the callable contract.
Continue with Locked facts for the addressed fact layer and Bi-temporal validity for the two clocks.