Metadata-Version: 2.4
Name: semantic-kernel-mycelium-ref-verify
Version: 0.1.0
Summary: Semantic Kernel plugin for action_ref / decision_binding_ref — content-addressed action and authorization refs
Author: giskard09
License: Apache-2.0
Project-URL: Homepage, https://argentum.rgiskard.xyz
Project-URL: Repository, https://github.com/giskard09/semantic-kernel-mycelium-ref-verify
Project-URL: Spec, https://github.com/giskard09/argentum-core/blob/main/docs/spec/decision-binding-ref-v1.0.md
Keywords: semantic-kernel,mycelium,action-ref,decision-binding-ref,verification,ai-agents
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: semantic-kernel>=1.0.0
Dynamic: license-file

# semantic-kernel-mycelium-ref-verify

Semantic Kernel plugin for `action_ref` and `decision_binding_ref` — the
content-addressed identifiers from the [argentum-core](https://github.com/giskard09/argentum-core)
spec family. `action_ref` identifies an agent action instance; `decision_binding_ref`
binds it to the authorization decision that permitted it. Both are
`SHA-256(JCS(preimage))` — deterministic, independently recomputable by any
third party, no trust in the emitting system required.

Same underlying logic as [`mycelium-ref-verify`](https://github.com/giskard09/mycelium-ref-verify)
(Agent Skill) and [`crewai-decision-binding-ref`](https://github.com/giskard09/crewai-decision-binding-ref)
(CrewAI Tool) — `action_ref.py` and `decision_binding_ref.py` here are the
same stdlib-only modules, wrapped as `@kernel_function`-decorated methods
instead of a `BaseTool`.

Specs:
[action-ref.md](https://github.com/giskard09/argentum-core/blob/main/docs/spec/action-ref.md) ·
[decision-binding-ref-v1.0.md](https://github.com/giskard09/argentum-core/blob/main/docs/spec/decision-binding-ref-v1.0.md)

## Install

```bash
pip install semantic-kernel-mycelium-ref-verify
```

## Usage

```python
from semantic_kernel import Kernel
from semantic_kernel_mycelium_ref_verify import MyceliumRefPlugin

kernel = Kernel()
kernel.add_plugin(MyceliumRefPlugin(), plugin_name="mycelium_ref")

fn = kernel.get_function("mycelium_ref", "compute_decision_binding_ref")
result = await kernel.invoke(
    fn,
    action_ref="sha256:...",
    decision_id="approval:...",
    decision_at_ms=1748736000000,
)
```

Four kernel functions are exposed:

| Function | Purpose |
|---|---|
| `compute_action_ref` | Derive `action_ref` from `agent_id`/`action_type`/`scope`/`timestamp`. |
| `verify_action_ref` | Recompute and, if `presented_ref` given, compare. |
| `compute_decision_binding_ref` | Derive `decision_binding_ref` from its preimage. |
| `verify_decision_binding_ref` | Recompute and, if `presented_ref` given, compare. |

## The four verify states

Both `verify_*` functions report one of four states, deliberately kept
separate from the `trail_status` ladder (`COMMITTED`/`PENDING`/`FAILED`)
used elsewhere in Mycelium for execution-outcome tracking. That ladder
answers a temporal question — did the post-execution receipt arrive? This
plugin answers a cryptographic one — does this hash match? `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 `decision_binding_ref` 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 — 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

Apache-2.0
