SECTION 17 — WATER LANE DEEP DIVE (Z6→Z0)

# ============================================================
# LONDON CITY OS — ALMOST-CODE (CANON) — v0.1
# SECTION 17 — WATER LANE DEEP DIVE (Z6→Z0)
#   Water = potable supply + wastewater removal + safe discharge.
#   Goal: keep pressure/quality stable under variance; prevent contamination + sewage cascades.
# ============================================================
CANON_VERSION: "v0.1"
PLACE:
  place_id: "GBR-LON"
  place_name: "London"
  lane: "WATER"
  z_scope: "Z6_to_Z0"
  pack: "WATER_DEEP_DIVE"
  depends_on_sections:
    - "SECTION_07_SENSORS_PACK"
    - "SECTION_08_ROUTER_CORE"
    - "SECTION_11_EVENT_SURGE"
    - "SECTION_12_GOV_GRAPH"
    - "SECTION_13_LANE_DIRECTORY_INDEX"
# ------------------------------------------------------------
# 17A) Definition locks (water-specific)
# ------------------------------------------------------------
DEFINITION_LOCK:
  POTABLE_WATER:
    >
    Treated water delivered to customers at safe quality + sufficient pressure.
    Two invariants: (1) microbiological safety, (2) pressure continuity.
  WASTEWATER:
    >
    Sewage and trade effluent conveyed to treatment, then discharged under permit conditions.
  SUPPLY_ZONE:
    >
    A pressure-managed distribution region; can be isolated with valves.
    (Key unit for truncation + staged stitching.)
  SEWER_CATCHMENT:
    >
    A drainage network region feeding pumping stations and treatment works.
    (Key unit for overflow risk + permit compliance.)
  WATER_P0:
    >
    Below-threshold safety/continuity: contamination event, widespread outage/low pressure,
    or uncontrolled wastewater discharge requiring hard truncation + emergency supply.
  QUALITY_BREACH:
    >
    Any condition where water is not demonstrably safe for consumption until cleared.
  PRESSURE_COLLAPSE:
    >
    Loss of pressure causing supply interruption + potential ingress risk.
  OVERFLOW_EVENT:
    >
    Wastewater exceeds conveyance/treatment; overflow or emergency discharge occurs.
  STITCHING_RULE:
    >
    Restoration must not create a second disaster: avoid pressure shocks, turbidity spikes,
    or re-starting plants into unstable chemistry/biological state.
# ------------------------------------------------------------
# 17B) Z6 org anchors (minimal viable London water stack)
#   NOTE: Expand suppliers by supply-zone later; keep tokens stable; do not rename.
# ------------------------------------------------------------
ORG_REGISTRY_Z6:
  GBR-LON::WATER::Z6::ORG.MAIN_WATER_WASTEWATER_OPERATOR:
    org_kind: "WATER_AND_WASTEWATER_COMPANY"
    canonical_real_world: "Thames Water (core London)"
    scope: ["POTABLE_SUPPLY","WASTEWATER","TREATMENT","NETWORKS","INCIDENT_RESPONSE"]
  GBR-LON::WATER::Z6::ORG.WATER_ONLY_SUPPLIERS:
    org_kind: "WATER_ONLY_COMPANIES"
    canonical_real_world_examples:
      - "Affinity Water (parts of London)"
    scope: ["POTABLE_SUPPLY","DISTRIBUTION_ZONES"]
    note: "Enumerate exact borough/zone boundaries later."
  GBR-ENG::WATER::Z6::ORG.ECONOMIC_REGULATOR_TRANSITION:
    org_kind: "ECONOMIC_REGULATION"
    canonical_real_world: "Ofwat (transition to proposed single regulator)"
    scope: ["PRICING","INVESTMENT_DUTY","SERVICE_STANDARDS"]
  GBR-ENG::WATER::Z6::ORG.DRINKING_WATER_QUALITY_REGULATOR:
    org_kind: "QUALITY_REGULATION"
    canonical_real_world: "Drinking Water Inspectorate"
    scope: ["QUALITY_COMPLIANCE","EVENT_RESPONSE","AUDIT"]
  GBR-ENG::WATER::Z6::ORG.ENVIRONMENTAL_REGULATOR:
    org_kind: "ENVIRONMENTAL_PERMITTING_AND_ENFORCEMENT"
    canonical_real_world: "Environment Agency"
    scope: ["DISCHARGE_PERMITS","INSPECTION","ENFORCEMENT","RIVER_WATER_QUALITY"]
  GBR-UK::WATER::Z6::ORG.POLICY_OWNER:
    org_kind: "NATIONAL_POLICY"
    canonical_real_world: "Defra (policy direction; regulation reform)"
    scope: ["LEGISLATION","REFORM_PROGRAMME","EMERGENCY_FRAMEWORKS"]
# ------------------------------------------------------------
# 17C) Z5 control nodes (who executes)
# ------------------------------------------------------------
CONTROL_NODES_Z5:
  GBR-LON::WATER::Z5::CTRL.NETWORK_OPERATIONS:
    owner_org: "GBR-LON::WATER::Z6::ORG.MAIN_WATER_WASTEWATER_OPERATOR"
    node_kind: "DISTRIBUTION_AND_TRUNK_MAIN_CONTROL"
    can_execute:
      - "ACT.WATER.ZONE_ISOLATION"
      - "ACT.WATER.PRESSURE_REBALANCE"
      - "ACT.WATER.MAINS_REPAIR_ROUTING"
      - "ACT.WATER.ALTERNATIVE_SUPPLY_DEPLOY"
      - "ACT.WATER.PUBLISH_SUPPLY_STATUS"
  GBR-LON::WATER::Z5::CTRL.WATER_TREATMENT_CONTROL:
    owner_org: "GBR-LON::WATER::Z6::ORG.MAIN_WATER_WASTEWATER_OPERATOR"
    node_kind: "TREATMENT_WORKS_CONTROL"
    can_execute:
      - "ACT.WATER.TREATMENT_UPSHIFT"
      - "ACT.WATER.QUALITY_EVENT_CONTAIN"
      - "ACT.WATER.BOIL_WATER_NOTICE_REQUEST"
      - "ACT.WATER.PUBLISH_QUALITY_STATUS"
  GBR-LON::WATER::Z5::CTRL.WASTEWATER_OPERATIONS:
    owner_org: "GBR-LON::WATER::Z6::ORG.MAIN_WATER_WASTEWATER_OPERATOR"
    node_kind: "SEWER_NETWORK_AND_TREATMENT_CONTROL"
    can_execute:
      - "ACT.WATER.PUMP_STATION_REBALANCE"
      - "ACT.WATER.STORM_STORAGE_MODE"
      - "ACT.WATER.OVERFLOW_EVENT_MANAGEMENT"
      - "ACT.WATER.PUBLISH_WASTEWATER_STATUS"
  GBR-ENG::WATER::Z5::CTRL.QUALITY_REG_AUDIT:
    owner_org: "GBR-ENG::WATER::Z6::ORG.DRINKING_WATER_QUALITY_REGULATOR"
    node_kind: "QUALITY_COMPLIANCE_AND_EVENT_OVERSIGHT"
    can_execute:
      - "ACT.WATER.QUALITY_ESCALATION"
      - "ACT.WATER.REQUIRE_REMEDIAL_ACTION"
      - "ACT.WATER.PUBLISH_REGULATORY_NOTICE"
  GBR-ENG::WATER::Z5::CTRL.ENV_ENFORCEMENT:
    owner_org: "GBR-ENG::WATER::Z6::ORG.ENVIRONMENTAL_REGULATOR"
    node_kind: "PERMITS_MONITORING_ENFORCEMENT"
    can_execute:
      - "ACT.WATER.PERMIT_ENFORCEMENT"
      - "ACT.WATER.INCIDENT_INVESTIGATION"
      - "ACT.WATER.PUBLISH_ENV_STATUS"
# ------------------------------------------------------------
# 17D) Z4 corridors (the pipes)
# ------------------------------------------------------------
CORRIDORS_Z4:
  GBR-LON::WATER::Z4::CORR.RAW_WATER_TO_TREATMENT:
    payload: "ABSTRACTION_TO_TREATMENT"
    anchors: ["CTRL.WATER_TREATMENT_CONTROL"]
    coupling: ["CLIMATE","POWER","CHEM_SUPPLY (optional)"]
  GBR-LON::WATER::Z4::CORR.TREATMENT_TO_DISTRIBUTION:
    payload: "SAFE_WATER_TO_ZONES"
    anchors: ["CTRL.NETWORK_OPERATIONS","CTRL.WATER_TREATMENT_CONTROL"]
    invariants: ["QUALITY","PRESSURE"]
  GBR-LON::WATER::Z4::CORR.DISTRIBUTION_ZONES:
    payload: "ZONE_PRESSURE_AND_LAST_MILE_SUPPLY"
    anchors: ["CTRL.NETWORK_OPERATIONS"]
    note: "Tile per SUPPLY_ZONE later."
  GBR-LON::WATER::Z4::CORR.WASTEWATER_COLLECTION:
    payload: "SEWER_CONVEYANCE_TO_TREATMENT"
    anchors: ["CTRL.WASTEWATER_OPERATIONS"]
  GBR-LON::WATER::Z4::CORR.WASTEWATER_TREATMENT_TO_DISCHARGE:
    payload: "TREATMENT_TO_PERMITTED_DISCHARGE"
    anchors: ["CTRL.WASTEWATER_OPERATIONS","CTRL.ENV_ENFORCEMENT"]
    invariants: ["PERMIT_COMPLIANCE","ECOLOGICAL_SAFETY"]
  GBR-LON::WATER::Z4::CORR.EMERGENCY_WATER_DISTRIBUTION:
    payload: "ALTERNATIVE_SUPPLY (BOTTLED/TANKERS/STAT_POINTS)"
    anchors: ["CTRL.NETWORK_OPERATIONS"]
    couples_to: ["SAFE","HEALTH","GOV","TRAN"]
# ------------------------------------------------------------
# 17E) Z3 portals (interfaces)
# ------------------------------------------------------------
PORTALS_Z3:
  GBR-LON::WATER::Z3::PORTAL.CUSTOMERS:
    corridor: "CORR.DISTRIBUTION_ZONES"
    portal_kind: "LAST_MILE_DEMAND"
  GBR-LON::WATER::Z3::PORTAL.TREATMENT_WORKS:
    corridor: "CORR.TREATMENT_TO_DISTRIBUTION"
    portal_kind: "PRODUCTION_GATE"
  GBR-LON::WATER::Z3::PORTAL.TRUNK_MAINS:
    corridor: "CORR.TREATMENT_TO_DISTRIBUTION"
    portal_kind: "BACKBONE_TRANSPORT"
  GBR-LON::WATER::Z3::PORTAL.PUMPING_STATIONS:
    corridor: "CORR.WASTEWATER_COLLECTION"
    portal_kind: "FLOW_LIFT_GATE"
  GBR-LON::WATER::Z3::PORTAL.SEWAGE_TREATMENT_WORKS:
    corridor: "CORR.WASTEWATER_TREATMENT_TO_DISCHARGE"
    portal_kind: "PROCESSING_GATE"
  GBR-LON::WATER::Z3::PORTAL.RIVER_DISCHARGE_POINTS:
    corridor: "CORR.WASTEWATER_TREATMENT_TO_DISCHARGE"
    portal_kind: "ENV_INTERFACE"
# ------------------------------------------------------------
# 17F) Z3 valves (choke controls)
# ------------------------------------------------------------
VALVES_Z3:
  GBR-LON::WATER::Z3::VALVE.ZONE_ISOLATION:
    owner_ctrl: "CTRL.NETWORK_OPERATIONS"
    purpose: "truncate main breaks; limit outage radius; protect pressure/ingress risk"
  GBR-LON::WATER::Z3::VALVE.PRESSURE_MANAGEMENT:
    owner_ctrl: "CTRL.NETWORK_OPERATIONS"
    purpose: "avoid pressure collapse and pressure-shock during restore"
  GBR-LON::WATER::Z3::VALVE.QUALITY_CONTAINMENT:
    owner_ctrl: "CTRL.WATER_TREATMENT_CONTROL"
    purpose: "contain contamination; trigger boil notice path; flush + verify"
  GBR-LON::WATER::Z3::VALVE.STORM_STORAGE_MODE:
    owner_ctrl: "CTRL.WASTEWATER_OPERATIONS"
    purpose: "buffer storm flows; reduce uncontrolled discharges"
  GBR-LON::WATER::Z3::VALVE.OVERFLOW_CONTROL:
    owner_ctrl: "CTRL.WASTEWATER_OPERATIONS"
    purpose: "manage overflow events to minimise harm; sequence recovery"
  GBR-LON::WATER::Z3::VALVE.EMERGENCY_SUPPLY_GATE:
    owner_ctrl: "CTRL.NETWORK_OPERATIONS"
    purpose: "deploy alternative water distribution to critical users first"
# ------------------------------------------------------------
# 17G) Z2 subnets (operational tiling)
#   NOTE: These are abstract tiles for v0.1. Later bind to real supply zones/catchments.
# ------------------------------------------------------------
SUBNETS_Z2:
  GBR-LON::WATER::Z2::SUBNET.CENTRAL_CORE:
    description: "highest consequence density; hospitals/finance/government coupling"
  GBR-LON::WATER::Z2::SUBNET.NORTH:
    description: "tile; overlaps some water-only supplier areas"
  GBR-LON::WATER::Z2::SUBNET.WEST:
    description: "tile; includes major trunk main corridors"
  GBR-LON::WATER::Z2::SUBNET.EAST:
    description: "tile; includes large wastewater conveyance pressure"
  GBR-LON::WATER::Z2::SUBNET.SOUTH:
    description: "tile; mixed density and storage"
  GBR-LON::WATER::Z2::SUBNET.OUTER_RING:
    description: "outer buffers; leverage for isolation and rerouting"
# ------------------------------------------------------------
# 17H) Z1 cells (where failure first appears)
# ------------------------------------------------------------
CELLS_Z1:
  GBR-LON::WATER::Z1::CELL.LOW_PRESSURE_CLUSTER:
    surface_kind: "LAST_MILE_CONFLICT_ZONE"
    parent_corridor: "CORR.DISTRIBUTION_ZONES"
  GBR-LON::WATER::Z1::CELL.MAINS_BREAK_QUEUE:
    surface_kind: "QUEUE_FIELD"
    parent_valve: "VALVE.ZONE_ISOLATION"
  GBR-LON::WATER::Z1::CELL.TURBIDITY_SPIKE_FRONTIER:
    surface_kind: "LAST_MILE_CONFLICT_ZONE"
    parent_valve: "VALVE.QUALITY_CONTAINMENT"
  GBR-LON::WATER::Z1::CELL.CUSTOMER_COMPLAINT_SURGE:
    surface_kind: "QUEUE_FIELD"
    parent_portal: "PORTAL.CUSTOMERS"
  GBR-LON::WATER::Z1::CELL.PUMP_STATION_FAILURE_QUEUE:
    surface_kind: "QUEUE_FIELD"
    parent_portal: "PORTAL.PUMPING_STATIONS"
  GBR-LON::WATER::Z1::CELL.OVERFLOW_EVENT_CLUSTER:
    surface_kind: "INCIDENT_FIELD"
    parent_valve: "VALVE.OVERFLOW_CONTROL"
# ------------------------------------------------------------
# 17I) Sensors (water specialisations)
# ------------------------------------------------------------
SENSORS_WATER:
  S.water.zone_pressure_delta:
    maps_to: "S.capacity_delta"
  S.water.outage_customers_proxy:
    maps_to: "S.queue_index"
  S.water.turbidity_proxy:
    maps_to: "S.variance_index"
  S.water.disinfectant_residual_proxy:
    maps_to: "S.variance_index"
  S.water.quality_event_flag:
    maps_to: "S.incident_state"
  S.water.treatment_capacity_delta:
    maps_to: "S.capacity_delta"
  S.water.storage_reservoir_level_delta:
    maps_to: "S.capacity_delta"
  S.water.burst_rate_proxy:
    maps_to: "S.queue_index"
  S.water.wastewater_flow_surge:
    maps_to: "S.throughput_rate"
  S.water.sewer_backflow_proxy:
    maps_to: "S.queue_index"
  S.water.overflow_event_rate:
    maps_to: "S.incident_state"
  S.water.permit_breach_risk_proxy:
    maps_to: "S.rebound_risk"
  S.water.public_trust_signal:
    maps_to: "S.substitution_pressure"
# ------------------------------------------------------------
# 17J) Tripwires (P1/P0) + truncation/stitch rules
# ------------------------------------------------------------
TRIPWIRES:
  WATER_P1_EARLY_WARNING:
    if:
      - "zone_pressure_delta negative 2 windows"
      - "OR turbidity_proxy rises 2 bands"
      - "OR customer_complaint_surge rising + outage proxy rising"
      - "OR overflow_event_rate rising during storm windows"
    then:
      - "activate PLAYBOOK.WATER.SUPPLY_CONTINUITY_TRUNCATION"
      - "activate PLAYBOOK.WATER.QUALITY_EVENT_PRECONTAIN"
      - "activate PLAYBOOK.WATER.STORM_OVERFLOW_TRUNCATION"
  WATER_P1_TRIGGER:
    if:
      - "outage_customers_proxy > 55"
      - "OR confirmed widespread low pressure cluster"
      - "OR repeated overflow events + backflow proxy rising"
    then:
      - "TRUNCATE: isolate zones, rebalance pressure, deploy emergency supply to critical sites"
      - "publish unified status via DATA/GOV comms spine"
  WATER_P0_TRIGGER:
    if:
      - "quality_event_flag in [CONFIRMED_CONTAMINATION]"
      - "OR outage_customers_proxy > 80"
      - "OR uncontrolled wastewater discharge with health risk escalation"
    then:
      - "HARD CONTAINMENT: boil water / do-not-use path as required"
      - "emergency distribution activated"
      - "stitch only after verification windows pass (quality + pressure + stability)"
# ------------------------------------------------------------
# 17K) Playbooks (executable sequences)
# ------------------------------------------------------------
PLAYBOOK_LIBRARY:
  PLAYBOOK.WATER.SUPPLY_CONTINUITY_TRUNCATION:
    intent: "Stop burst/pressure collapse from becoming citywide outage + ingress risk."
    truncate:
      - {act: ACT.WATER.ZONE_ISOLATION, owner: "CTRL.NETWORK_OPERATIONS"}
      - {act: ACT.WATER.PRESSURE_REBALANCE, owner: "CTRL.NETWORK_OPERATIONS"}
      - {act: ACT.WATER.MAINS_REPAIR_ROUTING, owner: "CTRL.NETWORK_OPERATIONS"}
      - {act: ACT.WATER.ALTERNATIVE_SUPPLY_DEPLOY, owner: "CTRL.NETWORK_OPERATIONS", when: "critical nodes"}
      - {act: ACT.WATER.PUBLISH_SUPPLY_STATUS, owner: "CTRL.NETWORK_OPERATIONS"}
    stitch:
      - "restore pressure in stages (avoid shock)"
      - "flush where needed; verify quality before full reopen"
      - "remove emergency supply only after 2-window P3 stability"
  PLAYBOOK.WATER.QUALITY_EVENT_PRECONTAIN:
    intent: "Contain suspected quality anomaly before it becomes population-scale harm."
    truncate:
      - {act: ACT.WATER.QUALITY_EVENT_CONTAIN, owner: "CTRL.WATER_TREATMENT_CONTROL"}
      - {act: ACT.WATER.BOIL_WATER_NOTICE_REQUEST, owner: "CTRL.WATER_TREATMENT_CONTROL", when: "threshold breached"}
      - {act: ACT.WATER.PUBLISH_QUALITY_STATUS, owner: "CTRL.WATER_TREATMENT_CONTROL"}
      - {act: ACT.WATER.QUALITY_ESCALATION, owner: "CTRL.QUALITY_REG_AUDIT", when: "regulatory trigger"}
    stitch:
      - "verification windows: microbiological + chemical + distribution integrity"
      - "lift notices only after passed windows; communicate clearly"
  PLAYBOOK.WATER.STORM_OVERFLOW_TRUNCATION:
    intent: "Keep storm flows from becoming uncontrolled discharges + health externalities."
    truncate:
      - {act: ACT.WATER.STORM_STORAGE_MODE, owner: "CTRL.WASTEWATER_OPERATIONS"}
      - {act: ACT.WATER.PUMP_STATION_REBALANCE, owner: "CTRL.WASTEWATER_OPERATIONS"}
      - {act: ACT.WATER.OVERFLOW_EVENT_MANAGEMENT, owner: "CTRL.WASTEWATER_OPERATIONS"}
      - {act: ACT.WATER.PUBLISH_WASTEWATER_STATUS, owner: "CTRL.WASTEWATER_OPERATIONS"}
    stitch:
      - "return from storm mode gradually; prevent backflow rebound"
      - "prioritise cleanup/monitoring at discharge interfaces"
  PLAYBOOK.WATER.EMERGENCY_DISTRIBUTION:
    intent: "Provide safe water when supply continuity or quality is broken."
    truncate:
      - {act: ACT.WATER.ALTERNATIVE_SUPPLY_DEPLOY, owner: "CTRL.NETWORK_OPERATIONS"}
      - {act: ACT.WATER.PUBLISH_SUPPLY_STATUS, owner: "CTRL.NETWORK_OPERATIONS"}
    stitch:
      - "scale down only when normal network verified stable; avoid premature withdrawal"
# ------------------------------------------------------------
# 17L) Failure mode traces (canonical, non-emotive)
# ------------------------------------------------------------
FAILURE_MODE_TRACE:
  TRACE_BURST_TO_PRESSURE_COLLAPSE:
    chain:
      - "trunk main failure ->"
      - "zone pressure drops ->"
      - "outage cluster expands ->"
      - "ingress risk rises ->"
      - "quality uncertainty"
    repair:
      - "zone isolation + pressure rebalance"
      - "repair routing"
      - "stitch via staged restore + verification"
  TRACE_STORM_TO_OVERFLOW_TO_HEALTH_PRESSURE:
    chain:
      - "storm surge ->"
      - "sewer capacity exceeded ->"
      - "overflow events ->"
      - "public exposure ->"
      - "health lane demand rises"
    repair:
      - "storm storage mode + pump rebalance"
      - "stitch gradual; monitor downstream"
  TRACE_QUALITY_EVENT_TO_TRUST_SHOCK:
    chain:
      - "quality anomaly ->"
      - "conflicting messages ->"
      - "panic substitution (bottled rush) ->"
      - "distribution strain ->"
      - "governance credibility hit"
    repair:
      - "single comms spine (Section 12)"
      - "clear notices + verification windows"
# ------------------------------------------------------------
# 17M) Cross-lane couplings (London)
# ------------------------------------------------------------
CROSS_LANE_COUPLINGS:
  WATER__HEALTH:
    strength: HIGH
    note: "quality/outage immediately routes into health demand and public safety actions"
  WATER__WASTE:
    strength: HIGH
    note: "wastewater is a coupled organ; failures propagate as environmental hazards"
  WATER__SAFE:
    strength: HIGH
    note: "incident management, public guidance, and crowd control at distribution points"
  WATER__DATA:
    strength: HIGH
    note: "trusted publishing prevents panic; supports boil/restore sequencing"
  WATER__TRAN:
    strength: MED
    note: "repair crews and tankers depend on movement corridors"
  WATER__FIN:
    strength: MED
    note: "investment/maintenance deficits manifest as rising burst/overflow rates"
  WATER__GOV:
    strength: HIGH
    note: "regulatory transition state must not create decision-latency during incidents"
# ------------------------------------------------------------
# 17N) Expansion rules (toward full London enumeration)
# ------------------------------------------------------------
EXPANSION_RULES:
  R1_SUPPLY_ZONE_ENUMERATION:
    do:
      - "Enumerate SUPPLY_ZONE records (Z2) and bind to valves + pressure sensors."
      - "Bind each borough/area to its water supplier(s) (water-only vs water+sewer)."
  R2_ASSET_BACKBONE_ENUMERATION:
    do:
      - "Enumerate treatment works, reservoirs, trunk mains, pumping stations (Z3 portals)."
      - "Tile critical single-points and redundancy paths."
  R3_WASTEWATER_CATCHMENT_ENUMERATION:
    do:
      - "Enumerate SEWER_CATCHMENT records (Z2) and overflow interface nodes (Z3)."
      - "Attach permit-risk sensors + enforcement escalation routes."
  R4_EXECUTABILITY_AUDIT:
    do:
      - "For every ACT.*: executor + publisher + pre-auth/policy path must exist."
  R5_RESTORATION_SAFETY_LOCKS:
    do:
      - "Define staged restore recipes per zone (pressure ramp rates, flush protocols, sampling windows)."
  R6_REGULATOR_TRANSITION_COMPAT:
    do:
      - "Model regulators as TRANSITION_STATE; version forward once single-regulator structure is final."