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

# Spend Guardrail (lite)

> Content addressed pre-payment decisions for the AlgoVoi substrate: bind a categorical ALLOW or DENY to the agent, the spend authority and the policy.

[![Keystone Enabled](https://img.shields.io/badge/Keystone-enabled-5cb9f8)](/keystone)

A pre-payment **ALLOW** or **DENY** on its own does not record **which agent** it was made for, **which spend authority** it was checked against, or **under which policy** it was decided. If any of those changes underneath it, an old decision gives no signal.

**Spend Guardrail (lite)** closes that gap. It is the one call an agent platform makes *before* executing a payment: it binds a categorical decision to the agent it was made for (`agent_ref`), the spend authority it was checked against (`mandate_ref`), and the policy in force (`policy_bound_ref`) — each imported by hash — into a deterministic, recomputable `guardrail_ref`. The whole pre-payment decision becomes one content address. **It moves no funds.**

Because the decision is bound to all three inputs by hash, an ALLOW made under one policy snapshot **does not recompute under a rotated policy** — and swapping the agent, the mandate, or the verdict diverges the `guardrail_ref`. It is **strictly additive over the frozen Layer 1**: no new cryptographic primitive, the same RFC 8785 JCS + SHA-256 already in use.

<Info>
  **Apache-2.0 open source.** Install via `pip install algovoi-spend-guardrail-lite`. Python and TypeScript are byte-for-byte identical on the same input. This is the **lite** tier — content-addressed, no signature; the commercial [Spend Guardrail](/spend-guardrail) adds Falcon-1024 post-quantum signing on the decision receipt and the full [Agent Passport](/agent-passport) + Payment Mandate enforcement stack.
</Info>

## How it works

One reference, computed with RFC 8785 JCS canonicalisation and SHA-256:

```
guardrail_ref = "sha256:" + SHA-256(JCS({ agent_ref, mandate_ref, policy_bound_ref, verdict }))
```

* **`agent_ref`** is the agent the decision was made for — a passport reference, imported by hash.
* **`mandate_ref`** is the spend authority it was checked against — a mandate reference, imported by hash.
* **`policy_bound_ref`** is the policy snapshot in force, from [Policy Binding](/policy-binding) — imported by hash.
* **`verdict`** is a closed enumeration: `ALLOW`, `DENY`. A value outside the set is rejected, not hashed.

## What a verifier can check

| Verifier holds                               | What they can check                                                                                  |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| A `guardrail_ref` + verdict + the three refs | That the decision was made for exactly this agent, authority and policy (`guardrail_ref` recomputes) |
| The same, with the policy under a rotation   | Rotation is detected — the `guardrail_ref` fails to recompute under `P'`                             |
| The same, with a different agent or mandate  | Agent / authority swap is detected — each input is byte-load-bearing                                 |
| A `guardrail_ref` + a different verdict      | Verdict tamper is detected — `ALLOW` and `DENY` are byte-distinct                                    |

No issuer call. No registry lookup. No AlgoVoi service. RFC 8785 JCS, SHA-256, and a JSON parser are the entire dependency. The binding **enables** rejection; acting on a mismatch is a runtime verifier decision, not a property of the construction.

## Use

```python theme={null}
from algovoi_spend_guardrail_lite import guardrail_ref, verify

# each input is imported by hash: a passport_ref, a mandate_ref, and a policy_bound_ref
agent   = "sha256:b3594e33…"
mandate = "sha256:a4f8cb5e…"
policy  = "sha256:aaee2091…"

ref = guardrail_ref("ALLOW", agent, mandate, policy)   # bind the decision
verify(ref, "ALLOW", agent, mandate, policy)           # True
verify(ref, "DENY",  agent, mandate, policy)           # False — verdict tamper
```

```ts theme={null}
import { guardrailRef, verify } from '@algovoi/spend-guardrail-lite';

const ref = guardrailRef('ALLOW', agent, mandate, policy);
verify(ref, 'ALLOW', agent, mandate, policy);          // true
```

## Conformance

The `spend_guardrail_lite_v1` vector set (10 vectors) is published in the public corpus —
[chopmob-cloud/algovoi-jcs-conformance-vectors](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors) —
with Python and Node runners. It covers the two verdicts, verdict / policy-rotation / agent / mandate tamper, and the closed-enumeration and malformed-reference rejections. Python and TypeScript reproduce every value byte-for-byte.

## The decision chain

Spend Guardrail (lite) is the keystone of an open, pinned pre-payment decision chain: it composes the agent (an [Agent Passport](/agent-passport) reference), the spend authority (a mandate reference), and the policy in force (a [Policy Binding](/policy-binding) reference) into one recomputable decision. Each input is imported by hash, so an L2 integrator can plug in their own agent, mandate, or policy source and still get a single, offline-verifiable decision address.

## Lite vs commercial

|                  | Lite (this package)               | [Spend Guardrail](/spend-guardrail) (commercial)               |
| ---------------- | --------------------------------- | -------------------------------------------------------------- |
| Licence          | Apache-2.0, open                  | Commercial OEM                                                 |
| Decision binding | content-addressed `guardrail_ref` | the same, **Falcon-1024 signed receipt**                       |
| Enforcement      | bring your own verdict            | full [Agent Passport](/agent-passport) + Payment Mandate stack |
| Verifier         | recompute offline                 | maintained verifier                                            |
| Best for         | open integrations, evaluation     | regulated production, enterprise terms                         |

## Adopters

If you build on `algovoi-spend-guardrail-lite`, pin `==0.1.0`, anchor a canonical vector hash from `spend_guardrail_lite_v1`, and keep the `NOTICE`, you qualify for a free **v0 licence key** for `algovoi-mandate-auditor`. The gate is `scripts/check_v0_adoption.py` (dependency + canonical hash anchor + NOTICE + version pin → ISSUE\_V0\_KEY). Apply: email [chopmob@gmail.com](mailto:chopmob@gmail.com).

## Relationship to the open substrate

Spend Guardrail (lite) sits directly on top of the open [JCS Canonicalisation Substrate](/canonicalisation-substrate) and composes with [Policy Binding](/policy-binding), [Compliance Gate (lite)](/compliance-gate-lite), and the [Retention Chain](/retention-chain-substrate). It uses the same RFC 8785 JCS and SHA-256 primitives — no additional cryptographic dependencies.

## Specification

`guardrail_ref` is an instance of the binding-ref framework specified in IETF Internet-Draft [`draft-hopley-x402-retention-chain`](https://datatracker.ietf.org/doc/draft-hopley-x402-retention-chain/) — the same content-addressed construction as Settlement-Action Binding (§7.6), Policy Binding (§7.7), and Compliance Gate Binding (§7.8): a closed-enum decision bound to a set of pinned references under RFC 8785 JCS + SHA-256. The normative byte-level artifact for this construction is the published [`spend_guardrail_lite_v1`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/spend_guardrail_lite_v1) conformance set. Additive over the frozen canonicalisation substrate, sole AlgoVoi authorship.