Audit Chain¶

Every significant event — each inference call, each block, each human decision, each configuration change — is written to a tamper-evident, append-only ledger. Entries are chained with HMAC-SHA256, so any retroactive edit breaks verification and is reported with the index where it broke. Two endpoints: one for the snapshot, one for the full cryptographic re-check.

Endpoints¶

Both endpoints live on G-1 Studio (/v1/glad/...). They take no parameters and no body — the ledger is global to the deployment.

GET /v1/glad/chain/status¶

What it does. Returns a snapshot of the ledger: how many entries it holds, the first and last chain hashes, whether the chain currently verifies, and the newest entries in a UI-friendly shape. This is the call the Audit & Chain page polls.

curl -s http://localhost:8080/v1/glad/chain/status | jq

import httpx

st = httpx.get("http://localhost:8080/v1/glad/chain/status").json()
print(st["total_entries"], "entries, integrity:", st["chain_integrity"])
for e in st["entries"][:5]:
    print(e["entry_index"], e["timestamp"], e["event_type"], e["chain_hash"][:12])

const st = await fetch("http://localhost:8080/v1/glad/chain/status").then(r => r.json())
console.log(st.total_entries, "entries, integrity:", st.chain_integrity)

What comes back

{
  "count": 14821,
  "total_entries": 14821,
  "first_hash": "7f2d4e1c…",
  "last_hash": "a8b3c1f0…",
  "chain_integrity": true,
  "broken_at": null,
  "verified_count": 14821,
  "entries": [
    {
      "index": 14820,
      "entry_index": 14820,
      "call_id": "call_xyz",
      "timestamp": "2026-06-10T10:23:45Z",
      "event_type": "call",
      "payload_hash": "3c9a…",
      "prev_chain_hash": "7f2d…",
      "chain_hash": "a8b3…",
      "metadata": {}
    }
  ],
  "recent": []
}

GET /v1/glad/chain/verify¶

What it does. Performs the full cryptographic verification: recomputes every entry HMAC from the genesis entry and checks that each chain_hash matches. Returns as soon as it finds a break, reporting where.

curl -s http://localhost:8080/v1/glad/chain/verify | jq

import httpx

v = httpx.get("http://localhost:8080/v1/glad/chain/verify", timeout=60).json()
if not v["valid"]:
    raise SystemExit(f"ledger tampered at entry {v['broken_at']}")
print(f"{v['verified_count']}/{v['total_count']} entries verified")

const v = await fetch("http://localhost:8080/v1/glad/chain/verify").then(r => r.json())
if (!v.valid) throw new Error(`ledger tampered at entry ${v.broken_at}`)

What comes back

{
  "valid": true,
  "broken_at": null,
  "verified_count": 14821,
  "total_count": 14821
}

Design¶

The audit chain is inspired by blockchain-style ledger design, but implemented as a simple hash-linked list stored in the SQLite database:

Each entry_hash is computed over: prev_hash + timestamp + event_type + payload. If any past entry is modified, the hash chain breaks, and GET /v1/glad/chain/verify reports the tampered entry.

Two kinds of tamper evidence¶

The hash chain proves that a record was not altered after the fact. It cannot, on its own, prove that the record was right — a perfectly intact chain of unexplainable decisions is still unexplainable.

Geodesia pairs it with a second, independent property: the decision's explanation is deterministic and recomputable. Causal explainability is a measurement over a deterministic detector — no gradients, no sampling, no LLM in the loop — so the same request, against the same detector build, yields the same responsible tokens for anyone who runs it, including an auditor who does not trust you.

This is a property an LLM provider structurally cannot offer. An explanation generated by a language model is another sample — temperature-dependent, unverifiable, different tomorrow. An explanation computed by intervening on a deterministic function is arithmetic, and arithmetic can be repeated.

What Gets Logged¶

Every entry in the chain has an event_type. The following events are automatically recorded:

For regulatory submission¶

For a complete audit bundle including FRIA, chain snapshot and call statistics, use POST /v1/glad/report. For the raw per-call records of one Application, GET /v1/glad/apps/{app_id}/export?fmt=sqlite.

Regulatory Mapping¶

Exporting the chain¶

There is no query/pagination endpoint on the ledger — chain/status returns the newest 20 entries and nothing else. To get a full, filtered export, use one of: