StandardsRFC-0001 SPANFORGE

Open standard / vendor-neutral / in development

RFC-0001 SPANFORGE

An open event-schema standard for observability of agentic AI systems. It defines a structured event envelope, 15 compliance and telemetry namespaces, HMAC audit chains, PII redaction, and four conformance profiles, from baseline AI spans to full compliance-grade evidence.

SpanForge SDK Validate events

Background

Why a standard for AI compliance?

Agentic AI systems produce compliance evidence that differs materially from traditional distributed systems telemetry. A single run can span dozens of LLM calls, tool invocations, sub-agent delegations, and reasoning steps, each carrying cost, latency, and regulatory risk.

There is still no broadly adopted cross-vendor standard for what an AI compliance event should contain, how it fits into a multi-agent trace tree, how cost should be attributed across nested steps, how PII should be handled before export, or how audit trail integrity is guaranteed.

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

Specification

The event envelope

Every SPANFORGE event is wrapped in a typed envelope with six required fields and four optional fields. The envelope is serialized as JSON and designed to align 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, for example llm.trace.span.
source	string	Required	Emitting tool and version, for example 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 whose schema depends on 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 and governance namespaces.

RFC-0001 SPANFORGE defines 15 namespaces across two categories: five compliance and governance namespaces and ten instrumentation and telemetry namespaces. Every event type is dot-separated, typed, and backed by a versioned JSON Schema payload definition.

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

hitl.*Human-in-the-loop review events for approvals, 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 for key rotation, verification, and tamper detection.

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

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

llm.cache.*Semantic cache hit, miss, write, and eviction events with similarity scores.

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

llm.eval.*Evaluation results with scores, pass-fail status, and evaluator metadata.

llm.fence.*Constraint boundary checks for fenced inputs and outputs against policy.

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 stream has not been modified, reordered, or truncated after the fact.

Audit chain integrity can be verified programmatically through 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 requirements mature.

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 for tamper-evident logging.

Conformance profile

spanforge-Privacy-2.0

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

Conformance profile

spanforge-Full-2.0

All profiles combined with export abstraction, governance primitives, and schema migration tooling.

Versioning

Schema versions.

The SPANFORGE schema uses semantic versioning. Version 1.0 is the stable baseline. Version 2.0 extends it with additional namespace event types and governance primitives. Both are published as JSON Schema Draft 2020-12 and can be exported through 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 plus trace, cost, cache, eval, and guard namespaces.
v2.0	Current	Full 15-namespace taxonomy, HMAC chains, PII redaction, and governance primitives.

Get started

Implement the standard.

The Python SDK is the reference implementation. It is pip-installable, keeps dependencies light, and covers all 15 namespaces.

Python SDK Validate your events

Back to SpanForge Platform Continue to Python SDK