Data model

This is a field-level companion to The Decision Ledger and the graph model.

Decision (ledger row)

The canonical record. Stored in a relational database with extracted columns plus structured JSON blobs.

Field	Type	Description
`ledger_id`	uuid	Primary key.
`agent_id` / `internal_agent_id`	string / uuid	Owning agent.
`session_id`	string	Owning session.
`user_id` / `user_role`	string	Owning person and role.
`tenant_id` / `workspace_id`	uuid	Tenancy scope (RLS-enforced).
`outcome_class`	enum	Canonical outcome classification.
`outcome_summary`	text	Free-text “what the agent did.”
`decision_title`	text	Short scannable headline.
`decision_intent`	enum	Work-type classification.
`decision_intent_confidence`	float	Confidence of the intent label.
`confidence_score`	float	Decision confidence.
`grounding_fidelity`	float	Grounding quality metric.
`logic_coherence`	float	Reasoning coherence metric.
`contradiction_ratio`	float	Self-contradiction metric.
`hallucination_index`	float	Hallucination metric.
`evidence_density`	float	Evidence support metric.
`cost_usd`	float	Cost of the decision.
`execution_ms`	int	Duration.
`human_review_required` / `human_review_status`	bool / string	Review state.
`timestamp_utc`	datetime	When the decision was made.

final_verdict / verdict_label exist for backward compatibility and are deprecated — use outcome_class / outcome_summary.

JSONB blobs (fetched via include= on get_decision) carry the full audit trail: reasoning trace, evidence, findings, artifacts, tool activity, and policy checks. A vector embedding supports semantic search.

Entity	Description
Agent	An AI worker; rollup of its sessions/decisions, plus a profile over time.
Session	One agent run; aggregates and a health view.
Feature	Auto-grouped delivered work with contributors, cost, and ROI.
Epic	Higher-level rollup above Features.
Insight	A drift/anomaly finding (entity / agent / session tier).
Pulse report	A generated daily/weekly/monthly briefing.
Tenant / Workspace / User	Tenancy and identity.

Graph entities

Nodes: Agent, Decision, Subject, Evidence, Step, Finding, Artifact. Edges: MADE, ABOUT, USED, DEPENDS_ON, STEP_NEXT, STEP_TO_FIND, SUPPORTS, REFUTES, MADE_ARTIFACT. Every node is scoped by tenant_id, workspace_id, user_id. See Evidence & the Logic Trace.

MCP Server

Data API

Decision (ledger row)

Graph entities

​Decision (ledger row)

​Derived & related entities

​Graph entities

Decision (ledger row)

Derived & related entities

Graph entities