> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifiedx.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Receipts

> The decision receipt returned by every protected boundary check.

A decision receipt is the structured contract VerifiedX returns for every protected boundary check.

Your system should usually branch on:

* `outcome`
* `safe_to_execute`
* `disposition.mode`

For deeper explanation, see [Decision Receipts](/concepts/decision-receipts).

## Fields

<ResponseField name="receipt_type" type="string" required>
  Always `verifiedx_decision_receipt`.
</ResponseField>

<ResponseField name="decision_id" type="string" required>
  Stable identifier for the decision.
</ResponseField>

<ResponseField name="outcome" type="string" required>
  One of:

  * `allow`
  * `allow_with_warning`
  * `replan_required`
  * `goal_fail_terminal`
</ResponseField>

<ResponseField name="action_class" type="string">
  The protected class involved, such as `memory_write`, `record_mutation`, `system_change`, or `external_message_send`.
</ResponseField>

<ResponseField name="safe_to_execute" type="boolean" required>
  Whether the requested boundary is safe to execute now.
</ResponseField>

<ResponseField name="human_review_terminal" type="boolean" required>
  Indicates whether this path should terminate into human review.
</ResponseField>

<ResponseField name="must_not_retry_same_action" type="boolean" required>
  Indicates whether the same blocked action should not be retried unchanged.
</ResponseField>

<ResponseField name="reasons" type="array" required>
  Structured reasons for the decision.
</ResponseField>

<ResponseField name="safe_next_steps" type="array" required>
  Safe next steps the workflow can take without pretending the blocked effect happened.
</ResponseField>

<ResponseField name="viewer_guidance" type="array" required>
  Extra guidance for reviewer-facing or operator-facing views.
</ResponseField>

<ResponseField name="what_would_change_this" type="array" required>
  Evidence, approvals, or context that would change the decision.
</ResponseField>

<ResponseField name="disposition" type="object" required>
  How the workflow should continue.

  <Expandable title="properties">
    <ResponseField name="mode" type="string" required>
      One of:

      * `continue_downstream`
      * `local_replan`
      * `upstream_replan`
      * `human_review`
      * `terminal_block`
    </ResponseField>

    <ResponseField name="downstream_allowed" type="boolean" required>
      Whether the workflow can continue downstream normally.
    </ResponseField>

    <ResponseField name="local_replan_recommended" type="boolean" required>
      Whether the current node should keep working locally toward the same goal.
    </ResponseField>

    <ResponseField name="upstream_replan_required" type="boolean" required>
      Whether the receipt should be routed upstream before retrying this node.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="routing" type="object" required>
  Routing hints for the next stage of the workflow.

  <Expandable title="properties">
    <ResponseField name="direction" type="string" required>
      High-level routing direction such as `downstream`, `local`, `upstream`, `human`, or `stop`.
    </ResponseField>

    <ResponseField name="target_hint" type="string">
      Optional hint for the next node, reviewer, or upstream stage.
    </ResponseField>

    <ResponseField name="return_to_node" type="string">
      Optional node identifier to resume or return to.
    </ResponseField>

    <ResponseField name="workflow_id" type="string">
      Optional workflow identifier when the decision is part of a larger workflow.
    </ResponseField>

    <ResponseField name="node_id" type="string">
      Optional current node identifier.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="resume_contract" type="object" required>
  Resume and retry semantics for the blocked or warned boundary.

  <Expandable title="properties">
    <ResponseField name="retry_this_node" type="boolean" required>
      Whether this node should be retried later.
    </ResponseField>

    <ResponseField name="pass_receipt_upstream" type="boolean" required>
      Whether the receipt should be passed upstream.
    </ResponseField>

    <ResponseField name="pass_new_upstream_context_on_retry" type="boolean" required>
      Whether new upstream context is expected before retry.
    </ResponseField>

    <ResponseField name="resume_when" type="array" required>
      Conditions or evidence that should be true before retry.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="runtime_loopback" type="object">
  Runtime loopback information when the workflow should replan locally or upstream.
</ResponseField>

<ResponseField name="metadata" type="object">
  Optional runtime or adapter metadata attached by the SDK.
</ResponseField>

## Example receipt

```json theme={null}
{
  "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": {}
}
```

## Outcome values

| Outcome              | Meaning                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `allow`              | The boundary can execute normally.                                                                                  |
| `allow_with_warning` | The boundary can execute, but the receipt still carries warnings and guidance.                                      |
| `replan_required`    | This exact side effect should not happen now. The workflow should continue through a safer or better-grounded path. |
| `goal_fail_terminal` | The requested path is terminally blocked for the current goal state.                                                |

<Note>
  When a blocked boundary is returned through a runtime or native adapter, the tool result usually also includes the same `decision_receipt` so the agent can replan immediately.
</Note>