This directory records the significant, hard-to-reverse decisions made while building Tollgate. Each record captures the context, the decision, and its consequences, so the reasoning is available later even when the people change.
The format follows Michael Nygard's Documenting Architecture Decisions.
- 0001 — Record architecture decisions
- 0002 — Relational, transactional core over event-sourcing
- 0003 — Pre-charge reservation with reconcile-on-commit
- 0004 — Invariant-guarded conditional writes for budget balances
- 0005 — Hierarchical reservation with deterministic lock ordering
- 0006 — READ COMMITTED with conditional writes on the hot paths
- 0007 — Idempotency caching policy
- 0008 — TTL and reapers for orphaned reservations and idempotency keys
- 0009 — The CounterStore port as the Redis-ready seam
- 0010 — Cost normalization to micro-USD via an immutable, versioned price book
- 0011 — Conservation and the per-node spend bound as an offline oracle
- 0012 — Gateway-neutral control plane, not a proxy
- 0013 — Import-linter boundary enforcement
- 0014 — UUIDv7 ledger identifiers
- 0015 — Per-principal authentication and scope-based authorization
- 0016 — Tokenizer-derived input bound with bounded, audited overage
- 0017 — Reservation identity-claim guard for exactly-once terminal effects
- 0018 — Reservation heartbeat and self-healing late commit
- 0019 — Fail-closed enforcement with an opt-in grace allowance
- 0020 — Empty applicable-budget set is a denial
- 0021 — Provider-qualified price book
- 0022 — The SDK guard enforces; the LiteLLM callback only meters
- 0023 — Async Alembic on asyncpg, no separate sync migration driver
- 0024 — Baseline migration builds the schema from the canonical MetaData
- 0025 — At most one budget per scope node in V1
- 0026 — Keyed deterministic token hash for credential lookup
Copy the structure of an existing record, give it the next number, and set its status. Records are immutable once accepted: to change a decision, add a new record that supersedes the old one and update the older record's status.