"""
Run the full pipeline over every building and write per-facet and
per-panel geometries (not just building-level aggregates) to
data/panel_layouts.geojson, so the frontend can show the actual proposed
layout -- not just a kWp number -- when a building is clicked.

One FeatureCollection, features tagged with a "kind" property ("facet" or
"panel") and "building_id" so the frontend can filter to just the
clicked building's layout. Facets carry slope/aspect/irradiance;
panels carry which facet they belong to.

Runs the per-building work across processes. Buildings are independent --
segmentation, obstruction detection and packing all read shared rasters and
write nothing shared -- and the parallel wrapper around this only fans out
across AREAS, so rebuilding one area (the loop actually iterated on) used
one core out of twelve and took hours. The same per-building work parallelises
to ~25 minutes for the pilot in scan_defects.py.

Usage: python src/build_layout_geojson.py [area ...] [--jobs N]
"""

import json
import os
import signal
import sys
import time
import multiprocessing
from multiprocessing.util import Finalize
from concurrent.futures import ProcessPoolExecutor, wait
from pathlib import Path

import pyproj
import rasterio
from shapely.ops import transform as shapely_transform

sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
import shapely
import config
from src.outline_fit import fitted_outlines
from src.preflight import preflight
import geopandas as gpd

from src.roof_segmentation import segment_building_best, roof_confidence, _note_fallback
from src.ridge_snap import snap_ridges_to_crest
from src.plane_seams import snap_seams_to_plane_intersections
from src.roof_levels import split_lower_levels
from src.face_steps import split_steps
from src.plane_refresh import refresh_planes
from src.pointcloud_source import PointCloudSource
from src.panel_fitting import fit_panels_on_facet, drop_minor_arrays, drop_scraps, assign_fill_ranks, building_frame, register_frame, enforce_arrays, shape_arrays, centre_panels
from src.obstruction_detection import detect_obstructions_combined
from src.obstruction_planarity import drop_edge_hugging, drop_roof_like
from src.solar_model import SolarModel
from src.curved_faces import split_curved_faces
from src.face_rectify import rectify_faces
from src.face_straighten import absorb_slivers, fit_seams, merge_coplanar_faces, seams_to_plane_lines, straighten_faces
from src.building_shading import building_shading_factor, facet_sun, facet_sun_context
from src.building_horizon import (far_profile as _hz_far_profile,
                                  facet_horizon_factor as _hz_facet_factor,
                                  eave_height as _hz_eave_height,
                                  load_far_dem as _hz_load_far_dem)
from src.region_build import area_paths, area_centroid_wgs84, areas_from_argv
from src.imagery_sources import selected_imagery_paths

DATA_DIR = Path(__file__).resolve().parent.parent / "data"
DEEP_SHADE_FACTOR = 0.45  # a panel keeping less than this share of the year's direct beam is
# under a tree/neighbour and should not be proposed at all

# Below this share of a roof's points lying within 30 cm of the planes we are
# about to place panels on, do not propose panels at all. 10 Stanley St is
# the case: a very complicated roof that should have no panels rather than a
# wrong layout.
# Showing a confident-looking layout on a roof we have not understood is worse
# than showing nothing -- the number carries authority it has not earned.
# 10 Stanley measures 35% on-plane; the next worst building in the sampled
# pilot set is 52%, so this separates the genuinely unmodelled roofs rather
# than trimming a continuum.
MIN_ROOF_CONFIDENCE = 0.45
BIG_ROOF_M2 = 1000.0
BIG_ROOF_FACET_MIN_FIT = 0.60
BIG_ROOF_MIN_PANELS = 8


def _facet_fit(f, pc_source):
    """This one facet's own on-plane fraction -- how believable it is alone."""
    try:
        g = f["geometry"]
        minx, miny, maxx, maxy = g.bounds
        pts = pc_source.points_in_bbox(minx, miny, maxx, maxy, building_only=True)
        if len(pts) < 12:
            return 1.0            # too few points to judge: do not punish
        inside = shapely.contains_xy(g, pts[:, 0], pts[:, 1])
        pts = pts[inside]
        if len(pts) < 12:
            return 1.0
        import numpy as np
        r = pts[:, 2] - (f["plane_a"] * pts[:, 0] + f["plane_b"] * pts[:, 1] + f["plane_c"])
        r = r - np.median(r)
        return float((np.abs(r) < 0.15).mean())
    except Exception:
        return 1.0

# Raised from 6. The 6 was set while chasing OOM crashes, and the actual cause
# turned out to be PointCloudSource caching all 441 LiDAR tiles unbounded --
# fixed with an LRU there -- but the cap was never put back. Measured startup is
# 0.4s per worker and steady RSS is well under a gigabyte each.
# Hard ceiling; the real limit is memory, below. Raised 10 -> 14 after measuring
# the VM mid-build: 16 vCPUs, 58 of 62 GB free, workers at 0.69 GB rather than
# the 1.75 GB budgeted. The memory bound allowed 21 and the CPU bound 15, so
# this constant -- not the machine -- was what held the stage to ten workers.
# Left at a ceiling rather than removed because the parent process merges every
# feature single-threaded, and past ~14 producers that merge is the bottleneck.
DEFAULT_MAX_JOBS = 14
PER_WORKER_GB = 1.75           # decoded LiDAR tile cache per worker process
USABLE_RAM_FRACTION = 0.6      # headroom for the parent process and the OS


def _memory_bounded_jobs(per_worker_gb=PER_WORKER_GB):
    """Workers this machine can actually feed. See the long note in main()."""
    try:
        total_gb = (os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
                    / 1024 ** 3)
    except (ValueError, OSError, AttributeError):
        return 4               # unknown machine: the conservative middle
    by_ram = int(total_gb * USABLE_RAM_FRACTION // per_worker_gb)
    return max(1, min(by_ram, (os.cpu_count() or 2) - 1, DEFAULT_MAX_JOBS))

# How long the whole pool may go without a single building completing before it
# says so, and before it gives up. Normal per-building time is around a second
# and the slowest roof measured on frankton_flats is 16s, so 120s of total
# silence across every worker already means something is wrong.
STALL_REPORT_S = 120
STALL_ABORT_S = 1800

# No single building may cost the district. Building 4722059 on frankton_flats
# (16,010 m2, 226 m across, 73,226 points) does not finish: partition_roof alone
# handles it in 41s, but segment_building_best compares several strategies and
# then post-processes 51 facets, and the whole call was still running after 14
# minutes. It stalled two rebuilds before the watchdog above could even name it.
# One airport-scale roof missing from the map is a far smaller loss than the
# other 14,000 buildings not shipping, so a building over budget is dropped and
# reported by id -- never silently.
BUILDING_TIME_BUDGET_S = 600  # the partition alone may now spend 240s on a
# big commercial roof (see roof_partition.CUT_TIME_BUDGET_MAX_S), so the
# whole-building alarm has to leave room for obstructions and panel fitting
# on top of that. Still bounded: a stall is cut off, just later.


class _BuildingTimeout(BaseException):
    # BaseException DELIBERATELY: the segmentation fallback machinery
    # catches Exception to try its next method, and on #4722059 it caught
    # the whole-building alarm as if RANSAC had merely failed -- the alarm
    # fires once, so the building then ran unbounded and stalled the
    # district build for 4.5 hours. A time budget must not be negotiable
    # by any except-Exception between here and the stall.
    pass


def _on_timeout(signum, frame):
    raise _BuildingTimeout()

_CTX = {}


def _close_worker_rasters():
    seen = set()
    for key in ("dsm_ds", "imagery_ds", "photo_ds"):
        dataset = _CTX.pop(key, None)
        if dataset is not None and id(dataset) not in seen:
            seen.add(id(dataset))
            dataset.close()


def _init_worker(area, model):
    """One heavy context per process. The SolarModel is built ONCE in the parent
    and shipped in (0.5 MB, picklable): constructing it per worker would fire a
    NASA POWER request per process."""
    _close_worker_rasters()
    # Close GDAL handles before interpreter teardown, while Rasterio's
    # Python callbacks are still available in spawned workers.
    Finalize(None, _close_worker_rasters, exitpriority=10)
    paths = area_paths(area)
    dsm_ds = rasterio.open(paths["dsm"])
    # Only the slice this region's rays can reach. The pool spawns rather than
    # forks, so whatever this reads is held once PER WORKER -- see
    # building_horizon.load_far_dem. A missing or non-overlapping wide DEM
    # degrades the far-horizon correction to a no-op rather than failing.
    _dw_band, _dw_tr, _dw_nd = _hz_load_far_dem(
        DATA_DIR / "dem_wide_mosaic.tif", dsm_ds.bounds)
    _CTX.update({"dem_wide_band": _dw_band, "dem_wide_transform": _dw_tr,
                 "dem_wide_nodata": _dw_nd})
    imagery_path, photo_path = selected_imagery_paths(paths)
    _CTX.update({
        # outlines slid onto the roof the LiDAR sees where clearly off
        # (src/outline_fit.py, SOLAR_OUTLINE_FIT)
        "gdf": fitted_outlines(gpd.read_file(paths["outlines"]),
                               paths["dir"]).set_index("building_id", drop=False),
        "dsm_ds": dsm_ds,
        "dsm_band": dsm_ds.read(1),
        "imagery_ds": rasterio.open(imagery_path) if imagery_path else None,
        # The photo that sits on the LiDAR (the survey year's own capture):
        # anything that samples colour INSIDE a LiDAR-derived shape reads
        # this one, or a 2-3 m strip samples the wall beside it through the
        # map photo's lean (src/register_imagery.py).
        "photo_ds": rasterio.open(photo_path) if photo_path else None,
        "pc_source": PointCloudSource(),
        "model": model,
        "to_wgs84": pyproj.Transformer.from_crs("EPSG:2193", "EPSG:4326",
                                                always_xy=True).transform,
    })
    # SOLAR_PIPELINE_PHOTO=reference: every image-derived step (colour and
    # bright obstructions, imagery cuts) reads the photo that sits on the
    # LiDAR instead of the map's leaning one. Off until measured.
    if os.environ.get("SOLAR_PIPELINE_PHOTO", "map") == "reference" and _CTX.get("photo_ds") is not None:
        _CTX["imagery_ds"] = _CTX["photo_ds"]


# SIGALRM IS POSIX-ONLY. Windows has no alarm signal, so the per-building
# budget below cannot exist there and every building would die on an
# AttributeError instead. Rather than bar Windows from the project (the
# quickstart said "macOS or Linux" without a reason), the budget becomes
# a no-op there, announced once so nobody is surprised later: without it a
# pathological roof can run unbounded instead of being dropped and named.
# Every other POSIX dependency in the build is already guarded -- the two
# os.sysconf calls fall back to a conservative worker count.
_HAVE_ALARM = hasattr(signal, "SIGALRM")
_ALARM_WARNED = [False]


def _set_alarm(seconds):
    if _HAVE_ALARM:
        signal.alarm(seconds)
    elif seconds and not _ALARM_WARNED[0]:
        _ALARM_WARNED[0] = True
        print("  note: no SIGALRM on this platform -- the per-building time "
              "budget is disabled, so a pathological roof will run long "
              "rather than being dropped", flush=True)


def _build_one(building_id):
    """Everything for one building. Returns its GeoJSON features."""
    if _HAVE_ALARM:
        signal.signal(signal.SIGALRM, _on_timeout)
    # the budget scales with the roof: a flat 600s cap zeroed the
    # district's biggest building (#4722059, 3,704 live panels) while
    # every neighbour got its estimate. One 30-minute outlier on one
    # worker is cheap; a dark landmark is not.
    try:
        _area = _CTX["gdf"].loc[building_id].geometry.area
    except Exception:
        _area = 0.0
    _cap = int(os.environ.get("SOLAR_BUILDING_BUDGET_CAP_S", "1800"))
    budget = int(min(_cap, max(BUILDING_TIME_BUDGET_S,
                               BUILDING_TIME_BUDGET_S + (_area - 1500) * 0.6)))
    _set_alarm(budget)
    try:
        return _build_one_inner(building_id)
    except _BuildingTimeout:
        print(f"  building {building_id} DROPPED: over {budget}s budget",
              file=sys.stderr, flush=True)
        return _no_estimate_only(building_id, "timed_out")
    except Exception as exc:
        print(f"  building {building_id} FAILED: {exc!r}", flush=True)
        return _no_estimate_only(building_id, "failed")
    finally:
        _set_alarm(0)


# WHY A BUILDING HAS NO ESTIMATE.
#
# Until now a building we could not model simply vanished: it emitted no
# features, so derive_solar_potential -- which aggregates over whatever appears
# in panel_layouts -- never saw it, and it was absent from the map entirely.
# The buildings should stay, marked with why they are not estimated.
#
# The failure mode is worse than a wrong number. A homeowner
# who searches their address and finds NOTHING cannot tell whether we think
# their roof is hopeless, whether we have never looked, or whether the site is
# broken. An honest "too steep to model" is a better answer than silence.
NO_ESTIMATE_REASONS = {
    "too_steep":     "Roof is steeper than we model (over {cap}\u00b0)",
    "no_lidar":      "Not enough laser survey data over this roof",
    "no_surface":    "No usable roof surface could be resolved",
    "low_confidence": "Roof shape could not be read confidently enough",
    "all_obstructed": "Roof is covered by vents, plant or other obstructions",
    "too_small":     "No roof area large enough for a panel",
    "demolished":    "Recorded as demolished or replaced since the survey",
    "timed_out":     "Too complex to finish modelling",
    "failed":        "Modelling failed on this building",
}


def _diagnose_no_facets(row_geom, pc_source):
    """Best available answer for why segmentation produced nothing.

    Deliberately cheap -- this runs only for buildings that already failed, and
    a wrong-but-honest reason is better than none."""
    import numpy as np
    try:
        pts = pc_source.points_in_bbox(*row_geom.bounds)
    except Exception:
        return "no_surface"
    if pts is None or len(pts) < 12:
        return "no_lidar"
    try:
        import shapely
        inside = pts[shapely.contains_xy(row_geom, pts[:, 0], pts[:, 1])]
        if len(inside) < 12:
            return "no_lidar"
        A = np.c_[inside[:, 0] - inside[:, 0].mean(),
                  inside[:, 1] - inside[:, 1].mean(), np.ones(len(inside))]
        coef, *_ = np.linalg.lstsq(A, inside[:, 2], rcond=None)
        slope = float(np.degrees(np.arctan(np.hypot(coef[0], coef[1]))))
        if slope > config.MAX_ROOF_SLOPE_DEG:
            return "too_steep"
    except Exception:
        return "no_surface"
    if row_geom.area < 8:
        return "too_small"
    return "no_surface"


def _no_estimate_feature(building_id, row_geom, to_wgs84, reason):
    """One feature carrying the building and the reason, so it still draws."""
    try:
        geom_wgs = shapely_transform(to_wgs84, row_geom)
    except Exception:
        return None
    return {
        "type": "Feature",
        "geometry": geom_wgs.__geo_interface__,
        "properties": {
            "kind": "no_estimate",
            "building_id": int(building_id),
            "no_estimate_reason": reason,
            "no_estimate_text": NO_ESTIMATE_REASONS.get(reason, reason).format(
                cap=config.MAX_ROOF_SLOPE_DEG),
        },
    }


def _geometry_stage(building_id, stage, facets, *args, **kwargs):
    """Run a stage that refines face geometry; it may improve a roof but
    never lose one. A stage that raises leaves the faces as they were, and
    faces it returns empty or invalid are repaired or dropped here -- an
    empty face reaching the yield step crashed four roofs on 25 Sep that had
    55 panels each on the live map."""
    try:
        out = stage(facets, *args, **kwargs)
    except Exception as exc:
        _note_fallback(stage.__name__, building_id, exc)
        return facets
    clean = []
    for f in out:
        g = f["geometry"]
        if g is None or g.is_empty:
            continue
        if not g.is_valid:
            g = shapely.make_valid(g)
            parts = [p for p in getattr(g, "geoms", [g]) if p.geom_type == "Polygon" and not p.is_empty]
            if not parts:
                continue
            g = max(parts, key=lambda p: p.area)
            f = dict(f, geometry=g)
            if "area_m2" in f:
                f["area_m2"] = g.area
        if g.area > 0:
            clean.append(f)
    return clean if clean else facets


def _no_estimate_only(building_id, reason):
    """Keep the building on the map even when its build blew up."""
    try:
        c = _CTX
        f = _no_estimate_feature(building_id, c["gdf"].loc[building_id].geometry,
                                 c["to_wgs84"], reason)
        return [f] if f else []
    except Exception:
        return []


def _build_one_inner(building_id):
    """Best of N layouts for one building, where N is configured.

    WHY THIS EXISTS. Placement is unstable with respect to its own input: a
    +/-10 cm nudge to the outline -- an order of magnitude finer than the
    outlines are surveyed to -- moves the panel count by a MEDIAN of 26%, worst
    case 88%, on a deterministic segmenter. The partition is a greedy recursive
    search and every cut has a threshold, so a nudge flips the marginal ones and
    the difference compounds through the facets beneath.

    We publish rooftop POTENTIAL, so the best valid packing is the honest answer
    rather than whichever one a greedy search happened to reach first.

    THE GAIN IS +3.45%, NOT THE +11.4% FIRST MEASURED. That first figure came
    from a harness that called segment_building_best and fit_panels_on_facet
    directly. The real pipeline also runs the panel gate, per-panel shading and
    the deep-shade veto, and those absorb most of the variance -- they strip
    marginal panels regardless of which partition produced them. Measured
    through THIS function over 26 pilot buildings:

        base            1073
        best-of-2       1110    (+3.45%)   2x layout compute

    11 of 26 buildings moved, all upward, since the base layout is always one
    of the candidates. Whether that is worth doubling the most expensive stage
    of a district build is a judgement call, and a much weaker one than the
    simplified harness suggested.

    VALIDATED BEFORE BEING OFFERED. The extra panels do not come from paving
    over equipment -- panel area landing on hand-marked obstructions went DOWN,
    6.43% to 5.65% of placed area -- and every panel stays inside the true
    outline, because the edge setback (config.PANEL_EDGE_SETBACK_M) keeps them clear of the boundary
    regardless of which boundary was used to find them.

    OFF BY DEFAULT. It multiplies the layout stage, which is the expensive one,
    so switching it on is a deliberate decision about compute rather than
    something to inherit silently.
    """
    nudges = list(getattr(config, "LAYOUT_PERTURBATIONS_M", ()) or ())
    if not nudges:
        return _build_one_at(building_id, None)

    best, best_panels = None, -1
    for nudge in [None] + nudges:
        try:
            feats = _build_one_at(building_id, nudge)
        except Exception:
            continue
        n_panels = sum(1 for f in feats
                       if f["properties"].get("kind") == "panel")
        if n_panels > best_panels:
            best, best_panels = feats, n_panels
    return best if best is not None else []


def _build_one_at(building_id, nudge_m):
    c = _CTX
    model, dsm_ds, dsm_band = c["model"], c["dsm_ds"], c["dsm_band"]
    to_wgs84, pc_source, imagery_ds = c["to_wgs84"], c["pc_source"], c["imagery_ds"]
    row_geom = c["gdf"].loc[building_id].geometry
    if nudge_m:
        # The nudge only ever perturbs the SEARCH. Panels are still fitted with
        # the real edge setback, and the setback is larger than any nudge here,
        # so nothing can end up outside the surveyed outline.
        try:
            g = row_geom.buffer(nudge_m)
            if not g.is_empty and g.is_valid:
                row_geom = g
        except Exception:
            pass

    features = []
    # Imagery is passed in so the partition can cut on roof creases the LiDAR
    # cannot resolve -- see roof_partition.partition_roof. Rural areas have no
    # imagery and fall back to LiDAR-only cuts.
    facets = segment_building_best(dsm_ds, pc_source, row_geom, building_id,
                                   imagery_ds=imagery_ds)
    if not facets:
        f = _no_estimate_feature(building_id, row_geom, to_wgs84,
                                 _diagnose_no_facets(row_geom, pc_source))
        return [f] if f else []
    _dsm_ev = (_CTX["dsm_band"], _CTX["dsm_ds"].transform, _CTX["dsm_ds"].nodata) \
        if _CTX.get("dsm_ds") is not None else None
    # Where two faces meet is decided by the crest the returns show, not by
    # where two noisy plane fits happen to cross -- see src/ridge_snap.py
    # (2 Preston Drive: a ridge 0.8 m off with a panel column astride it).
    # A face whose plane misfits its own returns misleads every stage below
    # (src/plane_refresh.py: 17 Church St, 27% -> 83% of returns on plane).
    # A PLAIN FORM IS EXACT (src/structured_roof.py): its ridges, hips and
    # valleys are the straight skeleton of the walls. The stages below move
    # lines to where noisy planes cross, and on a form they only damage it --
    # 4718459's T-shaped hip came out with a doubled ridge and curved seams at
    # the junction (20 Oct). Its planes are still refreshed; its lines stay.
    # SOLAR_KEEP_FORMS=0 runs every stage as before.
    _form = (os.environ.get("SOLAR_KEEP_FORMS", "1") != "0"
             and bool(facets) and all(f.get("structured") for f in facets))
    _reshape = (lambda stage, *a, **k: facets) if _form else \
        (lambda stage, *a, **k: _geometry_stage(building_id, stage, facets, *a, **k))
    facets = _geometry_stage(building_id, refresh_planes, facets, pc_source, dsm=_dsm_ev)
    facets = _reshape(snap_ridges_to_crest, pc_source, dsm=_dsm_ev)
    # ...and roof a face took from its neighbour across a hip or valley goes
    # back, or obstruction detection marks the neighbour's slope as an object
    # over clear roof (src/plane_seams.py).
    facets = _reshape(snap_seams_to_plane_intersections, pc_source, dsm=_dsm_ev)
    # ...and a lower roof level spanned by one face gets a face of its own,
    # or the sunken detector carves clear roof as an object (src/roof_levels.py).
    # ...and again after the seams moved geometry under unchanged planes.
    facets = _geometry_stage(building_id, refresh_planes, facets, pc_source, dsm=_dsm_ev)
    facets = _reshape(split_lower_levels, pc_source, dsm=_dsm_ev, photo=_CTX.get("photo_ds"))
    # ...and a face whose returns lie on two planes a step apart (or, with
    # SOLAR_STEP_SPLIT=2, folded) becomes two faces (src/face_steps.py;
    # SOLAR_STEP_SPLIT=0 turns it off).
    facets = _reshape(split_steps, pc_source)
    # ...and last, the edges between faces straightened together, so a ridge
    # is a line rather than the zig-zag the returns left (src/face_straighten.py).
    facets = _reshape(merge_coplanar_faces)
    facets = _reshape(absorb_slivers, pc_source)
    facets = _reshape(seams_to_plane_lines, pc_source)
    facets = _reshape(fit_seams, pc_source)
    # ...and seams rebuilt as straight lines where the faces allow it
    # (src/face_rectify.py; SOLAR_RECTIFY_FACES=1).
    facets = _reshape(rectify_faces, pc_source)
    facets = _reshape(straighten_faces)
    # ...and a face that curves in plan gets a plane per section (src/curved_faces.py,
    # off unless SOLAR_CURVED_SPLIT=1).
    facets = _reshape(split_curved_faces, pc_source)

    # Do not propose panels on a roof we have not understood -- see
    # MIN_ROOF_CONFIDENCE. Facets are still emitted so the roof draws on the
    # map; only the layout is withheld.
    confidence = roof_confidence(facets, pc_source, dsm=_dsm_ev) if facets else 0.0
    # A ROOF JOSH DREW IS NOT WITHHELD FOR LOW CONFIDENCE.
    #
    # roof_confidence asks how well the points fit the planes we FITTED.
    # On a roof whose faces came from his markup that question does not apply:
    # the faces are his, and small ones with too little survey under them
    # deliberately borrow a neighbour's plane, which by construction does not
    # fit their own points and drags the average down.
    #
    # Left unguarded this withheld 23 buildings that had panels before, 892
    # panels, five of them roofs he had labelled -- including 32 Frankton Road
    # (#4725584), which built 33 facets from his drawing at sensible flat-roof
    # slopes of 1-11 degrees and then shipped ZERO panels. He would have found
    # that on the map in seconds, and the cause would have been a confidence
    # score about planes nobody fitted.
    from_labels = bool(facets) and any(f.get("from_labels") for f in facets)
    # ...AND NOR IS A ROOF WE MODELLED OURSELVES where no LiDAR exists
    # (src/synthesize_dsm.py). Its planes are the model; scoring them against
    # the 1 m surface built from that same model measures rasterising, not
    # the roof, and withheld 62 of Bannockburn's 489 buildings.
    synthetic = bool(facets) and any(f.get("synthetic") for f in facets)
    if synthetic:
        confidence = 1.0      # not a survey measure: pitch_guessed carries the doubt
    modelled = from_labels or synthetic or confidence >= MIN_ROOF_CONFIDENCE

    # On large commercial roofs, find the large clear areas to place panels
    # on rather than squeezing in every possible face, and ignore any clean
    # area that would take fewer than 8 panels. 32 Frankton Road is the case: 4,032 m2 shipped
    # as two sheets fitting 15.3% and 16.3% carrying 1,138 panels. On big roofs
    # each facet must EARN panels: it has to be a believable plane on its own,
    # and it has to take at least 8 panels.
    big_roof = row_geom.area >= BIG_ROOF_M2

    # Per-building FAR terrain horizon: every number must take the
    # building's own horizon into account. The POA lookup carries the
    # AREA's shared profile; _hz_facet_factor converts each facet to this
    # building's own terrain, aspect-aware, so a valley-floor roof loses its
    # east sun where a hilltop roof three streets over does not. Near-field
    # neighbours/trees stay with building_shading_factor below -- the far/near
    # split is what stops the same blocker being counted twice.
    _bld_far = None
    if _CTX.get("dem_wide_band") is not None:
        _eave = _hz_eave_height(dsm_band, dsm_ds.transform, dsm_ds.nodata, row_geom)
        _bld_far = _hz_far_profile(_CTX["dem_wide_band"], _CTX["dem_wide_transform"],
                                   _CTX["dem_wide_nodata"], row_geom, _eave)

    per_facet = []
    # ONE GRID FRAME PER BUILDING (panel_fitting.building_frame): every face
    # racks to the same bearing from the same origin, so rows and columns
    # line up across the roof instead of each face choosing its own.
    # SOLAR_FRAME=0 lays out the old way (each face its own grid) for A/B runs
    _frame = building_frame(facets, row_geom) if facets and os.environ.get("SOLAR_FRAME", "1") != "0" else None
    # the building's sunniest real face, for the sunny-side rule (SUN_SIDE_REL)
    _sunniest = max([sun_share(model, f["slope_deg"], f["aspect_deg"]) for f in facets
                     if not f.get("no_panel") and f["geometry"].area >= SUN_SIDE_MIN_FACE_M2] or [1.0])
    if _frame is not None:
        try:
            # SOLAR_FRAME_MARKUP=1: the frame is chosen on the faces that will
            # take panels, around the drawn obstructions and fold lines, so a
            # gable's sunny side is not racked to suit its shady side or a face
            # marked "no panels here", and the markup governs the grid too.
            # On by default since the blind check noted in panel_fitting.
            if os.environ.get("SOLAR_FRAME_MARKUP", "1") == "1":
                _counted = [f for f in facets if not f.get("no_panel")
                            and not away_from_sun(model, f["slope_deg"], f["aspect_deg"], _sunniest)]
                _fobs, _fko = None, None
                try:
                    from src.roof_line_source import drawn_obstruction_polys, drawn_line_keepouts
                    _fobs = drawn_obstruction_polys(building_id) or None
                    _fko = drawn_line_keepouts(building_id) or None
                except Exception:
                    pass
                _frame = register_frame(_frame, facets, obstructions=_fobs, counted=_counted,
                                        fold_keepouts=_fko)
            else:
                _frame = register_frame(_frame, facets)
        except Exception as exc:
            _note_fallback("register_frame", building_id, exc)
    # ...unless the roof has nothing on its sunny side after all (obstructions,
    # shade, a face too narrow to rack): then, as an installer would, its
    # next-best side is used, still above SUN_SIDE_ABS. A second pass, only
    # for such roofs.
    for _pass in (0, 1):
        per_facet = []
        _rel_skipped = False
        _rel_area = 0.0
        for f in facets:
            facet_centroid = f["geometry"].centroid
            # Shading: the direct sun that clears the near (1 m DSM) and far
            # (8 m DEM) horizons together scales the direct part of the
            # sunlight, the open sky the diffuse part (building_shading.facet_sun,
            # SolarModel.kept_sun). The per-facet sun arrays are built once
            # and reused for every panel below.
            _sctx = facet_sun_context(model.hourly, f["slope_deg"], f["aspect_deg"],
                                      model.horizon_profile, _bld_far)
            _fs = facet_sun(dsm_band, dsm_ds.transform, dsm_ds.nodata,
                            facet_centroid.x, facet_centroid.y, model.hourly, _sctx,
                            own_geom=f["geometry"], terrain_horizon_profile=model.horizon_profile)
            shading_factor = model.kept_sun(f["slope_deg"], f["aspect_deg"], _fs["beam"], _fs["sky"])
            facet_poa = model.annual_poa_kwh_per_m2(f["slope_deg"], f["aspect_deg"])
            if not modelled:
                per_facet.append({"facet": f, "panels": [], "obstructions": [],
                                  "poa": facet_poa * shading_factor,
                                  "shading_factor": shading_factor})
                continue
            plane = (f["plane_a"], f["plane_b"], f["plane_c"])
            _keepouts = []
            _edge_drops = []
            _drawn_obs = []
            obstructions = detect_obstructions_combined(imagery_ds, pc_source, f["geometry"], plane,
                                                        roof_geom=f.get("building_geometry"),
                                                        keepouts=(_edge_drops if os.environ.get(
                                                            "SOLAR_EDGE_DROPS", "1") != "0" else None))
            try:
                from src.roof_line_source import drawn_obstruction_polys
                _drawn_obs = drawn_obstruction_polys(f.get("building_id"))
                if _drawn_obs:
                    # This roof's obstructions are marked in detail; the auto
                    # detector was hallucinating 140 m2 of phantom blockage on a
                    # bright membrane where the markup totals 17 m2 (#5372565,
                    # clear empty space left unfilled). Where the markup speaks,
                    # only it speaks.
                    obstructions = [o for o in _drawn_obs
                                    if o.intersects(f["geometry"])]
                from src.roof_line_source import drawn_line_keepouts
                # His fold lines are no-panel strips even where the partition
                # did not split on them (#4735237: 264/450 panels crossed drawn
                # lines inside two big derived faces). Keepouts, not verdicts.
                _keepouts = [k for k in drawn_line_keepouts(f.get("building_id"))
                             if k.intersects(f["geometry"])]
            except Exception:
                pass
            # ...and a detected patch whose returns lie on a roof plane is roof
            # (src/obstruction_planarity.py); his markup is never second-guessed
            if not _drawn_obs:
                obstructions = drop_roof_like(obstructions, f, facets, pc_source)
                obstructions = drop_edge_hugging(obstructions, f, pc_source)
            # Existing solar marked by hand is panel area: the detector flags an
            # array as an obstruction because it looks nothing like the roofing
            # around it (src/obstruction_detection.py), so cut it back out.
            try:
                from src.roof_line_source import drawn_solar_polys
                _solar = drawn_solar_polys(f.get("building_id"))
            except Exception:
                _solar = []
            if _solar:
                from shapely.ops import unary_union as _uu
                _sol = _uu(_solar)
                obstructions = [d for d in (o.difference(_sol) for o in obstructions if o is not None)
                                if not d.is_empty and d.area > 0.05]
            # edge drops the detector found stay panel-free, unless the markup
            # governs this roof's obstructions
            if not _drawn_obs:
                _keepouts = list(_keepouts) + _edge_drops
            siblings = [other for other in facets if other is not f]
            # A FACE JOSH DREW IS NOT JUDGED ON ITS PLANE FIT, for the same reason
            # it is not withheld for low confidence: _facet_fit asks how well the
            # points sit on a plane WE fitted, and on a face he drew that question
            # is upside down. A 713 m2 flat roof has camber and ponding well beyond
            # the 15 cm tolerance, so it scores badly while being exactly one roof
            # plane.
            #
            # This is the same filter that took 32 Frankton Road to 18 panels. It
            # is measured to be at risk on 11 of his labelled roofs, all of them
            # over 1,000 m2 and all of them the big commercial buildings that
            # carry the most capacity: #5372239 (7,568 m2), #5372232 (5,526),
            # #4725584 (4,032), and 1 Memorial Street, one of the two roofs he
            # first showed me as wrong.
            drawn = f.get("from_labels")
            # A low plane-fit big-roof facet used to get NO panels at all. 100%
            # panel density must fill every possible area -- and
            # #4735613 shipped its 372 and 337 m2 facets EMPTY through this skip
            # (382 panels refit vs 107 shipped). The facet still fits, but its
            # panels are DEMOTED to the straggler band: hidden at default density,
            # present at 100%. Deleting is a verdict; demotion is a ranking.
            low_fit = (big_roof and not drawn
                       and _facet_fit(f, pc_source) < BIG_ROOF_FACET_MIN_FIT)
            if f.get("no_panel"):
                # This face is marked "no panels here". It exists as
                # geometry -- the drawn lines are the roof's lines -- and takes
                # nothing. See facets_from_drawn_faces.
                panels = []
            elif away_from_sun(model, f["slope_deg"], f["aspect_deg"], _sunniest):
                panels = []
                _rel_skipped = _rel_skipped or not away_from_sun(model, f["slope_deg"], f["aspect_deg"], 0.0)
                if not away_from_sun(model, f["slope_deg"], f["aspect_deg"], 0.0):
                    _rel_area += f["geometry"].area
            else:
                panels = fit_panels_on_facet(f, obstructions=obstructions,
                                             sibling_facets=siblings,
                                             fold_keepouts=_keepouts,
                                             frame=_frame)
            if low_fit:
                for pnl in panels:
                    pnl["straggler"] = True
                    pnl["low_conf_fit"] = True
            # Same exemption: "this face is too small to bother racking" is a
            # judgement about a face the pipeline guessed at. He drew this one.
            if big_roof and not drawn and len(panels) < BIG_ROOF_MIN_PANELS:
                for pnl in panels:
                    pnl["straggler"] = True
                    pnl["low_conf_fit"] = True
            kept_panels = []
            for pnl in panels:
                cpt = pnl["geometry"].centroid
                _ps = facet_sun(dsm_band, dsm_ds.transform, dsm_ds.nodata,
                                cpt.x, cpt.y, model.hourly, _sctx, own_geom=f["geometry"],
                                terrain_horizon_profile=model.horizon_profile)
                # deep-shade veto stays a NEAR-FIELD direct-sun test: the far
                # terrain lowers yield but must not delete panels a valley
                # still deserves
                if _ps["near"] < DEEP_SHADE_FACTOR:
                    continue
                psf = model.kept_sun(f["slope_deg"], f["aspect_deg"], _ps["beam"], _ps["sky"])
                pnl["poa_kwh_m2_yr"] = facet_poa * psf
                pnl["shading_factor"] = psf
                kept_panels.append(pnl)
            # clean arrays only: after the shade veto, which can leave fragments
            # (src/panel_fitting.py RACKING)
            if os.environ.get("SOLAR_FACE_DEBUG"):
                print(f"[sun {building_id}] pass {_pass} face {f['geometry'].area:.0f} m2 "
                      f"{f['slope_deg']:.0f}/{f['aspect_deg']:.0f} share "
                      f"{sun_share(model, f['slope_deg'], f['aspect_deg']):.2f} of {_sunniest:.2f}: "
                      f"{len(panels)} fitted, {len(kept_panels)} after shade")
            kept_panels = enforce_arrays(kept_panels, face_area=f["geometry"].area)
            kept_panels = shape_arrays(kept_panels, face_area=f["geometry"].area)
            kept_panels = centre_panels(kept_panels, f["geometry"],
                                        [o.buffer(0.3) for o in obstructions if o is not None] + list(_keepouts))
            per_facet.append({"facet": f, "panels": kept_panels, "obstructions": obstructions,
                              "poa": facet_poa * shading_factor, "shading_factor": shading_factor})
        if _pass == 0 and _rel_skipped:
            # A sunny side must be a real part of the roof. On 4734459
            # (Fernhill) a 16 m2 east face took 3 panels and became the
            # sunny side, so the 157 m2 south-east face (0.68 of it, under
            # 0.78) went bare: 36 panels to 6. Where the faces holding panels
            # are under SUN_SIDE_MIN_SHARE of the area the rule left bare
            # plus theirs and hold under SUN_SIDE_MIN_PANELS, the roof uses
            # its next-best side (still above SUN_SIDE_ABS). An ordinary
            # gable is about half and half; a sunny row of 11 on a narrow
            # face (4735330) is an install, and its shady side stays bare.
            # SOLAR_SUN_SIDE_MIN_SHARE=0 reruns only when the roof is empty.
            _held = sum(pf["facet"]["geometry"].area for pf in per_facet if pf["panels"])
            _held_n = sum(len(pf["panels"]) for pf in per_facet)
            if _held == 0 or (_held_n < SUN_SIDE_MIN_PANELS
                              and _held < SUN_SIDE_MIN_SHARE * (_held + _rel_area)):
                _sunniest = 0.0
                continue
        break

    kept_panel_lists = drop_minor_arrays([pf["panels"] for pf in per_facet])
    # ...and a scrap of two or three that belongs to no array goes (drop_scraps)
    kept_panel_lists = drop_scraps(kept_panel_lists)
    all_kept = [pnl for panels in kept_panel_lists for pnl in panels]
    if all_kept:
        assign_fill_ranks(all_kept)

    for pf, panels in zip(per_facet, kept_panel_lists):
        f = pf["facet"]
        if EMPTY_FACE_REFIT and not panels:
            _refit_empty_face(f, pf, pc_source, model)
        features.append({
            "type": "Feature",
            "geometry": shapely_transform(to_wgs84, f["geometry"]).__geo_interface__,
            "properties": {
                "kind": "facet",
                "building_id": int(building_id),
                # provenance, so a shipped file can PROVE which geometry
                # chain produced it (the 10 Sep no-op build was only
                # detectable by bit-identical totals)
                **({"from_selected": 1} if f.get("from_selected") else {}),
                **({"from_labels": 1} if f.get("from_labels") else {}),
                "slope_deg": round(f["slope_deg"], 1),
                "aspect_deg": round(f["aspect_deg"], 1),
                "poa_kwh_m2_yr": round(pf["poa"], 0),
                "panel_count": len(panels),
                "roof_confidence": round(confidence, 2),
                # the face's plane, z = a x + b y + c in NZTM metres, unrounded
                # (a 1e-6 error in a is a metre of height at NZTM x). Not
                # shipped (output_contract); tools/layout_health.py measures
                # how far each seam sits from where its two planes cross.
                **({"plane": [float(f["plane_a"]), float(f["plane_b"]), float(f["plane_c"])]}
                   if f.get("plane_a") is not None else {}),
                **_yield_inputs(f, pf["shading_factor"]),
            },
        })
        for o in pf["obstructions"]:
            features.append({
                "type": "Feature",
                "geometry": shapely_transform(to_wgs84, o).__geo_interface__,
                "properties": {"kind": "obstruction", "building_id": int(building_id)},
            })
        for pnl in panels:
            y = model.facet_yield(f, 1, shading_factor=pnl.get("shading_factor", pf["shading_factor"]))
            features.append({
                "type": "Feature",
                "geometry": shapely_transform(to_wgs84, pnl["geometry"]).__geo_interface__,
                "properties": {
                    "kind": "panel",
                    "building_id": int(building_id),
                    "ac_kwh_year": round(y["ac_kwh_year"], 0),
                    **_yield_inputs(f, pnl.get("shading_factor", pf["shading_factor"])),
                    "fill_rank": pnl["fill_rank"],
                    "fill_order": pnl["fill_order"],
                    "array_id": pnl["array_id"],
                    "array_size": pnl["array_size"],
                    **({"low_conf_fit": 1} if pnl.get("low_conf_fit") else {}),
                    **({"gap_fill": 1} if pnl.get("gap_fill") else {}),
                },
            })
    return features


# THE SUNNY SIDE ONLY. Installers rack the faces that point at the sun: north,
# east and west, and any roof shallow enough that its direction hardly matters.
# Where a roof has a sunny side, the side turned away from the sun is left bare
# even when the roof is "full" -- Josh, 24 Oct, on 29 York Street: "Panels
# being placed on the shady side of this roof, not the sunny side".
#
# Installers think in directions: north, east and west faces are used; a face
# turned south -- more than SUN_SIDE_SECTOR_DEG off north, south-east through
# south-west -- is left bare when the same roof has a sunnier side (its sun
# share under SUN_SIDE_REL of the building's sunniest face). Sunshine here is
# by direction and pitch only, as a share of the best direction at this site
# (shade has its own veto). Below SUN_SIDE_ABS no face takes panels, whatever
# its direction. At Queenstown: 29 York St's south-west face (24 degrees, 0.72
# beside a 0.96 sunny side) goes; a steep west face (44 degrees, ~0.76) stays
# -- a pure share threshold took those too (5370578, Arrowtown: 75 -> 9); a
# house whose only roof faces south at 15 degrees (0.76; 4751212 on the hill)
# keeps its panels, as an installer would; a south face at 30 degrees (0.63)
# never takes any. A roof whose sunny side ends up empty uses its next-best
# side (the second pass below).
SUN_SIDE_REL = float(os.environ.get("SOLAR_SUN_SIDE_REL", "0.78"))  # 0.80 in v58 took the
# shady side of 15-degree commercial gables (4749452 Frankton, 4729246 Wanaka: 0.79 of their north
# faces), where installers use both sides; 29 York St's south-west face is 0.767 of its sunny side
SUN_SIDE_ABS = float(os.environ.get("SOLAR_SUN_SIDE_ABS", "0.65"))  # 0.70 zeroed 88
# all-south houses in v57 (one 24-29 degree face, 0.66-0.70); 0.65 keeps a south roof up to ~27 degrees
SUN_SIDE_SECTOR_DEG = 112.5   # off north: east-south-east through west-south-west
SUN_SIDE_MIN_FACE_M2 = 10.0   # a face this small does not make a roof's sunny side
SUN_SIDE_MIN_SHARE = float(os.environ.get("SOLAR_SUN_SIDE_MIN_SHARE", "0.25"))  # nor a sunny side
# this small a share of the roof it would leave bare (second pass)
SUN_SIDE_MIN_PANELS = 8      # ...holding fewer panels than a small home system (8 x 500 W = 4 kW)


def sun_share(model, slope_deg, aspect_deg):
    """This direction and pitch's sunshine over the best at this site, under
    an OPEN sky: the rule judges direction and pitch, and the model's own
    table also carries the area's mountain horizon. Mountains are shade, and
    shade has its own checks."""
    open_poa = getattr(model, "_open_poa", None)
    if open_poa is None:
        if getattr(model, "lat", None) is not None and hasattr(model, "lookup"):
            from src.solar_model import (build_poa_lookup_table, _nearest_bin, SLOPE_BIN_DEG, ASPECT_BIN_DEG,
                                         solarview_calibrated_monthly_factors, SOLARVIEW_CAL_LOCATION,
                                         era5_spatial_ratio)
            # This site's sun, under ONE reference climate (the basin's, where
            # SUN_SIDE_REL was tuned): a 14 deg south face is 0.76-0.79 of its
            # north face depending on which station calibrates the town, and
            # the rule must not flip faces on and off with the station.
            # Basin regions get exactly the factors they always had; others the
            # basin's, moved by ERA5's smooth spatial ratio, never by a station.
            ref = solarview_calibrated_monthly_factors(*SOLARVIEW_CAL_LOCATION, None)
            r5 = era5_spatial_ratio(model.lat, model.lon, *SOLARVIEW_CAL_LOCATION)
            ref = {m: v * r5[m] for m, v in ref.items()} if r5 else ref
            table = build_poa_lookup_table(model.lat, model.lon, monthly_factor=ref)[0]
            def open_poa(sl, asp):
                return table[(_nearest_bin(sl, SLOPE_BIN_DEG, max_value=config.MAX_ROOF_SLOPE_DEG),
                              _nearest_bin(asp, ASPECT_BIN_DEG))]
        else:
            open_poa = model.annual_poa_kwh_per_m2
        model._open_poa = open_poa
        model._best_open = max(open_poa(sl, 0.0) for sl in range(0, 61, 2))
    return open_poa(slope_deg, aspect_deg) / model._best_open


def away_from_sun(model, slope_deg, aspect_deg, building_best=1.0):
    """True for a face an installer would leave bare: building_best is the
    sun_share of the building's sunniest face (see SUN_SIDE_REL)."""
    if os.environ.get("SOLAR_SUN_SIDE", "1") == "0":
        return False
    share = sun_share(model, slope_deg, aspect_deg)
    if share < SUN_SIDE_ABS:
        return True
    off_north = abs((aspect_deg + 180.0) % 360.0 - 180.0)
    return off_north > SUN_SIDE_SECTOR_DEG and share < SUN_SIDE_REL * building_best


# AN EMPTY FACE DOES NOT KEEP A TILT ITS OWN RETURNS REJECT.
#
# A face that takes no panels -- a plant deck under a drawn obstruction, a
# face the sun rule leaves empty -- still draws in the 3D view and colours the
# heat map at its tilt, and nothing downstream checks that tilt, because no
# panel is priced on it. #5372566 (19 Camp St): its plant deck carries
# 4.4 deg / 200 deg; its returns sit a median 0.38 m off that plane, and the
# best plane through them is about 1 deg. The 3D view drew the deck as a
# wedge and stood its obstruction box 1.2 m above the surveyed deck.
#
# So with no panels on a face, its tilt is replaced when it misfits its own
# returns by more than EMPTY_FACE_MAX_RES_M (median |residual|): by the robust
# refit or by flat, whichever fits better, and only if that is at least
# EMPTY_FACE_GAIN better. The gain is modest because on a cluttered deck the
# clutter dominates every plane's residual: on #5372566's deck the returns
# span -0.5 to +1.1 m round their median (AC units), the stored tilt misfits
# by 0.43 m, flat by 0.43 m and the robust refit (2.8 deg) by 0.32 m.
# A face with panels is never touched here -- its panels were priced on its
# tilt. Off by default (SOLAR_EMPTY_FACE_REFIT=1).
EMPTY_FACE_REFIT = os.environ.get("SOLAR_EMPTY_FACE_REFIT", "0") == "1"
EMPTY_FACE_MAX_RES_M = 0.15
EMPTY_FACE_GAIN = 0.8
EMPTY_FACE_MIN_POINTS = 30
# Too small to judge: on 450 sampled roofs the refits of faces under 20 m2 were
# split, and the one that went wrong was a 4 m2 face the DSM reads at 57 deg
# (#4742511) set flat.
EMPTY_FACE_MIN_M2 = 20.0
EMPTY_FACE_MAX_REFIT_DEG = 15.0


def _refit_empty_face(f, pf, pc_source, model):
    try:
        import math
        import numpy as np
        from src.roof_partition import _fit_plane_robust, _slope_aspect
        g = f["geometry"]
        if f.get("plane_a") is None or g.area < EMPTY_FACE_MIN_M2:
            return
        core = g.buffer(-0.45)
        core = core if not core.is_empty and core.area > 2 else g
        pts = pc_source.points_in_bbox(*core.bounds, building_only=True)
        if len(pts) == 0:
            return
        pts = pts[shapely.contains_xy(core, pts[:, 0], pts[:, 1])]
        if len(pts) < EMPTY_FACE_MIN_POINTS:
            return

        def res(a, b):
            r = pts[:, 2] - (a * pts[:, 0] + b * pts[:, 1])
            c = float(np.median(r))
            return float(np.median(np.abs(r - c))), c

        now, _ = res(f["plane_a"], f["plane_b"])
        if now <= EMPTY_FACE_MAX_RES_M:
            return
        cands = [(0.0, 0.0)]
        pl = _fit_plane_robust(pts)
        # a misfit face is cluttered or spans a wall, and a free fit through it
        # finds the wall: on 150 pilot roofs, unbounded refits took 2.7 deg
        # faces to 62.7 and 72.5 deg. A refit may not be steeper than
        # EMPTY_FACE_MAX_REFIT_DEG or the tilt it replaces.
        if pl is not None and math.degrees(math.atan(math.hypot(pl[0], pl[1]))) <= max(
                EMPTY_FACE_MAX_REFIT_DEG, f["slope_deg"]):
            cands.append((float(pl[0]), float(pl[1])))
        best = min(((res(a, b), a, b) for a, b in cands), key=lambda t: t[0][0])
        (score, c), a, b = best
        if score > EMPTY_FACE_GAIN * now:
            return
        slope, aspect = _slope_aspect((a, b, c))
        f.update(plane_a=a, plane_b=b, plane_c=c, slope_deg=slope, aspect_deg=aspect,
                 empty_face_refit=True)
        pf["poa"] = model.annual_poa_kwh_per_m2(slope, aspect) * pf["shading_factor"]
    except Exception:
        return


def _yield_inputs(facet, shading_factor):
    """Everything the yield layer needs, unrounded, on the feature itself.

    THE GEOMETRY AND THE SUN ARE SEPARATE LAYERS. Where panels go and how
    shaded each one is (geometry: faces, obstructions, the near-field and
    far-terrain horizon) is expensive and needs the LiDAR. What a
    square metre at a given slope and aspect earns in a year (the sun: the
    lookup table, the cloud calibration, the derate) is cheap and changes
    for different reasons. src/apply_yield.py recomputes every kWh from these
    three numbers with the current model, so a calibration change re-runs in
    minutes instead of re-laying every roof. Full precision so the recompute
    is bit-identical to what was computed here."""
    return {"plane_slope_deg": float(facet["slope_deg"]),
            "plane_aspect_deg": float(facet["aspect_deg"]),
            "shading_factor": float(shading_factor)}


def main(area="pilot", jobs=None, limit=0, dry_run=False):
    preflight("build_layout_geojson", area)
    paths = area_paths(area)
    gdf = gpd.read_file(paths["outlines"])
    ids = [int(b) for b in gdf["building_id"].tolist()]
    if limit:
        ids = ids[:limit]

    # A missing imagery mosaic is ACCEPTED (rural regions genuinely have none --
    # LINZ aerial is urban-only) but it must never pass unremarked: obstruction
    # detection loses the colour half of its evidence and roof_partition loses
    # its image lines, so the build is quietly worse than one with imagery. This
    # bit us on Island Bay, where a rebuild was queued against a mosaic that had
    # been cleaned up for disk and would have shipped a degraded layout with
    # nothing in the log to say why.
    if not paths["imagery"].exists():
        print(f"[{area}] WARNING: no imagery mosaic -- building LiDAR-ONLY. "
              f"Obstruction detection and roof partitioning are degraded. "
              f"Fetch with: python src/fetch_regions.py {area}", flush=True)
    # Same rule for the wide DEM: its absence turns the per-building far-horizon
    # correction into a no-op, so yields quietly revert to the area-wide terrain
    # profile. Written as a silent fallback when the horizon work landed -- which
    # is precisely the failure mode that cost us the terrain masks and nearly
    # cost us an Island Bay rebuild.
    if not (DATA_DIR / "dem_wide_mosaic.tif").exists():
        print(f"[{area}] WARNING: no data/dem_wide_mosaic.tif -- per-building "
              f"horizons are OFF and yields fall back to the area terrain "
              f"profile.", flush=True)
    # And the point cloud, which is the PRIMARY input: without tiles over this
    # region every building silently drops to the 1 m DSM, which is roughly a
    # sixteenth of the Wellington survey's sampling and cannot resolve a hip.
    try:
        _probe = PointCloudSource()
        _b = gdf.total_bounds
        if len(_probe.points_in_bbox(_b[0], _b[1], _b[2], _b[3], building_only=True)) == 0:
            print(f"[{area}] WARNING: NO LiDAR point-cloud tiles cover this "
                  f"region -- every building falls back to the 1 m DSM. "
                  f"Fetch with: python src/fetch_pointcloud_regions.py {area}",
                  flush=True)
    except Exception as _exc:
        print(f"[{area}] WARNING: could not probe the point cloud ({_exc!r})", flush=True)

    print(f"[{area}] Building solar yield lookup table (pvlib + NASA POWER)...")
    centroid = area_centroid_wgs84(area)
    model = SolarModel() if centroid is None else SolarModel(*centroid)

    # Bounded by MEMORY, not by core count. PointCloudSource caches every
    # decoded LiDAR tile for the life of its process (the full set is ~10GB
    # decoded), so each worker carries its own copy of whatever tiles its
    # buildings touch, and the ceiling is RAM per worker rather than cores.
    #
    # This used to be a literal, and the literal and the comment above it had
    # drifted apart: the comment recorded that 11 workers got a run killed and
    # that six was the measured-safe number, while the constant said ten. Both
    # were right about different machines -- 11 died on the 18GB Mac, and ten
    # runs fine on the 62GB VM. No single number can be correct for both, which
    # is exactly why it drifted, so derive it instead.
    #
    # PER_WORKER_GB is calibrated to reproduce both measured-good values:
    # 18GB Mac -> 6 workers (the number actually measured working, 280s -> 114s
    # on 100 buildings), 62GB VM -> 10. HARD_CAP keeps a very large machine from
    # spawning a pool whose parent-side merge becomes the bottleneck.
    # ...and by THIS survey: a worker caches MAX_CACHED_TILES decoded tiles,
    # and how big a decoded tile is depends on the survey's density, which
    # the LAZ headers state. PER_WORKER_GB stays the floor (Queenstown's
    # measurement); a denser survey raises the budget and lowers the count.
    if not jobs:
        from src.pointcloud_source import per_worker_gb, MAX_CACHED_TILES
        from src.region_build import area_bbox_nztm
        try:
            budget, tile_gb, density = per_worker_gb(PER_WORKER_GB, 0.3, MAX_CACHED_TILES,
                                                     area_bbox_nztm(area))
            print(f"[{area}] survey: {density:.1f} returns/m2, largest tile "
                  f"{tile_gb:.2f} GB decoded -> {budget:.2f} GB per worker", flush=True)
        except Exception as exc:
            budget = PER_WORKER_GB
            print(f"[{area}] survey size unknown ({exc!r}); {budget} GB per worker", flush=True)
        jobs = _memory_bounded_jobs(budget)
    print(f"[{area}] {len(ids)} buildings on {jobs} workers", flush=True)

    features, done, t0 = [], 0, time.time()
    if jobs == 1:
        _init_worker(area, model)
        for bid in ids:
            features.extend(_build_one(bid))
            done += 1
            if done % 200 == 0:
                print(f"  {done}/{len(ids)} elapsed={time.time() - t0:.1f}s", flush=True)
    else:
        # Submitted one building at a time rather than ex.map(chunksize=8), and
        # watched. ex.map yields strictly in order, so a single roof that never
        # finishes stops the counter dead while the other workers quietly drain
        # and go idle -- the build then sits at one core pegged at 100% with no
        # error, no log line, and no way to tell which building is responsible.
        # That happened twice on frankton_flats on 28 Aug and cost the evening;
        # the second time it burned an hour before anyone looked at ps. Per-task
        # dispatch overhead is microseconds against ~1s of work per building, so
        # the chunking was buying nothing worth this.
        results = {}
        # SPAWN, not the Linux default fork. On 1 Sep every worker on the VM
        # blocked in futex_wait_queue the instant the pool started: 209
        # buildings, ten workers, load average 0.00, and not one building
        # completed in half an hour. The same building built in 10 seconds when
        # called directly, so the work was fine and the POOL was deadlocked.
        #
        # That is the classic fork hazard: a child inherits the parent's memory
        # including any lock held at fork time, and the numeric stack this
        # pipeline sits on (numpy/OpenBLAS, GEOS, GDAL, pvlib) all take locks
        # the parent has already touched by the time the SolarModel is built.
        # A child that inherits one held lock waits on it forever, and no owner
        # exists in that process to release it.
        #
        # spawn starts each worker from a clean interpreter, so no lock is
        # inherited. It costs a little startup per worker -- which is why the
        # SolarModel is built ONCE in the parent and shipped in as an argument
        # rather than reconstructed per worker.
        with ProcessPoolExecutor(max_workers=jobs, initializer=_init_worker,
                                 initargs=(area, model),
                                 mp_context=multiprocessing.get_context("spawn")) as ex:
            futs = {ex.submit(_build_one, b): b for b in ids}
            pending, last_progress = set(futs), time.time()
            while pending:
                finished, pending = wait(pending, timeout=STALL_REPORT_S)
                for fut in finished:
                    results[futs[fut]] = fut.result()
                    done += 1
                    if done % 200 == 0:
                        print(f"  {done}/{len(ids)} elapsed={time.time() - t0:.1f}s",
                              flush=True)
                if finished:
                    last_progress = time.time()
                    continue
                stalled = time.time() - last_progress
                outstanding = sorted(futs[f] for f in pending)
                print(f"  [STALL] no building has completed in {stalled:.0f}s. "
                      f"{len(outstanding)} outstanding: {outstanding[:10]}"
                      f"{' ...' if len(outstanding) > 10 else ''}",
                      file=sys.stderr, flush=True)
                if stalled > STALL_ABORT_S:
                    # Abort loudly rather than pretend. A build that silently
                    # drops buildings would publish a map with holes in it.
                    for f in pending:
                        f.cancel()
                    raise RuntimeError(
                        f"[{area}] build stalled {stalled:.0f}s with "
                        f"{len(outstanding)} buildings outstanding: {outstanding[:20]}")
        # emitted in the input order so two builds of the same area diff cleanly
        for b in ids:
            features.extend(results.get(b, []))

    if dry_run:
        print(f"[{area}] dry run: {len(features)} features in {time.time() - t0:.0f}s "
              f"on {jobs} workers -- nothing written")
        return
    from src.build_keys import yield_code_hash
    # which sun computed these kWh (src/apply_yield.py re-stamps it)
    geojson = {"type": "FeatureCollection", "yield_model": yield_code_hash(),
               "features": features}
    out_path = paths["panel_layouts"]
    out_path.write_text(json.dumps(geojson))
    # What every building in this file was built from (src/build_keys.py), so
    # the next incremental build rebuilds exactly the ones whose reading,
    # markup or geometry code has changed since. Not for a --limit run, which
    # did not build the region.
    if not limit:
        from src.build_keys import record_keys
        record_keys(area, ids, replace=True)

    n_facets = sum(1 for f in features if f["properties"]["kind"] == "facet")
    n_panels = sum(1 for f in features if f["properties"]["kind"] == "panel")
    n_obs = sum(1 for f in features if f["properties"]["kind"] == "obstruction")
    gated = len({f["properties"]["building_id"] for f in features
                 if f["properties"]["kind"] == "facet"
                 and f["properties"].get("roof_confidence", 1.0) < MIN_ROOF_CONFIDENCE})
    print(f"\nSaved {out_path} ({out_path.stat().st_size / 1e6:.1f}MB) in {time.time() - t0:.0f}s")
    print(f"{n_facets} facets, {n_panels} panels, {n_obs} obstructions across {len(ids)} buildings")
    print(f"{gated} buildings withheld as not confidently modelled (<{MIN_ROOF_CONFIDENCE:.0%} on-plane)")


if __name__ == "__main__":
    _jobs, _limit = None, 0
    _argv = sys.argv[:]
    for _flag in ("--jobs", "--limit"):
        if _flag in _argv:
            _i = _argv.index(_flag)
            _val = int(_argv[_i + 1])
            _argv = _argv[:_i] + _argv[_i + 2:]
            if _flag == "--jobs":
                _jobs = _val
            else:
                _limit = _val
    _dry = "--dry-run" in _argv
    _argv = [a for a in _argv if a != "--dry-run"]
    for _area in areas_from_argv(_argv):
        main(_area, jobs=_jobs, limit=_limit, dry_run=_dry)
