Metadata-Version: 2.4
Name: crewai-decision-binding-ref
Version: 0.1.0
Summary: CrewAI tool for decision_binding_ref — content-addressed binding between an action and the decision that authorized it
Author: giskard09
License: MIT
Project-URL: Homepage, https://argentum.rgiskard.xyz
Project-URL: Repository, https://github.com/giskard09/crewai-decision-binding-ref
Project-URL: Spec, https://github.com/giskard09/argentum-core/blob/main/docs/spec/decision-binding-ref-v1.0.md
Keywords: crewai,mycelium,decision-binding-ref,verification,ai-agents
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: crewai>=0.50.0

# crewai-decision-binding-ref

CrewAI tool for `decision_binding_ref` — a content-addressed identifier for
the binding between a specific action instance and the authorization
decision that permitted it. Any verifier holding the preimage fields can
independently confirm that this exact instance was authorized, without
trusting the system that executed it.

Spec: [decision-binding-ref-v1.0.md](https://github.com/giskard09/argentum-core/blob/main/docs/spec/decision-binding-ref-v1.0.md)
(stable, extended 2026-08-04 with optional `context_digest`).

## Install

```bash
pip install crewai-decision-binding-ref
```

## Usage

```python
from crewai_decision_binding_ref import DecisionBindingRefTool

tool = DecisionBindingRefTool()

# compute mode — no presented_ref
result = tool.run(
    action_ref="sha256:...",
    decision_id="approval:...",
    decision_at_ms=1748736000000,
)
# {"state": "PENDING_NON_NULL", "computed_ref": "sha256:..."}

# verify mode — presented_ref given
result = tool.run(
    action_ref="sha256:...",
    decision_id="approval:...",
    decision_at_ms=1748736000000,
    presented_ref="sha256:...",
)
# {"state": "COMMITTED", "computed_ref": "sha256:..."} or {"state": "MISMATCH", ...}
```

## The four verify() states

`verify()` reports one of four states, deliberately kept separate from the
`trail_status` ladder (`COMMITTED`/`PENDING`/`FAILED`) used elsewhere in
Mycelium for execution-outcome tracking
([guarantee-model.md](https://github.com/giskard09/argentum-core/blob/main/docs/spec/guarantee-model.md#trail-status-states)).
That ladder answers a temporal question — did the post-execution receipt
arrive? This tool answers a cryptographic one — does this hash match? The two
axes are orthogonal; this tool's `verify()` never returns `FAILED`.

| State | Meaning |
|---|---|
| `COMMITTED` | Recompute succeeded and matches the presented ref. |
| `MISMATCH` | Recompute succeeded but does **not** match the presented ref. Fail-closed — same pattern as `CONTEXT_SET_MISMATCH` in the spec's `context_digest` extension. Never silent. |
| `PENDING_NON_NULL` | Preimage complete, ref computed, no presented ref given yet (compute-only mode). |
| `PENDING_NULL` | Preimage incomplete (`action_ref` or `decision_id` missing) — recompute cannot be attempted. |

## Tests

Conformance tests reuse the byte-verified fixtures already published in
`argentum-core`, no new vectors invented:

- Fixtures A–D from `decision-binding-ref-v1.0.md`
- Vectors `cd-001`..`cd-004` from
  [`examples/conformance/decision-binding-context-digest-v1/`](https://github.com/giskard09/argentum-core/tree/main/examples/conformance/decision-binding-context-digest-v1)

```bash
pip install -e .
pytest
```

## License

MIT
