How it works

The recorder extracts the operation

The surface adapter pulls the operation bytes out of the tool call and routes them to a guard, either from an explicit --resource hint or by inferring the integration from the tool name and the payload shape. SQL text goes to the SQL guard, terraform show -json output to the Terraform guard, git argv to the git guard. Anything unrecognised is still recorded, as a generic_exec record with no classification.

The guard parses the real grammar

The SQL guard parses the statement with libpg_query — the actual PostgreSQL parser, not a regex. It sees a DELETE with a WHERE clause, evaluates the clause for tautology at the AST level, and classifies it as a bounded write. Had the WHERE been absent, or 1=1, the class would be unbounded write and the base risk CRITICAL.

Guards are pure libraries: no network, no filesystem, no clock. Each runs inside a pipeline wrapper with a 25 ms CPU budget and a 1 MB input cap. Input over the cap is not parsed and carries INPUT_TRUNCATED; a panic is caught and becomes a guard_error record. Nothing non-parsing is silently allowed — unparseable SQL yields SQL_PARSE_ERROR and, by default, REQUIRE_APPROVAL.

The guard returns a decision, a risk class, reason codes, and a structure: statement kinds, schema-qualified relations, and a WHERE skeleton with typed placeholders such as created_at < <timestamp>. Literals do not appear in the structure.

Policy decides locally

The recorder holds a signed policy bundle in a local cache. Evaluation is an in-process function call over that cached bundle: no network request is on the decision path, and the elapsed time is written into the record as eval_ms.

Policy binds rules to resources and turns the guard's classification into one of ALLOW, WARN, REQUIRE_APPROVAL or BLOCK. Each binding also carries a mode. In observe mode the recorded verdict is the guard's own decision and nothing is stopped. In enforce mode the policy decision is recorded, and BLOCK makes the hook return deny — the tool never runs.

When sync is enabled the recorder refreshes the bundle from the Console at process start. That refresh is best-effort: an unreachable Console does not stop the recorder, it falls back to the cached signed bundle. A cache older than 24 hours is stale, and each binding declares its own stale_action (for example fail_closed) for that case.

The record is built, chained and spooled

The engine assembles one record. The payload — the SQL text — is never stored. It is reduced to a salted BLAKE3 commitment. The structural detail from the guard goes into action_detail, which stays on your side of the boundary.

The record is canonicalised with JCS (RFC 8785), hashed with BLAKE3-256, and its prev_hash is set to the hash of the previous record in the stream. It is appended to an NDJSON segment file in the spool. In enforce mode the write is fsync'd before the decision is returned, so a committed record survives a crash at the moment of the operation.

A checkpoint signs a Merkle root

Individual records are not individually signed — that cost is paid once per batch instead. The recorder emits a CheckpointNote every 1,000 records and at clean shutdown. The note carries the sequence range, the chain head hash, a Merkle root over the covered records' hashes (RFC 6962 leaf and node prefixes, BLAKE3), the tree size, and a link to the previous checkpoint. It is signed Ed25519 with the recorder's identity key.

A record is attested once a valid checkpoint covers it.

Metadata syncs to the Console

If the recorder is enrolled, it pushes the signed checkpoints and a projection of the records to the Console over gRPC, authenticated with the recorder's own credential. The Console verifies the recorder signature, checks that seq_from equals its stored head plus one, and only then countersigns — recording its view of how far the stream has advanced.

Sync is best-effort. A failure is logged, never fatal; the records are already durable locally and sync resumes later.