Architecture Decision Records¶
This directory holds the project's Architecture Decision Records (ADRs). An ADR captures a single architectural decision, the context that prompted it, and the consequences that follow.
ADRs are append-only and immutable. Once an ADR is merged, it is not edited except to update its status. If a decision changes, write a new ADR that supersedes the old one.
When to write an ADR¶
Write an ADR when the team makes a decision that:
- Constrains future architecture (technology choice, service boundary, data ownership).
- Has tradeoffs the team explicitly weighed.
- Is hard to reverse, or expensive to reverse.
- Future contributors will benefit from understanding the reasoning behind.
You do not need an ADR for:
- Routine implementation choices within an already-decided architecture.
- Bug fixes.
- Pure refactors that preserve behaviour.
- Decisions that are obvious from the code itself.
If you're unsure, err toward writing one — they are cheap, and the value comes from having them when you need them.
Format¶
Use the standard ADR template:
# NNNN — <Title>
## Status
<Proposed | Accepted | Superseded by NNNN | Folded into <doc> | Deprecated>
## Context
What is the situation that prompts this decision? What forces are at play?
## Decision
What did we decide?
## Consequences
What follows from this decision — good, bad, and neutral?
Filenames are numbered and lowercase-hyphenated: 0001-use-multi-regional-architecture.md, 0002-postgres-as-primary-store.md, etc. Numbers are zero-padded to four digits and assigned sequentially.
Lifecycle¶
- Proposed — open as a PR for team review.
- Accepted — merged. The decision stands.
- Superseded by NNNN — a later ADR replaces this one. The original ADR stays in the repo; only its Status field is updated.
- Folded into
<doc>— the decision still holds, and its durable rule now lives as prose in a FEATURES / SYSTEMS / DATA_MODELS / OPERATIONS doc. The ADR body is thinned to a Context line plus a pointer to that doc, which is the canonical reference. The decision is not reversed or superseded — only its detailed restatement is consolidated into the doc that owns the rule, to keep the ADR set free of duplicated tables and formulas. The original ADR stays in the repo (append-only); only its body and Status are updated. - Distributed-fold: N/M items landed — for a batch/group ADR (multiple named sub-items under one ADR number, e.g. the
Batch N/Group Xseries) where the fold-pass reconciling the ADR against shipped code finds that only SOME of its items match live behavior.Nitems are confirmed live (verified against actual code, not assumed);M − Nremain design intent — flag each as 📐 Design-only at its fold target with the verify-first evidence (grep output / file:line), not silently left implied-shipped by a blanket "Folded" status. Distinct from plain Folded, which implies the whole ADR's content is now live prose elsewhere: a batch ADR is never "wholly Folded" if any of its items are unverified or contradicted by the current codebase — that overclaims the unshipped remainder as much as leaving the whole ADR marked Accepted with no fold at all would. Worked example: 0055 folded intocombat-resolver.mdwith 3 of its 6 items (X-D2, S-V2, S-F2) confirmed live and 3 (S-V3, S-F1, S-F4) corrected to 📐 Design-only after a 2026-08-04 verify-first pass caught the original fold silently asserting all 6 as shipped. - Deprecated — the decision no longer applies, and no replacement is needed.
Distributed-fold exit criterion. A Distributed-fold ADR graduates to plain Folded when its remaining gap between N and M closes to zero by either route, per item — never by re-labeling alone:
1. Ships — the item lands in code and its distributed doc-page citation is updated from 📐 Design-only to reflect shipped reality (verify-first: the same grep / file:line evidence standard the Index row itself already requires), or
2. Gets its own tracked entry — the item is judged intentionally not-building (superseded by a different mechanism, judged out of scope, etc.) and that judgment is recorded as its own BACKLOG.md or DECISIONS.md entry, so the "why not built" reasoning has a durable home independent of this ADR.
Once every one of an ADR's sub-items has cleared by one of those two routes, the distributed doc pages collectively carry 100% of the ADR's canonical description — nothing is left silently asserted-shipped or silently unaccounted-for — and the ADR's Index row flips from Distributed-fold: N/M to plain Folded into <doc(s)>, same as a single-decision ADR. A Distributed-fold ADR is not eligible for this flip merely because its N/M count has been stable across several re-verification passes — a shrinking-but-nonzero gap is still a gap, and "stable" is not "closed."
Re-verification cadence. A Folded or Distributed-fold entry's Index row is a claim about the current codebase, not a one-time assertion — code drifts after the fold pass lands. Periodically re-check a folded/distributed-fold entry's Index row against current code (verify-first: grep / file:line, not assumption), and record the check inline as _(re-verified YYYY-MM-DD)_ appended to the row, matching the tag format already in use throughout the Index below. This is an intentional convention, not incidental session discipline — a row with no _(re-verified …)_ tag has not been re-checked since it was written and should not be trusted as current without doing so first.
ADRs are never deleted. They are the project's decision history.
Index¶
Add an entry below for each accepted ADR. Split 2026-08-05 (WO-CANON-CLEANUP-ADR-README-ARCHIVE-TIER + INDEX-VERIFICATION-ESSAYS): Active rows keep a short open-item pointer; verification essays live in the ADR body / queue, not here. Historical rows are id + title + fold/supersede pointer only.
Active / has open items¶
| # | Title | Status |
|---|---|---|
| 0049 | Player-exploit close-outs (Batch 2) | Distributed-fold (4/6) — SK9 confirmed shipped 2026-08-07; SK13 superseded (DECISIONS.md#adr-0049-sk13-superseded-by-locker-model); SK14 genuine gap, design-only (DECISIONS.md#adr-0049-sk14-salvage-break-lock-design-only) — do not flip to plain Folded until SK14 ships |
| 0050 | Provisioning, generation, and lifecycle hardening (Batch 3) | Distributed-fold (8/10) — SK17/SK18-lock/SK20/SK22-Phase14 + asset cascade shipped; open: region subscription takeover + SK22 owner-relocation offer (re-verified 2026-08-11) |
| 0059 | Governance + citadel-defense fixes (Group I) | Distributed-fold (5/6) — N-V5 grief-detection consumer parked (no producer/consumer yet); tracked DECISIONS.md#adr-0059-n-v5-grief-detection-parked — do not flip to plain Folded until a destroy/disable producer ships |
| 0060 | Pirate ecosystem and holdings hardening (Group A) | Distributed-fold (10/11) — 1 genuine gap: G-V2 (no re-seed mechanism exists to attach the predicate to); tracked DECISIONS.md#adr-0060-g-v2-reseed-race-parked — do not flip to plain Folded until the re-seed mechanism ships |
| 0091 | Site Discovery & Landscape-Driven Citadel Grid | Folded — T3 landscape re-template remainder tracked audit/BACKLOG.md P10-greenfield-landscape-retemplate (⚑ DEFERRED M8, destructive migration) |
| 0092 | ARIA intelligence architecture: the operator arc, dual-brain model, Resonance fuel, and the Antecessor lattice | Split — see 0092a + design-brief for remainder |
| 0093 | Consolidated rulings, 2026-07-10 session | Distributed-fold (37/41) |
| 0095 | — | intentionally unassigned — PR closed before merge |
| 0096 | Bring-your-own-ARIA | Proposed — gated on an automation-policy ruling (deferred design session 13) |
Fully folded — historical record¶
| # | Title | Status |
|---|---|---|
| 0055 | Destruction-handler composition (Group D) | Folded into SYSTEMS/combat-resolver.md + SYSTEMS/bounty-and-reputation.md — 6/6 closed (re-verified 2026-08-11) |
| 0094 | API-first playability | Folded into README design-pillars + this ADR body — points 1–3 closed; genesis twin residual retired (sole deploy POST /planets/genesis/deploy) (re-verified 2026-08-17 tip 02c99117, LEG-258) |
| 0001 | Use multi-regional architecture | Folded into multi-regional.md (re-verified 2026-08-06) |
| 0002 | Terraforming formula model | Folded into terraforming.md (re-verified 2026-08-06) |
| 0003 | Personal reputation tier system | Folded into ranking.md (re-verified 2026-08-06) |
| 0004 | Continuous turn regeneration | Folded into turns.md + turn-regeneration.md (re-verified 2026-08-06) |
| 0005 | Capital Sector and compound sector identity | Folded into galaxy.md (re-verified 2026-08-06) |
| 0006 | Galaxy evolution = region attachment only | Folded into galaxy.md (re-verified 2026-08-06) |
| 0007 | Cargo Wreck mechanic | Folded into ships.md (re-verified 2026-08-06) |
| 0008 | Ship Registry overhaul | Folded into ship-registry.md (re-verified 2026-08-06) |
| 0009 | Quantum Crystal assembly venue split | Folded into quantum-resources.md (re-verified 2026-08-06) |
| 0052 | Cross-system contradictions (Batch 5) | Folded into ship-registry.md + warp-gates.md (re-verified 2026-08-10) |
| 0010 | Warp gate cap formula | Folded into warp-gates.md (re-verified 2026-08-06) |
| 0011 | Warp gate invulnerability window | Folded into warp-gates.md (re-verified 2026-08-06) |
| 0012 | Genesis tier pricing | Folded into genesis-devices.md (re-verified 2026-08-06) |
| 0013 | Advanced Genesis consumption model | Folded into genesis-devices.md (re-verified 2026-08-06) |
| 0014 | Genesis planet-type taxonomy | Folded into genesis-devices.md (re-verified 2026-08-06) |
| 0015 | Solo Genesis no sector lock | Folded into genesis-devices.md (re-verified 2026-08-06) |
| 0016 | Per-player ARIA, no aggregate ML | Folded into aria-companion.md (re-verified 2026-08-06) |
| 0017 | ARIA Consciousness Level 1–5 scale | Folded into aria-companion.md (re-verified 2026-08-06) |
| 0018 | Faction reputation action deltas | Folded into factions-and-teams.md; mission-completion entries superseded by 0032 (re-verified 2026-08-06) |
| 0019 | Faction reputation decay rule | Folded into factions-and-teams.md (re-verified 2026-08-06) |
| 0020 | Pirate spawn / encounter mechanics | Folded into faction-lore.md (re-verified 2026-08-06) |
| 0021 | Territory taxonomy and influence math | Folded into factions-and-teams.md (re-verified 2026-08-06) |
| 0022 | Rank progression gate model | Folded into ranking.md (re-verified 2026-08-06) |
| 0023 | Turn-cap source canonicalization | Folded into turns.md (re-verified 2026-08-06) |
| 0024 | Personal reputation 8-tier scheme | Folded into ranking.md (re-verified 2026-08-06) |
| 0025 | Personal reputation decay scope | Folded into ranking.md (re-verified 2026-08-06) |
| 0026 | First login fundamentals | Folded into first-login.md (re-verified 2026-08-06) |
| 0027 | Flat is_admin, RBAC dropped | Superseded by 0058 (re-verified 2026-08-06) |
| 0028 | Medal storage as association table over JSONB | Folded into medal-service.md (re-verified 2026-08-06) |
| 0029 | Warp Jumper consumption at gate creation | Folded into warp-gates.md (re-verified 2026-08-06) |
| 0030 | Quantum Jump multi-step commit | Folded into movement.md (re-verified 2026-08-06) |
| 0031 | Long-range scanner fuzzy disclosure | Folded into sectors.md (re-verified 2026-08-06) |
| 0032 | Emergent reputation action set | Folded into factions-and-teams.md (re-verified 2026-08-06) |
| 0033 | Astral Mining FactionType promotion | Folded into gameplay.md (re-verified 2026-08-06) |
| 0034 | One-way warp tunnel design | Folded into special-formations.md (re-verified 2026-08-06) |
| 0035 | Dual-ceiling population model (citadel-bound vs habitability-bound) | Folded into colonization.md (re-verified 2026-08-06) |
| 0036 | Phase 3 harmonization atomicity split (HARMONIZING ship status) | Folded into warp-gates.md (re-verified 2026-08-06) |
| 0037 | Lumen Crystal supply economy | Folded into quantum-resources.md (re-verified 2026-08-06) |
| 0038 | ARIA observation-log learning model (Trade DNA retired) | Folded into aria-companion.md (re-verified 2026-08-06) |
| 0039 | TradeDock resource atomicity on cancellation | Folded into tradedock-shipyard.md (re-verified 2026-08-06) |
| 0040 | Quantum Jump from Carrier hangar rejection | Folded into sectors.md (re-verified 2026-08-06) |
| 0041 | TradeDock seeding at galaxy generation (Phase 10.5) | Folded into galaxy-generation.md (re-verified 2026-08-06) |
| 0042 | Police engagement spawn-delay mechanism | Folded into police-forces.md (re-verified 2026-08-06) |
| 0043 | Region ↔ Nexus connection is a natural warp in the Frontier outer reaches | Folded into region-lifecycle.md (re-verified 2026-08-06) |
| 0044 | Cluster and Special-Formation naming convention | Folded into galaxy.md (re-verified 2026-08-06) |
| 0045 | Per-player ARIA-driven warp knowledge database | Folded into aria-companion.md (re-verified 2026-08-06) |
| 0046 | Forbid Warp Sink inside Bubble (worldgen invariant) | Folded into special-formations-generation.md (re-verified 2026-08-06) |
| 0047 | Pirate Holdings: pre-seeded hostile sites in the Frontier | Folded into pirate-holdings.md (re-verified 2026-08-06) |
| 0048 | Pirate ecosystem dynamics: self-regulating population | Folded into pirate-ecosystem.md (re-verified 2026-08-06) |
| 0051 | Scale targets and performance commitments (Batch 4) | Folded into multi-regional.md / galaxy-generator-design.md / sector-presence.md / realtime-bus.md / DATA_MODELS/player.md (SK32 shipped) (re-verified 2026-08-07) |
| 0053 | Runtime services (Batch 6) | Folded into quantum-depletion-service.md, anchor-repair-service.md, special-formations-generation… (re-verified 2026-08-06) |
| 0054 | Region-lifecycle composition (Group B) | Folded into region-lifecycle.md, ship-registry.md, monetization.md, realtime-bus.md (6/6 shipped) (re-verified 2026-08-07) |
| 0056 | Reputation composition + multi-account detection (Group G) | Folded into factions-and-teams.md, message-beacons.md, regional-governance.md, player.md, multi-a… (re-verified 2026-08-06) |
| 0057 | ARIA security, cost, and isolation invariants (Group L) | Folded into OPERATIONS/aria.md (A-D1 rate limits, A-V1 layered injection defense incl. 0093-item-… (re-verified 2026-08-06) |
| 0058 | Monetization, admin, webhook security (Group M) | Folded into OPERATIONS/monetization.md (A-D3 webhook validation incl. code-wins env-var correctio… (re-verified 2026-08-06) |
| 0061 | Combat correctness and rank wiring (Group C) | Folded into SYSTEMS/combat-resolver.md, FEATURES/gameplay/{ranking,ships,ship-insurance}.md. Both… (re-verified 2026-08-06) |
| 0062 | Economy: tariffs, contracts, and market-data hardening (Group F) | Folded into market-pricing.md, contracts.md, black-market.md, bang-integration.md, economy.md, mi… (re-verified 2026-08-06) |
| 0063 | NPC scheduler and lifecycle hardening (Group H) | Folded into npc-scheduler.md, npc-lifecycle.md (re-verified 2026-08-06) |
| 0064 | Worldgen pipeline cleanup (Group J) | Folded into galaxy-generator-design.md (re-verified 2026-08-06) |
| 0065 | Schema and data-model parity (Group K) | Folded across DATA_MODELS/, FEATURES/, OPERATIONS/ (16/16; last ghost ref fixed 2026-08-04) (re-verified 2026-08-06) |
| 0066 | Doc philosophy compliance (Group N) | Folded (re-verified 2026-08-06) |
| 0067 | Tractor / tow / Quantum Jump composition (Group E) | Folded into sectors.md, ships.md (re-verified 2026-08-06) |
| 0068 | Player experience and ARIA narration hooks (Group O) | Folded into aria-companion.md (re-verified 2026-08-06) |
| 0069 | Bang produces fully-formed region snapshots | Folded into bang-import-pipeline.md (re-verified 2026-08-06) |
| 0070 | Lost clusters and archipelagoes: graph-disconnected formations reachable only via Quantum Jump | Folded into special-formations.md (re-verified 2026-08-06) |
| 0071 | Four-tag version filter: Live, Current, Release, Future | Folded into CONTRIBUTING.md §Phase tags, tags.md (re-verified 2026-08-06) |
| 0072 | ARIA course plotting, autopilot, and the chart knowledge economy | Superseded by 0092 (re-verified 2026-08-06) |
| 0073 | Sector celestial composition & planet discovery/naming | Folded into star-systems.md (re-verified 2026-08-06) |
| 0074 | NPC trader economy | Folded into npc-traders.md (re-verified 2026-08-06) |
| 0075 | ARIA route intelligence scope | Folded into aria-companion.md (re-verified 2026-08-06) |
| 0076 | Planetary defense unit pricing | Folded into defense.md (re-verified 2026-08-06) |
| 0077 | Faction mission completion | Superseded by 0090 (re-verified 2026-08-06) |
| 0078 | Warp-gate staged construction | Folded into warp-gates.md (re-verified 2026-08-06) |
| 0079 | Haggling numerical model | Folded into FEATURES/economy/haggling.md (re-verified 2026-08-06) |
| 0080 | Siege resolution | Folded into defense.md (re-verified 2026-08-06) |
| 0081 | Ship insurance premium pricing | Folded into ship-insurance.md (re-verified 2026-08-06) |
| 0082 | Citadel safe commodity valuation | Folded into citadels.md (re-verified 2026-08-06) |
| 0083 | Armored mine combat model | Folded into combat.md (re-verified 2026-08-06) |
| 0084 | Planetary registration tiers & registry lookup | Folded into genesis-devices.md (amended by 0091) (re-verified 2026-08-06) |
| 0085 | OAuth tokens out of the redirect URL via single-use code exchange | Folded into auth.md (re-verified 2026-08-06) |
| 0086 | Shield-generator build hours | Folded into citadels.md (re-verified 2026-08-06) |
| 0087 | Colony specialization affects defense & research | Folded into FEATURES/planets/colonization.md (re-verified 2026-08-06) |
| 0088 | Genesis deploy restrictions ratified | Folded into genesis-devices.md (amended by 0091) (re-verified 2026-08-06) |
| 0089 | Player-to-player direct trading | Folded into player-trading.md (re-verified 2026-08-06) |
| 0090 | Faction reputation is emergent-only | Folded into factions-and-teams.md (re-verified 2026-08-06) |
| 0092a | ARIA data index and dual-brain architecture (shipped substrate, split from 0092) | Folded into aria.md §2 and aria-data-index.md (re-verified 2026-08-07) |
Cross-linking¶
When a SYSTEMS/, OPERATIONS/, ARCHITECTURE/, or FEATURES/ doc rests on an ADR, link to the ADR from that doc. Conversely, ADRs may reference the docs they constrain. See CONTRIBUTING.md → "Cross-linking rules" for the path conventions.