SpanForge Learning Curriculum · April 2026

The SpanForge Book

A complete, structured curriculum built from the SpanForge‑Core codebase. Every chapter maps directly to real implementation code — cryptographic audit chains, PII compliance, enterprise SDK patterns, and production observability for AI systems.

8Parts
47Chapters
~120 hrsEstimated study time
6Concept tracks

About this curriculum

Built from a real codebase

SpanForge‑Core is a compliance-grade AI observability SDK that covers an unusually broad range of computer science and engineering concepts: cryptographic audit chains, distributed tracing, privacy regulation, compliance engineering, SDK architecture patterns, enterprise security, and production testing.

Built in 2 months with AI-assisted development, it represents a condensed reference implementation across all of these domains. This curriculum organises every concept in the codebase into 8 parts and 47 chapters, structured to build understanding progressively — from the core event model through to enterprise deployment and supply chain security.

Each chapter includes specific learning points grounded in the actual SpanForge implementation. Parts 1 and 2 are prerequisites for all tracks — the event model and security primitives underpin every other module in the codebase.

Six concept tracks

CoreEvent model, tracing, exporters
SecurityCryptography, auth, secrets
CompliancePII, regulations, evidence chains
OpsObservability, cost, drift, alerts
AdvancedSDK architecture, enterprise
TestingTesting, DX, toolchain

Complete Table of Contents

47 chapters · 8 parts

Chapters are published progressively. Upcoming chapters are listed so you can see exactly what's coming.

Part 1core

Foundations — how SpanForge works

Everything in SpanForge rests on a small number of carefully designed primitives: the event envelope, the ULID, the tracer, and the batch exporter. Understanding these well means understanding every module that builds on them.

8 chapters·~12 hrs est.
1.1What is AI observability and why it matterscore1.2The RFC-0001 event envelope — schema, fields, versioningcore1.3ULID — lexicographically sortable IDs without coordinationcore1.4The event type registry — 74 canonical types across 17 namespacescore1.5Traces, spans, and the context propagation modelcore1.6The tracer, the @trace decorator, and span lifecycle hookscore1.7The batch exporter — buffering, backpressure, and circuit breakingcore1.8Sampling strategies — TraceIdRatio, ParentBased, AlwaysOncore
Part 2security

Security primitives — cryptography you can trust

This part covers the cryptographic foundations of SpanForge — HMAC chains, key management, JWT authentication, TOTP, and secrets scanning. Every concept here is implemented in pure stdlib with no external cryptographic dependencies.

10 chapters·~18 hrs est.
2.1HMAC-SHA256 signing — how and why every event is signedUpcoming
2.2Tamper-evident audit chains — chain linkage, prev_id, and tombstonesUpcoming
2.3Key rotation — rolling keys without breaking the chainUpcoming
2.4GDPR tombstone erasure — right to erasure in an immutable logUpcoming
2.5API key lifecycle — format, scoping, rotation, and revocationUpcoming
2.6JWT authentication — HS256 vs RS256, JWKS, and token introspectionUpcoming
2.7TOTP / MFA — RFC 6238, backup codes, and brute-force lockoutUpcoming
2.8Secrets scanning — 20 patterns, Shannon entropy, SARIF outputUpcoming
2.9Timing-safe comparisons and SecretStr — writing code that doesn't leakUpcoming
2.10SSRF protection — why IP allowlists alone are not enoughUpcoming
Part 3compliance

Privacy & PII — compliance-by-design

PII protection in production AI systems is not just about regex patterns. This part covers the full stack from detection through redaction, the five-level sensitivity model, multi-regulation compliance, and the consent boundary enforcement that ties it all together.

8 chapters·~14 hrs est.
3.1PII detection — regex vs. Presidio NLP vs. hybrid approachesUpcoming
3.2Sensitivity levels — from public to critical, and the 5-tier modelUpcoming
3.3Redaction policies — flag, redact, block, and the audit trail they createUpcoming
3.4Luhn, Verhoeff, and SSN validation — structured PII verificationUpcoming
3.5GDPR Article 17, CCPA DSAR, HIPAA Safe Harbor — regulation-specific patternsUpcoming
3.6India DPDP Act — patterns, consent enforcement, and data residencyUpcoming
3.7Consent boundaries — granting, revoking, and emitting consent.violation eventsUpcoming
3.8Differential privacy — Laplace noise on numeric quasi-identifiersUpcoming
Part 4ops

Observability — making AI systems legible

Observability for LLM systems requires more than standard APM. This part covers OpenTelemetry alignment, the full export backend stack, cost tracking, drift detection, and the alert routing system that makes all of it actionable.

10 chapters·~16 hrs est.
4.1OpenTelemetry alignment — OTel Semantic Conventions for GenAI v1.27+Upcoming
4.2W3C TraceContext and Baggage — propagating context across service boundariesUpcoming
4.3Export backends — OTLP, Datadog, Grafana Loki, Splunk, ElasticUpcoming
4.4WORM append-only storage — S3 Object Lock, GCS, Azure Immutable BlobUpcoming
4.5Cost tracking — per-model pricing, BudgetMonitor, and budget alertsUpcoming
4.6Drift detection — behavioural baselines, distribution stats, and alert thresholdsUpcoming
4.7Alert routing — topic-based publish, dedup, escalation, and on-call integrationUpcoming
4.8Metrics extraction — latency percentiles, p95, and aggregation from tracesUpcoming
4.9The span processor pipeline — enrichment, redaction, and custom processorsUpcoming
4.10Debug tooling — print_tree, visualize(), Gantt timelines, and the trace storeUpcoming
Part 5compliance

Compliance engineering — from evidence to attestation

This part bridges the gap between code and regulatory compliance. It covers the five major frameworks SpanForge maps to, the Compliance Evidence Chain that packages evidence for auditors, and the T.R.U.S.T. scorecard that makes compliance visible to non-technical stakeholders.

10 chapters·~16 hrs est.
5.1EU AI Act — Articles 9, 10, 12, 13, 14, 15 and what they require technicallyUpcoming
5.2NIST AI RMF — GOVERN, MAP, MEASURE, MANAGE as engineering controlsUpcoming
5.3ISO/IEC 42001 and ISO 27001 — AI management systems and Annex A.12.4Upcoming
5.4SOC 2 Type II — CC6, CC7, CC9 and how audit logs satisfy themUpcoming
5.5The Compliance Evidence Chain — building a signed ZIP bundle auditors can verifyUpcoming
5.6HMAC-signed PDF attestations — what goes in them and how they are verifiedUpcoming
5.7RFC 3161 trusted timestamps — cryptographic proof of existence for legal proceedingsUpcoming
5.8GDPR Article 30 Records of Processing — auto-generating RoPA from audit metadataUpcoming
5.9The T.R.U.S.T. scorecard — Transparency, Reliability, UserTrust, Security, TraceabilityUpcoming
5.10Human-in-the-Loop — EU AI Act Article 14, HITL queues, SLA tracking, escalationUpcoming
Part 6advanced

SDK architecture — building services the right way

This is the engineering education core of the curriculum. The patterns SpanForge uses — circuit breaker, sliding window rate limiter, zero-dependency design, namespace schemas, plugin discovery, auto-instrumentation — all transfer directly to any SDK or platform library.

12 chapters·~18 hrs est.
6.1The SFServiceClient base class — retry, circuit breaker, auth refresh, fallbackUpcoming
6.2Circuit breaker pattern — failure thresholds, OPEN/CLOSED/HALF-OPEN statesUpcoming
6.3Sliding window rate limiting — per-key counters without external dependenciesUpcoming
6.4Local fallback architecture — graceful degradation when services are unreachableUpcoming
6.5Zero required dependencies — designing with stdlib-only constraintsUpcoming
6.6The namespace schema system — 19 namespaces, dataclasses, and RFC-grounded designUpcoming
6.7The plugin system — entry-point discovery and third-party scorer registrationUpcoming
6.8Auto-instrumentation — monkey-patching 8 providers without breaking their APIsUpcoming
6.9The prompt registry — versioning, A/B routing, and reproducible audit trailsUpcoming
6.10Model registry — lifecycle tracking (active → deprecated → retired) with HMAC eventsUpcoming
6.11Schema migration — v1 → v2 event migration and the MD5 rehash patternUpcoming
6.12The CI/CD gate pipeline — YAML-driven pass conditions, 6-gate architecture, SLSAUpcoming
Part 7advanced

Enterprise patterns — production at scale

Enterprise deployments have requirements that don't appear in development environments: tenant isolation, data residency, encryption key management, air-gap deployment, and formal security review processes. This part covers all of them with concrete implementation patterns.

8 chapters·~14 hrs est.
7.1Multi-tenancy — project isolation, HMAC chain scoping, cross-project query guardsUpcoming
7.2Data residency — EU, US, APAC, India routing and enforcement at the SDK layerUpcoming
7.3Encryption at rest — AES-256-GCM, envelope encryption, and cloud KMS integrationUpcoming
7.4mTLS and FIPS 140-2 mode — certificate rotation and algorithm restrictionUpcoming
7.5Air-gap deployment — offline mode, Docker Compose self-hosted stack, Helm chartUpcoming
7.6OWASP API Security Top 10 — each category as a code-level checklistUpcoming
7.7STRIDE threat modelling — applied to the 8 SpanForge service boundariesUpcoming
7.8Supply chain security — CycloneDX SBOM, Sigstore/cosign, SLSA provenanceUpcoming
Part 8testing

Testing, DX, and shipping production SDKs

The test suite and developer experience layer of SpanForge are as carefully designed as the production code. This part covers the testing patterns, toolchain configuration, and DX investments that make the SDK usable and verifiable by teams other than the one that built it.

7 chapters·~12 hrs est.
8.1Property-based testing with Hypothesis — strategies, settings, and invariant designUpcoming
8.2The conformance suite — portable JSON fixtures, clause IDs, and third-party verificationUpcoming
8.3The mock layer — mock_all_services(), call recording, and test isolationUpcoming
8.4Sandbox mode and the doctor CLI — zero-network local developmentUpcoming
8.5Type stubs (.pyi) — writing stubs that make mypy strict and IDEs happyUpcoming
8.6Toolchain setup — ruff, mypy strict, bandit, pip-audit, pre-commit, hatchlingUpcoming
8.7Writing SDK examples that actually teach — the production_multi_agent.py patternUpcoming

Based on SpanForge‑Core v2.0.10 · 47 chapters · 8 parts · ~120 hours · 6 concept tracks