> ## 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 -- a database write, a streamed event, a lineage run, an HTTP request -- to the keystone decision that authorised it, producing a content-addressed execution_ref any party can recompute offline. Open, keystone-only editions, available on request.
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 are **not published to a registry** -- they are made
available on request. Email [chopmob@gmail.com](mailto:chopmob@gmail.com) for the package and
integration notes. 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)
## 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.
## Requesting a connector
These editions are available on request rather than from a public registry. Tell us which data
plane you are binding ([chopmob@gmail.com](mailto:chopmob@gmail.com)) and we will share the package
and integration notes. New connectors (other databases, object stores, RPC, message brokers) are
built to the same pattern on request.
Related: [The Keystone](/keystone) · [execution\_ref](/execution-ref) · [Conformance vectors](/conformance-vectors)