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

# Runtime and journal

> algovoi-keystone-runtime runs a Keystone chain and persists every emitted reference to a queryable, tamper evident SQLite journal that recomputes offline.

The connector layer emits an `execution_ref` for every write and the behaviour layer emits a
`behaviour_ref` for every decision, but something has to run the chain and keep those references.
`algovoi-keystone-runtime` is that piece: it assembles stages, connectors and behaviours into one
pipeline, gates each write through the behaviour layer, and journals everything it emits. Every entry
recomputes offline from its own fields, and the journal itself is a hash chain over those references,
so nothing can be inserted, removed or reordered without detection. Apache-2.0.

<Note>
  This is the open journal. The commercial [audit-chain](/compliance-command-center) is the same shape
  with durable, post-quantum signed, append-only storage. You develop against the open journal and
  upgrade the storage without changing your code.
</Note>

## Install

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

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

## Run a chain, keep the record

```python theme={null}
from algovoi_keystone_runtime import Journal, Runtime
from algovoi_keystone_agent.library import cap_charges, deny_writes_to

rt = Runtime(Journal("keystone.db"), decision_ref=decision_ref)

passport_ref = rt.record_stage("passport", {"agent": "agent-7", "issuer": "acme"})
rt.record_stage("mandate", {"passport_ref": passport_ref, "cap": "500USD"})

s3 = rt.bind(keystone_s3_client, behaviours=[cap_charges(500), deny_writes_to("Bucket", ["locked"])])
s3.put_object(Bucket="receipts", Key="r1.json", Body=b"{}")   # gated + journaled
s3.put_object(Bucket="locked",   Key="x.json",  Body=b"{}")   # denied before commit, block recorded
```

`bind` returns a client that gates each write through the behaviours and records both the
`behaviour_ref` (every firing) and the `execution_ref` (every committed write). A denied write never
reaches the data plane, and the block is recorded. Reads pass through and journal nothing.
`record_stage` journals the upstream stages of the chain.

## Query, verify, replay

```python theme={null}
rt.journal.chain(decision_ref)     # every record under a decision, in order
rt.journal.by_kind("execution")    # filter by execution / behaviour / stage
rt.journal.head()                  # the tamper-evident chain tip

report = rt.journal.verify()       # every record recomputes AND the hash chain is intact
assert report.ok
```

`verify()` proves two things at once: each stored reference recomputes from its own fields, and the
journal is a hash chain over those references. Mutate a record, or remove or reorder a row, and
`verify()` fails. `export()` dumps every record for external offline verification by any third party.

## From the command line

With the [SDK](/keystone-sdk) installed, verify a journal without writing any code:

```
keystone journal keystone.db --show
  passport     sha256:14dfdccd1231bf7a8...
  execution    sha256:da6efe518a0d166fd...  ALLOW
  execution    sha256:1b13052f20eeea554...
  [ok] all 3 records recompute their own reference - 3/3
  [ok] journal hash chain intact (no insert / remove / reorder)
  => PASS
```

Exit code is non-zero if anything fails to recompute, so this drops straight into CI. See the
[SDK and CLI](/keystone-sdk), [Agent behaviours](/keystone-agent), and the [Keystone chain](/keystone).