Introduction

GlassBox

A DataHub-native execution-provenance and control layer for AI agents.

Quickstart

Bring up the pinned estate, record a receipt, change a field, watch a decision go stale.

How GlassBox works

Capture, sign, project, assess, recover — end to end.

Architecture

The full runtime topology in one diagram.

Run it

glassbox-dbom, glassbox-otlp-receiver, glassbox-invalidation-state.

The problem

Data lineage tells you where data went. It does not tell you what your agents believed, and what they did because of it.

When an agent writes a recommendation, an approval, or a price, that output is a claim about the state of the world at a moment in time. It depended on specific fields, in specific datasets, at specific versions. Nothing normally records that dependency — so when a schema field changes six weeks later, there is no mechanical way to answer the only question that matters: which decisions are no longer safe to trust?

The usual substitute is a human reading dashboards and guessing. That does not scale, and it is not evidence.

The one rule

Nothing in this system is proven by a screenshot or a mocked response. A DataHub capability is marked proven only after a live probe writes metadata and reads it back directly from the configured server. Every claim in these docs traces to a committed, raw-free evidence report.

What GlassBox does

GlassBox sits at the boundary between an agent run and the governed metadata graph, and does five things:

Records a signed DBOM

Every consequential output gets a canonicalised, Ed25519-signed Decision Bill of Materials — the dependencies it read, the tools it ran, and the verification state of each.

Binds evidence to DataHub

Runtime evidence resolves to real DataHub URNs and publishes as a governed projection, verified by direct entity readback rather than write acknowledgement.

Invalidates deterministically

A metadata change becomes a content-addressed campaign. Declarative rule packs decide materiality — not a model — and the reason code is durable.

Recovers under authority

Quarantine, fingerprint-authorized replay in a digest-pinned sandbox, and append-only supersession that leaves both receipts intact.

The loop

text

agent run ──OTLP──▶ compiler ──▶ signed receipt ──▶ DataHub projection
                                       │                    │
                                       │            metadata change
                                       │                    │
                                       │                    ▼
                                       └──── campaign ── assessment ──▶ writeback
                                                              │
                                        quarantine ◀──────────┘
                                             │
                                    authorized replay ──▶ supersession ──▶ closure

The differentiator is not provenance in isolation. It is the complete closed chain: runtime evidence → governed projection → deterministic assessment → durable quarantine → authorized recovery → verified closure.

What GlassBox records

Record	Contract	Notes
Decision receipt	DBOM 0.1	Canonicalised and signed; tamper tests are part of the suite
Runtime influence	Qualified dependency set	Each dependency carries role, state, and evidence ID
Field coverage	`COMPLETE` / `INCOMPLETE`	Drives whether an assessment can be exact
Invalidation campaign	Content-addressed	Bound to the exact change event and policy version
Assessment	Reason code + policy version	Raw-free and durable; no free text
Replay bundle	Replay Bundle 0.1	Digest-bound approvals, structurally non-executing dry run
Supersession	Append-only	Both receipt Documents remain unchanged

Adoption surfaces

DataHub

Actions plugin, incident writeback, ownership routing, and live proof.

OTLP & Kafka

Authenticated receiver, durable obligations, independent recovery.

Forensics MCP

Seven proof-carrying read-only tools and a credential-free judge test.

Kafka and PostgreSQL Queue claims are deliberately independent: each is proven against its own live estate, and neither is presented as evidence for the other.

Honest boundaries

The SQLite profile coordinates processes on one host. It is not a multi-node or network-filesystem deployment.
The PostgreSQL proof establishes real multi-connection coordination. It does not claim physical multi-host deployment, managed failover, or network-partition recovery.
Field-lineage coverage may be INCOMPLETE. When it is, an assessment says so rather than inferring a result.
The reference OTLP receiver is single-flight and expects TLS termination and rate limiting in a production proxy.

Start with the Quickstart to run the whole chain on your machine from one command, or read the architecture guide for the concepts first.