Decision Record

Definition

A DecisionRecord is an append-only, schema-validated artifact emitted by the Decision plane whenever a governed decision reaches a checkpoint or terminal state.

RunContext + CompiledContext
  -> Planner / Critic / Executor loop
  -> ToolEnvelope + policy decisions + approvals + scorecard
  -> DecisionRecord
       evidence_refs
       policy_decisions
       approvals
       controls_active
       outputs
       lineage
       trace_id
       audit?                 # optional deployment profile

The record is the audit contract for the run. The trace explains where execution moved. The DecisionRecord explains what the system accepted as the governed outcome.

It does not independently authenticate an actor, prove current authorization or demonstrate that an external effect completed. The compatible execution-contract attachment binds the exact action, stored approval, stable operation and verified effect/postcondition evidence. Keep those artifacts correlated without adding required fields to the v1 receipt. controls_active records compiled obligations; it is not an attestation that a sandbox, broker or redactor enforced them.

Published validator: /schemas/decision-record.v1.schema.json. Replay inputs use /schemas/replay-packet.v1.schema.json.

Why it exists

Production agent systems fail audit when they can only answer with prose: “the model said this because it saw that.” Prose is interpretation. Audit needs typed evidence.

Relationship to nearby contracts

One DecisionSpec produces many DecisionRecords over time. One run may emit more than one DecisionRecord when it crosses multiple governed checkpoints, but it must emit one terminal record for the primary decision.

Anatomy

Minimum viable record

Your MVP record can be small, but it cannot be vague.

Recommended optional fields add useful domain or evaluation detail: subject_ids, inputs_refs, outputs, tool_lineage, scorecard, confidence, rationale, replay, and audit. A DecisionSpec can make some of these mandatory for a particular decision even though the base v1 schema does not.

Example

This v1 receipt illustrates a confirmed refund with no outstanding escalation. Short hashes are display placeholders. reversal_token below carries a protected ledger reference; raw compensation authority remains outside the model-visible record. The INR output is a domain amount; the action binding uses explicit currency/minor units, while cost_usd_cents retains its legacy fractional-cent semantics.

{
  "record_id": "dr_2026_05_09_a17",
  "decision_key": "support.refund.execute",
  "decision_version": "1.0.0",
  "timestamp": "2026-05-09T09:31:42Z",
  "status": "DECIDED",
  "actor": { "type": "AGENT", "id": "agt_support" },
  "intent_ref": "support.refund",
  "subject_ids": ["customer:cus_77", "order:ord_881"],
  "inputs_refs": {
    "request": "req_9f3a12",
    "session": "sess_42f1",
    "attachment": "artifact:invoice_881#sha256:2f9cc0"
  },
  "outputs": {
    "outcome": "approved",
    "refund_amount_inr": 4200,
    "currency": "INR",
    "transaction_id": "txn_q9"
  },
  "evidence_refs": [
    "kg:order:ord_881#snapshot_kg_2026_05_09_T0930",
    "tool:adp_orders.lookup:tc_117",
    "tool:adp_policy.eval:tc_119",
    "tool:adp_payments.issue_refund:tc_121"
  ],
  "policy_decisions": [
    {
      "policy_decision_id": "pol_9900",
      "bundle_id": "POLICY_RETURNS_V4",
      "rule_ids": ["R_REFUND_REQUIRES_IDV"],
      "verdict": "allow"
    },
    {
      "policy_decision_id": "pol_9901",
      "bundle_id": "POLICY_RETURNS_V4",
      "rule_ids": ["R_HIGH_VALUE_REQUIRES_APPROVAL"],
      "verdict": "require_approval"
    }
  ],
  "approvals": [
    {
      "gate_id": "GATE_FINANCE_APPROVAL",
      "approver": "user_finance_lead_77",
      "approval_mode_effective": "destructive",
      "evidence_snapshot_hash": "sha256:b2a1",
      "decided_at": "2026-05-09T09:31:30Z"
    }
  ],
  "controls_active": {
    "must_refuse": [],
    "must_escalate": [],
    "approval_gates_active": ["GATE_FINANCE_APPROVAL"],
    "redaction_rules_active": ["pan", "credit_card"],
    "context_admission": {
      "data_only_block_ids": ["ev_0", "ev_1", "mem_0", "session"],
      "untrusted_block_ids": [],
      "privileged_sink_policy": "verified_or_user_intent"
    },
    "evidence_gates": [
      {
        "decision_key": "support.refund.execute",
        "required": ["order_lookup", "policy.eval", "identity_verified"],
        "satisfied": ["order_lookup", "policy.eval", "identity_verified"],
        "unresolved": [],
        "rejected_evidence": [],
        "conflicts": [],
        "sufficiency": "sufficient",
        "commit_allowed": true
      }
    ]
  },
  "tool_lineage": [
    {
      "tool_call_id": "tc_121",
      "tool_result_id": "tr_121",
      "approval_mode_effective": "destructive",
      "idempotency_key": "ik_2x9k4j7m1q8w0p3z",
      "reversal_token": "effect-ledger-ref:refund_txn_q9_compensation"
    }
  ],
  "scorecard": {
    "policy": 1,
    "utility": 0.94,
    "latency": 0.86,
    "safety": 1,
    "cost": 0.91
  },
  "budget_usage": {
    "tokens": 4720,
    "tool_calls": 4,
    "cost_usd_cents": 0.91,
    "wall_clock_ms": 1840
  },
  "lineage": {
    "pack_version": "ctxpack.support@5.2.0",
    "policy_versions": ["POLICY_RETURNS_V4@4.0.0"],
    "decision_spec": "support.refund.execute@1.0.0",
    "kg_snapshot": "kg_2026_05_09_T0930",
    "model_profile": "model_profile.support.safe@1.0.0",
    "evaluator_suite": "eval.support.refund@1.0.0"
  },
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "replay": {
    "replay_packet_id": "rp_2026_05_09_a17",
    "compiled_context_hash": "sha256:9f0b",
    "tool_transcript_chain_hash": "sha256:7c4a"
  },
  "audit": {
    "prev_hash": "sha256:6ad0",
    "record_hash": "sha256:9ea1",
    "signed_by": "kid_runtime_2026Q2"
  }
}

Lifecycle

1. Select spec — the Orchestrator resolves decision_key from the Intent-Task Catalog and Decision Catalog.
2. Compile context — the Compiler emits manifests and runtime controls from the pinned Context Pack.
3. Verify plan — the Critic checks required evidence, tool surface, policy obligations, and budget before execution.
4. Collect required approvals — before the protected effect, bind the complete action and evidence/policy/profile/release pins, eligible approvers, validity and quorum. The v1 approval entry is a receipt projection, not the complete approval authorization object.
5. Execute tools — the Gateway checks current authority/policy, exact stored approval and atomic redemption, active boundary/data route and budget reservation before dispatch. Retain stable operation identity and explicit uncertain effects across retries and resume; emit ToolCallEnvelope / ToolResultEnvelope receipts.
6. Verify and score result — verify required external effects and postconditions, then evaluate Policy, Utility, Latency, Safety, and Cost. A lost acknowledgement remains uncertain until reconciled.
7. Emit record — the runtime writes the DecisionRecord with all refs, not copied raw data.
8. Seal record when required — deployments that adopt the tamper-evidence profile compute a canonical hash, link the prior hash, and sign the record.
9. Replay — replay re-runs the canonical loop against pinned inputs and recorded transcripts, then applies the declared comparison policy.

Status values

Validation rules

Replay contract

Replay is the difference between evidence and reconstruction. Given a trace_id, the harness must fetch:

Audit replay does not re-execute side-effecting tools. It uses recorded transcripts and model request/response artifacts. Deterministic compiler and policy artifacts can be compared exactly. Model-dependent stages need declared property, scorecard, or tolerance checks. Keep action, operation, approval and release pins with the packet when applicable; a checkpoint is not fresh dispatch authority. A mismatch returns a typed diff such as changed evidence, policy, tool transcript, compiled context, scorecard, or detected tampering.

Storage model

Store DecisionRecords append-only. Retractions and corrections create new records that supersede prior records; they do not edit history.

Query patterns

-- High-value refunds with approver and evidence in a quarter.
SELECT
  record_id,
  trace_id,
  outputs->>'refund_amount_inr' AS amount_inr,
  approvals,
  evidence_refs,
  lineage
FROM decision_records
WHERE decision_key = 'support.refund.execute'
  AND (outputs->>'refund_amount_inr')::numeric > 10000
  AND timestamp >= '2026-01-01'
  AND timestamp < '2026-04-01';

-- Policy rules producing the most denials this week.
SELECT
  jsonb_array_elements(policy_decisions)->>'policy_decision_id' AS policy_decision_id,
  count(*) AS records
FROM decision_records
WHERE status = 'REJECTED'
  AND timestamp >= now() - interval '7 days'
GROUP BY 1
ORDER BY records DESC;

-- Replay health by pack version.
SELECT
  lineage->>'pack_version' AS pack_version,
  count(*) AS sampled_records,
  avg(CASE WHEN replay->>'last_status' = 'replay_equal' THEN 1 ELSE 0 END) AS replay_equal_rate
FROM decision_records
WHERE timestamp >= now() - interval '30 days'
GROUP BY 1;

Standards alignment

DecisionRecord is ContextOS-specific, but it should interoperate with operational standards:

Readiness checklist

Common misconceptions

• A DecisionRecord is not the trace. The trace is the path; the record is the accepted governed outcome.
• A DecisionRecord is not model chain-of-thought. Store typed rationale, evidence, and policy decisions. Do not store hidden reasoning.
• A DecisionRecord is not merely a warehouse row. It must be schema-valid, replay-addressable, and bound to lineage; append-only tamper evidence is the recommended governed-storage profile.
• A DecisionRecord is not optional for read-only decisions. Read-only decisions still need evidence and provenance when they affect a user, a downstream workflow, or future memory.
• A DecisionRecord is not authored after the incident. It is emitted by the runtime while the decision is made.