Condense reactor design spec

docs/design.md

@@ -1,224 +1,112 @@
-# Reactor Maintenance V1 Design
+# Reactor Maintenance Design
 
-## Status
+## Concept
 
-This document is the authoritative v1 design for Reactor Maintenance.
+The player controls a maintenance robot inside a failing reactor facility. The game is a deterministic, turn-based systems puzzle about reading a visible machine, forecasting failure, and choosing between local stabilization and longer-term network control.
 
-The earlier prototype simulation, editor tools, save files, effects, tests, and terminology are not compatibility targets. V1 is a clean replacement. Serialization version `1` belongs to this design. Prototype-shaped JSON must be rejected with a clear unsupported-format or invalid-level error; no migration is required.
+The simulation uses a small formal core:
 
-## Core Concept
+- static floor and wall terrain
+- underground fuel, coolant, and electricity networks
+- surface props for controls, terminals, supplies, doors, and reactor activation
+- reachable leaks that project hazards onto floor cells
+- explicit reactor requirements bound to consumer props
+- deterministic rule events and forecasts
 
-The player controls a maintenance robot inside a failing reactor facility.
+The game should feel logical, tactical, readable, and systemic. It should avoid randomness, action pressure, and hidden information after the player earns the relevant diagnostic access.
-
-The game is a deterministic, turn-based systems puzzle. The player studies a visible machine, predicts its failures, and chooses between short-term on-site stabilization and longer-term network control.
-
-The simulation model is intentionally narrow:
-
-- a static surface grid of walkable floor cells and blocked wall cells
-- an underground fuel network
-- an underground coolant network
-- an underground electricity network
-- surface props that expose controls, terminals, supplies, doors, and repair access
-- leaks that are always reachable by the robot from a floor cell
-- one or more reactors with explicitly bound required consumers
-- a diagnostic UI that exposes visible state, forecasts, and all underground layers only after all-seeing-eye terminal access
-
-The main fantasy is:
-
-> "I understand this machine well enough to prevent the next disaster."
-
-The game should feel logical, tactical, deterministic, readable, and systemic. It should not feel hectic, random, action-heavy, or dependent on hidden information after the correct inspection tool is acquired.
 
 ## Turn Structure
 
-Each gameplay turn has three phases:
+Each turn has three phases:
 
-1. Player phase: the player spends the level's action budget.
+1. Player phase: the player spends the level action budget.
-2. Simulation phase: network flow, consumers, leaks, local hazards, doors, robot safety, and level state resolve deterministically.
+2. Simulation phase: networks, consumers, leaks, hazards, doors, robot safety, and level state resolve.
 3. Event phase: rule events, remedy block durations, and heat immunity duration advance.
 
-The simulation advances once after the player spends or ends the turn's action budget. Individual player actions do not tick the simulation.
+The simulation advances once after the player spends or ends the turn action budget. Individual player actions do not tick the simulation.
 
-## Goal
+## Goal And Failure
 
-Each reactor starts offline.
+Each reactor starts offline. A reactor becomes ready when:
 
-To win a level, the player must:
+- its bound fuel consumer is enabled, supplied, and producing
+- its bound coolant consumer is enabled, supplied, and producing
+- its bound electricity consumer is enabled, supplied, and producing
+- reactor heat is below the terminal condition
 
-- restore fuel delivery to the reactor's bound fuel consumer
+When a reactor is ready, the level shows `REACTOR READY`. The player wins by spending an action at that reactor control site.
-- restore coolant delivery to the reactor's bound coolant consumer
-- restore electricity delivery to the reactor's bound electricity consumer
-- keep the reactor area below the terminal heat condition
-- reach the reactor control site and activate the core
 
-When every bound required consumer is enabled, supplied, and producing service, and no terminal reactor condition is active, the level shows:
+The level is lost when:
 
-> REACTOR READY
+- reactor heat reaches the terminal threshold
+- the robot occupies an unsafe final hazard state without applicable protection
+- a rule event marks terminal failure
+- level-authored unrecoverable conditions are met
 
-The player can then spend an action at the reactor control site to activate the core and win.
+Consumer starvation blocks readiness but does not directly cause loss.
 
-## Loss Conditions
+## Information
 
-The player loses if the level reaches a clearly predicted terminal state.
+The player can always inspect:
 
-Primary loss conditions:
+- surface terrain
-
+- surface props and visible prop state
-- reactor overheating reaches the terminal heat threshold
+- visible leaks and repair faces
-- the robot occupies a hazardous final cell state without applicable protection
+- visible surface hazards
-- a rule event resolves to terminal failure
+- door state
-- cascading hazards make the level explicitly unrecoverable according to level-authored rules
-
-Required consumer starvation does not directly cause loss. A starved or disabled required consumer prevents `Ready`, but failure still comes from terminal heat, robot loss, rule terminal events, or other explicit terminal rules.
-
-Failure should not be instant unless the player knowingly allows a predicted critical state to mature or moves the robot into an unsafe final hazard state.
-
-## Information Design
-
-All surface information is visible and predictable. Underground information is controlled by terminal access during gameplay.
-
-The player can always see:
-
-- floor and wall terrain
-- surface props and their visible states
-- visible leaks and their reachable repair faces
-- visible surface hazards on floor cells
-- door open or closed state
 - remedy inventory and supply props
-- whether each consumer is producing, starved, disabled, or unknown
+- consumer state: disabled, starved, supplied, producing, or unknown
-- current level state
+- level state
-- scheduled and rule-based upcoming warnings that the forecast can prove
+- forecasted warnings the simulation can prove
 
-Before all-seeing-eye access, the player cannot freely inspect underground layers. Underground causes may be inferred from visible leaks, prop state, and forecasts, but exact underground topology and numeric network values are hidden.
+Underground topology and numeric network values are hidden until all-seeing-eye terminal access is unlocked. With access, the player can inspect underground fuel, coolant, and electricity topology, network structural state, carrier amount, pressure or voltage, and source-to-consumer connectivity.
 
-After interacting with an all-seeing-eye terminal prop, the player can inspect all underground layers:
+The editor always sees and authors every layer.
 
-- underground fuel, coolant, and electricity topology
+Safe, caution, and critical labels are display and forecast bands derived from balance thresholds. Numeric simulation values remain authoritative.
-- structural state of each underground network cell
-- carrier amount
-- pressure for fuel and coolant
-- voltage for electricity
-- source-to-consumer connectivity
 
-The editor is not gated by all-seeing-eye access. It always sees and authors every layer.
+## Grid And State
-
-Safe, caution, and critical labels are UI and forecast labels derived from balance thresholds. They are not stored as authoritative simulation state.
-
-## Layered Grid
 
 Each map coordinate contains:
 
 - one static surface terrain cell: `Floor` or `Wall`
-- zero or one fuel network cell underground
+- zero or one underground fuel cell
-- zero or one coolant network cell underground
+- zero or one underground coolant cell
-- zero or one electricity network cell underground
+- zero or one underground electricity cell
 - zero or one surface prop
-- zero or more visible hazard amounts on floor cells
+- visible hazard amounts on floor cells
 - optionally the robot, only on a floor cell
 
-Cells cannot change between floor and wall during gameplay. Terrain is level-authored and static.
+Terrain is authored and does not change during play. Wall cells are not walkable and do not store surface hazards.
 
-The three underground networks are disjunct. They do not share edges and do not directly interact underground.
+Underground cells use one structural state:
-
-Same-carrier underground cells connect by inferred cardinal adjacency. There are no per-edge connection flags in v1. The validator rejects topology that cannot produce unambiguous source-to-consumer and source-to-junction flow.
-
-Each network has:
-
-- one or more outside-of-level source connections exposed through flow props
-- zero or more consumer props
-- optional T-junction props on surface floor cells
-- optional cross-junction props on surface floor cells
-
-## Numeric Model
-
-Simulation values use C# `float`.
-
-Runtime values are not rounded internally. Balance constants define minimum and maximum clamps. The UI rounds visible numeric values to one decimal place and displays the corresponding safe/caution/critical band.
-
-Tests should not assert arbitrary exact float values. Tests assert:
-
-- safe/caution/critical bands
-- readiness and loss transitions
-- validation outcomes
-- connectivity outcomes
-- monotonic direction of numeric effects
-- exact values only for isolated formulas where the formula itself is the behavior under test
-
-## State Inventory
-
-### Surface Terrain
-
-Surface terrain states:
-
-- `Floor`: walkable, can hold the robot, props, visible hazards, fuel/coolant leaks, and repair access to electricity wall leaks.
-- `Wall`: not walkable, can hold wall-routed underground cells and electricity wall leaks.
-
-Wall cells do not store surface hazard amounts.
-
-### Underground Network Cells
-
-Each underground network cell has one carrier family:
-
-- `Fuel`
-- `Coolant`
-- `Electricity`
-
-Each underground network cell has one structural state:
 
 - `Absent`
 - `Intact`
 - `Leaking`
 
-Each underground network cell stores:
+Underground cells store carrier amount plus pressure for fuel/coolant or voltage for electricity. Same-carrier underground cells connect by inferred cardinal adjacency.
 
-- carrier amount
+Surface floor cells store:
-- pressure for fuel and coolant
-- voltage for electricity
 
-Fuel and coolant use pressure. Electricity uses voltage. Fields that do not apply to the carrier are ignored by simulation and should not be shown as meaningful UI values.
+- leaked fuel
-
+- leaked coolant
-### Surface Hazards
+- leaked electricity
-
+- heat
-Each floor cell stores:
-
-- leaked fuel amount
-- leaked coolant amount
-- leaked electricity amount
-- heat amount
 - active elemental remedy blocks
 
-There is no v1 smoke, fire, pressure-pipe, cell-integrity, or facility-stability system.
+Simulation values use C# `float`. Runtime values are clamped and retain full float precision. UI shows visible values rounded to one decimal plus the safe/caution/critical band.
 
-### Robot
+## Level State
 
-The robot stores:
+The derived level states are:
 
-- current floor position
+- `Stable`: no terminal path is near and required systems are not deteriorating.
-- carried remedial consumables
+- `Caution`: required service is missing, a consumer is starved or disabled, a hazard is growing, or reactor heat is concerning.
-- active heat-immunity duration
-
-Robot damage is not a recoverable v1 state. If the robot occupies a cell whose final hazard values exceed safety predicates and no applicable protection is active, the level is lost.
-
-### Level State
-
-The whole level has these states:
-
-- `Stable`
-- `Caution`
-- `Critical`
-- `Ready`
-- `Lost`
-- `Won`
-
-Meaning:
-
-- `Stable`: no terminal path is near and required systems are not actively deteriorating.
-- `Caution`: a required service is missing, a consumer is starved or disabled, a hazard is growing, or reactor heat is concerning.
 - `Critical`: forecast predicts loss without near-term intervention, or reactor heat is close to terminal.
-- `Ready`: a reactor's bound required consumers are producing and reactor conditions allow activation.
+- `Ready`: a reactor can be activated.
 - `Lost`: terminal failure has occurred.
-- `Won`: the reactor has been activated successfully.
+- `Won`: a reactor has been activated successfully.
-
-Level state is derived after each simulation step and after successful activation.
 
 ## Props
 
@@ -233,66 +121,41 @@ Surface prop categories:
 - remedy supply prop
 - reactor control prop
 
-Props exist on floor cells unless the prop type explicitly stores a wall-facing repair/emission relationship. Props do not participate directly in the local hazard pair condition table.
+Props exist on floor cells. Props do not directly participate in the surface hazard pair table.
 
 ### Flow Props
 
-A flow prop is bound to exactly one carrier family:
+A flow prop is bound to fuel, coolant, or electricity. It can be `Enabled` or `Disabled`.
 
-- fuel flow prop
+During network flow, an enabled flow prop injects source carrier amount and pressure or voltage into its connected underground network cell. A disabled flow prop injects nothing.
-- coolant flow prop
-- electricity flow prop
-
-Flow props have two states:
-
-- `Enabled`
-- `Disabled`
-
-During network flow, an enabled flow prop injects source carrier amount and pressure or voltage into its connected underground network cell. The injected values are balance constants. A disabled flow prop injects nothing and isolates its bound source from outside supply.
 
 ### Consumer Props
 
-A consumer prop is bound to exactly one carrier family:
+A consumer prop is bound to fuel, coolant, or electricity. It can be `Enabled` or `Disabled`.
 
-- fuel consumer
+An enabled consumer derives one service state after network propagation:
-- coolant consumer
-- electricity consumer
 
-Consumer props have two player-controlled states:
+- `Supplied`: enough carrier and pressure or voltage reaches the bound underground cell.
+- `Starved`: supply predicates fail.
+- `Producing`: the consumer was supplied this simulation step and emits service.
 
-- `Enabled`
+A disabled consumer consumes nothing, produces nothing, and cannot satisfy reactor readiness.
-- `Disabled`
-
-Each consumer derives one current service state:
-
-- `Disabled`: prop is off, consumes nothing, produces no service, and does not starve.
-- `Supplied`: prop is enabled and receives enough carrier amount plus pressure or voltage.
-- `Starved`: prop is enabled but receives too little carrier amount, pressure, or voltage.
-- `Producing`: prop was supplied this simulation step and its required service is active.
-
-`Supplied` is the input condition. `Producing` is the output condition used by reactor readiness.
-
-If enabled and supplied, the consumer removes or reserves demand and produces service for the turn. If enabled and unsupplied, it emits a visible starvation warning and blocks readiness. If disabled, it cannot satisfy readiness.
 
 ### Reactor Control Props
 
-A reactor control prop is the activation site for one reactor.
+A reactor control prop is the activation site for one reactor. Each reactor stores required consumer bindings by grid position:
 
-Each reactor stores required consumer bindings by grid position:
+- fuel consumer position
+- coolant consumer position
+- electricity consumer position
 
-- required fuel consumer position
+The level is invalid if any binding is missing, out of bounds, or points to the wrong prop type.
-- required coolant consumer position
-- required electricity consumer position
-
-The level is invalid if any binding is missing, out of bounds, not a floor prop, or points to a consumer of the wrong carrier family.
 
 ### Junction Props
 
-Junction props regulate flow after it leaves a source.
+A junction prop must be on a floor cell whose coordinate has exactly one underground carrier. That carrier is the regulated network.
 
-A junction prop must be placed on a floor cell whose coordinate has an underground network cell for exactly one carrier family. That network cell defines the carrier regulated by the junction.
+T-junction modes:
-
-T-junction props split one incoming path into two outgoing branches. Allowed modes:
 
 - `0/4`
 - `1/3`
@@ -300,202 +163,125 @@ T-junction props split one incoming path into two outgoing branches. Allowed mod
 - `3/1`
 - `4/0`
 
-Cross-junction props split one incoming path into three outgoing branches. Allowed modes:
+Cross-junction modes:
 
 - `0/3/3`
 - `3/0/3`
 - `3/3/0`
 - `2/2/2`
 
-The engine auto-infers incoming and outgoing branch directions from valid network topology and enabled source paths. The editor and engine must reject maps where a junction's incoming direction or outgoing branches are ambiguous.
+The engine infers incoming and outgoing branch directions from valid network topology and enabled source paths. Ambiguous junction flow is invalid. Ratio numbers are weights that divide carrier amount and pressure or voltage by balance-defined math. A zero-weight branch receives no intentional outflow.
 
-Ratio numbers are weights. They divide available carrier amount and pressure or voltage according to balance-defined ratio math. A zero-weight branch receives no intentional outflow from that junction.
+The gameplay UI exposes ratio modes.
 
-The gameplay UI exposes ratio modes. It does not need to label live downstream effects in v1.
+### Doors
 
-### Door Props
+A door stores one edge between two adjacent floor cells. Door states are `Open` and `Closed`.
 
-Door props have two states:
+Closed doors block fuel, coolant, electricity, and heat propagation across their edge. They do not block robot movement, underground network flow, source feeding, consumer supply, or hazards already present on either side.
 
-- `Open`
+### Terminals And Supplies
-- `Closed`
 
-Each door stores one authored propagation edge between two adjacent floor cells. When open, surface fuel, coolant, electricity, and heat may propagate across that edge. When closed, those hazards do not propagate across that edge.
+An all-seeing-eye terminal unlocks underground inspection for the level.
 
-Closed doors do not:
+Remedy supply props are single-use pickups:
-
-- block robot movement
-- block underground network flow
-- block source feeding
-- block consumer supply
-- extinguish hazards already present on either side
-
-The level is invalid if a door edge is missing, non-adjacent, out of bounds, or does not connect two floor cells.
-
-### All-Seeing-Eye Terminal Props
-
-All-seeing-eye terminal props have two player states:
-
-- `Locked`: underground layer inspection is unavailable.
-- `Unlocked`: interacting with the terminal has enabled all underground layer inspection for the level.
-
-No other action or prop grants full underground inspection.
-
-### Remedy Supply Props
-
-Remedy supply props are single-use typed pickups:
 
 - `FuelRemedySupply`
 - `CoolantRemedySupply`
 - `ElectricityRemedySupply`
 - `HeatRemedySupply`
 
-Each supply prop provides one fixed remedy type once. After pickup it becomes depleted.
+Each supply provides one matching inventory item and then becomes depleted.
 
-## Leaks
+## Leaks And Remedies
 
-Each leak stores:
+Each leak stores carrier type, underground coordinate, accessible floor coordinate, and repair state.
 
-- carrier type
+Fuel and coolant leaks:
-- underground coordinate
-- accessible floor coordinate
-- current repair state
 
-Fuel and coolant leak rules:
+- occur under floor cells
-
-- may only occur when the underground leak coordinate is under a floor cell
 - use the same coordinate as their accessible floor coordinate
 - can be repaired or remediated by the robot standing on that floor cell
 
-Electricity leak rules:
+Electricity leaks:
 
-- may only occur when the underground leak coordinate is in a wall cell
+- occur in wall cells
-- must store exactly one adjacent floor cell as its accessible emission face
+- store exactly one adjacent floor cell as the emission face
-- can be repaired or remediated by the robot from the chosen floor cell
+- can be repaired or remediated from that floor cell
-- emits only to the stored floor face
+- emit only to that stored face
 
-All authored and rule-created leaks must have valid floor access. Invalid leaks are validation errors for authored state and rejected events at runtime.
+All leaks must have valid floor access. Repair changes the underground cell from `Leaking` to `Intact` and stops future injection. Repair does not clean existing surface hazards.
 
-A repaired leak changes the underground network cell from `Leaking` to `Intact` and stops future injection. Repairing does not clean existing surface hazards.
+The robot carries remedial consumables with balance-defined inventory capacity:
-
-## Remedies
-
-The robot has a small inventory for remedial consumables. Inventory capacity is balance data.
-
-Remedy types:
 
 - `FuelNeutralizer`
 - `CoolantNeutralizer`
 - `ElectricityNeutralizer`
 - `HeatShield`
 
-Element neutralizers:
+Element neutralizers remove the matching surface element from a target floor cell or reachable leak face, then apply a temporary same-element re-entry block. They do not remove other elements, reduce heat, or repair leaks.
 
-- are consumed when applied to a target floor cell or reachable leak face
+Heat shield gives the robot heat immunity for a balance-defined number of movement steps. It does not remove heat, block heat propagation, or protect against fuel, coolant, or electricity hazards.
-- remove the current matching surface element from that target
-- apply a temporary block preventing that same element from re-entering the target
-- do not remove or block any other element
-- do not reduce heat
-- do not repair the underlying leak
-
-Heat shield:
-
-- is consumed when activated by the robot
-- makes the robot immune to heat damage for a balance-defined number of robot movement steps
-- does not reduce heat
-- does not block heat propagation
-- does not protect against fuel, coolant, or electricity hazards
-
-Mixed hazards require multiple remedies. A floor cell containing fuel, electricity, and heat requires a fuel neutralizer, an electricity neutralizer, and heat immunity or another heat-management solution to be locally safe.
 
 ## Player Actions
 
-Each player action costs one action unless balance or level data explicitly says otherwise.
-
 Player actions:
 
 - `MoveRobot`: move to an adjacent floor cell.
-- `InteractProp`: interact with the prop on the robot's current floor cell.
+- `InteractProp`: use the prop on the robot's current floor cell.
-- `InteractLeak`: repair a reachable leak or apply a matching carried elemental remedy.
+- `InteractLeak`: repair a reachable leak or apply a matching elemental remedy.
 - `ApplyHeatShield`: activate a carried heat shield.
-- `ActivateReactor`: activate a reactor at the current reactor control prop.
+- `ActivateReactor`: activate a ready reactor at the current reactor control prop.
 - `EndTurn`: forfeit remaining actions and run the simulation/event phases.
 
-Invalid actions do not mutate gameplay state except for reporting a refused action. Invalid actions do not spend an action unless a future balance rule explicitly says otherwise.
+Each valid action costs one action unless balance or level data defines otherwise. Invalid actions report refusal and do not mutate gameplay state.
 
-`InteractProp` covers:
+`InteractProp` covers flow toggles, consumer toggles, junction ratio changes, door toggles, terminal unlock, and remedy pickup.
-
-- enabling or disabling flow props
-- enabling or disabling consumer props
-- cycling or selecting T-junction ratio modes
-- cycling or selecting cross-junction ratio modes
-- opening or closing doors
-- unlocking all-seeing-eye terminal access
-- picking up a remedy from a supply prop
-
-`ActivateReactor` wins only if the level is `Ready` for that reactor. Otherwise it reports that the reactor is not ready.
 
 ## Network Flow
 
-The network flow step runs independently for fuel, coolant, and electricity.
+Network flow runs independently for fuel, coolant, and electricity.
 
 For each carrier:
 
-1. Clear transient carrier amount and pressure or voltage values from the previous turn.
+1. Clear transient carrier amount and pressure or voltage.
 2. Start from every enabled flow prop connected to that carrier.
-3. Walk through connected intact and leaking underground cells of that carrier.
+3. Walk through connected intact and leaking underground cells.
 4. Stop at absent cells and disconnected topology.
-5. Apply distance falloff to carrier amount and pressure or voltage.
+5. Apply distance falloff.
-6. Apply junction ratio weights at valid junction props.
+6. Apply valid junction ratio weights.
 7. Assign each reached cell its best incoming carrier amount and best incoming pressure or voltage.
-8. Clamp final values to balance min/max.
+8. Clamp final values.
 
-If multiple non-ambiguous source paths reach the same non-junction cell, the cell uses the best carrier amount and best pressure or voltage. Ambiguous junction flow is invalid and must be caught by validation.
+Multiple non-ambiguous source paths may reach the same non-junction cell; the cell uses the best carrier amount and best pressure or voltage. Junction ambiguity is a validation error.
 
-Consumers evaluate after propagation.
+A consumer is supplied when carrier amount, pressure or voltage, and connectivity predicates pass.
-
-A consumer is supplied if all required balance predicates pass:
-
-- enough carrier amount reaches the bound underground cell
-- enough pressure reaches a fuel or coolant consumer
-- enough voltage reaches an electricity consumer
-- the bound network path is not disconnected by topology or junction ratios
 
 ## Surface Hazards
 
-A leaking underground cell remains part of network propagation while leaking.
+Leaking underground cells remain part of network propagation.
 
 During leak injection:
 
-- fuel leaks inject leaked fuel into the accessible floor cell
+- fuel leaks add leaked fuel to the accessible floor cell
-- coolant leaks inject leaked coolant into the accessible floor cell
+- coolant leaks add leaked coolant to the accessible floor cell
-- electricity leaks inject leaked electricity into the stored accessible floor face
+- electricity leaks add leaked electricity to the stored floor emission face
-- active matching remedy blocks prevent the matching element from entering the protected floor cell
+- active matching remedy blocks prevent matching element entry
 
-Leak injection magnitudes are balance data and may depend on local carrier amount, pressure, or voltage.
+Injection magnitude is balance data and may depend on local carrier amount, pressure, or voltage.
 
-After injection, the engine evaluates local interactions between leaked fuel, leaked coolant, leaked electricity, and heat on each floor cell and between adjacent floor cells.
+After injection, the engine evaluates local interactions between leaked fuel, leaked coolant, leaked electricity, and heat on the same floor cell and across unblocked adjacent floor cells.
 
-Closed doors block pair evaluation across their authored edge.
+## Hazard Bands And Pair Table
 
-## Condition Bands And Pair Table
+Balance thresholds project numeric values into safe, caution, and critical bands:
-
-Authoritative simulation values are numeric floats. Balance thresholds project values into UI/forecast bands:
-
-- safe
-- caution
-- critical
-
-Projected labels:
 
 - `FuelSafe`, `FuelCaution`, `FuelCritical`
 - `CoolantSafe`, `CoolantCaution`, `CoolantCritical`
 - `ElectricitySafe`, `ElectricityCaution`, `ElectricityCritical`
 - `HeatSafe`, `HeatCaution`, `HeatCritical`
 
-The pair table maps projected bands to deterministic event effects. It is implemented in code using balance thresholds and effect magnitudes, not loaded from data in v1.
+The pair table maps projected bands to deterministic effects:
-
-Pair event legend:
 
 - `Hold`: no direct change.
 - `FuelFlow`: equalize leaked fuel.
@@ -527,43 +313,32 @@ Pair event legend:
 | HeatCaution |  |  |  |  |  |  |  |  |  |  | Hold | HeatFlow |
 | HeatCritical |  |  |  |  |  |  |  |  |  |  |  | Hold |
 
-Design intent:
+Design rules:
 
-- fuel only becomes dangerous through electricity or heat
+- fuel becomes dangerous through electricity or heat
-- coolant only becomes dangerous through electricity
+- coolant becomes dangerous through electricity
 - coolant opposes heat
 - heat equalizes between neighboring floor cells
 - same-carrier leaked surface amounts equalize between neighboring floor cells
-- doors and active remedy blocks gate local interactions
+- doors and remedy blocks gate local interactions
 
 ## Rule Events
 
-V1 supports deterministic rule-triggered events.
+Rule events are deterministic and forecastable. Each event stores enabled state, once/repeat behavior, priority, predicates, effects, and optional forecast text. All predicates must pass for the event to trigger.
 
-Each rule event stores:
+Predicate families:
 
-- enabled state
+- turn comparisons
-- once or repeat behavior
-- priority/order
-- predicate list
-- effect list
-- optional player-facing forecast text
-
-All predicates in the predicate list must pass for the event to trigger.
-
-Supported predicate families:
-
-- turn number comparisons
 - level state comparisons
-- reactor readiness/loss/won comparisons
+- reactor readiness/loss/win comparisons
-- prop type/state at position
+- prop type or state at position
 - consumer service state at position
-- network carrier amount, pressure, or voltage band at position
+- network value band at position
 - surface hazard band at position
 - robot position or inventory condition
 - all-seeing-eye unlocked state
 
-Supported effects:
+Effects:
 
 - start a valid leak
 - worsen an existing leak
@@ -575,177 +350,93 @@ Supported effects:
 - mark terminal loss
 - emit warning text
 
-Rule events must be deterministic and forecastable. Random predicates and random effects are not part of v1.
-
 ## Simulation Order
 
-The simulation loop for one completed turn is:
+One completed turn resolves in this order:
 
-1. Apply all player actions already accepted during the player phase.
+1. Apply accepted player actions.
-2. Validate that runtime state remains valid enough to simulate.
+2. Validate runtime state.
-3. Apply start-of-simulation rule events whose predicates pass.
+3. Apply matching start-of-simulation rule events.
-4. Resolve source injection and underground network propagation for each carrier.
+4. Propagate underground networks.
 5. Resolve consumers and service production.
-6. Inject leaks into accessible floor cells, respecting remedy blocks.
+6. Inject leaks.
-7. Evaluate local same-cell surface interactions.
+7. Evaluate same-cell surface interactions.
-8. Evaluate right and bottom neighbor interactions when no closed door blocks the edge.
+8. Evaluate adjacent floor interactions across unblocked edges.
-9. Accumulate emitted deltas.
+9. Accumulate and apply deltas in deterministic priority order.
-10. Apply deltas in deterministic priority order.
+10. Clamp values.
-11. Clamp numeric values.
+11. Resolve robot safety.
-12. Resolve robot safety; unsafe final robot state marks the level `Lost`.
+12. Derive reactor readiness and level state.
-13. Derive reactor readiness and level state.
+13. Apply matching end-of-turn rule events.
-14. Apply end-of-turn rule events whose predicates pass.
+14. Advance remedy blocks and heat immunity.
-15. Advance remedy block durations and heat immunity duration.
+15. Refresh forecasts.
-16. Refresh forecasts.
 
-If multiple events modify the same value in one step, their deltas are accumulated before clamping unless a specific event consumes, reserves, or blocks a value earlier in the order.
+If multiple events modify the same value in one step, deltas accumulate and then clamp. Event priority may consume, reserve, or block a value first.
 
 ## Forecasts
 
-V1 forecasts guarantee:
+Forecasts are deterministic simulations over copied state. Forecasting does not mutate the actual level.
+
+Forecast output includes:
 
 - terminal loss forecasts
 - reactor ready forecasts
-- near-term warnings for starved required consumers
+- starved required consumer warnings
-- near-term warnings for growing hazards that cross caution or critical bands
+- growing hazard warnings when values cross caution or critical bands
-- rule event warnings when predicates can be proven for the forecast horizon
+- rule event warnings when predicates can be proven within the forecast horizon
-
-Forecasts are deterministic simulations over copied state. Forecasting must not mutate the actual level.
 
 The forecast horizon is balance data.
 
 ## Validation
 
-The editor must block run and save when validation errors exist. Warnings may allow save/run but must be visible.
+The editor blocks run and save when validation errors exist. Warnings are visible and non-blocking.
 
 Validation errors:
 
-- level dimensions below minimum
+- invalid dimensions or cell counts
-- cell array dimensions mismatch
+- robot out of bounds or not on floor
-- robot is out of bounds or not on floor
+- wall cell with surface hazards
-- wall cell stores surface hazards
+- prop on invalid terrain
-- prop is out of bounds or on invalid terrain
+- missing or invalid reactor consumer binding
-- reactor binding is missing, out of bounds, or points to the wrong consumer type
+- invalid door edge
-- door edge is missing, non-adjacent, out of bounds, or not floor-to-floor
+- invalid leak access
-- fuel or coolant leak is not under a floor cell
+- invalid rule target
-- electricity leak is not in a wall cell or lacks exactly one adjacent floor emission face
+- junction without exactly one underground carrier
-- rule-created leak target would be invalid
+- ambiguous junction flow
-- junction is not on a floor cell with exactly one underground carrier
+- network loop or equal-source ambiguity at a junction
-- junction incoming or outgoing flow is ambiguous
+- malformed required data
-- inferred network topology contains loops or ambiguous equal source paths at a junction
-- rule predicate or effect references an invalid target
-- all required v1 data is absent or malformed
 
 Validation warnings:
 
 - unreachable non-required consumer
-- underground cell with no possible source path
+- underground cell with no source path
-- required consumer initially starved
+- initially starved required consumer
-- reactor initially not ready
+- initially unready reactor
 - unused remedy supply
-- visible hazard with no nearby remedy or route, when detectable by static analysis
+- visible hazard with no detectable nearby remedy or route
 
-## Editor Requirements
+## Editor And Schema
 
-The v1 editor must be able to author every v1 concept:
+The editor authors:
 
 - surface terrain
 - underground fuel, coolant, and electricity cells
-- flow props
+- flow props and consumer props
-- consumer props
 - reactor controls and reactor consumer bindings
-- T-junction and cross-junction props
+- junction props and ratio modes
-- junction ratio modes
 - door props and door edges
 - all-seeing-eye terminals
 - remedy supplies
-- fuel/coolant floor leaks
+- floor leaks and electricity wall leaks
-- electricity wall leaks and emission faces
 - initial surface hazards and heat
 - robot start position
 - rule events
 
-The editor always shows all layers. Gameplay preview may include a locked/unlocked diagnostic display mode, but authoring is never hidden from the designer.
+The serialized level schema stores level metadata, dimensions, terrain, underground layers, props and prop state, reactor bindings, leaks, doors, robot state, inventory, rule events, all-seeing-eye state, and dynamic state when saving active play.
 
-The editor save command must run validation and refuse to save on errors.
+The loader accepts only schema-valid level data and returns clear errors for malformed data.
 
-## Serialization
+## Balancing And Tests
 
-V1 level files use serialization version `1`.
+Balancing defines source strengths, falloff, ratio math, consumer predicates, leak magnitudes, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, action costs, and forecast horizon.
 
-The serialized schema stores:
+Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, junction effects, consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, leak access, remedies, door blocking, rule events, forecasts, and serialization round trips.
-
-- level metadata
-- dimensions
-- terrain cells
-- underground network layers
-- surface props and prop state
-- reactor consumer bindings by grid position
-- leaks
-- doors and door edges
-- robot state
-- inventory
-- rule events
-- initial all-seeing-eye unlocked state
-- current dynamic state for saved games, if save-game support is enabled
-
-Prototype-shaped files are not compatible, even if they used an earlier `Version: 1` wrapper. The loader accepts only this v1 schema and returns a clear unsupported or invalid-level error for prototype or malformed data.
-
-## Balancing Data
-
-The design deliberately assigns these values to balancing:
-
-- source strengths
-- carrier amount falloff
-- pressure and voltage falloff
-- ratio-to-flow math
-- consumer demand predicates
-- leak injection magnitudes
-- local interaction magnitudes
-- UI safe/caution/critical thresholds
-- robot safety thresholds
-- terminal heat thresholds
-- inventory capacity
-- remedy block duration
-- heat immunity duration
-- action costs beyond the default one-action rule
-- forecast horizon
-
-Tests should assert behavior against configured balance values and bands, not hardcoded design numbers.
-
-## Test Requirements
-
-V1 test coverage must include:
-
-- validation rejects ambiguous networks, loops, invalid leaks, invalid doors, invalid reactor bindings, invalid robot placement, and invalid rule references
-- inferred adjacency propagates each carrier through valid networks
-- junction ratios affect branch service or leak severity by observable band/result
-- consumers derive disabled, starved, supplied, and producing states
-- bound reactor readiness requires the three bound consumers and safe reactor heat
-- activation wins only from `Ready`
-- terminal reactor heat loses
-- unsafe robot final hazard state loses
-- heat immunity prevents only heat-caused robot loss while active
-- fuel, coolant, and electricity leaks inject through their valid access rules
-- remedies remove only matching hazards and create temporary matching blocks
-- closed doors block surface propagation across their edge only
-- rule events trigger deterministically from predicate lists
-- forecasts report terminal loss, ready state, starved required consumers, and growing hazards
-- serialization round-trips valid v1 levels and rejects prototype or malformed files
-
-## Summary
-
-V1 reduces Reactor Maintenance to a small deterministic formal core:
-
-- static surface terrain
-- three inferred-adjacency underground networks
-- float carrier, pressure, voltage, leak, and heat values
-- flow, consumer, junction, door, terminal, remedy, and reactor props
-- explicit reactor-to-consumer bindings
-- reachable floor and wall leak rules
-- surface hazards gated by doors and remedies
-- rule-triggered deterministic events
-- forecastable ready, warning, and loss states
-- editor validation that blocks ambiguous authored content
-
-This is the implementation target for replacing the prototype simulation, tests, and editor.