SYSTEMS

Prescriptive subsystem specifications. Each doc here describes the target design of a single subsystem: the algorithm, the state machine, the chain of operations triggered by an event, the invariants the system must hold, and the failure modes it has to handle.

How SYSTEMS differs from the other sections

Section	Question it answers
DATA_MODELS/	What columns and relationships exist?
FEATURES/	What does the player experience and what is the implementation status?
ARCHITECTURE/	What services, processes, networks, and deployments make up the system?
OPERATIONS/	What are the running pieces (UIs, AI assistant, infra) and how are they operated?
SYSTEMS/	When event X happens, what is the chain of operations? What state changes? What invariants hold? What are the failure modes?

Conventions

• Each system doc is prescriptive — written in present tense, describing the target design ("the resolver applies damage in this order…"), not the current code state.
• Source-map tables list the target locations for the responsible code.
• Cross-links use repo-relative paths (e.g. ../DATA_MODELS/combat.md).
• Implementation status (drift from these specs, known bugs, partial coverage) is tracked inline in the matching FEATURES/ file using ✅ / 🚧 / 📐 / 🐛 markers — never here.

Index

The 20 system specs are grouped by subject area — mirroring the topical grouping in the Features tab. Each system spec describes the target lifecycle / state machine / invariants for one subsystem; cross-link to the matching Features doc for the player-facing rules.

Onboarding & Progression

System	One-liner
first-login.md	First-login state machine for ship claim, dialogue evaluation, and Player record creation.
turn-regeneration.md	Lazy turn-pool refill driven by elapsed time, ARIA multiplier, and rank cap.
medal-service.md	Award dispatcher: gameplay event → catalog match → idempotent grant → realtime broadcast → admin tools.
bounty-and-reputation.md	Personal-reputation deltas, automatic system bounties, bounty placement, collection-on-kill.

Combat & Fleets

System	One-liner
combat-resolver.md	Phased combat pipeline: initiation, drone screen, ship-vs-ship, cleanup, post-combat hooks.
fleet-coordination.md	Fleet state machine, formation modifiers, morale/supply tick, role-based combat contribution.
ship-registry.md	Registration, theft reports, abandonment, peer-to-peer sale, manual eject + board.

Galaxy

System	One-liner
galaxy-generator-design.md	Architectural blueprint — pulls every constraint (ADRs, DECISIONS, feature docs) into one phased pipeline a future implementer can build directly from. Sits above galaxy-generation.md.
galaxy-generation.md	Implementation-side pipeline from galaxy metadata down to seeded sectors, stations, planets, and warp graph.
special-formations-generation.md	Stamping pipeline for graph-topology formations (Bubbles, Tunnels, Dead-Ends, Blisters) — anchor selection, template stamping, validation, rarity controls.
central-nexus-clusters.md	20-cluster thematic overlay for Central Nexus: sector ranges, cluster-type biases, gateway plaza role.
sector-presence.md	Sector occupancy tracking, encounter rolls on entry, tunnel events, broadcast on join/leave.
course-plotting.md	Min-time route computation over the player's known graph (visited ∪ corp-shared ∪ current sector); the plot half of ARIA's autopilot.
npc-lifecycle.md	Unified NPC framework: 9 archetypes (police, traders, faction leaders, etc.), schedule mechanism (8h shifts / off-duty / sleep), career progression (recruit → senior → decorated → retired/KIA), succession on death/retirement. NPCs aren't 24/7 automata; they live full days like players do.
npc-scheduler.md	Runtime that executes the lifecycle: schedule executor (Loop A), roster maintenance (Loop B), engagement routing, KIA processing, off-duty rotation.
bang-import-pipeline.md	End-to-end translator from sw2102-bang Universe JSON into the gameserver multi-region schema.

Economy

System	One-liner
market-pricing.md	Supply/demand pricing, transaction settlement, market-history snapshots, price-alert evaluation.

Planets

System	One-liner
genesis-deploy.md	Genesis-device pre-flight, formation timer, planet creation, failure modes.
planetary-production-tick.md	Per-tick planet production: colonist consumption, resource generation, citadel multipliers.
citadel-grid.md	Landscape-driven citadel grid: at-settle generation pipeline, shape classes, three-channel cap, progressive reveal, template library invariants. (ADR-0091)

Governance

System	One-liner
regional-governance.md	Election scheduling, policy proposal/voting/enactment, treaty negotiation.

AI & Realtime

System	One-liner
aria-dialogue.md	ARIA conversation flow: sanitization, intent, multilingual routing, tool invocation, audit.
realtime-bus.md	WebSocket event bus: auth handshake, room model, presence, broadcast/unicast, reconnection.