Architecture Decision Records
Architecture Decision Records capture decisions that should remain stable across future implementation work.
Records
- ADR#0000: Architecture Decision Record Process
- ADR#0001: Workspace Runtime Taxonomy
- ADR#0002: Rust Crate Boundaries
- ADR#0003: AI Protocol Transport Taxonomy
- ADR#0004: Protocol and Transport Layering
- ADR#0005: Polyglot Workspace Layout
- ADR#0006: Helpers Naming
- ADR#0007: Configuration Sources
- ADR#0008: OpenTelemetry Observability
- ADR#0009: Protocol Buffers Wire Contracts
- ADR#0010: Unit Tests First, Testcontainers Only When Necessary
- ADR#0011: JSON-RPC over NATS Binding
- ADR#0012: ARD-Compatible Discovery Catalog
- ADR#0013: Origin Stream Sequence Header
- ADR#0014: Command and Query Naming
- ADR#0015: Rust TLS Library
- ADR#0016: Protocol Buffers RPC over NATS micro Binding
- ADR#0017: AAuth Agent Authentication over a Trogon NATS PoP Binding
- ADR#0018: ConnectRPC Gateway for Browser Product Surfaces
- ADR#0019: Console Webapp Stack
- ADR#0020: ACP SDK 1.x Boundary and Bridge-Owned Callback Traits
- ADR#0021: Typed Decode over Passthrough Forwarding
- ADR#0022: Canonical ACP Method Vocabulary in the NATS Layer (Rejected)
- ADR#0023: Secret Management and Key Custody on OpenBao behind a Platform Secrets Service
- ADR#0024: Agent Platform Stream Topology
- ADR#0025: Agent Definition Data Ownership
- ADR#0026: Command Authorization Principal and Authorizer Hook for Decider Execution
- ADR#0027: Declared Subject Scope for Decider Stream Resolution
- ADR#0028: Admission Control for Decider Command Execution
- ADR#0029: Snapshot-Derived Retention Watermark for Decider Streams
- ADR#0030: Customer-Controlled Key Backend Routing
- ADR#0031: Agent Implementation and Session Plan
- ADR#0032: Model Route and Credential Binding
- ADR#0033: Key Custody Product Model
- ADR#0034: Rust Crate Domain Grouping
- ADR#0035: Session Store as a Decider Aggregate on NATS JetStream
- ADR#0036: Agent Self-Certifying Cryptographic Identity
- ADR#0037: Agent Identity Governance: Decentralized Verification under Governed Authority
- ADR#0038: Agent Identity Cryptographic Suite and Crypto-Agility
- ADR#0039: Self-Authenticating Event Provenance
- ADR#0040: Contract Field Vocabulary: Identifiers, Handles, and Display Labels
- ADR#0041: Canonical MCP JSON-RPC Bodies over NATS (Draft)
- ADR#0042: NATS Trace Context and Message Path Tracing (Draft)
- ADR#0043: Agent Instructions Ownership and Shape (Draft)
- ADR#0044: Inbound Media Is Fetched Out of Band by a Dedicated Consumer (Draft)
- ADR#0045: Aggregate-Oriented Module Layout for Event-Sourced Services
- ADR#0046: Project-Anchored Resource Hierarchy for the Credential Platform
- ADR#0047: Event Stream as the Credential Metadata Source of Truth
- ADR#0048: One-Time Plaintext Exposure Contract
- ADR#0049: Revocation Propagation Latency Target
- ADR#0050: Signed Proof-of-Possession as the Strongly Recommended Caller Authentication
- ADR#0051: Fully Bound Per-Request Signing Contract
- ADR#0052: Cloud KMS Auto-Unseal Is Mandatory for Production OpenBao
- ADR#0053: External OIDC Federation Surface for Agent Identity (Draft)
- ADR#0054: NATS Protocol Binding Documentation (Draft)
- ADR#0055: NATS Subject Design for JSON-RPC Protocol Bindings (Draft)
- ADR#0056: Canonical JSON-RPC Bodies over NATS (Draft)
- ADR#0057: Decider Command NATS Binding (Draft)
- ADR#0058: Decider Module Distribution (Draft)
- ADR#0059: Stream Incarnation Fencing by Subject Isolation and Sealing (Draft)
- ADR#0060: The Session Read Contract Is a Query Proto, Not the Projection Value (Draft)
- ADR#0061: Turn Identity Belongs on Every Turn-Scoped Session Event, Not Only the Conversation and Tool Ones (Draft)
- ADR#0062: Runtime-Owned Settings and Platform Declarations (Draft)
- ADR#0063: An Agent Declares the Connections It Needs, and the Declaration Carries No Version (Draft)
- ADR#0064: Invariants Are Declared in the Schema Before Anything Enforces Them (Draft)
- ADR#0065: Generation Settings, Usage, and Citations Grow to the Provider-Neutral Superset of Anthropic, OpenAI, and Gemini (Draft)
- ADR#0066: A Project Is Work Attached Below a Workspace, and Its Initial Access Is Recorded at Creation
- ADR#0067: A Session Binds to a Checkout, Not a Workspace
- ADR#0068: A Reference Field Says It Is a Reference in Both Its Name and Its Type
- ADR#0069: Every Event Envelope Records Who Caused It and When Each Step Happened (Draft)
- ADR#0070: An Agent Declares What It Offers and Whose Authority It Carries; Throughput Ceilings Stay on the Policy Plane (Draft)
- ADR#0071: What an Agent May Reach, How Far It May Go, and Whether It May Run at All Are Policy Bindings on a Subject (Draft)
- ADR#0072: Agents Improve by Running Recorded Candidates, Scored Blind, and Promoted Only Through Proposals (Draft)
- ADR#0073: A Slack Acknowledgement Body Comes From a Consumer Over NATS Request/Reply, After the Durable Publish (Draft)
- ADR#0074: Credential Platform Extraction Boundary
- ADR#0075: API Key Format and Bearer Verifier Construction
- ADR#0076: API Keyspaces and Root Key Bootstrap
- ADR#0077: API Key Authorization Model and Rate Limits
- ADR#0078: API Key Rotation Grace and the First-Release Audit Set
- ADR#0079: External Secret Sources Resolve Behind the Secrets Service (Draft)
- ADR#0080: A Bolt for JavaScript App Consumes the Gateway's Slack Traffic Through a
NatsReceiverThat Dispatches What the Gateway Already Verified and Stored (Draft) - ADR#0081: Every NATS Connection Uses TLS Unless Explicitly Disabled, and Clients Enter Operator-Mode Accounts Only Through Platform Credentials or the Auth Callout
- ADR#0082: Inside the Bus the Principal Is Derived from the Subject, and Proof of Possession Is Enforced Only at the External Edge
- ADR#0083: Credential Material, Claim-Check Blobs, and Sensitive Tenant Streams Under a Customer Managed Key Are Sealed in an Owned AEAD Envelope, and Nothing Else Is
- ADR#0087: MCP and ACP Callers Are Known the Same Way A2A Callers Are: the Principal Comes from the Subject, and a Verified Credential Is Required Only at Each Server's HTTP Edge (Draft)
- ADR#0092: A Third-Party Connection Is a Consented Provider Authority Pinned to an Immutable Connector Release and Provider App, and Its Aggregates Hold Only Secret References (Draft)
- ADR#0093: A Connection's Custody Project Is Separate from Its Logical Owner, Person-Owned Use Needs an Explicit Revocable Delegation, and Every Owner Kind Has an Offboarding Cascade (Draft)
- ADR#0094: The Platform Authorizes Third-Party Connections as an OAuth Client Through a Single-Use, Write-Ahead Attempt, and Fetches Untrusted Discovery Data Outside Custody (Draft)
- ADR#0095: Each Connection's OAuth Token Set Is One Sealed, CAS-Written OpenBao Secret, Refreshed Only Through a Write-Ahead Credential Transaction (Draft)
- ADR#0096: An Agent Uses a Connection Through an Authorized HTTP Proxy That Injects Credentials Held by Custody (Draft)
- ADR#0097: A GitHub App Installation Is a Provider Fact Learned by Reconciliation, Bound to an Owner Only by an In-Session Claim, and Never by the Setup Redirect (Draft)
- ADR#0098: Workload Identity Requires Attested Issuance, Rotating X.509 Credentials and Independent Authorization (Draft)
- ADR#0099: Bazel Builds and Tests the JavaScript and TypeScript Projects with rules_js, on the Node.js mise Installs (Draft)
