> ## 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.

# execution_ref

> Decision bound execution evidence over the AlgoVoi substrate: binds an executed agent action to the exact decision that authorised it. RFC 8785, SHA-256.

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

`execution_ref` is the post-decision tier of the AlgoVoi keystone. Identity proves
*who* an agent is; a `decision_ref` proves an action was *authorized*. `execution_ref`
closes the remaining gap: it proves *what the agent did* and binds that execution back
to the exact decision that authorized it, so a verifier can confirm the executed action
is consistent with the decision, not merely correlated with an identity.

```
execution_ref = "sha256:" + SHA-256(JCS({
  "decision_ref":   "<the keystone decision that authorized this execution>",
  "action_type":    "<what was executed>",
  "scope":          "<the scope it executed under>",
  "outcome":        "COMMITTED | SKIPPED | FAILED | REVERSED",
  "executed_at_ms": <integer milliseconds>
}))
```

The preimage is serialised using [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785),
and `executed_at_ms` is an epoch-millisecond **integer hashed directly**, so the hash
reproduces byte-for-byte across any language without a string-conversion step.

## Why it is a distinct primitive

`decision_ref` is a load-bearing field of the preimage. That is what makes
`execution_ref` a new primitive rather than a bare action hash: change the authorizing
decision and the `execution_ref` diverges. An execution recorded under one decision
cannot be re-attributed to another. No raw `agent_id` appears in the preimage (it is
already bound inside `decision_ref`), so `execution_ref` is no PII by construction.

`outcome` is a closed enum: `COMMITTED` is the single committing result, `SKIPPED` is
the exactly-once dedupe result, `FAILED` and `REVERSED` are terminal non-committing
states.

## The keystone flow

`execution_ref` completes one recomputable chain from identity to execution:

```
passport_ref  ->  mandate_ref  ->  policy_bound_ref  ->  decision_ref  ->  execution_ref  ->  trust_query_ref
 (identity)       (authority)      (policy)             (decision)        (execution)        (one verdict)
```

Each reference is content-addressed; recompute any input field and that reference and
everything downstream of it diverges. `trust_query_ref` can assess the full ordered
chain, so one verdict spans identity through execution. The end-to-end composition is
proven byte-for-byte in the conformance corpus (`keystone_v1` composition and the
`execution_ref_v1` set).

## Library

```
pip install "algovoi-substrate>=1.0.0"
npm  install @algovoi/substrate@^1.0.0
```

```python theme={null}
from algovoi_substrate import execution_ref

ref = execution_ref(
    decision_ref="sha256:2a444c629892f44fde1bd004aba9be01dd6cc7fe251eecdd545b82dca9f0bf97",
    action_type="payment",
    scope="bilateral",
    outcome="COMMITTED",
    executed_at_ms=1716460800000,
)
```

Python and TypeScript produce byte-identical output. To compose the entire chain
in one call, see [`build_keystone`](/keystone).

## Relationship to action\_ref

`execution_ref` does not replace [`action_ref`](/action-ref-verifier) field for field
(the shapes differ on purpose). `action_ref` remains available and unchanged for existing
adopters; `execution_ref` is the decision-bound evidence primitive the keystone leads
with. The two coexist, so you can upgrade to the latest substrate and continue as normal,
or adopt `execution_ref` when you are ready by binding your executed action to the
`decision_ref` that authorized it.

## See also

* [Spend decision chain](/spend-decision-chain): the decision tier `execution_ref` binds to
* [Conformance vectors](/conformance-vectors): the `execution_ref_v1` set and `keystone_v1` composition
* [Canonicalisation substrate](/canonicalisation-substrate): the JCS discipline underneath