Skip to content

Decision Graph

Loomtracer’s ledger is projected into a graph. The graph has four content node types and several typed edge kinds. Status is always derived from edges — never stored, never overwritten.

TypeDescription
DecisionA specific choice made by one or more actors
OptionAn alternative that was considered
EvidenceA factual observation the decision rests on
HypothesisA belief still in flight — not yet refuted or confirmed

Actor (a human, agent, or system) is provenance metadata — every node and edge carries an actor as attribution, but Actor is not a content node in the decision graph.

EdgeFrom → ToMeaning
PROPOSED_BYDecision → ActorActor who proposed the decision
ACCEPTED_BYDecision → ActorActor who accepted the decision
REJECTED_BYDecision → ActorActor who rejected the decision
SUPERSEDESDecision → DecisionThis decision replaces an older one
HAS_OPTIONDecision → OptionAn option that was considered
CHOSEDecision → OptionThe option that was selected
BASED_ONDecision → EvidenceEvidence the decision rests on
PREMISED_ONOption → HypothesisHypothesis the chosen option depends on being true
PREMISED_ON_DIRECTDecision → HypothesisHypothesis a decision depends on directly (not via an option)
SUPPORTSEvidence → HypothesisEvidence that corroborates a hypothesis
REFUTESEvidence → HypothesisEvidence that contradicts a hypothesis

A DecisionRequest (an open ask — “should we do X?” — with no decision made yet) carries its own edge kinds to Actor, distinct from a Decision’s:

EdgeFrom → ToMeaning
DECISION_REQUESTED_BYDecisionRequest → ActorActor who raised the request, with no accept/reject position on record yet
REQUEST_PROPOSED_BYDecisionRequest → ActorActor who proposed the position under a contested request (has at least one REQUEST_ACCEPTED_BY or REQUEST_REJECTED_BY on the same request)
REQUEST_ACCEPTED_BYDecisionRequest → ActorActor who accepted the proposed position
REQUEST_REJECTED_BYDecisionRequest → ActorActor who rejected the proposed position
DECISION_REQUEST_FOR_DECISIONDecisionRequest → DecisionThe decision made in response to this request
DECISION_REQUEST_REQUIRED_OWNERDecisionRequest → ActorActor whose sign-off the request is waiting on

Implementation detail — why two proposer/acceptor/rejecter edge kinds exist: Kuzu (the graph backend) binds a relationship table to a fixed (from, to) node-kind pair. PROPOSED_BY/ACCEPTED_BY/REJECTED_BY are bound to Decision → Actor, so a DecisionRequest’s proposer/accepter/rejecter positions use the separate REQUEST_PROPOSED_BY/REQUEST_ACCEPTED_BY/REQUEST_REJECTED_BY tables instead of widening the existing ones. This is a storage-layer detail, not a semantic distinction — “who proposed this” means the same thing on both node kinds.

Status is derived from the edges present on a decision node:

StatusCondition
proposedNo ACCEPTED_BY or REJECTED_BY edge; not superseded
acceptedAt least one ACCEPTED_BY edge; no active rejection
contestedBoth ACCEPTED_BY and REJECTED_BY edges exist from different actors
supersededA newer decision has a SUPERSEDES edge pointing here

contested is a first-class status. Two actors disagreeing is the signal, not an error to resolve silently. Both positions stay in the graph, queryable, reviewable, and eventually resolvable through explicit action.

When a Hypothesis is refuted, every Decision premised on it (through a chosen option’s PREMISED_ON edge or a direct PREMISED_ON_DIRECT edge) surfaces hypothesis_refuted: true in queries. Staleness is visible by default — not hidden.

When one decision supersedes another, the old decision is not deleted or mutated. A new decision carries a SUPERSEDES edge. You can walk the full chain backward to the original proposal with:

Terminal window
loomtracer query get_supersession_chain --id decision:abc123
Decision: "Use SQLite for local prototype"
PROPOSED_BY → Actor: human:alice
ACCEPTED_BY → Actor: human:alice
BASED_ON → Evidence: "SQLite WAL is sufficient for current local writes"
HAS_OPTION → Option: "Postgres"
HAS_OPTION → Option: "DuckDB"
HAS_OPTION → Option: "SQLite"
CHOSE → Option: "SQLite"
PREMISED_ON → Hypothesis: "Single-node deployments are the primary case for 2026"

If the hypothesis is later refuted, the decision surfaces hypothesis_refuted: true. If a new decision supersedes this one, this one’s status becomes superseded — and its full history remains queryable forever.