Skip to main content
A decision receipt is the structured contract VerifiedX returns for every protected boundary check. It is not just a yes or no. It tells your system:
  • what outcome VerifiedX reached
  • whether the side effect is safe to execute
  • how the workflow should continue
  • where a replan should happen
  • what would have to change before retrying
Receipts are designed so your agent or orchestrator can keep working toward the same goal state safely instead of guessing what to do next.

​
What a receipt contains

FieldDescription
receipt_typeAlways verifiedx_decision_receipt
decision_idStable identifier for this decision
outcomeOne of allow, allow_with_warning, replan_required, or goal_fail_terminal
action_classThe protected class involved, such as memory_write, record_mutation, system_change, or external_message_send
safe_to_executeWhether the requested boundary is allowed to execute now
reasonsStructured reasons for the decision
safe_next_stepsSafe next steps the system can take without pretending the blocked effect happened
viewer_guidanceExtra guidance for reviewer or operator-facing views
what_would_change_thisWhat new evidence, approvals, or context would change the decision
dispositionHow the workflow should continue
routingWhere the result should go next: downstream, local, upstream, human, or stop
resume_contractWhether to retry this node, pass the receipt upstream, and what must change before retry
runtime_loopbackRuntime loopback details when the boundary should not or did not complete
metadataOptional adapter or runtime metadata

​
Disposition modes

The most important part of the receipt is usually disposition.mode.
ModeWhat it means
continue_downstreamThe boundary is allowed and the workflow can continue normally
local_replanThe current node should keep working locally toward the same goal without executing the denied effect
upstream_replanThe current node should stop local work and return the receipt upstream so missing support or approvals can be gathered
human_reviewThe workflow should pause for human review
terminal_blockThe current path is terminally blocked

​
Example receipt

This is a representative replan_required receipt for a composed workflow that needs upstream recovery: 
{
  "receipt_type": "verifiedx_decision_receipt",
  "decision_id": "dec_composed_replan_1",
  "outcome": "replan_required",
  "action_class": "system_change",
  "safe_to_execute": false,
  "human_review_terminal": false,
  "must_not_retry_same_action": false,
  "reasons": [
    {
      "code": "missing_upstream_support",
      "message": "The workflow update is missing required upstream approval."
    }
  ],
  "safe_next_steps": [
    {
      "code": "GET_LEGAL_REVIEW",
      "message": "Obtain legal review approval for WF-2302."
    }
  ],
  "viewer_guidance": [],
  "what_would_change_this": [
    "A legal review event confirming WF-2302 is approved_with_follow_up."
  ],
  "disposition": {
    "mode": "upstream_replan",
    "downstream_allowed": false,
    "local_replan_recommended": false,
    "upstream_replan_required": true
  },
  "routing": {
    "direction": "upstream",
    "target_hint": "workflow_supervisor",
    "return_to_node": "workflow_supervisor",
    "workflow_id": "REQ-2302",
    "node_id": "handoff_note_node"
  },
  "resume_contract": {
    "retry_this_node": true,
    "pass_receipt_upstream": true,
    "pass_new_upstream_context_on_retry": true,
    "resume_when": [
      "A legal review event confirming WF-2302 is approved_with_follow_up."
    ]
  },
  "runtime_loopback": {
    "same_goal_state": true
  },
  "metadata": {}
}

​
How to use receipts

Receipts are synchronous outputs of the protected-boundary flow. Your system should branch on the receipt, not guess from prose. Typical handling looks like this:
  • continue_downstream
    • The boundary is allowed.
    • The side effect may execute.
    • The workflow can continue normally.
  • local_replan
    • Do not execute the denied side effect.
    • Keep the receipt local.
    • Replan inside the same node or agent using reasons, safe_next_steps, and what_would_change_this.
  • upstream_replan
    • Do not keep pushing locally.
    • Return the receipt upstream.
    • Let the parent orchestrator or supervisor gather the missing evidence, approval, or context before retrying this node.
  • human_review
    • Surface the receipt to a reviewer.
    • Use viewer_guidance, reasons, and resume_contract to drive the review step.
  • terminal_block
    • Do not claim success.
    • Fail truthfully.
    • Hand off to a human or upstream workflow if appropriate.

​
Receipts and loopback results

When a protected boundary is blocked at runtime, VerifiedX usually returns a structured blocked tool result as well as the receipt. That blocked result typically includes:
  • ok: false
  • blocked: true
  • boundary_outcome
  • safe_next_steps
  • decision_receipt
So the receipt is the routing contract, and the loopback result is the runtime-friendly payload your agent can act on immediately.

​
Key idea

A receipt is not just an audit artifact. It is the machine-readable contract that lets your system continue safely:
  • downstream when execution is allowed
  • locally when replanning should stay on the current node
  • upstream when the blocker must be resolved by a parent stage
  • truthfully when the workflow has to pause or stop