Propose epistemics truth v1

docs/proposals/ADR-0019-epistemics-truth-v1.md

@@ -0,0 +1,110 @@
+# Proposal ADR-0019 — Epistemics Truth V1
+
+Status: Proposed
+Task: DEV-000103
+
+## Problem and evidence
+
+The audit found that Domovoy has experience and reflection evidence, but no
+small, explicit truth model for observations, claims, source provenance,
+freshness or conflicts. Without that boundary, research, context compilation
+and future learning could silently turn an unverified statement into durable
+fact. The proposal is architecture-only: it does not add tables, runtime
+handlers, connectors or belief mutation.
+
+## Decision proposed
+
+1. Do not create a new canonical owner. Epistemics owns truth evidence and
+   rebuildable truth projections; Interaction, Situation, Work, Capability and
+   Artifact retain ownership of their canonical records.
+2. Define six typed records, with immutable identity and append-only history:
+   `Observation`, `Claim`, `BeliefAssessment`, `Source` and `ProvenanceEdge`,
+   plus a typed `VerificationState` value. Records reference other owners by
+   typed IDs and never copy their canonical payloads.
+3. An `Observation` is a bounded acquired datum with acquisition time,
+   source snapshot reference, excerpt/hash reference, collector identity and
+   privacy/egress classification. It is evidence, not truth.
+4. A `Claim` is a proposition with explicit subject/predicate/object or
+   proposition payload, scope, language, creator and claim status. It is not a
+   fact merely because it is repeated or model-generated.
+5. A `BeliefAssessment` is a revisable, scoped assessment over one claim,
+   carrying verification state, confidence band, freshness result, coverage
+   result, conflict set and supporting/contradicting provenance edges.
+6. `Source` identifies the origin and retrieval policy; a source snapshot is
+   the immutable artifact used for a particular observation. Source identity
+   alone is never a citation.
+7. `ProvenanceEdge` records typed support, contradiction, derivation,
+   correction or supersession between evidence and claims. A projection may
+   be rebuilt from these edges and append-only records.
+8. Verification states are explicit: `UNVERIFIED`, `SUPPORTED`,
+   `CORROBORATED`, `CONFLICTED`, `STALE`, `RETRACTED` and `UNKNOWN`.
+   `UNKNOWN` and `ASSUMED` remain visible and cannot be promoted implicitly.
+9. Freshness and coverage are evidence dimensions, not confidence shortcuts.
+   A stale or incomplete source may support a claim only with that limitation
+   attached. Conflicts are retained and surfaced; they are not resolved by
+   latest-write-wins.
+10. Privacy, authorization and egress filtering happen before observation
+    persistence or external citation. Secrets and unapproved personal data
+    are fail-closed and cannot become source snapshots.
+
+## Alternatives considered and rationale
+
+- Store truth directly in Situation or Interaction: rejected because those
+  owners would become provenance/verification authorities and would mix
+  canonical operational state with revisable evidence.
+- Use a single confidence score or latest-write-wins: rejected because it
+  hides freshness, incomplete coverage and contradiction, and cannot explain
+  why an assessment changed.
+- Introduce a universal ontology engine: rejected because it expands scope,
+  makes ownership ambiguous and is unnecessary for the bounded claims needed
+  by the research and context work packages.
+
+The proposed small typed set keeps evidence historical, makes uncertainty
+visible and allows projections to be rebuilt without granting models or
+connectors canonical authority.
+
+## Lifecycle and correction
+
+Observation and source snapshots are append-only and retention-governed.
+Claims and assessments are superseded or retracted by new typed records;
+history is never deleted to hide an earlier conclusion. Human correction is
+strong evidence with explicit provenance, but does not become a permanent
+rule without a later assessment. Rebuildable projections may be compacted
+only while preserving their source record references and retention policy.
+
+## Boundaries and non-goals
+
+- No universal ontology, generic `BeliefManager` or `map[string]any` truth
+  store.
+- No model output directly mutates claims, assessments, authority or source
+  snapshots.
+- No web/repository connector, citation resolver, migration or UI change is
+  included in this proposal.
+- External research remains read-only until a separate WP-102 contract and
+  connector task is accepted.
+
+## Consequences
+
+Truthful product surfaces can distinguish evidence, assessment, uncertainty,
+staleness and conflict. Research and context compilation gain stable
+provenance inputs, while implementation must carry typed references and
+explicit freshness/coverage results. The proposal adds review and storage
+discipline but intentionally provides no immediate runtime capability.
+
+## Migration and rollback
+
+There is no migration in this proposal. If accepted, implementation must add
+append-only records and projections behind owner-local interfaces, with a
+rebuild harness and a feature flag/canary before any existing response path
+consumes assessments. Rejection or rollback disables the projection consumer;
+historical source evidence remains intact and no canonical operational state
+is mutated.
+
+## Acceptance and revisit triggers
+
+The proposal is ready for acceptance when owner boundaries, identifiers,
+retention/privacy rules, correction/supersession lifecycle, rebuildable
+projections and conflict semantics have implementation-level contract tests
+specified without introducing a new owner. Revisit if a source requires
+write access, if retention law changes, if a second canonical owner is
+proposed, or if confidence is used as an authority/permission decision.