Decision Ledger

Decision Ledger | Corevexa Docs
CVX Corevexa Docs
Home Getting Started Architecture API Roadmap FAQ

Decision Ledger
Append-Only Governance Record

The decision ledger is the audit backbone of Layer-7. It stores immutable, append-only records of decision evaluation, authority approvals, policy gates, overrides, and enforcement outcomes—so governance can be reconstructed.

Ledger Model Event Types Integrity Reconstruction
Append-only Tamper-evident Queryable audits
Non-negotiable: if the ledger cannot confirm a write, execution must not proceed for governed actions.

Why the Ledger Exists

Modern AI systems can execute faster than humans can supervise. The ledger solves the accountability gap by recording: what was requested, which policy gates applied, what risk was computed, which authority approved, and what was enforced.

Audit-grade traceability

Reconstruct decision pathways for audits, incidents, and compliance reviews.

Governance drift detection

Detect policy changes, inconsistent approvals, and escalation anomalies over time.

Operational reporting

Generate governance posture metrics: risk distribution, override rates, and approval latency.

If you can’t reconstruct it, you can’t defend it. The ledger is the defense.

Ledger Model (Append-Only)

The ledger is a stream of events keyed by decision_id. Decisions are not rewritten; they are evolved by new events. Each event includes a hash chain pointer for tamper evidence.

{ “record_id”: “ldr_*”, “decision_id”: “dec_*”, “event_id”: “evt_*”, “event_type”: “decision.created|decision.evaluated|policy.gate|risk.scored|authority.required|approval.added|override.added|enforcement.result|decision.executed|decision.expired”, “policy_version”: “v1.0”, “actor”: { “id”: “string|null”, “role”: “string|null” }, “payload”: {}, “integrity”: { “hash”: “sha256:*”, “prev_hash”: “sha256:*|null”, “sequence”: 1 }, “timestamps”: { “at”: “ISO-8601” } }
Append-only means: the only legal mutation is adding a new event. Prior events are immutable.

Event Types

These event types form the minimum decision trail. You can add additional domain-specific events, but do not remove these.

Event type Purpose Typical payload fields
decision.created Initial decision envelope created action, context, policy_version
decision.evaluated Evaluation complete; gates + risk computed status, evaluation_summary
policy.gate Policy gate pass/fail/exception requirement gate_id, result, reason
risk.scored Risk score + reasons captured score, band, reasons[]
authority.required Required roles + signature counts computed required_roles[], min_signatures
approval.added Approval signature recorded actor, intent, method, signature_ref
override.added Override recorded (exception path) actor, reason, scope, expires_at
enforcement.result Allow/deny/queue/escalate produced result, allow_if[], unmet_conditions[]
decision.executed Downstream gateway confirms execution occurred executor, outcome, external_refs
decision.expired Decision timed out and is no longer valid ttl, reason
A decision trail is complete only when it contains an enforcement event and (if executed) an execution confirmation event.

Integrity Strategy (Tamper-Evident)

The ledger must be tamper-evident. At minimum, each event includes a hash and a pointer to the previous event hash. This creates a hash chain per decision stream.

Minimum integrity controls

  • Hash chain per decision stream (prev_hash → hash).
  • Monotonic sequence numbers to detect missing events.
  • Write confirmation required for execution gates.
  • Immutable storage configuration (append-only tables / WORM buckets).

Optional upgrades

  • Periodic anchors (daily digest hash stored externally).
  • Signed events for approvals/overrides (actor signature verification).
  • Dual-write to separate storage tiers (hot DB + cold archive).
  • Independent verifier service to validate chains and report anomalies.
Integrity is about evidence. The ledger must make tampering detectable, not merely “unlikely.”

Query Patterns

Ledger queries are read-only and must support common governance workflows: audits, incident response, and reporting.

Common filters

  • Time window: from/to timestamps
  • Risk band: low/medium/high/critical
  • Outcome: allow/deny/queue/escalate
  • Actor / role: who approved / who requested
  • Action class: deploy_code / write_data / transfer_funds

Operational metrics

  • Approval latency: time to satisfy authority
  • Override rate: overrides / critical decisions
  • Policy gate failures: top failing gates
  • Risk distribution: score histogram by domain
# Example query envelope (concept) GET /v1/ledger?from=2026-02-01T00:00:00Z&to=2026-02-24T23:59:59Z &risk_band=high &event_type=enforcement.result &action_class=deploy_code
Governance reporting is not an “extra.” It’s the practical payoff of Layer-7 being structural.

Retention & Access Control

Ledger retention must satisfy compliance needs without exposing sensitive details. Access should be strict: most users can see summaries; few can see raw payloads.

Retention reference

  • Hot storage: 30–180 days for operational queries
  • Cold archive: 1–7 years depending on regulatory needs
  • Redaction: store hashes/refs for secrets, not raw secrets
  • PII controls: minimize payload; use pointers where possible

Access controls

  • Role-based read for summary vs raw event payloads
  • Break-glass reads logged as separate events
  • Export controls for audit downloads
  • Immutable admin logs for ledger access activity
Store secrets as references. The ledger is not a secret vault; it is an accountability record.

Audit Reconstruction Workflow

Reconstruction means producing a human-readable narrative of what happened, backed by event evidence. The ledger enables “show your work” governance.

Step Goal Ledger evidence
1 Identify decision decision.created, correlation_id
2 Confirm policy context policy_version + policy.gate events
3 Confirm risk rationale risk.scored score + reasons
4 Confirm authority path authority.required + approval.added
5 Confirm enforcement outcome enforcement.result
6 Confirm execution (if occurred) decision.executed + external_refs
7 Verify integrity hash chain validation + sequence
If integrity validation fails, the reconstruction must explicitly declare the record unreliable and trigger an investigation workflow.
Next: Security Model Back: Authority Model API Reference
Corevexa Docs — Layer-7 Governance Infrastructure
© Corevexa Labs