> ## 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.
# Keystone Connectors
> Keystone connectors bind a real data layer operation, such as a database write or an HTTP request, to the keystone decision that authorised it.
A keystone decision answers *was this action authorised?* before it happens. A keystone
**connector** answers the question after: *did the action that actually touched the data match the
decision that allowed it?* Each connector binds one real data-layer operation to the
`decision_ref` that authorised it and emits an [`execution_ref`](/execution-ref): decision-bound,
content-addressed execution evidence that any party can recompute offline, with no issuer contact.
This closes a gap most audit trails leave open. A log says an operation happened. A connector
makes the operation **provably consistent** with the decision that permitted it: change the table,
the topic, the path, the outcome, or the decision it points to, and the `execution_ref` no longer
recomputes. Correlation becomes proof.
The connectors are open, keystone-only editions (Apache-2.0), built on the AlgoVoi substrate's
RFC 8785 JCS + SHA-256 discipline. They install from the **Keystone control panel** (the integrity
path: it pulls the validated wheels from the AlgoVoi index) and are **also published to PyPI** for
those who prefer plain `pip` -- both are compiled wheels, CPython 3.10 to 3.13; see below. The
signed, hash-linked chain of operations (PQC + CCC ingest) is the commercial tier.
## Where they fit
Connectors hang off the `execution_ref` stage of the keystone. One decision can authorise work
that lands across several data planes at once; every plane carries the same decision's fingerprint.
```
passport_ref -> mandate_ref -> policy_bound_ref -> decision_ref -> execution_ref -> trust_query_ref
^
a connector binds each real operation here
```
## The connectors
Wraps any DB-API 2.0 cursor (pyodbc, sqlite3, psycopg, and the wider ODBC family). Every executed
statement is bound to its decision, with the action type derived from the SQL verb
(insert / update / delete) and the table as scope. Use it when a write to a system of record must
be provably tied to the decision that allowed it.
[](/keystone)
One call registers a listener on a SQLAlchemy session; each flushed change (insert / update /
delete) is bound to the keystone with no model or query changes. Use it when persistence goes
through the dominant Python ORM and you want binding without touching application code.
[](/keystone)
Wraps any producer (kafka-python, confluent-kafka, aiokafka); each produced message carries an
`execution_ref` keyed to the topic, with failed sends recorded as such. Use it when an event on
the bus represents a decision being acted on and downstream consumers need to verify it.
[](/keystone)
Attaches a keystone run facet to each OpenLineage RunEvent, so the data-lineage standard's own
events carry the `execution_ref`; the outcome is derived from the event type. Use it when a data
job's lineage should also prove which decision authorised the run -- the keystone rides the
standard you already emit.
[](/keystone)
One middleware (FastAPI, Starlette, Flask, Django, and any ASGI/WSGI app) binds every
state-changing request to its decision, with the outcome derived from the response status. Use it
to make a whole service's write surface decision-bound from a single integration point, with no
framework lock-in.
[](/keystone)
A server interceptor binds each unary call to its decision, keyed to the full method, with the
outcome reflecting whether the handler completed or raised. Use it when service-to-service calls
over the RPC standard need to prove which decision authorised each invocation; streaming handlers
pass through unbound.
[](/keystone)
Wraps any boto3-style S3 client so each object write (put / delete / upload) carries an
`execution_ref` keyed to `bucket/key`, while reads pass through untouched. Use it when an object
landing in a bucket represents a decision being acted on -- a stored receipt, export, or artifact
that must be provably tied to its decision.
[](/keystone)
Wraps any redis-py client so each write command (set, delete, hset, expire, lpush, sadd, ...)
carries an `execution_ref` keyed to the key, while reads pass through untouched. Use it when a
cached or stateful value being written represents a decision being acted on -- a session, a quota,
a lock, a counter.
[](/keystone)
Wraps any pymongo collection so each write (insert, update, delete, replace, bulk) carries an
`execution_ref` keyed to the `db.collection` namespace, while reads pass through untouched. Use it
when a document landing in a collection must be provably tied to the decision that authorised it.
[](/keystone)
Wraps any pika-style channel so each publish carries an `execution_ref` keyed to
`exchange/routing_key`, while consumers and declarations pass through. Use it when a message on a
broker represents a decision being acted on and downstream consumers need to verify it -- the
classic broker counterpart to the Kafka connector.
[](/keystone)
Wraps any elasticsearch-py-style client so each write (index, create, update, delete, bulk)
carries an `execution_ref` keyed to `index/doc_id`, while reads pass through untouched. Use it when
a document indexed for search must be provably tied to the decision that produced it.
[](/keystone)
Wraps any nats-py connection so each publish carries an `execution_ref` keyed to the subject,
while subscribes and requests pass through. Use it when a message on a cloud-native bus represents
a decision being acted on; JetStream publishes wrap the same way.
[](/keystone)
Wraps any GCS blob so each object write (upload / delete) carries an `execution_ref` keyed to
`bucket/name`, while reads pass through untouched. The GCP counterpart to the S3 connector, for a
stored object that must be provably tied to its decision.
[](/keystone)
Wraps any azure-storage-blob container client so each object write (upload / delete) carries an
`execution_ref` keyed to `container/blob`, while reads pass through. The Azure counterpart to the S3
and GCS connectors.
[](/keystone)
Wraps any boto3 SQS client so each message send carries an `execution_ref` keyed to the queue, while
receives pass through. The AWS counterpart to the Kafka and Service Bus connectors.
[](/keystone)
Wraps any boto3 SNS client so each publish carries an `execution_ref` keyed to the topic, while reads
pass through. Pub/sub notifications, bound to the decision that raised them.
[](/keystone)
Wraps any azure-servicebus sender so each send carries an `execution_ref` keyed to the queue or
topic, while receivers pass through. The Azure messaging counterpart to Kafka, AMQP and NATS.
[](/keystone)
Wraps any Pub/Sub PublisherClient so each publish carries an `execution_ref` keyed to the topic,
while subscribes pass through. The GCP messaging counterpart.
[](/keystone)
Wraps any boto3 DynamoDB client so each write (put / update / delete / batch) carries an
`execution_ref` keyed to the table, while reads pass through. The cloud-NoSQL counterpart to the
MongoDB connector.
[](/keystone)
Wraps any httpx.Client or requests.Session so each outbound state-changing call
(POST / PUT / PATCH / DELETE) carries an `execution_ref` keyed to `host/path`, while reads pass
through. The outbound counterpart to the ASGI / WSGI middleware.
[](/keystone)
Wraps a Celery task or app so each dispatch (apply\_async / delay / send\_task) carries an
`execution_ref` keyed to the task name; a dispatch that raises is recorded FAILED.
[](/keystone)
Wraps any Pinecone Index so each vector write (upsert / delete / update) carries an `execution_ref`
keyed to `index/namespace`, while reads pass through. Binds an agent's memory writes to the decision
that authorised them.
[](/keystone)
Wraps any QdrantClient so each vector write (upsert / delete / payload) carries an `execution_ref`
keyed to the collection, while reads pass through. The agent-memory data plane, bound to its
decision.
[](/keystone)
## Verified end to end
The connectors are proven together, not just in isolation. A single decision is driven through all
the planes at once -- a database insert and update, a streamed event, a lineage run, an HTTP
write, a gRPC call, and an object write -- and an independent verifier then recomputes every
`execution_ref` from its recorded fields. The chain reconciles only when three things hold for
every operation:
* **Recompute** -- the recorded fields reproduce the exact `execution_ref` byte-for-byte.
* **Decision-bound** -- swap in a different `decision_ref` and every ref changes; the binding is
load-bearing, not decorative.
* **Tamper-evident** -- alter any field (table, topic, path, outcome) and the ref no longer
matches.
One decision, many operations across every data plane, one reconciling chain -- reproduced
byte-for-byte on a clean machine. That is the property a connector guarantees: the data layer
cannot drift from the decision that governs it without the evidence showing it.
## Validating the evidence
Connectors *emit* `execution_ref` records; `algovoi-keystone-validate` *checks a batch of them*.
Every connector record is **self-describing** -- it carries the `decision_ref` and a normalised
`scope` alongside the `execution_ref` -- so the output of any connector drops straight into the
validator with no mapping. It recomputes every `execution_ref` offline against the same primitive,
optionally asserts they all bind to the decision you expect, and logs what failed and why --
separating two failure classes an operator must never confuse:
* **Integrity error** -- the recorded fields do not recompute to the claimed `execution_ref`
(tampering or corruption); the evidence cannot be trusted.
* **Operational error** -- the `execution_ref` is valid, but records an operation whose outcome was
`FAILED`; a real, trustworthy record of a runtime failure.
```bash theme={null}
keystone-validate records.jsonl --log errors.jsonl --decision-ref sha256:...
# keystone-validate: 142 records | 140 ok | 0 integrity | 2 operational | 0 malformed | trustworthy=True
```
It exits non-zero on any integrity or malformed error (untrustworthy evidence), so it drops
straight into CI. The validator never trusts the claimed hash; it always recomputes.
## Installing a connector
There are two ways in, and they install the same compiled wheels (CPython 3.10 to 3.13, Linux
x86\_64/aarch64 or Windows AMD64). Prerequisites, control-panel setup, and `keystone doctor`
verification are on the [Keystone install hub](/keystone#install-and-run).
**From the Keystone control panel (the integrity path).** The panel installs each connector from the
AlgoVoi index. The index is baked into the installer, so you are provably running the validated build
rather than a mutable public artifact -- the point is supply-chain integrity of what you run. Open
the panel, pick the data planes you need, and each is installed and ready to wrap your client with no
code changes. The same builds install from the AlgoVoi index on the command line, and every
connector is available here, newest included:
```bash theme={null}
pip install --extra-index-url https://pip.algovoi.co.uk/simple/ algovoi-keystone-s3
```
**From PyPI (for those not using the panel).** The connectors are also published to PyPI:
```bash theme={null}
pip install algovoi-keystone-s3
```
New releases land on the AlgoVoi index first, then publish to PyPI, so a very recent connector may be
on the index ahead of PyPI; the index command above always resolves it. See
[Publishing a Keystone bolt-on](/publishing-bolt-ons) for the panel.
To write and self-certify a connector for a plane not listed here, use the
[build-a-bolt-on toolkit](/keystone-connect): a connector is about twelve lines, and the same
conformance battery proves it before you ship. New connectors (other databases, object stores, RPC,
message brokers, vector stores) are built to the same pattern on request.
Related: [The Keystone](/keystone) · [execution\_ref](/execution-ref) · [Build a bolt-on](/keystone-connect) · [Conformance vectors](/conformance-vectors)