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

# Build and test a Keystone bolt-on

> algovoi-keystone-connect is an open toolkit for Keystone bolt-ons: build a data layer connector in about twelve lines, and verify any bolt-on offline.

Bolting onto the Keystone should be small. `algovoi-keystone-connect` is an open (Apache-2.0)
toolkit with two halves: **build** a data-plane connector from a declarative spec, and **test** any
bolt-on at any stage of the chain, fully offline. Every reference reduces to one primitive,
`ref = "sha256:" + SHA-256(RFC 8785 JCS(payload))`, so there is no AlgoVoi software in your trust
base and nothing new to learn.

<Note>
  `algovoi-keystone-connect` is pure Python and readable on purpose: the whole binding is about thirty
  inspectable lines. It installs from the Keystone control panel (the integrity path, from the AlgoVoi
  index) and, like the connectors, is also available from PyPI for those not using the panel. Its
  output is byte-identical to the hand-written connectors, so records drop straight into
  `algovoi-keystone-validate`.
</Note>

## Install

```bash theme={null}
pip install algovoi-keystone-connect
```

CPython 3.10 to 3.13 on Linux (x86\_64 / aarch64) or Windows (AMD64). Prerequisites, the AlgoVoi-index
integrity path, control-panel setup, and `keystone doctor` verification are documented once on the
[Keystone install hub](/keystone#install-and-run).

## Build a connector

A connector binds each real write on a data plane to the `decision_ref` that authorised it. With the
toolkit that is a spec, not a class:

```python theme={null}
from algovoi_keystone_connect import connector

keystone_s3 = connector("s3", writes={
    "put_object":    ("put",    lambda call: f"{call.kwargs['Bucket']}/{call.kwargs['Key']}"),
    "delete_object": ("delete", lambda call: f"{call.kwargs['Bucket']}/{call.kwargs['Key']}"),
})

client = keystone_s3(boto3_s3, decision_ref=decision_ref)
client.put_object(Bucket="receipts", Key="2026/r1.json", Body=b"{}")   # bound
ref = client.execution_ref
```

That is a complete connector. `writes` maps each write method to `(action, scope_fn)`. The
`scope_fn(call)` receives a `Call(args, kwargs, client)`, so it reads `call.kwargs` or `call.args`
for per-call values and `call.client` for fixed context such as a container name or a queue entity.
Reads pass through unbound; a write that raises is recorded `FAILED` and re-raised. The emitted
`execution_ref` is byte-identical to the hand-written `algovoi-keystone-s3`, so the short way and the
long-hand way are provably the same.

## Test a bolt-on at any stage

You do not need a live gateway or real payments to know a bolt-on is correct. `synth_ref(stage)`
gives a content-addressed stand-in for whatever precedes your bolt-on, and the check battery verifies
the keystone properties.

<Tabs>
  <Tab title="Execution stage (a connector)">
    ```python theme={null}
    from algovoi_keystone_connect import check_connector

    report = check_connector(keystone_s3, FakeS3(), [
        ("put_object", {"Bucket": "receipts", "Key": "r1"}),
    ])
    assert report.ok
    print(report)
    ```
  </Tab>

  <Tab title="Any stage (a ref-builder)">
    ```python theme={null}
    from algovoi_keystone_connect import check_ref_builder, synth_ref, keystone_ref

    def mandate_ref(payload):
        return keystone_ref(payload)

    report = check_ref_builder(
        mandate_ref,
        {"passport_ref": synth_ref("passport"), "cap": "500USD", "scope": "payments"},
        prev_field="passport_ref",
    )
    assert report.ok
    ```
  </Tab>
</Tabs>

`check_ref_builder` works at any stage of the chain, passport through trust\_query, because every
stage is the same primitive over its own payload.

## The conformance battery

Both checks return a `Report` with an `ok` roll-up. Between them they assert:

| Property          | Meaning                                                                 |
| ----------------- | ----------------------------------------------------------------------- |
| Recompute         | the recorded fields reproduce the claimed `execution_ref` byte for byte |
| Decision-bound    | swap the `decision_ref` and every reference changes                     |
| Tamper-evident    | mutate the scope and the reference no longer recomputes                 |
| Self-describing   | each record carries the fields a verifier needs, with no mapping        |
| Predecessor-bound | a ref-builder binds to its upstream stage                               |

A connector that ignores its `decision_ref`, or a ref-builder that is not content-addressed, fails
`report.ok`. The harness never crashes on a broken bolt-on; it reports the failure.

## Package and publish

For internal use the `connector(...)` value is enough: wrap your client and go. To share a connector,
wrap it in a small module and publish it like any other Keystone bolt-on, per
[Publishing a Keystone bolt-on](/publishing-bolt-ons). Consumers get the same one-line ergonomics and
can self-certify with the same `check_connector` battery, so coverage of new data planes becomes the
ecosystem's job, not a bottleneck.

## One primitive

Everything above is one function:

```python theme={null}
from algovoi_keystone_connect import keystone_ref

keystone_ref(payload)   # "sha256:" + SHA-256(RFC 8785 JCS(payload))
```

Any party recomputes any reference with a stock RFC 8785 implementation and standard SHA-256, with no
AlgoVoi software involved. That is what lets a developer build on the Keystone without adopting it
into their trust base. See the [connector catalogue](/keystone-connectors) and the
[Keystone chain](/keystone).