Keystone Connectors

​

Where they fit

passport_ref -> mandate_ref -> policy_bound_ref -> decision_ref -> execution_ref -> trust_query_ref
                                                                        ^
                                                    a connector binds each real operation here

​

The connectors

Relational databases (ODBC / DB-API)

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.

SQLAlchemy ORM

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.

Apache Kafka

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.

OpenLineage

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.

HTTP services (ASGI / WSGI)

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.

gRPC services

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.

Object storage (S3 / boto3)

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.

Redis

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.

MongoDB (pymongo)

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.

AMQP / RabbitMQ

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.

Elasticsearch

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.

NATS

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.

Google Cloud Storage

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.

​

Verified end to end

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

​

Validating the evidence

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

keystone-validate records.jsonl --log errors.jsonl --decision-ref sha256:...
# keystone-validate: 142 records | 140 ok | 0 integrity | 2 operational | 0 malformed | trustworthy=True

​

Requesting a connector