Planetary Survey & Site Discovery

Founding a colony on a planet is not automatic. A planet's landscape is explored by expedition, and where you settle determines your colony's grid shape, usable slot count, energy baseline, resource access, habitability, and hazard load. Surveying and choosing where to settle is the mandatory first act of founding — and on a freshly-formed or unclaimed world it is a contested race: ownership attaches at the moment of settle, and the first to settle claims the world.

📐 Design-only. The whole survey/site-discovery system is specified here and gated on ADR-0091. No production code exists yet. The grid-shape and citadel-cap consequences live in citadels.md and ../../SYSTEMS/citadel-grid.md.

Discovery is the mandatory first act

Founding a colony requires running the discovery loop: you run a ground expedition, receive a landscape result, and settle on it. There is no zero-effort default colony — the missing exploration beat is now required, not opt-in. To keep "mandatory" from ever hard-blocking a player, the hard-pity floor (below) guarantees the loop can always eventually reach a successful result, and the magnitude is bounded.

📐 Design-only [P]. Settling requires at least one successful ground expedition result on this planet — an orbital scan triages but cannot settle — so discovery is genuinely mandatory rather than a skippable scan (M36).

Onboarding accommodation

A player's first colony runs through the same loop, but comped (colony #1 only, M35), so a newcomer is taught rather than walled:

• The comped first expedition returns a guaranteed-GOOD result (M38): ≥12 slots, decent ceiling, sev-0 hazards, native energy present, ≥1 T1–T2 deposit — structurally good, not faucet-multiplying.
• Expedition cost is waived and the risk roll is forced to SUCCESS for the comped step.
• 2–3 free demo expeditions at zero stakes (M39) teach the re-roll/compare mechanic before the real founding commitment.
• The starter planet's contestable window is suppressed (M40) — it is a sovereign reserved planet (reserved_for_player_id), non-snipeable, so a brand-new player cannot be claimed out.
• A scripted Survey Officer guides the onboarding loop in v1 (M43 ⚑; ARIA-voiced only post-v1 behind AI-safety sign-off).
• ~5-min TTFC target (M44) + an optional one-click assisted-settle (offered-never-auto; still runs a real expedition, honoring R1).

📐 Design-only. After onboarding completes (the first self-founded colony), the loop runs at full cost, risk, and contestability. The comp teaches the loop before it bites.

The discovery loop

arrive → orbital scan → ground expedition(s) → compare → SETTLE (= claim) → Grid Manager

The at-launch expedition model

Each expedition generates its result at launch — there are no pre-stored candidate sites and no concept of "the same site" across two runs. Every expedition is a fresh roll. The planet's profile (type, size, characteristic hazard, terrain) weights what the roll is likely to return (M12): a VOLCANIC planet skews toward COMPACT/IRREGULAR shapes and Geothermal energy; a TERRAN planet skews toward SPRAWLING and balanced traits.

The loop is re-roll-until-satisfied: launch → result → ACCEPT (settle on this result's grid) or re-roll (launch another expedition; costs another round of turns + credits). Casuals take the first or second result; min-maxers keep rolling for the best. Only the SETTLED result persists as the colony's grid. Expedition results before settlement are ephemeral — they are not banked long-term per planet per player.

Two-tier information economy

📐 Design-only [P].

Tier	Cost	Returns
Orbital Scan	free, instant, repeatable	presents the planet as a rendered continent with candidate spot markers (dots) for the player to select where to dispatch an expedition. Spot markers carry cosmetic/suggestive differentiators — these are presentational only and do not tie to any underlying data. The expedition result is an RNG roll at launch regardless of which spot is chosen. Orbital scan provides the UI dispatch point, not real site data.
Ground Expedition	turns + credits [P]; optional short EXPEDITION_DELAY_MINUTES (default 10, env-tunable, not a hard gate)	a landscape result at-launch: shape, slots, energy, resources, native-life risk, hazards on SUCCESS; banded/uncertain information on PARTIAL; nothing on FAILURE.

Turns are the primary scarcity lever; the optional real-time delay is decoupled flavor texture. No survey-kit consumable in v1 (M49) — expeditions cost turns + credits only.

Risk and pity

📐 Design-only [P]. The outcome roll is weighted by the planet's radiation_level, temperature extremes, and the NEW additive native_life column (M54 — does not exist in the live codebase today; additive column to add). Hostile worlds are genuinely costlier to explore.

• Outcomes: SUCCESS / PARTIAL / FAILURE. Benign baseline 85 / 12 / 3 [P]; hazard and native-life shift mass toward PARTIAL then FAILURE.
• SUCCESS → a complete decision-grade landscape result.
• PARTIAL → banded/uncertain information on grid potential, hazards; deep-only fields undetected.
• FAILURE → turns and credits spent (M19); no usable intel returned. The area was not successfully explored. Nothing is stored.
• Hard pity (M20): K consecutive FAILED expeditions → forced SUCCESS (K = 4–5 [P], ground-tier only, general-population). Anti-lockout; the forced SUCCESS yields only the decision-grade result with no bonus reward.
• Native-life encounter (gated by the new native_life column): at minimum surfaces indigenous life as a special; at most shifts the outcome to PARTIAL/FAILURE.

Cost, concurrency, and re-rolling

📐 Design-only [P].

• Expeditions launch from a ship in orbit in the planet's sector.
• Per-player global concurrency cap: 3 expeditions in flight [P] (across all planets).
• Re-rolling means launching another expedition after receiving a result you do not want to accept. Each re-roll costs the same base expedition price — there is no escalating cost, because there is no "same site" to repeatedly scout. The cost is the competitive stake.
• Onboarding is comped (see above): the first colony's expedition cost is waived.

Three-tier no-dead-end floor (M37): 1. Soft: credits refunded on FAILURE. 2. Hard pity: K consecutive FAILUREs → forced SUCCESS (M20). 3. Rescue charge: stranded-detection one-time emergency comp for new players.

The Expedition Result (Site Intel)

📐 Design-only. Delivered as an ephemeral landscape result when the expedition resolves — shown via an expedition_complete event (a notification, not a presence requirement; an offline player sees results on next login). Expedition results before settlement are not banked long-term.

#	Field	Detail
1	Location identity	region name, coords, terrain/landscape type
2	Grid potential	shape class + usable slot count (exact on SUCCESS, banded on PARTIAL) + starting slots on settle; cell layout stays fogged until placed
3	Citadel energy source	type + magnitude
4	Natural resources	site-local deposits + the production multipliers they confer (captured only by the matching economy building on the deposit plot)
5	Defensibility	terrain modifiers — informational-only in v1 (see defense.md)
6	Hazards	site-specific ongoing risks
7	Special features	the wonder tier (deep-intel / rare) — deferred to the post-combat phase
8	Suitability summary	at-a-glance role tags for fast comparison

The site-trait system

A result's intel is a roll of traits drawn against a point budget (benefits spend, drawbacks refund), each resolving onto a mechanic the game already has. The planet profile weights the roll distribution.

Categories — v1 vs. deferred

📐 Design-only.

Cat	Trait	v1?	Hook
A	Grid Form & Capacity	v1	shape class × multiplier band → usable slots (see citadels.md)
B	Energy Sources	v1 (4 common)	native power supply, a flat early-only baseline (outgrown by a built-out colony's draw; NOT a late-game scaling source — M6)
C	Resource Deposits	v1	per-plot terrain_bonus, capped at the existing 0.30 ceiling (no new faucet — M47); deposit depletion ships v1
F	Habitability & Life-support	v1	modifies habitability_score (→ max_population, growth) + seeded plot axes
G	Hazards & Drawbacks	v1	one-time clear cost / chronic upkeep tax / stochastic event — the primary live drawback
D	Logistics soft-modifiers	deferred	architecture present, content withheld until the combat seam
E	Defensibility-as-live-axis	deferred	informational-only until the combat math (T2) ships
H	Legendary Wonders	deferred	≤1/site; held until post-combat; region-rationed when shipped

Energy sources (v1)

📐 Design-only [P]. Native supply is a flat early-game baseline — eases the early power burden but is outgrown by a built-out colony's draw. ABUNDANT capped flat (M6). Typically ≤1 source per result.

Source	Mechanic	Native baseline (T1/T2/T3/T4)	Affinity
Geothermal Vents	flat + POWER_PLANT bonus on volcanic/highland	40 / 120 / 300 / 600	volcanic, mountainous
Tidal Flux	scales with hydro axis	40 / 110 / 260 / 480	oceanic
Solar Flats	high cap, day/night variance	50 / 130 / 300 / 560	desert, barren
Wind Corridors	moderate, terrain/season	30 / 90 / 200 / 380	ice, arctic, highland

The rare/legendary sources (Fusion Seam, Aurora Node, Cryo-Thermal, Leyline) ship with the deferred wonder tier.

Magnitude, rarity, and the trait budget

📐 Design-only [P].

Tier	production_mult add	plot swing	native power	hazard	habitability
T1	±0.05–0.10	±1	~40	sev-1 clear-only	±3–5
T2	±0.15–0.20	±2–3	~120	sev-2 clear/chronic	±6–10
T3	±0.25–0.30 (capped at the live 0.30)	±4–6	~300	sev-3 chronic	±12–18
T4	0.30 (no exceed)	large	~600	sev-3 chronic/stochastic	±20+

Rarity weights: Common ~62% (T1–T2), Uncommon ~28% (T2–T3), Rare ~10% (T3). Legendary/wonders not rolled in v1.

Every result rolls a trait budget in points — benefits spend, drawbacks refund. Variance is bounded both ways: worst-case stays playable (the floor guarantee), best-case is structural, not faucet-multiplying, so no result is game-winning on economy alone.

Per-planet-type envelope

📐 Design-only [P]. The planet type sets the trait envelope and shape distribution; each expedition rolls within that envelope. On mono-output worlds (VOLCANIC/BARREN), the roll cannot change what you produce — only slots/shape/energy/hazard/habitability.

Type	Shape weights	Favored energy	Favored deposits	Hazards	Habitability
VOLCANIC	COMPACT 55 / IRREGULAR 35 / TERRACED 10	Geothermal	sulfur/fuel, rare-earth — never organics	Magma Surge, Seismic	low
OCEANIC	LINEAR 50 / IRREGULAR 35 / COMPACT 15	Tidal	Hydrocarbon Sea, Delta	Flood, Storm	mid–high
DESERT	SPRAWLING 60 / LINEAR 30 / COMPACT 10	Solar, Wind	Silicate (equip), Deep Ore	Diurnal Swing, Dust Storm	low–mid
MOUNTAINOUS	TERRACED 55 / COMPACT 35 / LINEAR 10	Geothermal, Wind	Rare-Earth (equip), Ore	Seismic, Avalanche	mid; top defensibility (informational)
BARREN	IRREGULAR 55 / COMPACT 35 / LINEAR 10	Solar	Metallic — only equip/fuel	Radiation, Micrometeor	~0
ICE / ARCTIC	COMPACT 50 / TERRACED 30 / LINEAR 20	Wind	Ice-Volatiles (fuel)	Permafrost, Blizzard	low–mid
JUNGLE / TROPICAL	SPRAWLING 50 / IRREGULAR 40 / TERRACED 10	Solar	Bio-Luminous, Mycelial	Megafauna (high), Flood	high
TERRAN (hub)	SPRAWLING 70 / TERRACED 30	balanced	balanced	minimal	max — capital hub
GAS_GIANT	uncolonizable, no expeditions	—	—	—	—
ARTIFICIAL	ENGINEERED 100	—	engineered	structural decay	engineered

Compare and settle

📐 Design-only.

When you have a successful expedition result you are happy with, the Survey Ledger shows the result alongside any other recent expedition results still available for comparison (before settlement, ephemeral results can be compared across your recent runs). Columns cover usable slots, shape class, energy, sprawl tax, hazard, habitability, production, and (informational only) defensibility.

SETTLE is the commit act and the ownership-claim transaction:

• Consumes the colonization requirements — settling is colonization (the pioneer/founding grant, or the genesis grant — see colonization.md).
• Claims the world — on a contestable planet, the first valid SETTLE claims ownership and ends the contest (see Contested settle, below).
• Requires a successful ground expedition result on this planet held by your account (M36) — orbital scan alone cannot settle.
• Materializes the citadel grid from the expedition result's rolled landscape, seeded fully server-side by structures.py (single writer).
• Places L1, reveals the initial tranche; the remainder reveal atomically per upgrade completion (see citadels.md).
• Marks the planet COLONIZED / Outpost. Other expedition results from other runs are discarded.
• Irreversible — paired with buyable pre-commit certainty (re-rolling until satisfied), the floor guarantee, and an honest guaranteed-max-citadel-level display (C_practical, the achievable floor) so it is weight without gotcha. Abandon-the-whole-planet is the only exit.

After settlement, LAND works and the survey UI yields to the existing Grid Manager.

Contested settle (the claim race)

📐 Design-only [P]. On any contestable world (freshly-formed or existing-unclaimed — M28 RETROACTIVE), ownership attaches at settle, not at formation or genesis-deploy. Until the first valid settle, the planet is in a contestable window: eligible players may run expeditions and race to settle. Onboarding starter planets are exempt (their window is suppressed).

Rule	v1 behaviour (MAX-RULINGS canonical)
Who attaches ownership	the player who commits the first valid SETTLE (atomic CAS)
Eligibility	ADR-0056 real-player gates (anti-sybil) + ADR-0088 rep-tier / distance / ≤25%-region budget. No payment gate (M24/M27 CANON)
Retroactive scope	existing unclaimed worlds also become contestable (M28 CANON); CAS resolver replaces first-come /claim; additive migration (galaxy is empty pre-launch — no player communications required)
Genesis-deployer priority	a deployer gets a settle-only head-start (rivals may still run expeditions during priority): 3h default / 24h for paid subscribers (M23 REVISED CANON, narrow firewall exception)
Contest visibility	set by the deployer at genesis-deploy via registration tier (M26b CANON): Clandestine = HIDDEN from formation (rivals must purchase the paid black-market registry-lookup per ADR-0084 to find and contest); Registered/Chartered = visible + free-to-contest immediately from deploy
Resolution	atomic first-valid-settle (CAS) — decided by intel speed + turn/credit readiness; no combat interdiction in v1
Loser relief	ZERO (M25 CANON) — the expedition cost is the competitive stake; losing the race is a genuine loss
Claim granularity	first settle claims the whole planet; per-site multi-tenancy is deferred
Contestable window	planet stays UNSETTLED (fully contestable) indefinitely until the first valid settle (M22 RESOLVED); no LAPSED_DORMANT state, no decay timer; a world unsettled for >24h may receive a cosmetic "dormant" UI label with no state-machine effect

📐 Design-only. The advanced genesis tier (see ../galaxy/genesis-devices.md) under the at-launch model: advanced-genesis tiers buy a probabilistically better outcome scaling by tier — better planet location (more likely in the habitable zone), larger size, better expedition rolls (weighted toward high-slot/high-habitability outcomes), more resources, higher habitability. Higher tier = higher probability across all these axes; no outcome is guaranteed. The old "free survey of all N sites" framing is MOOT (GAP-2 resolved in ADR-0091).

Exploit guards

📐 Design-only [P].

• Re-rolling is the intended mechanic — every expedition is a fresh roll by design. The anti-exploit is M19 (FAILURE = no intel, costs turns and credits), making blind grinding net-negative.
• Hard pity (M20) limits consecutive failures to K attempts; the forced SUCCESS yields no bonus reward, so the floor cannot be farmed for intel.
• Expeditions grant no standalone reward — no RP/XP/medals/loot; the reward is the information. Remove the CRT +50 RP survey grant (the expedition-as-reward-farming anti-pattern).
• Settle-griefing (a rival cheaply settling purely to deny) is bounded by the ADR-0056/ADR-0088 eligibility gates + the deployer priority window (M23). A spite-settler becomes the real owner (full cost + registration, irreversible, counts against their ≤25% region cap).
• Zero loser relief (M25) means there is no relief-farming vector.
• No relief between ADR-0056 linked accounts (Amendment A to ADR-0056).

Source map

Topic	Path
At-launch expedition result + grid bake	services/gameserver/src/services/structures.py
Expedition lifecycle	services/gameserver/src/models/ (expeditions — additive table)
Contestable window + claim state	services/gameserver/src/models/planet.py (contestable-window / claim-state columns — additive)
Expedition/scan/settle/claim endpoints	services/gameserver/src/api/routes/ (orbital-scan, dispatch-expedition, expedition-status, settle-site)
Deep-intel tech node	services/gameserver/src/services/tech_tree.py (t.exploration.survey.2 — NEW; do NOT reuse survey.1)
Planet-type traits for risk weighting	services/gameserver/src/models/planet.py (radiation_level, temperature, NEW native_life column — M54 additive)
ADR-0056 anti-sybil eligibility surface	services/gameserver/src/services/multi_account_detection.py (Amendment A — additive)

Status: 📐 Design-only — gated on ADR-0091. All numbers flagged [P] are provisional and not yet ratified.