Open Standard · Vendor-Neutral · In Development

RFC-0001 SPANFORGE

An open event-schema standard for observability of agentic AI systems. Defines a structured event envelope, 10 observability namespaces, HMAC audit chains, PII redaction, and four conformance profiles — from basic AI spans to full compliance.

SpanForge SDK →Validate events →

Background

Why a standard for AI compliance?

Agentic AI systems produce compliance evidence that is fundamentally different from traditional distributed-systems telemetry. A single agent run can span dozens of LLM calls, tool invocations, sub-agent delegations, and reasoning steps — each with its own cost, latency, and regulatory risk profile.

Yet today there is no broadly adopted cross-vendor standard for what an “AI compliance event” looks like: what fields it carries, how it identifies its place in a multi-agent trace tree, how cost is attributed across nested steps, how PII is handled before data reaches a backend, or how the integrity of an audit trail is guaranteed.

RFC-0001 SPANFORGE fills this gap. It is an open specification for compliance and governance of agentic AI systems, designed for incremental adoption and vendor-neutral integration across every AI framework and observability backend.

Specification

The Event Envelope

Every SPANFORGE event is wrapped in a typed envelope with six required fields and four optional fields. The envelope is serialised as JSON and is designed to be compatible with OpenTelemetry span context.

python

from spanforge import Event, EventType
from spanforge.namespaces.trace import SpanPayload, TokenUsage, ModelInfo, GenAISystem

event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="spanforge@1.0.0",
    payload=SpanPayload(
        span_name="summarise_document",
        span_kind="LLM",
        status="ok",
        duration_ms=830,
        token_usage=TokenUsage(input_tokens=411, output_tokens=128, total_tokens=539),
        model_info=ModelInfo(system=GenAISystem.OPENAI, name="gpt-4o"),
    ).to_dict(),
    tags=["prod", "summarisation"],
)

Field	Type	Required	Description
event_id	string (ULID)	Required	Globally unique monotonic event identifier.
timestamp	ISO-8601 UTC	Required	UTC timestamp with millisecond precision.
event_type	string	Required	Dot-separated namespace path, e.g. llm.trace.span.
source	string	Required	Emitting tool and version, e.g. spanforge@1.0.0.
trace_id	hex-32	Required	W3C TraceContext-compatible 128-bit trace identifier.
span_id	hex-16	Required	64-bit span identifier within the trace.
payload	object	Required	Namespace-typed payload object (schema varies by event_type).
parent_span_id	hex-16	Optional	Parent span_id for nested span trees.
tags	string[]	Optional	Arbitrary string tags for filtering and grouping.
hmac	string	Optional	HMAC-SHA256 signature for audit chain integrity.

Namespace Taxonomy

15 compliance & governance namespaces.

RFC-0001 SPANFORGE defines 15 namespaces across two categories: five compliance & governance namespaces (consent, hitl, model_registry, explanation, audit) and ten instrumentation & telemetry namespaces. Every event type is dot-separated, typed, and has a versioned JSON Schema payload definition.

consent.*Consent recording and verification events — data-use consent, withdrawal, and scope checks.

hitl.*Human-in-the-loop review events — approval requests, outcomes, and escalation records.

model_registry.*Model registration and risk-tier enrichment events for model provenance tracking.

explanation.*Explainability records and explanation coverage metrics for regulatory accountability.

llm.audit.*HMAC audit chain events — key rotation, chain verification, and tamper detection records.

llm.trace.*Span lifecycle events — agent runs, steps, tool calls, and OpenTelemetry-compatible span trees.

llm.cost.*Token usage and USD cost attribution across models, steps, and sessions.

llm.cache.*Semantic cache hit/miss/write/evict events with cosine-similarity scores.

llm.diff.*Prompt or output diff events for detecting changes between runs.

llm.eval.*Evaluation results — scores, pass/fail status, and evaluator metadata.

llm.fence.*Constraint boundary checks — input/output fenced against defined policies.

llm.guard.*Safety and content-policy checks with provider and outcome metadata.

llm.prompt.*Prompt rendering and template resolution events with variable bindings.

llm.redact.*PII detection and redaction events, including field-level re-identification risk.

llm.template.*Template registration, rendering, and version-diff events.

Security

HMAC-SHA256 audit chains.

SPANFORGE includes a tamper-evident audit logging mechanism. Each event can carry an HMAC-SHA256 signature that chains it to the preceding event in a session. Verifying the chain proves that the event stream has not been modified, re-ordered, or truncated after the fact.

Audit chain integrity can be verified programmatically via the Python SDK or on the command line with spanforge audit-chain events.jsonl.

bash

# Verify HMAC signing chain integrity
spanforge audit-chain production-events.jsonl

# Expected output:
# [OK] Chain verified: 1,204 events, no breaks detected.

Adoption

Four conformance profiles.

SPANFORGE is designed for incremental adoption. Start with the Core profile and layer in Security, Privacy, and Full-Suite capabilities as your requirements grow.

Conformance Profile

spanforge-Core-1.0

Structured event envelope with at least llm.trace.* events. The baseline for any compliant implementation.

Conformance Profile

spanforge-Security-2.0

Core plus HMAC-SHA256 audit chains. Required for compliance-grade tamper-evident logging.

Conformance Profile

spanforge-Privacy-2.0

Core plus PII redaction via llm.redact.* namespace before any event reaches a backend.

Conformance Profile

spanforge-Full-2.0

All four profiles combined. Export abstraction, governance primitives, and schema migration tooling included.

Versioning

Schema versions.

The SPANFORGE schema is versioned using semantic versioning. The v1.0 schema is the stable baseline; v2.0 extends it with additional namespace event types and governance primitives. Both schemas are published as JSON Schema Draft 2020-12 and can be exported via the validation CLI.

bash

# Export the current schema (v2.0 by default)
spanforge validate --export-schema > spanforge-schema.json

# Pin validation to a specific schema version
spanforge validate events.jsonl --schema-version 1.0

Version	Status	Notes
v1.0	Stable	Original envelope + trace, cost, cache, eval, guard namespaces.
v2.0	Current	Full 15-namespace taxonomy, HMAC chains, PII redaction, governance primitives.

Get started

Implement the standard.

The Python SDK is the reference implementation. Zero required dependencies, pip-installable, covers all 15 namespaces.

Python SDK →Validate your events →

← SpanForge Platform Python SDK →