Document campaign choice rescue

docs/design.md

@@ -8,7 +8,7 @@ The simulation core is built from:
 
 - static floor and wall terrain,
 - underground fuel, coolant, and electricity networks,
-- surface props for controls, terminals, supplies, doors, and reactor activation,
+- surface props for sources, isolation valves, controls, terminals, supplies, doors, and reactor activation,
 - consumers that consume whichever underground services exist under their cell,
 - reachable leaks and sprinkler valves that project hazards or suppression water onto floor cells,
 - transport network structural integrity,
@@ -28,7 +28,7 @@ Quick actions do not mutate the environment and do not trigger a pulse:
 
 Lengthy actions commit an intervention and immediately trigger one pulse:
 
-- `InteractProp`: toggle flow props, toggle consumers, cycle junction ratios, open or close doors, pick up remedy supplies, or activate all-seeing-eye access from a terminal,
+- `InteractProp`: toggle flow props, toggle isolation valves, toggle consumers, cycle junction ratios, open or close doors, pick up remedy supplies, or activate all-seeing-eye access from a terminal,
 - `InteractLeak`: repair a reachable leak or apply a matching elemental remedy,
 - `ApplyHeatShield`: spend one heat shield and set heat immunity movement steps,
 - `ActivateReactor`: activate a ready reactor at the current reactor control prop.
@@ -65,6 +65,30 @@ The level is lost when:
 
 Consumer starvation blocks readiness but does not directly cause loss.
 
+## Campaign Progression
+
+The campaign grows by teaching one intervention grammar at a time. A guided tutorial may use a one-action setup to teach pulse playback, but campaign levels should not rely on a single obvious lengthy action. Every non-tutorial campaign level should present at least two plausible first interventions whose pulses create different readable consequences.
+
+Early levels can still use one carrier, but they need a real systems choice:
+
+- feed the service now and risk worsening a pressure-fed fault,
+- isolate the damaged branch and temporarily starve a consumer or reactor feed,
+- repair the leak while the root pressure remains unresolved,
+- reroute or rebalance the network before restoring service.
+
+Campaign authoring should answer two questions for each level:
+
+- What are the plausible first lengthy actions?
+- What does each resulting pulse visibly improve, worsen, or reveal?
+
+Recommended progression:
+
+1. Tutorial: one safe guided action may teach that lengthy actions trigger pulses.
+2. First campaign level: one carrier, one pressure-fed leak, one source, one isolation valve, one repair site, and reactor activation.
+3. Next single-carrier levels: add routing, junction ratios, doors, or limited remedies.
+4. Mid campaign: add heat and coolant sprinkler tradeoffs.
+5. Late campaign: add electricity, wet conduction, multi-service consumers, and full three-system cascades.
+
 ## Information
 
 The player can always inspect:
@@ -143,6 +167,7 @@ The derived level states are:
 Surface prop categories:
 
 - flow prop,
+- isolation valve prop,
 - consumer prop,
 - junction prop,
 - door prop,
@@ -157,7 +182,15 @@ Props exist on floor cells. Props do not directly participate in the surface haz
 
 A flow prop is bound to fuel, coolant, or electricity. It can be `Enabled` or `Disabled`.
 
-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.
+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. Flow props are source feeders; use isolation valves for branch shutoffs so startup, shutdown, and damaged-branch isolation stay readable as separate player decisions.
+
+### Isolation Valve Props
+
+An isolation valve prop is bound to fuel, coolant, or electricity and sits on a floor cell whose coordinate has exactly one matching underground carrier. It can be `Open` or `Closed`.
+
+During network flow, an open isolation valve allows carrier propagation through the underground branch normally. A closed isolation valve blocks intentional network propagation across that underground cell's connected branch boundary. Closing a valve can stop pressure or voltage from reaching a damaged segment, but it can also starve downstream consumers, sprinkler valves, or reactor feed.
+
+Toggling an isolation valve is a lengthy action and triggers one pulse. The forecast and inspection UI should make the affected branch, isolated leak, and downstream service loss readable before the player commits.
 
 ### Consumer Props
 
@@ -239,6 +272,8 @@ Each supply provides one matching inventory item and then becomes depleted.
 
 Each leak stores carrier type, underground coordinate, accessible floor coordinate, and repair state.
 
+Leaks are pressure-fed or voltage-fed faults. A leaking underground cell remains damaged until repaired, but fresh surface injection only occurs when the leaking cell currently receives positive amount and positive pressure or voltage from network propagation. Isolating a leak therefore stops new hazard growth without repairing the underlying fault. Repair removes the fault and restores structural integrity, but it does not clean hazards already on the surface.
+
 Fuel leaks:
 
 - occur under floor cells,
@@ -254,7 +289,7 @@ Electricity leaks:
 - can be repaired or remediated from that floor cell,
 - emit only to that stored face.
 
-All leaks must have valid floor access. Repair changes the underground cell from `Leaking` to `Intact`, restores structural integrity to max, and stops future injection. Repair does not clean existing surface hazards.
+All leaks must have valid floor access. Repair changes the underground cell from `Leaking` to `Intact`, restores structural integrity to max, and stops future injection. Repair does not clean existing surface hazards. If the repaired segment is immediately returned to unsafe pressure or voltage, structural integrity rules may damage it again on later pulses.
 
 The robot carries remedial consumables with balance-defined inventory capacity:
 
@@ -276,9 +311,9 @@ For each carrier:
 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.
-4. Stop at absent cells and disconnected topology.
+4. Stop at absent cells, closed isolation valve boundaries, and disconnected topology.
 5. Apply distance falloff.
-6. Apply valid junction ratio weights.
+6. Apply valid junction ratio weights and isolation valve branch blocking.
 7. Assign each reached cell its best incoming carrier amount and best incoming pressure or voltage.
 8. Clamp final values.
 
@@ -288,13 +323,13 @@ A consumer is supplied when carrier amount, pressure or voltage, and connectivit
 
 ## Surface Hazards
 
-Leaking underground cells remain part of network propagation.
+Leaking underground cells remain part of network propagation unless isolated by a closed valve.
 
 During leak injection:
 
-- fuel leaks add leaked fuel to the accessible floor cell,
-- coolant pipe failures and sprinkler valves add sprinkler water to valid floor cells,
-- electricity leaks add leaked electricity to the stored floor emission face,
+- fed fuel leaks add leaked fuel to the accessible floor cell,
+- fed coolant pipe failures and sprinkler valves add sprinkler water to valid floor cells,
+- fed electricity leaks add leaked electricity to the stored floor emission face,
 - active matching remedy blocks prevent matching element entry.
 
 Injection magnitude is balance data and may depend on local carrier amount, pressure, or voltage. If the target floor cell has an active matching remedy block, that matching element is not injected into the cell for that step. Remedy blocks do not block other elements or heat.
@@ -447,6 +482,7 @@ Forecast output includes:
 - starved required consumer warnings,
 - growing hazard warnings when values cross caution or critical bands,
 - wet-electricity spread warnings,
+- isolation valve warnings for branch shutoff, restored pressure, isolated leaks, and downstream starvation,
 - coolant pressure-drop warnings from sprinkler valve use,
 - structural integrity leak warnings when weakened cells are expected to leak.
 
@@ -466,6 +502,7 @@ Validation errors:
 - invalid door cell,
 - invalid leak access,
 - invalid coolant sprinkler valve outlet or missing coolant network connection,
+- isolation valve without exactly one matching underground carrier,
 - junction without exactly one underground carrier,
 - ambiguous junction flow,
 - network loop or equal-source ambiguity at a junction,
@@ -477,6 +514,7 @@ Validation warnings:
 - underground cell with no source path,
 - initially starved required consumer,
 - initially unready reactor,
+- isolation valve with no meaningful upstream/downstream distinction,
 - unused remedy supply,
 - sprinkler valve with no useful suppression target,
 - visible hazard with no detectable nearby remedy or route.
@@ -488,6 +526,7 @@ The editor authors:
 - surface terrain,
 - underground fuel, coolant, and electricity cells,
 - flow props,
+- isolation valves,
 - multi-service consumer props,
 - required fuel, coolant, and electricity consumer counts,
 - junction props and balance-defined ratio mode index,
@@ -515,6 +554,6 @@ The loader accepts only schema-valid level data and returns clear errors for mal
 
 ## Balancing And Tests
 
-Balancing defines source strengths, falloff, ratio math, consumer predicates, leak magnitudes, sprinkler discharge, coolant pressure drops, evaporation, wet-electricity conduction, structural integrity thresholds and damage scale, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, and forecast horizon.
+Balancing defines source strengths, falloff, ratio math, isolation valve branch blocking, consumer predicates, leak magnitudes, sprinkler discharge, coolant pressure drops, evaporation, wet-electricity conduction, structural integrity thresholds and damage scale, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, and forecast horizon.
 
-Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, junction effects, multi-service consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, structural integrity degradation and leak creation, leak access, sprinkler valves, coolant pressure drops, coolant mitigation, evaporation, wet-electricity spread, remedies, door blocking, forecasts, and serialization round trips.
+Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, isolation valve branch blocking, junction effects, multi-service consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, structural integrity degradation and leak creation, pressure-fed leak injection, leak access, sprinkler valves, coolant pressure drops, coolant mitigation, evaporation, wet-electricity spread, remedies, door blocking, forecasts, campaign authoring rules, and serialization round trips.