Evidence-grounded recovery
Keep observation, hypothesis, uncertainty, contradiction, and missing context visible throughout the recovery lifecycle.
The evidence vocabulary
| Contract | Meaning |
|---|---|
| EvidenceItem | A bounded observation with source, kind, detail, confidence, optional reference, time, and attributes. |
| EvidenceRequest / EvidenceCollection | The bounded ask (kinds, budgets, redaction flag) and the typed answer (items, structured failures, truncation signal). |
| confirmed_facts | Statements directly supported by supplied context. |
| root_cause_hypothesis | A causal possibility that remains explicitly uncertain. |
| missing_evidence | Context required to strengthen, contradict, or reject the hypothesis. |
| requires_human_review | An explicit review boundary, true by default. |
Collection stays bounded and failure-aware
EvidenceService enforces a timeout, an evidence-kind allowlist, duplicate-ID handling, per-item and total character budgets, and optional conservative redaction on every provider. Oversized details are marked and truncated rather than silently dropped. Provider exceptions and timeouts become EvidenceFailure values in the collection—unavailable context can never be mistaken for a confirmed observation.
Confidence does not authorize action
Deterministic-rule confidence is authored calibration, not a computed probability. Model confidence is also an unconfirmed claim. Risk, policy, approval, execution, verification, and truth state remain separate decisions with separate contracts.
Required evidence versus missing evidence
Structured rules distinguish two roles. spec.evidence.required is a hard match precondition: the rule cannot win until every required kind is supplied. spec.diagnosis.missingEvidence records follow-up context that would strengthen or contradict an already-matched hypothesis. A value cannot appear in both lists—ambiguous duplication fails validation.