# Approval consumption API

Status: implemented under Gate House decision `GH-DEC-2026-003`.

The normative protocol is
`gate-house/docs/contracts/approval-consumption.md`. This document records the
approval-engine implementation surface; it does not redefine the protocol.

## Endpoint

```text
POST /v1/approvals/{id}/consume
```

```json
{
  "request_digest": "sha256:<64 lowercase hex>",
  "decision_id": "decision:optional-provenance"
}
```

The caller is the PEP that is about to perform the protected side effect. It
calls consume after an ALLOW and before that side effect. `request_digest` is
the canonical digest from the PDP decision binding, not a newly serialized
request and not approval-engine's native binding digest.

## Results

- First valid consume: atomically stores the digest, changes `approved` to
  `consumed`, and inserts one `approval.use` outbox row in the same transaction.
- Same digest after consumption: `200` idempotent success and no second outbox
  row.
- Different digest after consumption: `409 conflict`; the PEP must not act.
- Revoked, superseded, expired, outside-window, requested, or unknown object:
  conflict or not-found; the PEP must not act.
- Outbox insert/store failure: `503`; the transaction rolls back and the PEP
  must not act.

There is no unconsume, release, or reserve. If the protected side effect fails
after consumption, the approval remains spent and a retry needs a new approval.

The response is mutation evidence, not a permission decision. It contains no
`effect`, `allow`, `deny`, or decision result.