Skip to content

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 X series) where the fold-pass reconciling the ADR against shipped code finds that only SOME of its items match live behavior. N items are confirmed live (verified against actual code, not assumed); M − N remain 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 into combat-resolver.md with 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)
0097 LEG-1137 leaderboard medals — GS payload gap Proposed — LEG-DEC-443 WO-ADR-006 materialize (adr_id=5)
0098 Authorize GS personal WebSocket topic ownership (LEG-454) Proposed — LEG-DEC-214 WO-ADR-006 materialize (adr_id=6)
0099 Authorize PC RegisterForm invite_code work (auth-gated record) Proposed — LEG-DEC-224 WO-ADR-006 materialize (adr_id=7)
0100 [Draft initiative · Gameserver] Enforce ownership for personal WebSocket topics Proposed — LEG-DEC-225 WO-ADR-006 materialize (adr_id=8)
0101 Authorize GS canon regional RBAC enforcement draft Proposed — LEG-DEC-226 WO-ADR-006 materialize (adr_id=9)
0102 Authorize /auth/mfa/* work (auth/MFA record only) Proposed — LEG-DEC-236 WO-ADR-006 materialize (adr_id=10)
0103 Materialize ADR/decision files for LEG-DEC-228 Proposed — LEG-DEC-237 WO-ADR-006 materialize (adr_id=11)
0104 Authorize bang-integration honesty work (ore/CLI/env; not density pin) Proposed — LEG-DEC-259 WO-ADR-006 materialize (adr_id=12)
0105 Authorize feat→master slice-1 unrelated-histories GO (LEG-629) Proposed — LEG-DEC-381 WO-ADR-006 materialize (adr_id=13)
0106 Materialize ADR/decision files for LEG-DEC-399 Proposed — LEG-DEC-433 WO-ADR-006 materialize (adr_id=14)
0107 Materialize ADR/decision files for LEG-DEC-213 Proposed — LEG-DEC-434 WO-ADR-006 materialize (adr_id=15)
0108 Authorize PC region-invite /join work (auth-gated record) Proposed — LEG-DEC-435 WO-ADR-006 materialize (adr_id=16)
0109 Defer Admin Gold Bubble placement UI pending GS place_gold_bubble Proposed — LEG-DEC-34 WO-ADR-006 materialize (adr_id=17)
0110 Pin Bang --density enforcement semantic Proposed — LEG-DEC-120 WO-ADR-006 materialize (adr_id=18)
0111 Authorize GS cleanup_completed_at stamp after live station terminate Proposed — LEG-DEC-438 WO-ADR-006 materialize (adr_id=19)
0112 Materialize ADR/decision files for LEG-DEC-443 Proposed — LEG-DEC-445 WO-ADR-006 materialize (adr_id=20)
0113 Materialize ADR/decision files for LEG-DEC-214 Proposed — LEG-DEC-455 WO-ADR-006 materialize (adr_id=21)
0114 Materialize ADR/decision files for LEG-DEC-224 Proposed — LEG-DEC-456 WO-ADR-006 materialize (adr_id=22)
0115 Build missing admin.subscriptions. / admin.webhooks. surfaces Proposed — LEG-DEC-104 WO-ADR-006 materialize (adr_id=23)
0116 Materialize ADR/decision files for LEG-DEC-225 Proposed — LEG-DEC-457 WO-ADR-006 materialize (adr_id=24)
0117 Materialize ADR/decision files for LEG-DEC-226 Proposed — LEG-DEC-458 WO-ADR-006 materialize (adr_id=25)
0118 Materialize ADR/decision files for LEG-DEC-236 Proposed — LEG-DEC-459 WO-ADR-006 materialize (adr_id=26)
0119 Materialize ADR/decision files for LEG-DEC-237 Proposed — LEG-DEC-460 WO-ADR-006 materialize (adr_id=27)
0120 Materialize ADR/decision files for LEG-DEC-443 Proposed — LEG-DEC-470 WO-ADR-006 materialize (adr_id=28)
0121 Materialize ADR/decision files for LEG-DEC-214 Proposed — LEG-DEC-471 WO-ADR-006 materialize (adr_id=29)
0122 Materialize ADR/decision files for LEG-DEC-224 Proposed — LEG-DEC-472 WO-ADR-006 materialize (adr_id=30)
0123 Pin sw2102-docs adr_path before materializing unanswered LEG-DEC-228 Proposed — LEG-DEC-238 WO-ADR-006 materialize (adr_id=38)
0124 Keep GS #2138 blocked until a trade-pact filing surface exists Proposed — LEG-DEC-397 WO-ADR-006 materialize (adr_id=39)
0125 Admin UI #276 ARIA per-player security-ops: park vs GS-first vs comb Proposed — LEG-DEC-474 WO-ADR-006 materialize (adr_id=40)
0126 Record LEG-DEC-475 option A (diameter) without pinning bang-integration.md Proposed — LEG-DEC-475 WO-ADR-006 materialize (adr_id=41)
0147 Region takeover Phase 0 threat review authorization (LEG-286) Proposed — LEG-DEC-851 WO-ADR-006 materialize (adr_id=67)
0148 Max GO merge sw2102-docs honesty PRs #68 and #70 Proposed — LEG-DEC-852 WO-ADR-006 materialize (adr_id=68)
0149 Max GO merge sw2102-docs PR #70 monetization GC routes Proposed — LEG-DEC-854 WO-ADR-006 materialize (adr_id=69)
0150 Max GO merge sw2102-docs PR #72 tip re-stamps Proposed — LEG-DEC-858 WO-ADR-006 materialize (adr_id=71)
0151 Max GO merge sw2102-docs PR #70 GC Admin UI panel Proposed — LEG-DEC-855 WO-ADR-006 materialize (adr_id=70)
0152 Max GO merge sw2102-docs closer batch #74/#75/#84/#86 Proposed — LEG-DEC-872 WO-ADR-006 materialize (adr_id=72)
0153 Requeue LEG-3677 ADR materialization Proposed — LEG-DEC-883 WO-ADR-006 materialize (adr_id=73)
0154 PC raid UI blocked until GS holding_id discovery (LEG-DEC-955) Proposed — LEG-DEC-955 WO-ADR-006 materialize (adr_id=74)
0155 Authorize GS contract anti-griefing blocklist + pairwise hostility (LEG-3994) Proposed — LEG-DEC-905 WO-ADR-006 materialize (adr_id=75)

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.