Provenance
Provenance is the explanation graph that shows why every candidate, decision, fact, intent, and effect exists, traced back to the observations that support it.
Provenance is Tarski’s explanation graph. It answers why a candidate, proposal, decision, trusted fact, intent, effect, or gate exists by walking backward through derivation edges to the observations and typed atoms that support it.
Provenance is a required part of the evaluated product; it is not optional debugging metadata. When a bad intent appears, you follow edges backward to the observation that caused it. This is the zero-code debugger: you can locate a cause without reading the generated rules.
What provenance preserves
The graph keeps the distinction between evidence and interpretation:
- An observation is raw evidence.
- A typed atom is deterministic evidence extracted from one observation.
candidate.*is provisional fact-domain evidence;proposal.*is provisional action-domain evidence.decision.*is deterministic adjudication.- A trusted fact is committed fact-domain truth, and an intent is a committed action-domain request. The graph keeps the two separate.
- An effect receipt becomes new evidence only by appending observations.
How to read a provenance chain
Start from the outcome and walk backward:
- Identify the selected candidate, proposal, decision, fact, intent, effect, or gate.
- Identify the rule or relation that produced it.
- Follow input relations to prior trusted facts, decisions, candidate/proposal evidence, or typed atoms.
- Follow typed atoms back to the observation and mapper output.
- If an effect is involved, follow from receipt observation back to effect attempt, request, intent, and the admitted evaluator/package identity.
Use this walk as a repeatable debugging method: find the earliest wrong edge in the chain and fix it.
| Earliest wrong edge | Fix |
|---|---|
| The observation is wrong | Fix ingress or the fixture |
| The atom is wrong | Fix the mapper |
| Evidence is right but the fact is wrong | Fix ontology or helper logic |
| The fact is right but an unsafe action was admitted | Fix decision graph cuts, intent rules, invariants, or effect authority |
Provenance in the product
- Studio renders provenance as a deterministic graph seeded from any evidence row. Every fact, intent, and effect row links to its neighborhood. The only client-side control is a labeled, presentation-only view depth. See Studio.
- Verification bundles include provenance, so audit evidence explains why expected worlds hold as well as that they hold. See Scenarios & fixtures.
- The counterexample flywheel starts from provenance. A provenance-pinned misbehavior promotes into a fixture in one step, and an authoring agent iterates until verification proves the fix.