Architecture Decision Records¶

Every major technical decision in Trails is documented as an ADR. These are living documents — updated when decisions evolve, with amendment ADRs (e.g., 0012a, 0017a) for significant changes.

North Star

ADR-0021 — Progressive Enhancement is the guiding principle. Every other ADR is evaluated against it.

Foundation¶

ADR	Decision
0001	Rust kernel + Python surface
0002	Python-first shapes, emit SHACL
0003	Hybrid IRI minting strategy
0004	Query-time reasoning, opt-in, cached
0007	Oxigraph as default triple store

Capabilities & Transport¶

ADR	Decision
0005	Rich capability manifest; MCP as projection
0008	MCP primary, HTTP secondary
0015	WoT AgentCard alignment
0015a	MCP / WoT projection rule (amendment)
0016	WoT Discovery at `/.well-known/wot`
0060	MCP as Agent Authoring Surface

Trust & Identity¶

ADR	Decision
0006	Cedar as policy engine
0009	Provenance (PROV-O) always on
0010	Biscuit tokens for capability authorization
0011	DIDs + VCs for principal identity
0013	ACT/ECT as trust primitives
0014	Supply chain and build integrity
0022	Cedar unified matcher — strongest-available type
0030	Verifiable Credentials v2
0080	Agent governance interop — Microsoft AGT crosswalk (no adoption)

Data Surface¶

ADR	Decision
0012	Cost as framework primitive
0012a	Cost envelope nesting (amendment)
0017	ActiveGraph ORM
0017a	Property-path semantics (amendment)
0017b	Cross-graph traversal under Cedar (amendment)
0020	Tiered KG surface (superseded by 0021)
0021	Progressive enhancement (north star)

Agents & Runtime¶

ADR	Decision
0018	Agent runtime — planners, LLM client, sessions
0018a	Session forks, branches, replay (amendment)
0019	App surface — ingestion, vector, admin UI
0037	Hypothesis-Driven Agent Loops

Advanced KG Features¶

ADR	Decision
0035	Temporal Knowledge Graph — Bitemporal Queries
0036	Semantic Diff — Git-style KG Change Tracking
0038	Explainable Provenance — Citation Graphs and Confidence
0040	Multi-Modal KG Nodes
0054	Trails Ontology — Formal Vocabulary

Integration & Scale¶

ADR	Decision
0023	SPARQL Federation and Instance Mesh
0024	RML declarative data mapping
0025	Auto-Ontology Generation
0026	Schema Transformation & Enrichment
0027	Baseline Configurations
0028	Schema Migrations
0029	KG Test Primitives

Design Patterns¶

ADR	Decision
0043	Generic typed FSM with guards and callbacks
0044	Chain of Responsibility for request processing
0045	App Facade, Federation Proxy, Unit of Work
0063	Repository and Service patterns — typed data-access + domain orchestration

Agent Memory¶

ADR	Decision
0051	Persistent shared knowledge for AI agents — 10 MCP capabilities, cross-agent sharing via federation, provenance tracking
0052	Memory security — application layer separation, provenance integrity, trust calibration
0053	Trust boundaries — read isolation, data classification, epistemic status, federation trust

Developer Tooling¶

ADR	Decision
0069	LSP server — diagnostics, completion, hover, go-to-definition for Trails projects
0070	Property-based KG testing — Hypothesis strategies from @node_type schemas
0071	End-to-end OTel trace context propagation with W3C Traceparent
0072	SPARQL EXPLAIN — query analysis with cardinality estimation and optimization suggestions
0076	Explainable SHACL Validation — rule-based + LLM-enhanced violation explanations and fix suggestions (xpSHACL)

GraphRAG & Retrieval¶

ADR	Decision
0074	HippoRAG 2 / GraphRAG Agent Memory Backend — PPR hippocampal index for multi-hop QA retrieval

Security¶

ADR	Decision
0075	MCP Security Hardening — OWASP MCP Top 10 mitigations, tool-poisoning detection, StruQ sanitisation, rug-pull detection

Trust & Credentials (extended)¶

ADR	Decision
0077	SD-JWT RFC 9901 + BBS+ Selective Disclosure Alignment — RFC 9901-compliant JWT envelope and unlinkable BBS+ presentations (Proposed, deferred to M33)