Quickstart

This quickstart is a worked contract example for a support.refund workflow. Read Adopt a Harness Contract first if you are deciding where to add controls to an existing runtime.

You will model the context, decision, tool, and replay artifacts needed to inspect one run. The TypeScript compiler reference can exercise the compile stage; production model calls, a payment adapter, approval service, persistence, and a replay runner are supplied by your implementation. Completing the example does not deploy those services.

MVP mental model

Start with one workflow and explicit acceptance cases. For a refund, eligibility, permission, and observed payment completion are separate checks. Include unauthorized callers, insufficient evidence, expired approval, interruption, and a provider write whose response is lost. Keep a deterministic workflow when it already meets the task.

user request
  -> RunContext
  -> Context Pack
  -> CompiledContext
  -> Plan + Critic checks
  -> ToolEnvelope through the Tool Gateway
  -> DecisionRecord
  -> Replay packet + improvement proposal

The model is only one participant. ContextOS specifies the control and evidence boundary around the implementing runtime.

Pick one workflow

Use a workflow that is valuable, narrow, and easy to audit. For this quickstart:

Choice	MVP value
Workflow	`support.refund`
User request	”Refund order `ord_881` for INR 4200.”
Business risk	money movement, customer impact, fraud exposure
First tool	`adp_orders.lookup` as `read_only`
Risky tool	`adp_payments.issue_refund` as `destructive`
Final artifact	`DecisionRecord` for `support.refund.execute`

Your first workflow should have one primary intent, one or two entities, one safe read tool, one governed write tool, and one explicit decision.

Those tools describe this refund example; a useful read-only MVP does not need a write. Before work starts, declare actual workflow features and admit the exact contextos.enterprise@1 requirements using the compatible execution attachment. The runtime supplies authenticated observations, atomic stores and enforcement; support negotiation alone does not authorize a call. Add durable/delegated or high-assurance requirements when the workflow requires them, with the corresponding evidence.

Step 1: Name the business entities

The Intelligence plane starts by making the workflow’s nouns stable. For refund support, the minimum ontology is Customer, Order, and a relationship between them.

{
  "ontology": {
    "namespace": "ont.support",
    "version": "1.0.0",
    "entity_types": ["Customer", "Order"],
    "relationship_types": ["order_belongs_to_customer"]
  },
  "identity_layer": {
    "ceid_namespaces": ["customer", "order"],
    "examples": {
      "customer": "customer:cus_77",
      "order": "order:ord_881"
    }
  }
}

Minimum bar:

Check	You are done when
Entity identity	Every important object has a stable canonical ID.
Relationship meaning	The runtime can explain how the order belongs to the customer.
Evidence source	The order lookup can produce an evidence ref, not just a value.

Read next: Ontology, Identity Layer, Knowledge Graph.

Step 2: Define the RunContext

RunContext is the cross-cutting identity and limit envelope. It travels through every plane.

{
  "run_id": "run_refund_001",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "session_id": "sess_support_42",
  "tenant_id": "tenant_acme_prod",
  "user": {
    "user_id": "usr_771",
    "role": "support_agent",
    "delegation": {
      "auth_type": "oauth2",
      "subject": "u:user:771",
      "scopes": ["orders.read", "payments.refund"],
      "token_ref": "tok_user_7a"
    }
  },
  "agent": {
    "agent_id": "agt_support",
    "role": "support_ops",
    "workload_identity": "spiffe://contextos/agents/support",
    "token_ref": "tok_agent_92"
  },
  "intent": "support.refund",
  "locale": "en-IN",
  "safety_mode": "destructive",
  "run_budget": {
    "total_tokens": 12000,
    "bucket_tokens": {
      "business": 1200,
      "policy": 1800,
      "tool": 1200,
      "evidence": 3500,
      "memory": 1300,
      "session": 3000
    },
    "max_tool_calls": 8,
    "max_replan_attempts": 2,
    "wall_clock_ms": 30000,
    "max_cost_cents": 25,
    "tokens_used": 0,
    "tool_calls_used": 0,
    "latency_ms_used": 0,
    "cost_cents_used": 0
  }
}

Minimum bar:

Field	Why it exists
`run_id`	Lets every artifact belong to one execution.
`trace_id`	Propagates through model calls, policy checks, and tools.
`tenant_id`	Binds the intended tenant; trusted brokers and actual access checks enforce isolation.
`user.delegation`	Names claimed delegated authority; current scope, audience, ancestry and revocation still require verification.
`agent.workload_identity`	Names the workload identity that the runtime authenticates.
`safety_mode`	Sets the highest v1 compatibility projection this run may produce; native `ActionRisk` is evaluated independently.
`run_budget`	Makes loops, cost, latency, and context use bounded.

Step 3: Write the minimal Context Pack

The Context Pack is the versioned input contract. It tells the runtime what the workflow may know, which policies apply, which tools exist, which decision must be produced, and how memory can be used.

{
  "contract_meta": {
    "contract_name": "ctxpack.support",
    "contract_version": "1.0.0",
    "issuer": "tenant_acme_prod",
    "created_at": "2026-05-09T00:00:00Z",
    "compatibility": {
      "requires": { "runtime": ">=1.0.0", "ontology": ">=1.0.0" }
    }
  },
  "pack_meta": {
    "pack_id": "ctxpack.support",
    "pack_version": "1.0.0",
    "tenant": { "tenant_id": "tenant_acme_prod", "name": "Acme Support" },
    "environment_defaults": {
      "language": "en",
      "timezone": "Asia/Kolkata",
      "currency": "INR",
      "region": "ap-south-1"
    },
    "ttl_seconds": 86400,
    "data_classification": "INTERNAL"
  },
  "intelligence_refs": {
    "ontology": {
      "namespace": "ont.support",
      "version": "1.0.0",
      "entity_types": ["Customer", "Order"],
      "relationship_types": ["order_belongs_to_customer"]
    },
    "knowledge_graph": { "snapshot_pin_rule": "alias:prod" },
    "identity_layer": { "ceid_namespaces": ["customer", "order"] }
  },
  "business_context": {
    "summary": {
      "what_we_do": "Post-purchase customer support",
      "who_we_serve": ["customers"],
      "differentiators": ["fast, policy-compliant resolution"]
    },
    "non_negotiables": ["never promise a refund before policy verification"]
  },
  "policy_layer": {
    "policy_bundles": [
      {
        "bundle_id": "POLICY_RETURNS_V4",
        "priority": 10,
        "policy_dsl": {
          "language": "jsonlogic",
          "rules": [
            {
              "rule_id": "R_REFUND_REQUIRES_IDV",
              "applies_to": { "intent": "support.refund" },
              "if": { "==": [{ "var": "request.context.identity_verified" }, true] },
              "then": { "allow": true, "requires": ["order_lookup"] },
              "rationale": "Refunds require verified customer identity."
            },
            {
              "rule_id": "R_HIGH_VALUE_REQUIRES_APPROVAL",
              "applies_to": { "intent": "support.refund" },
              "if": {
                "and": [
                  { "==": [{ "var": "user.role" }, "support_agent"] },
                  { ">": [{ "var": "request.context.refund_amount" }, 3000] }
                ]
              },
              "then": {
                "allow": true,
                "approval_mode": "destructive",
                "requires_approval_gate": "GATE_FINANCE_APPROVAL"
              },
              "decision_binding": "support.refund.execute",
              "rationale": "High-value refunds require finance approval."
            }
          ]
        }
      }
    ],
    "guardrails": {
      "must_refuse": ["refund_without_identity"],
      "must_escalate": ["fraud_signal_high"],
      "redaction_rules": ["pan", "credit_card"]
    },
    "approval_gates": [
      {
        "gate_id": "GATE_FINANCE_APPROVAL",
        "when": { ">": [{ "var": "request.context.refund_amount" }, 3000] },
        "required_approver_role": "finance_lead",
        "ttl_seconds": 7200
      }
    ]
  },
  "tooling_layer": {
    "adapter_registry": [
      {
        "adapter_id": "adp_orders",
        "type": "OPENAPI",
        "endpoint_ref": "internal://orders",
        "capabilities": ["lookup"],
        "capability_risks": {
          "lookup": {
            "effect": "none",
            "authority": "service",
            "reversibility": "read_only",
            "interaction": "api",
            "data_scope": "CONFIDENTIAL"
          }
        },
        "approval_mode": "read_only"
      },
      {
        "adapter_id": "adp_policy",
        "type": "OPENAPI",
        "endpoint_ref": "internal://policy",
        "capabilities": ["eval"],
        "capability_risks": {
          "eval": {
            "effect": "none",
            "authority": "service",
            "reversibility": "read_only",
            "interaction": "api",
            "data_scope": "CONFIDENTIAL"
          }
        },
        "approval_mode": "read_only"
      },
      {
        "adapter_id": "adp_payments",
        "type": "OPENAPI",
        "endpoint_ref": "internal://payments",
        "capabilities": ["issue_refund"],
        "capability_risks": {
          "issue_refund": {
            "effect": "external_state",
            "authority": "user_delegated",
            "reversibility": "compensatable",
            "interaction": "api",
            "data_scope": "CONFIDENTIAL",
            "decision_ttl_seconds": 120
          }
        },
        "approval_mode": "destructive"
      }
    ],
    "permissions": [
      { "permission_id": "p_orders_lookup", "adapter_id": "adp_orders", "capability": "lookup", "allow": true },
      { "permission_id": "p_policy_eval", "adapter_id": "adp_policy", "capability": "eval", "allow": true },
      {
        "permission_id": "p_issue_refund",
        "adapter_id": "adp_payments",
        "capability": "issue_refund",
        "allow": true,
        "requires_approval_gate": "GATE_FINANCE_APPROVAL",
        "arg_constraints": {
          "amount_inr": { "min": 1, "max": 50000 },
          "idempotency_key": { "required": true }
        }
      }
    ]
  },
  "decision_layer": {
    "decision_specs": [
      {
        "decision_key": "support.refund.execute",
        "version": "1.0.0",
        "owner_role": "support_ops",
        "required_evidence": ["identity_verified", "order_lookup", "policy.eval"],
        "allowed_outcomes": ["approved", "denied", "escalated"],
        "approval_mode": "destructive",
        "decision_right": "execute"
      }
    ]
  },
  "memory_layer": {
    "memory_policy": {
      "tier_ttls": { "working": "1h", "episodic": "24h", "semantic": "365d", "durable": "1825d" },
      "write_classes_allowed": ["preference", "decision_outcome", "correction"],
      "consent_gating": { "pii_write_back_allowed": false }
    },
    "promotion_thresholds": { "auto_promote_confidence": 0.95 }
  },
  "evaluation_layer": {
    "eval_targets": [
      { "intent": "support.refund", "policy": 1.0, "utility": 0.9, "latency_p99_ms": 3000, "safety": 1.0, "economics_cents_per_decision": 1.5 }
    ]
  },
  "tone_and_comms": {
    "voice_attributes": ["clear", "neutral"],
    "do": ["cite policy", "explain approval status"],
    "dont": ["promise outcomes before approval"]
  }
}

Minimum bar:

Layer	MVP requirement
`intelligence_refs`	Pinned ontology, graph snapshot rule, and identity namespaces.
`policy_layer`	At least one allow rule, one guardrail, and one approval gate for risky work.
`tooling_layer`	Safe read tool plus governed write tool with native risk and a conservative v1 mode.
`decision_layer`	One `DecisionSpec` with required evidence and allowed outcomes.
`memory_layer`	Write classes and consent behavior, even if memory writes are disabled at first.
`evaluation_layer`	Minimum score targets for policy, safety, utility, latency, and cost.

Step 4: Compile, do not prompt-stuff

The Context plane compiles the pack and request into a CompiledContext; the runtime sends its admitted prompt projection to the model while enforcing controls outside it. An applicable policy-expression error stops compilation with a structured ContextCompileError; safely serialize that failure at the invocation boundary. A false predicate still follows its defined false/else path.

Input request (identity and delegation are supplied by the trusted runtime from the RunContext above):

{
  "request_id": "req_refund_001",
  "session_id": "sess_support_42",
  "tenant_id": "tenant_acme_prod",
  "user": { "user_id": "usr_771", "delegation": { "auth_type": "oauth2", "subject": "u:user:771", "scopes": ["orders.read", "payments.refund"] } },
  "agent": { "agent_id": "agt_support", "role": "support_ops", "workload_identity": "spiffe://contextos/agents/support" },
  "context_pack_refs": ["ctxpack.support@1.0.0"],
  "input": {
    "intent": "support.refund",
    "message": "Refund order ord_881 for INR 4200.",
    "channel": "app_chat",
    "locale": "en-IN",
    "context": {
      "identity_verified": true,
      "refund_amount": 4200,
      "order_id": "ord_881"
    }
  },
  "mode": "stream",
  "runtime": {
    "plan_timeout_ms": 15000,
    "max_tool_calls": 8,
    "max_payload_bytes": 1048576,
    "max_cost_cents": 25
  },
  "trace": {
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7",
    "trace_flags": "01"
  }
}

Structured evidence candidate:

{
  "evidence_ref": "kg:order:ord_881#snapshot_2026_05_09",
  "source_id": "orders-db",
  "content": "{\"order_id\":\"ord_881\",\"customer_id\":\"cus_77\",\"status\":\"delivered\"}",
  "integrity": "verified",
  "freshness": "current",
  "satisfies": ["order_lookup"]
}

The retrieval service supplies the record; the compiler does not perform I/O. It derives the content hash and fails if an optional supplied hash mismatches, then renders the content as data_only. Hash derivation does not authenticate the source or its freshness labels. Likewise, identity_verified: true must come from authenticated verification, not be trusted because the caller wrote it. A legacy string evidence ref has neither proof of integrity nor freshness, so it is normalized as untrusted/unknown and cannot satisfy the decision gate.

Compiled output shape:

This is an abridged display with placeholder hashes and illustrative token counts. With only the order candidate and verified identity context, policy.eval is still unresolved. Read steps can collect that missing evidence; no refund may commit yet. Named guardrails below are compiled obligations whose trigger conditions the runtime evaluates, not proof that a redactor or escalation handler ran.

{
  "compiled_prompt": {
    "system": "You are an agent governed by ContextOS...",
    "developer": "Honor the policy_manifest, tool_manifest, runtime_controls, and required_evidence at every step.",
    "task": "Handle refund request req_refund_001.",
    "context_blocks": [
      {
        "block_id": "ev_order",
        "bucket": "evidence",
        "content": "{\"order_id\":\"ord_881\",\"customer_id\":\"cus_77\",\"status\":\"delivered\"}",
        "priority": 60,
        "provenance": {
          "source_refs": ["kg:order:ord_881#snapshot_2026_05_09"],
          "origin": "retrieval",
          "integrity": "verified",
          "freshness": "current",
          "instruction_treatment": "data_only",
          "inclusion_reason": "retrieved evidence admitted for support.refund",
          "content_hash": "sha256:..."
        }
      }
    ]
  },
  "manifests": {
    "policy_manifest": [
      { "bundle_id": "POLICY_RETURNS_V4", "rule_ids": ["R_REFUND_REQUIRES_IDV", "R_HIGH_VALUE_REQUIRES_APPROVAL"] }
    ],
    "tool_manifest": [
      { "adapter_id": "adp_orders", "capabilities": ["lookup"] },
      { "adapter_id": "adp_policy", "capabilities": ["eval"] },
      { "adapter_id": "adp_payments", "capabilities": ["issue_refund"] }
    ],
    "evidence_manifest": [
      {
        "evidence_ref": "kg:order:ord_881#snapshot_2026_05_09",
        "source_id": "orders-db",
        "hash": "sha256:...",
        "integrity": "verified",
        "freshness": "current",
        "instruction_treatment": "data_only",
        "satisfies": ["order_lookup"]
      }
    ]
  },
  "runtime_controls": {
    "must_refuse": ["refund_without_identity"],
    "must_escalate": ["fraud_signal_high"],
    "approval_gates_active": ["GATE_FINANCE_APPROVAL"],
    "redaction_rules_active": ["pan", "credit_card"],
    "context_admission": {
      "data_only_block_ids": ["ev_order"],
      "untrusted_block_ids": [],
      "privileged_sink_policy": "verified_or_user_intent"
    },
    "evidence_gates": [
      {
        "decision_key": "support.refund.execute",
        "required": ["identity_verified", "order_lookup", "policy.eval"],
        "satisfied": ["identity_verified", "order_lookup"],
        "unresolved": ["policy.eval"],
        "rejected_evidence": [],
        "conflicts": [],
        "sufficiency": "insufficient",
        "commit_allowed": false
      }
    ]
  },
  "budget_report": {
    "tokens_allocated": { "business": 1200, "policy": 1800, "tool": 1200, "evidence": 3500, "memory": 1300, "session": 3000 },
    "tokens_used_at_compile": 620,
    "tokens_used_by_bucket": { "evidence": 28 },
    "bucket_truncations": {},
    "dropped_block_ids": {},
    "omissions": [],
    "warnings": []
  },
  "context_ledger": {
    "pack_ref": "ctxpack.support@1.0.0",
    "intent": "support.refund",
    "request_id": "req_refund_001",
    "policy_bundles": ["POLICY_RETURNS_V4"],
    "policy_rule_ids": ["R_REFUND_REQUIRES_IDV", "R_HIGH_VALUE_REQUIRES_APPROVAL"],
    "tools": ["adp_orders.lookup", "adp_policy.eval", "adp_payments.issue_refund"],
    "evidence_refs": ["kg:order:ord_881#snapshot_2026_05_09"],
    "memory_refs": [],
    "dropped_block_ids": [],
    "omissions": [],
    "budget": {
      "tokens_used_at_compile": 620,
      "tokens_used_by_bucket": { "evidence": 28 },
      "truncated_buckets": []
    },
    "compiled_context_hash": "sha256:..."
  }
}

Minimum bar:

Check	Failure if missing
`policy_manifest`	You cannot explain which policy shaped the run.
`tool_manifest`	The planner may hallucinate or overexpose tools.
Provenance-bearing blocks	You cannot distinguish control text from retrieved data or reproduce its source.
Admitted `evidence_manifest`	The final decision cannot prove which current, verified facts were eligible to support it.
`context_admission` and `evidence_gates`	Guardrails live only in prompt text, and missing evidence can appear complete.
`budget_report.omissions`	Context loss becomes invisible and can falsely appear as evidence coverage.
`context_ledger`	Replay cannot reconstruct the exact compiler decision.

Step 5: Bind the decision before the model acts

The Decision plane does not let the model “just answer.” It binds the run to a typed decision.

{
  "decision_key": "support.refund.execute",
  "version": "1.0.0",
  "required_evidence": ["identity_verified", "order_lookup", "policy.eval"],
  "allowed_outcomes": ["approved", "denied", "escalated"],
  "approval_mode": "destructive",
  "decision_right": "execute"
}

The Planner can propose this plan:

{
  "plan_id": "plan_refund_001",
  "intent": "support.refund",
  "steps": [
    { "id": "s1", "tool": "adp_orders.lookup", "params": { "order_id": "ord_881" }, "approval_mode": "read_only" },
    { "id": "s2", "tool": "adp_policy.eval", "depends_on": ["s1"], "approval_mode": "read_only" },
    {
      "id": "s3",
      "tool": "adp_payments.issue_refund",
      "depends_on": ["s2"],
      "approval_mode": "destructive",
      "requires": ["GATE_FINANCE_APPROVAL"]
    }
  ],
  "decision_checkpoints": [
    { "decision_id": "support.refund.execute", "after_step": "s2" }
  ]
}

The Critic must verify the plan before execution:

Critic check	Required answer
Is every tool in the `tool_manifest`?	yes
Does every tool argument satisfy schema and constraints?	yes
Does native risk and policy require the named approval gate?	yes
Before the protected checkpoint, is every required-evidence item satisfied by admitted, current, verified evidence or verified request context?	yes; initially `policy.eval` is unresolved, so collect it through the authorized read and recompile/revalidate the gate before `s3`
Are retrieval and memory blocks still `data_only`?	yes
Does the plan fit `run_budget`?	yes

Read next: Orchestration, Decision Catalog.

Step 6: Route effects through ToolEnvelope

Every external effect goes through the Action plane. This refund is proposed, approved because policy selected a gate, and then executed. It is never a direct model-to-API call.

Freeze the complete ActionBinding, including the exact nested arguments, actor/tenant, operation/proposal, evidence/policy/profile/release pins and INR amount in explicit minor units. Verify current eligible approvers, validity/quorum and separation rules; atomically redeem the stored approval for this operation. Immediately before dispatch, recheck current authority/revocation, observed boundary, actual data recipient/processor and aggregate budget reservation. A principal-chain name, auth reference or frozen evidence hash alone cannot establish these facts.

{
  "envelope_version": "contextos.tool_call.v1",
  "tool_call_id": "tc_refund_001",
  "run_id": "run_refund_001",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "session_id": "sess_support_42",
  "capability_id": "adp_payments.issue_refund",
  "args": {
    "order_id": "ord_881",
    "amount_inr": 4200,
    "currency": "INR",
    "idempotency_key": "ik_refund_ord_881_4200"
  },
  "principal_chain": [
    { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" },
    { "kind": "agent", "id": "agt_support", "tenant_id": "tenant_acme_prod" }
  ],
  "approval_mode_requested": "destructive",
  "approval_mode_effective": "destructive",
  "approval_mode_highest": "destructive",
  "action_risk_requested": {
    "effect": "external_state",
    "authority": "user_delegated",
    "reversibility": "compensatable",
    "interaction": "api",
    "data_scope": "CONFIDENTIAL",
    "decision_ttl_seconds": 120
  },
  "action_risk_effective": {
    "effect": "external_state",
    "authority": "human_approved",
    "reversibility": "compensatable",
    "interaction": "api",
    "data_scope": "CONFIDENTIAL",
    "decision_ttl_seconds": 120
  },
  "policy_decision_id": "pol_refund_001",
  "evidence_refs": [
    "kg:order:ord_881#snapshot_2026_05_09",
    "policy:POLICY_RETURNS_V4#R_HIGH_VALUE_REQUIRES_APPROVAL"
  ],
  "idempotency_key": "ik_refund_ord_881_4200",
  "auth_ref": "claim_hash:sha256:..."
}

Minimum bar:

Boundary	Why it matters
Native risk	Effect, authority, reversibility, interaction, data, and TTL are explicit before execution.
v1 compatibility	Required approval-mode fields remain conservative for existing consumers.
Approval gate	Current eligible authority approves the exact frozen action; the stored approval is validated and atomically redeemed.
Idempotency key	Retry safety depends on verified provider scope/retention/semantics; a key alone cannot guarantee deduplication.
Principal chain and auth ref	The call links human/agent authority without placing raw credentials in the envelope.
Trace identity	Tool behavior is connected to the original run; W3C headers travel in protocol telemetry.

Step 7: Emit the DecisionRecord

The MVP is not done until the run emits a durable DecisionRecord.

The receipt below assumes the policy evidence has now been admitted and the refund effect and business postconditions verified. DECIDED alone does not prove payment. Any triggered refusal or escalation blocks this successful path until explicitly handled. Keep exact action/approval/operation artifacts linked through the execution attachment; short hashes below remain display placeholders.

{
  "record_id": "dr_refund_001",
  "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_refund_001",
    "session": "sess_support_42",
    "context_pack": "ctxpack.support@1.0.0",
    "snapshot": "kg:snapshot_2026_05_09"
  },
  "outputs": {
    "outcome": "approved",
    "refund_amount_inr": 4200,
    "transaction_id": "txn_q9"
  },
  "evidence_refs": [
    "kg:order:ord_881#snapshot_2026_05_09",
    "tool:adp_orders.lookup:tc_order_001",
    "policy:POLICY_RETURNS_V4#R_HIGH_VALUE_REQUIRES_APPROVAL",
    "tool:adp_payments.issue_refund:tc_refund_001"
  ],
  "policy_decisions": [
    { "policy_decision_id": "pol_refund_001", "rule_ids": ["R_REFUND_REQUIRES_IDV", "R_HIGH_VALUE_REQUIRES_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": ["refund_without_identity"],
    "must_escalate": ["fraud_signal_high"],
    "approval_gates_active": ["GATE_FINANCE_APPROVAL"],
    "redaction_rules_active": ["pan", "credit_card"],
    "context_admission": {
      "data_only_block_ids": ["ev_order"],
      "untrusted_block_ids": [],
      "privileged_sink_policy": "verified_or_user_intent"
    },
    "evidence_gates": [
      {
        "decision_key": "support.refund.execute",
        "required": ["identity_verified", "order_lookup", "policy.eval"],
        "satisfied": ["identity_verified", "order_lookup", "policy.eval"],
        "unresolved": [],
        "rejected_evidence": [],
        "conflicts": [],
        "sufficiency": "sufficient",
        "commit_allowed": true
      }
    ]
  },
  "confidence": 0.95,
  "budget_usage": {
    "tokens": 4720,
    "tool_calls": 3,
    "cost_usd_cents": 0.91,
    "wall_clock_ms": 1840
  },
  "lineage": {
    "pack_version": "ctxpack.support@1.0.0",
    "snapshot_version": "kg:snapshot_2026_05_09",
    "policy_versions": ["POLICY_RETURNS_V4"],
    "decision_spec": "support.refund.execute@1.0.0"
  },
  "replay": {
    "replay_packet_id": "replay_refund_001",
    "compiled_context_hash": "sha256:...",
    "last_status": "not_run"
  },
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

The DecisionRecord should let an operator answer:

Operator question	Where to look
What did the agent decide?	`outputs`, `status`, `decision_key`
What did it rely on?	`evidence_refs`, `inputs_refs`
Which policy allowed it?	`policy_decisions`, `controls_active`
Who approved the risky action?	`approvals`
What did it cost?	`budget_usage`
How do we replay it?	`trace_id`, `replay.replay_packet_id`, and `lineage`

Step 8: Create the replay packet

Replay is what turns the MVP from a demo into a harness.

{
  "replay_packet_id": "replay_refund_001",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "session_id": "sess_support_42",
  "source_kind": "decision_record",
  "source_ref": "dr_refund_001",
  "context_pack_ref": "ctxpack.support@1.0.0",
  "run_context_ref": "run-context:run_refund_001",
  "knowledge_snapshot_ref": "kg:snapshot_2026_05_09",
  "compiled_context_hash": "sha256:...",
  "tool_transcript_chain_hash": "sha256:...",
  "side_effect_policy": "transcript_only",
  "expected": {
    "status": "DECIDED",
    "decision_record_hash": "sha256:...",
    "properties": [
      "no live tool call occurred",
      "required evidence was satisfied before the protected action",
      "recorded approval remained attached"
    ]
  },
  "latest_result": {
    "status": "not_run"
  }
}

Use replay for three things:

Use	What changes	What must stay pinned
Debug	Inspect the same run after an incident.	request, pack, snapshot, policy, tool transcripts
Regression	Test a new pack or policy version against known cases.	request and expected verdict
Improvement	Compare a proposed fix against the original failure.	evidence and evaluation criteria

MVP acceptance checklist

Do not call the workflow a ContextOS MVP until every row is true.

Check	Pass condition
Workflow scope	One named intent with clear allowed and disallowed outcomes.
Entity model	Core entities have stable IDs and evidence-producing lookups.
Context Pack	Pinned version contains intelligence refs, policy, tools, decision spec, memory rules, and eval targets.
RunContext	Run identity, tenant, user delegation, agent identity, safety mode, and budget are explicit.
Profile admission	Exact required profile/control revisions and actual feature requirements are supported without demotion.
Compiler output	`CompiledContext` includes provenance-bearing blocks, admitted manifests, context-admission controls, evidence gates, structured omissions, and ledger hash.
Decision binding	The run binds to one `DecisionSpec` before risky action.
Tool boundary	Every external effect passes through a `ToolEnvelope`.
Risk and approval	Capabilities carry native risk and a conservative v1 mode; policy selects any required gate.
Current dispatch	Trusted authority/revocation, exact stored approval, actual boundary/data route and reserved aggregate budget pass at the effect boundary.
Recovery	Lost acknowledgement, revoked authority, stop/cancel, stale worker and checkpoint cases preserve stable operations, uncertain effects and original limits.
Evidence	Useful and denied workflow cases have current deployment evidence; reference checks alone are insufficient for conformance.
Decision record	Final output is a typed `DecisionRecord`, not free-form text.
Replay	Request, pack, snapshot, policies, tool transcripts, and expected verdict are replayable.
Improvement	Failed or corrected runs become proposals, not silent prompt edits.

Common wrong starts

Wrong start	Better first move
”Let’s make the agent autonomous.”	Pick one workflow and one decision.
”Let’s write the perfect system prompt.”	Write the Context Pack and compiler output first.
”Let’s connect all tools.”	Connect only the governed capabilities needed for the first useful workflow.
”Let’s log everything and debug later.”	Emit `DecisionRecord` and replay packet on the first MVP.
”Let’s let the model decide when to escalate.”	Put escalation in policy and Critic verdicts.
”Let’s improve the prompt after every miss.”	Turn misses into replayed, reviewed improvement proposals.

MVP mental model

Pick one workflow

Step 1: Name the business entities

Step 2: Define the RunContext

Step 3: Write the minimal Context Pack

Step 4: Compile, do not prompt-stuff

Step 5: Bind the decision before the model acts

Step 6: Route effects through ToolEnvelope

Step 7: Emit the DecisionRecord

Step 8: Create the replay packet

MVP acceptance checklist

Common wrong starts

What to read next