Metadata-Version: 2.4
Name: algovoi-execution-ref
Version: 0.1.0
Summary: AlgoVoi execution_ref -- decision-bound execution evidence bound to the keystone. Proves an executed action is consistent with the decision that authorized it. Runs on any algovoi-substrate version (v0/v1); uses only JCS RFC 8785 canonicalisation.
Author-email: AlgoVoi <chopmob@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://api.algovoi.co.uk
Project-URL: Documentation, https://docs.algovoi.co.uk/execution-ref
Project-URL: Repository, https://github.com/chopmob-cloud/algovoi-execution-ref
Project-URL: Issues, https://github.com/chopmob-cloud/algovoi-execution-ref/issues
Keywords: x402,ap2,a2a,mpp,jcs,rfc8785,canonicalisation,agentic-payments,execution_ref,keystone,decision-bound,execution-evidence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: algovoi-substrate>=0.3.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Dynamic: license-file

# algovoi-execution-ref

Decision-bound execution evidence, bound to the keystone. A standalone, pinned,
Apache-2.0 app.

`execution_ref` proves an executed action is consistent with the decision that
authorized it, not merely correlated with an identity:

```
execution_ref = "sha256:" + SHA-256(JCS({decision_ref, action_type, scope, outcome, executed_at_ms}))
```

It binds the full keystone chain:

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

## Runs on any substrate version (v0 and v1)

This app uses only the substrate's JCS canonicalisation, which is byte-stable and
present in every release. It pins `algovoi-substrate>=0.3.0` and runs unchanged on
substrate v0 (0.x) and v1 (1.x). You get `execution_ref` and the keystone **without
upgrading your substrate**:

```
pip install algovoi-execution-ref     # installs next to whatever substrate you already have
```

## Use

```python
from algovoi_execution_ref import bind_keystone, verify_record, execution_ref

record = bind_keystone(
    passport_ref="sha256:...", mandate_ref="sha256:...", policy_bound_ref="sha256:...",
    verdict="ALLOW", action_type="payment", scope="bilateral",
    outcome="COMMITTED", executed_at_ms=1716460800000, trust_outcome="TRUSTED",
)
record["execution_ref"]    # decision-bound execution evidence
record["trust_query_ref"]  # content address: one verdict over the whole chain
verify_record(record)      # recomputes every ref from raw fields -> True
```

## CLI

```
echo '{"passport_ref":"sha256:...", ...}' | algovoi-execution-ref
algovoi-execution-ref --verify < record.json    # exit 0 if consistent, 1 if not
```

## Conformance and tiers

The composed chain reproduces the public corpus byte for byte
(`execution_ref_v1` and the `keystone_v1` composition). This is the open tier: it
binds and proves. Post-quantum signing and CCC-ingestable evidence chains are the
commercial Substrate 2 tier. `outcome` is the closed enum
`{COMMITTED, SKIPPED, FAILED, REVERSED}`; `executed_at_ms` is an integer
epoch-millisecond; no raw agent id appears in the preimage, so it carries no PII.
