magicciv/.project/objectives/p2-77-deposit-destruction-taxonomy.md

id	title	priority	status	scope	updated_at	blocked_by
p2-77	Deposit-destruction environmental taxonomy — destruction_effect classes + contamination engine	p2	missing	game1	2026-06-06	p2-76

Summary

When a deposit is destroyed (by a bunker p2-76, and any future deposit-destroying act), the environmental consequence depends on what the deposit was. This objective adds a destruction_effect field to deposit JSONs and the contamination-class engine that consumes it, generalising the single fixed-duration contamination from p2-76.

The field is optional — omit it for inert deposits (the default). Shape:

"destruction_effect": {
  "class": "combustion",
  "contamination_turns": 60,
  "spreads_to_adjacent": true,
  "follows_hydrology": false,
  "clearable_by": "decontamination_tech_id_or_null"
}

Class taxonomy (worked out for all 34 hills/mountains-valid deposits)

• inert (~24: all gems — diamond / ruby / sapphire / emerald / amethyst / etc., gold_vein, iron_ore, stone, marble, mithril, magesteel, obsidian, quartz, calcite, selenite, fantasy crystals, wine, sheep) → deposit lost, zero contamination, tile reusable immediately. Omit the field (default = inert).
• combustion (coal_seam) → ignites an underground coal fire: long contamination, spreads heat/smoke to adjacent tiles, self-extinguishes over time.
• acid_drainage (pyrite; partial iron sulfides) → sulfuric acid runoff, follows hydrology downhill / downstream, kills yields on affected tiles.
• chemical (saltpeter_deposit) → secondary explosion (extra damage)
  • nitrate leaching to water.
• toxic_mineral (fluorite = fluoride, malachite = copper) → localized heavy-metal / halide contamination.
• radioactive (uranium — NET-NEW deposit, does not yet exist) → extreme contamination, cleanup-tech-gated.

Acceptance

• ◻ destruction_effect schema added to the deposit JSON schema; the loader parses it into a typed DestructionEffect { class, contamination_turns, spreads_to_adjacent, follows_hydrology, clearable_by }. Absent field → inert default.
• ◻ All 34 hills/mountains-valid deposits classified per the taxonomy above; inert deposits leave the field omitted. (uranium deposit authored net-new as radioactive.)
• ◻ Contamination-class engine: on deposit destruction the engine reads the destroyed deposit's destruction_effect and writes the appropriate contamination overlay (generalising p2-76's fixed-duration overlay into per-class behaviour).
• ◻ spreads_to_adjacent: combustion contamination propagates to the 6 neighbours over turns and recedes.
• ◻ follows_hydrology: acid_drainage / chemical leaching propagate along the flow path produced by the runtime hydrology re-solve (p2-78) — downhill / downstream.
• ◻ clearable_by: a tile contaminated by a class with a non-null clearable_by is reclaimable only once that tech is researched (the decontamination path, p2-80); inert / short classes self-heal with no tech.
• ◻ Determinism: same seed + same destruction event → identical contamination spread sequence (PCG64 pin per WORLDGEN_RNG.md).
• ◻ cargo test green (per-class overlay behaviour, spread, hydrology-follow, clearable gating), headless GUT green, proof-scene screenshot of a coal-fire spread and an acid-drainage downstream plume reviewed.

Non-goals

• The bunker itself (p2-76) — this generalises its contamination.
• The hydrology re-solve mechanics (p2-78) — this consumes its flow output for follows_hydrology.
• Player decontamination UI polish — p2-80.

Risks

• Save-format growth: the contamination overlay gains per-class metadata (class, remaining turns, spread frontier); #[serde(default)].
• Determinism: spread frontier expansion and hydrology-follow must be order-stable and draw from a dedicated SeedDomain.
• Data-vs-code split (Rail 2): all class thresholds / durations live in the deposit JSONs and a tunable class table, never hardcoded.

Dependencies

• Inputs: p2-76 (the destruction-overlay foundation), deposit JSONs.
• Couples with: p2-78 (provides the flow path for follows_hydrology).
• Blocks: p2-80 (cascade integration), p2-80 decontamination path.