Complete Example

End-to-end example

entry = ledger.claim_next(status="NEW")
entry.mark("GUARDING")
context = derive_refund_risk(entry)
decision = haltstate.guard(
    action="refund.create",
    agent_id="retail-refund-agent",
    idempotency_key=f"refund:{entry.id}",
    context=context,
)

if decision.allowed:
    entry.mark("ALLOWED")
    ledger.write_execution_once(entry)
    proof = proof_packs.create(entry, decision)
    haltstate.report(decision, status="success", proof_id=proof.id)
    entry.mark("EXECUTED")
elif decision.requires_approval:
    entry.mark("APPROVAL_REQUIRED")
elif decision.denied:
    entry.mark("DENIED")
else:
    entry.mark("ERROR")

Invariants

• Every guarded action has a stable idempotency key.
• No denied action executes.
• No pending approval executes.
• No engine-failure path executes high-risk actions.
• Every execution has a post-action report.
• Public events are sanitized before publication.

Tests to keep

Test stable idempotency keys, duplicate execution prevention, denied execution blocking, approval-required pauses, fail-closed engine behavior, redaction allow-lists, Proof Pack creation, and post-action reports. These tests matter more than broad snapshot tests because they verify the safety invariants that keep the agent inside policy.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.