Decision Evidence Graph developer documentation.
The fixture format, node and edge reference, client contract and integration architecture behind the explorer. Everything here describes the shipped preview; nothing describes endpoints that do not exist yet.
Schema overview.
A graph fixture (deg-fixture/0.1) is one JSON document: identity and layout seed, a mandatory demonstration boundary (status: synthetic | sanitized, not_live_claim: true), mandatory honesty lists (verifiable / reported only / missing / uncertain), then nodes[] and edges[]. Every node and edge carries the same envelope: stable id, schema_version "deg/0.1", created timestamp, actor or source reference, evidence reference, integrity state, sensitivity, retention, limitations, and an optional external reference. Machine-readable schema: graph-schema.json · versioned manifest with sha256 bindings: manifest.json.
Node and edge reference.
| Node type | Meaning |
|---|---|
Source | A publisher of external facts (an agency feed, an API, a registry). |
Observation | One recorded reading from a source at a moment, with freshness at use. |
TrustReceipt | A sealed evidence artifact. Only receipts whose evidence_ref points into the published conformance package are cryptographically verifiable in this preview. |
EvidenceBundle | A named collection of observations and receipts a decision consumed. |
DecisionReference | An opaque reference to a machine decision. References in; the graph never carries the decision internals. |
AgentHandoff | Work moving between agents or from a decision to an executor. |
ActionReference | An opaque reference to an action a system reports it took. |
Outcome | What is reported or observed to have happened afterward. |
Review | A human or automated review event. |
Correction | A later correction of an earlier record (edge CORRECTS; acyclic). |
Supersession | A later record replacing an earlier one (edge SUPERSEDES; acyclic). |
Edge types: OBSERVED_FROM · SEALED_AS · DERIVED_FROM · SUPPORTS · CONTRADICTS · USED_BY · DELEGATED_TO · AUTHORIZED · TRIGGERED · RESULTED_IN · REVIEWED_BY · CORRECTS · SUPERSEDES · VERIFIED_BY. Endpoint-type rules (which edge may leave or land on which node type) are enforced by the published validator and mirrored in tests/test_evidence_graph.py.
Client contract.
The explorer talks only to EvidenceGraphClient (contract deg-client/0.1, source: evidence-graph-client.js). v0.1 binds a fixture adapter: the four published scenarios plus deterministic seeded synthetic graphs generated locally. The interface is the integration seam:
const client = new EvidenceGraphClient(); // FixtureAdapter by default
await client.getGraph("wx-logistics-a");
await client.getDecision(graphId, decisionId);
await client.getDecisionLineage(graphId, nodeId); // bounded, cycle-safe
await client.getReceiptLineage(graphId, receiptId);
await client.getHandoff(graphId, handoffId);
await client.verifyNode(graphId, nodeId); // Trust Receipts: Web-Worker verification
await client.verifyEdge(graphId, edgeId); // structural checks + reported state
await client.compareDecisions(graphId, a, b);
How future REST APIs replace the fixture adapter: the production backend (owned separately) will ship an adapter implementing this same interface over its APIs. Callers do not change; the adapter is the only replacement point, and it must preserve stable ids, schema_version, integrity state, sensitivity, retention and limitations end to end, with authorization enforced server-side. Those endpoints do not exist yet, and nothing in this preview pretends they do.
How to link an external decision ID: a DecisionReference node carries your identifier in external_ref (an opaque id or https URL) — the graph references your decision, it never ingests its contents. How to attach a Trust Receipt: a TrustReceipt node's evidence_ref names the sealed artifact; in this preview only manifest-bound conformance artifacts verify, via the published Trust Receipt v1 verifier.
Fixtures and example bundle.
Scenario fixtures (all demonstration data): weather logistics · cybersecurity escalation · vendor due diligence · agent authorization. Each is an example evidence bundle in itself; the explorer's Export button downloads the loaded graph as a portable .deg.json bundle. The manifest hash-binds every artifact.
Privacy and trust boundary.
A verified graph relationship proves that the referenced evidence and identifiers satisfy the implemented integrity checks. It does not, by itself, prove objective truth, completeness, safety, causation, that every relevant event was observed, or that the resulting decision was correct. Verification of Trust Receipts runs browser-local in a Web Worker against public TEST keys (no production trust). Analytics on the explorer are content-free event names; graph contents, labels, receipt bytes and source URLs are never transmitted or logged. This preview hosts no customer decision graphs.