Span Chain by GhostFactory MIT License OTLP/HTTP ingest Elixir / OTP Python + TypeScript SDK
Span Chain · auditable harness for AI agents

You can't ask what your agent did.
You have to prove it.

Every agent leaves a record. We keep it.

Span Chain is the auditable harness for production AI agents — every LLM call, every decision, every tool call captured in a tamper-evident, append-only chain. Cryptographically verifiable. Deterministically replayable without LLM calls.

Span entry · run 7f3a
Verified
04 L
Run
agent-run-7f3a
Span #
span#a4f1
Class
tool-call · model
Status
verified ✓
prev_hash
9e22...2d3b
SHA-256
a4f1c8e9...

Run observed across 4 spans in 265ms total. verify_ledger PASS — chain integrity intact, 4/4 spans signed and linked.

Replay this run deterministically from the cassette — no LLM calls, $0 cost. Structural diff against baseline shows the exact deviation point.

verify_ledger ✓
Hash-chain validated · self-hosted
SPAN CHAIN
Built
BY YOU
MIT · 2026
DWG # GF-SPAN-CHAIN-01
Hash chain · 4-span exploded view
Sheet 01 / 01
Scale 1:1
Rev MIT
L0 · root #33ce prev: null L2 · llm #71b8 prev: #33ce L3 · tool #9e22 prev: #71b8 L4 · resp #a4f1 prev: #9e22 SHA-256 hash-chain · append-only · 12ms verify verify_ledger Chain integrity: OK · 4/4 spans verified a single modified byte anywhere fails verification
Title
SPAN CHAIN · 4 entries
Built by
You
License
MIT
Sheet
01 / 01
Rev
v0.54.1
Self-host for free → Request early access 
git clone https://github.com/ghostfactory-art/spanchain.git
cd spanchain && cp .env.example .env
docker compose up
MIT License· OTLP/HTTP ingest· SHA-256 hash-chain· append-only· verify_ledger· Elixir / OTP· Python SDK· TypeScript SDK· tamper-evident· per-run isolation· VCR replay· $0 debug cost· open source· MIT License· OTLP/HTTP ingest· SHA-256 hash-chain· append-only· verify_ledger· Elixir / OTP· Python SDK· TypeScript SDK· tamper-evident· per-run isolation· VCR replay· $0 debug cost· open source·
01 — What's in a record

Six entries. One complete record.

Span Chain isn't a logging tool. It's six capabilities, signed and chained, that turn agent runs into evidence — searchable, replayable, verifiable.

Entry · 01Cryptographic

Tamper-evident audit trail

Every agent span — SHA-256 hash linked to the previous. verify_ledger detects any manipulation. One changed byte anywhere in history = chain broken.

Entry · 02Analytical

Structural run comparison

Run N agents on the same prompt. Span tree diff shows the exact deviation point — not just Run B was slower.

Entry · 03$0 cost

VCR deterministic replay

Replay any run deterministically — no LLM calls. Replay from cassette = $0. Every retry during debug would otherwise cost another LLM call.

Entry · 04Standard

OTLP/HTTP ingest

OpenTelemetry protocol. Python SDK + TypeScript SDK. Connect any OTel-compatible client — no proprietary SDK lock-in.

Entry · 05Live

Real-time trail

LiveView /trail — spans stream in live via PubSub, broadcast right after the hash-chain commit. No polling.

Entry · 06OTP

Per-run isolation

Every run in an isolated SessionGenServer (~2 KB heap). OTP actor model — a million concurrent runs without interference.

02 — Anatomy of a record

Eight signed fields. One signed entry.

Every span is a signed entry. Every entry links to the previous. One changed byte — chain broken. Below: every field that makes up one entry in the hash chain.

datum · run_id 01 span_id unique entry ID uuid v4 02 parent_span_id forms span tree nullable 03 timestamp_ns wall + monotonic ns precision 04 payload canonical JSON 05 prev_hash links previous sha-256 06 sha256_hash signs this entry 32 bytes 07 eval_id groups eval runs nullable 08 trace_id W3C OTel compat verify_ledger ✓ · entries signed · scale 1:1
Title
SPAN · anatomy · eight fields
DWG #
GF-SPAN-01
Scale
1:1
Sheet
02 / 03
Rev
v0.54.1
License
MIT · 2026

Key & legend

Each field, in the order it appears on the entry · DWG GF-SPAN-01
01
span_id
Unique entry ID

UUID v4 generated per span. Forms the leaf of the trace tree.

type uuidw 128 bit
02
parent_span_id
Forms the span tree

Null at root. SDK passes via ContextVar / AsyncLocalStorage — no manual plumbing.

type uuidnull at root
03
timestamp_ns
Wall + monotonic

Nanosecond precision. Drift detection across hosts. Wall clock + monotonic checkpoint.

res 1 nsp99 320ms
04
payload
Canonical JSON

Sorted keys, deterministic bytes. Hashable. Prompt, tool args, response, costs — all here.

enc UTF-8sort keys
05
prev_hash
Links previous entry

SHA-256 of the previous entry. Empty string at run start. Cross-epoch chain continuity.

algo sha-256w 32 B
06
sha256_hash
Signs this entry

Detects single-byte modification anywhere in the chain. verify_ledger re-walks instantly.

algo sha-256ver 12ms
07
eval_id
Groups eval runs

Late-bound on first ingest. First-wins idempotence. Compares N runs with same prompt.

type uuidbind late
08
trace_id
W3C OTel compat

128-bit identifier. Joins your existing distributed tracing. OTLP/HTTP ingest — no SDK rewrites.

w 128 bitstd W3C
03 — How a run enters the record

Three steps. One signed chain.

Standard OpenTelemetry input. Cryptographic chain in the middle. Mathematical verification on the way out — no sampling, no best-effort.

Step 01 · Instrument

Add @gf.trace.

Add @gf.trace to your agent. Every LLM call, tool use, and decision is captured automatically as a span. Python + TypeScript SDKs included.

Python · TypeScript
Step 02 · Chain

SHA-256 links each span.

The backend attaches a SHA-256 hash linked to the previous span. Append-only ledger. verify_ledger anytime — instant chain re-walk.

Elixir · OTP
Step 03 · Replay

Run failed? Replay from cassette.

When an agent fails, replay that exact run from cassette. No LLM calls, $0 cost. Compare two span trees side-by-side — see where it went wrong.

VCR · structural diff
Field report · GF-872

10,000 spans.
Zero corrupted.

Self-hosted OTP stress test: 1,000 concurrent agents, 17.5 seconds. Every run in its own isolated process — a crash in one doesn't touch the others. verify_ledger: 0 corrupted.

1,000
concurrent agents
10,000
spans total
571
spans / sec
0
corrupted
$ verify_ledger Chain integrity: OK · 20/20 sampled · 0 corrupted · Zero LLM calls
Verified

GF-872 · 2026-06-07 · Python asyncio / httpx · 1,000 coroutines · Elixir/OTP 28 · Bandit · self-hosted

04 — Positioning

Not another observability tool.

Span Chain is a compliance & governance layer. It sits beneath your observability — not What did the agent do?, but What did the agent do — proven.

LangSmith / Langfuse Span Chain
by GhostFactory
Question What did the agent do? What did the agent do — proven.
Data guarantee None SHA-256 hash-chain (tamper-evident)
Replay Session replay Deterministic VCR + structural diff
Debug cost Every retry = LLM call Replay from cassette = $0
Buyer Developer Developer without own framework + compliance
Security guarantee None — mutable traces can be rewritten Append-only, hash-chained — tamper-evident
Architecture Stateless API + DB Elixir/OTP actor model (per-run isolation)

Span Chain doesn't compete with LangSmith. It sits beneath it. Your observability shows what happened. Span Chain proves it — cryptographically.

05 — Open core

Open core. Three tiers.

Core is MIT and self-host for free — Elixir backend, both SDKs, OTLP, UI, VCR replay. Cloud and Enterprise extend self-hosted ergonomics, not feature paywalls.

Tier · Core
MIT · self-host

Core

Free / forever

Self-host everything. Elixir backend + Python/TS SDK + OTLP + UI + Comparator + VCR replay. All of it.

  1. Elixir/OTP backend + PostgreSQL 16
  2. Python SDK + TypeScript SDK
  3. OTLP/HTTP JSON ingest + Bearer auth
  4. LiveView /trail (real-time) + React UI
  5. Evals comparator — structural run diff
  6. VCR cassette replay + verify_ledger
Self-host for free →
Tier · Cloud
Coming soon

Cloud

TBD / managed

Managed hosting. Multi-tenant. Alerting. Advanced evals. For teams that don't want to run their own instances.

  1. Hosted Span Chain instance
  2. Multi-tenant workspace + RBAC
  3. Alerting (loop detection, cost spikes)
  4. Managed eval history + dashboards
  5. Usage-based billing (per spans)
  6. SLA + uptime monitoring
Join waitlist →
Tier · Enterprise
Contact us

Enterprise

Talk to us / regulated

For regulated work, compliance export, external timestamping. When cryptographically verifiable isn't enough and you need tamper-proof.

  1. RBAC + SSO (SAML, OIDC)
  2. Compliance export (PDF + JSON audit)
  3. External TSA anchoring (RFC 3161) — planned
  4. Tamper-proof guarantees (3rd party) — planned
  5. In-region deploy + indefinite retention
  6. Dedicated support + SLA
Request briefing →
Self-host for free → github.com/ghostfactory-art/spanchain
EU AI Act · Article 12 EU AI Act Article 12 requires audit trails integrated into core system design — not added as an afterthought. Annex III applies from 2. 12. 2027. Span Chain is built for this.

Built for audit & compliance programs

Supports EU AI Act Article 12 traceability, SOC 2 audit-trail controls, and HIPAA audit logging.

06 — Ship your first verified run

The chain is open.

Five minutes to install. One minute to instrument your first agent. verify_ledger in 12ms.

Self-host for free → Request early access
git clone https://github.com/ghostfactory-art/spanchain.git
cd spanchain && cp .env.example .env
docker compose up
Span ChainbyGhostFactory
FAQ

Frequently Asked Questions

What is Span Chain?

Span Chain is an auditable harness for production AI agents. Every LLM call, tool use, and decision is captured in a tamper-evident, append-only hash chain — SHA-256 verified, and deterministically replayable without LLM API calls.

How is Span Chain different from LangSmith or Langfuse?

Standard observability tools like LangSmith or Langfuse show you what your agent did via mutable traces. Span Chain proves it cryptographically. Traces in Span Chain are append-only, hash-chained, and self-hosted, ensuring the audit trail cannot be silently altered.

What does tamper-evident mean for AI agents?

Every Span Chain event is SHA-256 hashed and mathematically linked to the previous span. A single changed byte anywhere in the historical ledger breaks the hash chain. Span Chain does not prevent tampering; instead, the verify_ledger function makes any tampering instantly detectable.

Can I replay an AI agent run without LLM calls?

Yes. Span Chain records a VCR-style cassette of every agent run. Debug replay is deterministic and costs $0 — zero live LLM calls and zero API credits. Engineers can compare the replayed span tree against a baseline to identify the exact point of deviation during model upgrades.

Does Span Chain support OpenTelemetry?

Yes. Span Chain accepts OpenTelemetry (OTLP/HTTP) — partial standard subset. Engineers can connect any OTel-compatible client, including the official Span Chain Python and TypeScript SDKs, without proprietary vendor lock-in.

How do I self-host Span Chain?

Span Chain is self-hosted with Docker Compose: clone the GitHub repository (ghostfactory-art/spanchain), copy .env.example to .env, and run docker compose up. The core is MIT licensed. There are no usage limits, no external vendor dependencies, and no trace data leaves the user's infrastructure.

Is Span Chain relevant for EU AI Act compliance?

Yes. EU AI Act Article 12 requires strict audit trail documentation for high-risk AI systems (Annex III applies from 2. 12. 2027). Span Chain's append-only, cryptographically verifiable ledger is designed to support EU AI Act Article 12 traceability requirements.

What is the performance baseline for Span Chain?

Span Chain is built on Elixir/OTP, isolating every agent session into its own BEAM process. The system is benchmarked at 571 spans/second with 1,000 concurrent agents, achieving 0 corrupted chains and perfect integrity during the 10,000-span stress tests.

What programming languages does the Span Chain SDK support?

Span Chain provides official SDKs for Python (3.11+) and TypeScript/Node.js (18+). Because the ingestion layer is built on the OTLP/HTTP JSON standard, any language with an OpenTelemetry exporter can write to the ledger.