Every score Urban Pulse publishes is reproducible from the inputs and parameters documented below. This page is the single source of truth for the engine — the same registry powers the in-app MetricInfo popovers, the audit reports, and the Sandpit demo. No black boxes, no closed-source heuristics.
Mean accessibility across the six daily-life functions (Living, Working, Supplying, Caring, Learning, Enjoying) reachable within a 15-minute walk. Operationalises Moreno et al. (2021).
score_c = 100 · (1 − exp(−1.6 · count_c / target_c)); composite = mean(score_c) for c ∈ {Living…Enjoying}target_living6— Residential POIs for full saturationtarget_working4target_supplying8target_caring5target_learning4target_enjoying10k (decay)1.6— Diminishing-returns curve constantEach category score is bounded by counting noise on a small POI sample; we report the 95% band derived from a Poisson approximation on the smallest contributing category.
Composite of Jane Jacobs' four conditions for urban diversity: mixed primary uses, fine-grained block pattern, density, and (proxy for) building age variety via transit frequency.
Jacobs = 0.35·Diversity + 0.25·Density + 0.20·Grain + 0.20·TransitFreq
DiversityShannon evenness over Moreno categories × 100Densitymin(1, POIs_per_km² / 200) × 100GrainShannon evenness across 4 spatial quadrants × 100TransitFreqmin(1, transit_nodes / 8) × 100We simulate the index under POI omission rates of 10–30% (consistent with OSM completeness studies — Barron 2014, Zhang & Pfoser 2019) and report the resulting 95% band.
Weighted ratio of essential daily services (groceries, pharmacies, clinics, schools) to lifestyle amenities (cafés, bars, boutiques). Custom Urban Pulse indicator inspired by Frank et al. (2010) walkability composites and Ewing & Cervero (2010) D-variables.
ELR = (Σ w_essential + 0.5) / (Σ w_lifestyle + 0.5)
Laplace prior0.5— Stabilises ratio at low countsGentrification cutoffELR < 0.55Stagnation cutoffELR > 2.20Service-desert cutoffEssential+Lifestyle POIs < 81000-iteration bootstrap on the POI list; we report the 2.5–97.5 percentile band on the resulting ratio.
Evenness of POIs across the six Moreno categories using Shannon entropy normalised by maximum entropy of present categories. 0 = monoculture, 100 = perfectly mixed.
E = H / Hmax; H = −Σ p_i · log2(p_i)
Categories6 Moreno functionsBaselog₂Entropy estimator bias scales with 1/(2·N·ln2); reported as a ±band.
UN-Habitat indicator: proportion of population with convenient access to public transport. Operationalised here as 100 % when ≥1 stop is within 500 m walk; otherwise linearly degraded by nearest-stop walk minutes (cap at 15 min).
access = 100 if stops_within_500m ≥ 1, else clamp(100 − ((walk_min−6.25)/8.75)·100, 0, 100)
Walk threshold500 m ≈ 6.25 min— UN-Habitat 2019 referenceDecay floor15 min walk → 0 % accessSourcesTransitland v2 → OSM stop_position fallbackBinomial CI on stop-presence within the buffer; widens when the catalog is sparse (Transitland coverage gaps fall back to OSM, where completeness varies — Barron 2014).
UN-Habitat indicator: average share of built-up area allocated to open public space. We compute green / open-space area inside the isochrone divided by isochrone area, then score against the conventional 15 % planning benchmark.
score = clamp((green_area / iso_area) / 0.15 · 100, 0, 100)
Benchmark15 % open public space (UN-Habitat 2018)OSM tagsleisure∈{park,garden,nature_reserve,playground,pitch,dog_park}, landuse∈{recreation_ground,grass,forest,meadow,village_green}Park polygon detection is sensitive to OSM tagging completeness; we widen the band on small park counts.
Count of distinct species-occurrence records reported to GBIF inside the active area of interest. A v0 proxy for local biodiversity intensity — coarse, sampling-biased toward observer density, but the cheapest cross-comparable signal we can ship before the full Bio-Sync data plane (rasterised heat, GANs, NbS avoided cost) lands.
count = GBIF.occurrence.search({ geometry: WKT(polygon), limit: 0 }).countEndpointhttps://api.gbif.org/v1/occurrence/searchGeometry filterWKT POLYGON, lon/lat, CCW outer ringCache TTL24h via external_data_cacheGBIF coverage varies by country, taxon and observer effort; counts are not population-level abundance. We treat ±25% as the working envelope until we layer normalisation against GBIF country-baselines in Bio-Sync v1.
Order-of-magnitude annualized economic value tied to the neighborhood's social and spatial scores. Sums four orthogonal driver flows — active-transport health (WHO HEAT), local retail capture (Litman/Cervero), avoided CO₂ at EEA shadow price, and transit ridership equivalent (UITP/ITF) — each scaled to the audit's effective population.
value = Σ pop · driver_share(score) · €coef[low|mid|high] for driver ∈ {health, retail, carbon, transit}Health €/resident-yr€40 / €95 / €180— WHO HEAT lo/mid/hiRetail €/resident-yr/+10pt vitality€8 / €18 / €35— Litman / VTPICarbon tCO₂/resident-yr per +10pt Moreno0.025 / 0.05 / 0.10Carbon shadow price €/tCO₂€60 / €100 / €180— EEA 2023 handbookTransit €/resident-yr€6 / €14 / €28— UITP / ITFHeat €/resident-yr/°C anomaly€2 / €8 / €20— EEA UHI 2022 / WHO Europe heat-health 2021 (Sprint 30)Air €/resident-yr/µg/m³ PM2.5 over WHO€4 / €15 / €40— EEA Air Quality 2023 / WHO AQG 2021 (Sprint 31)Mobility €/resident-yr/pp car-share over SUMP 40%€3 / €12 / €30— INRIX 2024 / EU SUMP 2019 / UITP (Sprint 32)Flood loss multiplier (× modeled €/resident-yr)0.6× / 1.0× / 1.6×— EEA Floods Directive 2024 / JRC Pluvial 2020 / Munich Re NatCat 2023 (Sprint 35)Noise €/resident-yr/dB Lden over WHO 53€2 / €8 / €20— WHO 2018 / EEA 2020 / CNOSSOS-EU 2012 (Sprint 36)Housing €/resident-yr/pp RTI over Eurostat 40%€6 / €22 / €55— Eurostat SILC 2024 / JRC Affordable 2022 / OECD Housing 2023 (Sprint 37)Sensitivity envelope±20% on each driver coefficientBands are coefficient-driven, not site-specific. We report the lo/mid/hi envelope from the published source ranges. Replace coefficients with local elasticities for client-grade work.
Cumulative annual €-uplift over baseline produced by composing one or more named interventions from the catalog. Each intervention declares additive deltas to Moreno composite, Jacobs vitality, transit-frequency proxy and per-Moreno-category scores; the resulting projected snapshot is fed back through the Value-at-Stake module to produce the uplift band. CapEx and lead-time bands are summed from the catalog entries.
uplift = Σ V(snapshot ⊕ Δᵢ) − V(snapshot) where V = computeEconomicImpact, Δᵢ = intervention deltas (additive, clamped to score ranges)
Catalog size12 named interventions (active mobility, transit, public realm, land use, green infra)Score deltasAdditive points on 0–100 scales; clamped at boundsCapEx bandsPer-unit lo/mid/hi from NACTO / ITDP / C40 / World Bank / EU UMOLead timeMonths, taken as max across the stack for low/high; mean for centralSimple paybackcapex / annual uplift; capped at 99 yrs; band uses opposite extremesUplift band inherits the Value-at-Stake coefficient envelope (±20% per driver). CapEx bands are catalog-grade European mid-2020s; replace with site-specific quotes for tendering work. Score deltas are conservative central estimates from peer-reviewed implementation evidence.
Estimated land-surface-temperature (LST) anomaly above the regional climate baseline, plus the derived tropical-night count and heat-attributable mortality estimate per 100k residents. v0 is a deterministic surrogate keyed on latitude (climate zone), POI density (impervious-surface proxy), Moreno enjoying sub-score (parks/green cooling) and population density. Sprint 30.1 swaps the surrogate for a Copernicus Sentinel-3 SLSTR LST pull cached against the audit isochrone — output shape is preserved.
anomaly = clamp(zoneBaseline + impervious − cooling + densityIntensifier, 0, 6); tropicalNights = clamp(zoneFloor + 5·anomaly + max(0, dens−5000)/1500, 0, 90); deaths/100k = clamp(8·anomaly, 0, 80)
Zone baseline (°C)Mediterranean 1.5 / Continental 0.8 / Atlantic 0.4 / Nordic 0.1— EEA 2022 Urban Heat ReportTropical-night floor (nights/yr)25 / 8 / 3 / 0— Per-zone floor, EEA referenceImpervious liftclamp((poisPerKm² − 50) / 50, 0, 1) × 1.6 °CCooling discount(enjoying / 100) × 1.0 °C— Parks + green-leisure POIs reachable in 15 minDensity intensifier+0.8 °C above 8000/km², −0.3 °C below 2500/km²Mortality coefficient8 attributable deaths / 100k / °C anomaly— WHO Europe heat-health 2021Surrogate uncertainty is large (±40% of the anomaly) because zone baselines and impervious proxies are not site-calibrated. Tropical-night and mortality bands inherit the anomaly envelope.
Annual-mean PM2.5 and NO₂ concentration estimate plus the µg/m³ overshoot above the WHO 2021 Air Quality Guidelines (PM2.5 5 µg/m³, NO₂ 10 µg/m³) and the derived PM2.5-attributable mortality estimate per 100k residents. v0 is a deterministic surrogate keyed on latitude (climate zone background), POI density (traffic / activity proxy), Moreno enjoying sub-score (parks/tree-canopy dampening) and population density (canyon trapping). Sprint 31.1 swaps the surrogate for an OpenAQ v3 station pull cross-checked against a Sentinel-5P TROPOMI NO₂ tile, cached against the audit isochrone — output shape preserved.
pm25 = clamp(zoneBaseline + traffic·6 − green·2 + dens·0.5, 1, 60); no2 = clamp(zoneBaseline + traffic·10 − green·4 + dens, 1, 90); pm25AboveWho = max(0, pm25 − 5); deaths/100k = clamp(10·pm25AboveWho, 0, 120)
PM2.5 baseline (µg/m³)Mediterranean 14 / Continental 12 / Atlantic 8 / Nordic 5— EEA 2023 Air Quality in EuropeNO₂ baseline (µg/m³)Mediterranean 22 / Continental 18 / Atlantic 14 / Nordic 10— EEA 2023 zone-weighted meansTraffic liftclamp((poisPerKm² − 50) / 50, 0, 1) × {6 PM2.5, 10 NO₂} µg/m³Green-cover dampening(enjoying / 100) × {2 PM2.5, 4 NO₂} µg/m³— Tree-canopy + park area within reachDensity intensifier+3 µg/m³ NO₂ above 8000/km², −1.5 below 2500/km²WHO 2021 AQGPM2.5 5 µg/m³ · NO₂ 10 µg/m³ annual meanMortality coefficient10 attributable deaths / 100k / µg/m³ PM2.5 above WHO— EEA 2023 derivedSurrogate uncertainty is large (±40% of the overshoot) because zone backgrounds and traffic proxies are not site-calibrated. Mortality bands inherit the overshoot envelope.
Modeled modal split (active / transit / car) for an audit catchment plus the percentage-point overshoot of private-car share above the EU SUMP 2019 indicative target (40%) and the derived per-resident car-trips and per-trip congestion delay. v0 is a deterministic surrogate keyed on latitude (climate cycling factor + zone baselines), transit-frequency proxy, Moreno composite + jacobs vitality (active-mode lift), POI density (short-trip generator) and population density (canyon congestion intensifier). Sprint 32.1 swaps the surrogate for a Strava Metro tile pull cross-checked against a GTFS frequency parse, cached against the audit isochrone — output shape preserved.
transit% = clamp(zoneBaseline + transitLift·12 + dens·0.4, 5, 70); active% = clamp(zoneBaseline + (morenoLift + poiLift·6)·cyclingFactor + dens·0.6, 8, 80); car% = clamp(100 − transit% − active%, 5, 90); overshoot = max(0, car% − 40)
Active-mode baseline (%)Mediterranean 28 / Continental 32 / Atlantic 30 / Nordic 26— EU SUMP 2019 zone-weighted meansTransit baseline (%)Mediterranean 18 / Continental 22 / Atlantic 20 / Nordic 24Cycling climate factorMed 1.00 / Con 1.10 / Atl 0.95 / Nor 0.85— Wet/cold zones lose cycling potentialTransit liftclamp((transitFreq − 30) / 70, 0, 1) × 12ppMoreno active liftclamp((moreno − 40) / 60, 0, 1) × 14ppPOI short-trip liftclamp((poisPerKm² − 50) / 80, 0, 1) × 6pp × cyclingFactorDensity intensifier+4pp above 8000/km², −3pp below 2500/km² (split 0.4 transit / 0.6 active)EU SUMP car target40% private-car share— Sustainable Urban Mobility Plans (JRC 2019)Daily trips / resident3.0 (EU urban average)Congestion delay anchorINRIX 2024 — ~1.4 min/trip baseline → ~5 min/trip in canyonsSurrogate uncertainty is large (±40% on the modal shares) because climate baselines and density elasticities are not household-survey calibrated. Replace with a local Travel Survey or Strava Metro tiles for client-grade work.
Public realm quality composite on a 1–5 scale (1 = poor, 5 = exemplary). Three sub-scores — walkability (sidewalk continuity, crossings, traffic-calming proxy), tree canopy (shade, biophilic value, summer comfort) and façade quality (active ground floor, imageability + enclosure proxy from Ewing & Handy 2009). v0 is a deterministic surrogate keyed on Jacobs vitality, Moreno enjoying sub-score, latitude (canopy growth factor) and POI mix density. Sprint 33.1 swaps the surrogate for a Mapillary v4 image-grid pull (CC-BY-SA, free) classified by Gemini 2.5 Flash vision over a sampled 50-image grid per AOI — output shape preserved.
walkability = scaleToFive(jacobsLift); treeCanopy = scaleToFive(enjoyingLift × canopyFactor); facade = scaleToFive(poisPerKm² / 100); composite = (walkability + treeCanopy + facade) / 3
Walkability liftclamp((jacobs − 30) / 70, 0, 1) → 1–5Canopy liftclamp((enjoying − 30) / 70, 0, 1) × canopyFactor → 1–5Canopy climate factorMed 0.85 / Con 1.00 / Atl 1.10 / Nor 0.90— Atlantic & Continental zones grow more canopy at the same green-POI densityFaçade liftclamp(poisPerKm² / 100, 0, 1) → 1–5— Imageability + enclosure proxy (Ewing & Handy 2009)CompositeSimple average of three sub-scores on 1–5 scaleLevel thresholds<2.5 poor · <3.7 fair · ≥3.7 goodSampled images0 (v0 surrogate) — 50 per AOI in Sprint 33.1Surrogate uncertainty is large (±1 point on the 1–5 scale) because no street-level imagery is sampled in v0. Replace with a Mapillary + vision-LLM grid pull or a site-walked audit for client-grade work.
Ranks the audit AOI against a curated 25-city reference panel on four orthogonal dimensions — Essential:Lifestyle ratio, Moreno 15-minute composite, Jacobs vitality, and population density (log-transformed). Returns per-metric percentile + Hazen rank, the closest archetype, and a top-5 peer cohort sorted by z-score Euclidean distance. Similarity is exp(-distance) × 100 so a 50% similarity corresponds to ~0.69 z-units of separation. v0 panel ships with 25 globally representative cities; Sprint 34.1 swaps it for the Eurostat Urban Audit (~900 EU cities) plus GHSL + Copernicus Urban Atlas morphological signatures, with Gemini text-embeddings selecting the best-evidence comparator.
z(x) = (x − μ_panel) / σ_panel; d_ij = √Σ_k (z_ik − z_jk)²; similarity = round(100·e^−d); percentile = Hazen plotting position
Reference panelcity_baselines table (25 cities)— Curated mix across EU, Americas, APAC, Africa for v0 calibration.DimensionsELR · Moreno composite · Jacobs vitality · log10(population density)— Density log-transformed so megacities don't dominate the metric.Distance metricEuclidean in z-score space— Each dimension standardised against panel mean + sd before summation.Similarity decay100 × exp(−distance)— Identical = 100, ~50% at d≈0.69, ~10% at d≈2.3.Percentile ruleHazen (1914) plotting position— (below + 0.5·equal) / N — unbiased for small panels.Top-N peers5— Cohort size shown on /audit + PDF page 24.v0 distance is fully observable (no sampling noise) but the panel is small (n=25), so peer assignment is sensitive to which cities are seeded. Sprint 34.1 will publish a 95% bootstrap interval on similarity using a 1000-resample Eurostat Urban Audit cohort.
Modeled annual-average pluvial-flood loss intensity (€/resident-yr) for the audit catchment, plus the modeled extreme-rainfall intensity (mm/h, 1-in-10-yr return), annual exceedance probability of a damaging event and impervious-surface fraction. v0 is a deterministic surrogate keyed on latitude (climate-zone rainfall baseline), POI density (impervious-surface proxy), Moreno enjoying sub-score (green-infrastructure dampener) and population density (exposed-asset multiplier). Sprint 35.1 swaps the surrogate for a Copernicus EMS pluvial-hazard tile pull cross-checked against JRC LISFLOOD output cached against the audit isochrone — output shape preserved.
rainfall = baseline · (1 + imperviousLift · 0.25); AEP% = clamp(5 + imperviousLift · 0.8 − green · 12, 1, 35); loss€/res = clamp(40 · (0.3 + impervious · 1.2) · density · (1 − green), 8, 280)
1-in-10-yr rainfall baseline (mm/h)Mediterranean 38 / Continental 28 / Atlantic 24 / Nordic 18— EEA Floods Directive 2024 zone-weighted meansImpervious liftclamp((poisPerKm² − 30) / 90, 0, 1) × 35pp— Anchored on Copernicus Imperviousness HRL 2018 vs OSM POI densityGreen dampenerclamp((enjoying − 30) / 50, 0, 1) × 0.4 reduction on event lossDensity multiplierclamp(0.6 + dens / 12000, 0.6, 1.8)— Exposed-asset scaling per JRC pluvial damage curvesBaseline loss anchor€40/resident-yr in moderate urban catchment— Munich Re NatCat 2023 EU urban-flood synthesisLoss multiplier (€-driver)0.6× / 1.0× / 1.6× indirect-loss envelopeLevel thresholds<€35 low · <€90 medium · ≥€90 high (resident-yr)Surrogate uncertainty is large (±60% on the loss intensity) because rainfall baselines and impervious proxies are not site-calibrated. Loss bands inherit the indirect-loss envelope. Replace with site-specific drainage modelling (SWMM, InfoWorks ICM) for client-grade work.
Modeled day-evening-night equivalent sound level (dB Lden, A-weighted) for the audit catchment, plus the modeled night-time level (Lnight), dB above the WHO 2018 road-traffic guideline (53 dB), share of exposed residents highly annoyed (%HA per ISO 1996-1) and attributable premature deaths/100k/yr from chronic IHD + sleep disturbance. v0 is a deterministic surrogate keyed on POI density (traffic + commerce noise generators), population density (urban-canyon facade-reflection lift, CNOSSOS-EU §VI.4), Moreno enjoying sub-score (vegetation dampener) and the transit-frequency proxy (steady infrastructure floor). Sprint 36.1 swaps the surrogate for a CNOSSOS-EU strategic noise-map raster pull from the EEA NOISE viewer cached against the audit isochrone — output shape preserved.
Lden = clamp(50 + trafficLift + canyonLift + transitLift − greenDampener, 40, 78); Lnight ≈ Lden − 9; ldenAboveWho = max(0, Lden − 53); %HA = clamp((Lden − 50) · 1.8, 0, 55)
Baseline Lden50 dB— Quiet urban background per WHO 2018 §3.2Traffic liftclamp((poisPerKm² − 30) / 90, 0, 1) × 12 dB— CNOSSOS-EU emission curves vs OSM POI densityCanyon liftclamp(dens / 12000, 0, 1) × 5 dB— Facade-reflection per CNOSSOS §VI.4Transit lift(transitFreq / 100) × 3 dB— Steady Lden floor near bus/tram linesGreen dampenerclamp((enjoying − 30) / 50, 0, 1) × 3 dB reduction— Mature canopy + park frontage absorptionLnight offsetLden − 9 dB— EEA 2020 mixed-urban catchment medianWHO 2018 road-traffic Lden threshold53 dBCost coefficient (€-driver)€2 / €8 / €20 per resident-yr per dB above WHOLevel thresholds<2 dB low · <8 dB medium · ≥8 dB high (over WHO Lden)Surrogate uncertainty is large (±50% on the Lden overshoot) because emission curves are not site-calibrated and facade geometry is proxied via density. Cost bands inherit the WHO 2018 dose-response envelope. Replace with site-specific acoustic measurement (ISO 1996-2) for client-grade work.
Modeled tenant rent-to-income ratio (%) for the audit catchment, plus the percentage-point overshoot above the Eurostat housing-cost-overburden threshold (40%), share of resident tenants modelled as cost-overburdened (%HCO), affordable-units gap per 1,000 residents (10-yr cohort) and annual involuntary-displacement rate per 100k residents. v0 is a deterministic surrogate keyed on latitude (climate-zone baseline rent-to-income), Moreno composite (amenity premium), POI density (desirability lift), population density (supply-side pressure) and the transit-frequency proxy (TOD premium). Sprint 37.1 swaps the surrogate for a Eurostat SILC NUTS-3 overburden pull cross-checked against the OECD Housing Affordability Database 2024 deciles cached against the audit catchment — output shape preserved.
RTI% = clamp(baselineRTI + amenityPremium + desirabilityLift + densityPressure + transitPremium, 18, 72); hcoOvershoot = max(0, RTI − 40); %HCO = clamp((RTI − 25) · 1.6, 5, 65)
Baseline tenant RTI (%) by zoneMediterranean 35 / Continental 31 / Atlantic 30 / Nordic 28— Eurostat SILC 2024 ilc_lvho07a zone-weighted mediansAmenity premiumclamp((moreno − 30) / 70, 0, 1) × 15pp— JRC Affordable Housing 2022 amenity-rent gradientDesirability liftclamp((poisPerKm² − 30) / 90, 0, 1) × 6pp— Commerce + culture POI density proxyDensity pressureclamp(dens / 12000, 0, 1) × 8pp— Eurostat SILC 2024 dense-decile lift over national tenant medianTransit premium(transitFreq / 100) × 4pp— UITP 2022 TOD rent gradientEurostat HCO threshold40% of disposable income on housing (rent + utilities)Cost coefficient (€-driver)€6 / €22 / €55 per resident-yr per pp above HCOLevel thresholds<1pp comfortable · <8pp stretched · ≥8pp overburdened (over Eurostat HCO)Surrogate uncertainty is large (±35% on the rent-to-income overshoot) because rent-to-income baselines are not site-calibrated and amenity premiums are proxied via Moreno. Cost bands inherit the JRC Affordability + OECD Housing displacement-cost envelope. Replace with site-specific rent-roll + income microdata for client-grade work.
Snapshots stamp the version they were computed under. A "stale" pill in the portfolio or trend card deep-links here so reviewers can see exactly what changed since.
v2026.12.sS11_catchment_geometry_audit2026-05-28currentSprint S11 — NEW page 67 "Catchment geometry audit" slots into the Methodology & defensibility bucket after the Reproducibility manifest. Exposes the exact Mapbox Isochrone API inputs (pin, mode, minutes, profile, assumed free-flow speed), the derived geometry that came back (area km²/m², perimeter, vertex count, bounding box E–W × N–S, compactness ratio, centroid offset from pin, expected free-flow disc, reach efficiency vs disc), and renders the polygon itself overlaid on the live Mapbox Dark basemap so an independent reviewer can verify the reach matches the address before trusting downstream metrics. No AI, no new data dependencies — every figure is computed from the existing `data.catchmentRing` + `data.audit` + `data.areaKm2` payload using a single `haversineKm` import from `@/lib/spatial`.
v2026.12.sS10_defensibility_appendix2026-05-23Sprint S10 — NEW Defensibility Appendix (pages 62–66) makes every recommendation, observation and finding in this report independently re-derivable from the PDF alone. Five pure pages slot into the existing 'Methodology & defensibility' bucket between the Methodology Appendix (18) and the Bibliography (19): 62 Calculation lineage (inputs → formula → parameters → output → uncertainty for every indicator that fired) · 63 €-driver coefficient ledger (4-driver Value-at-Stake table with low/central/high bands, sensitivity rank, sources) · 64 Live-anchor provenance (which Copernicus / EEA / NASA / OpenAQ feeds fired live vs which fell back to v0 surrogate) · 65 Rule firing log (which insight rules, intervention rules and recommendation branch emitted what fired) · 66 Reproducibility manifest (audit id, pin, reach, methodology version, changelog tail + reproduction checklist). NEW `src/lib/defensibility-appendix.ts` is the single source of the five pure builders — no AI, no new data dependencies, no schema migration.
v2026.12.sS9_about_this_report2026-05-23Sprint S9 — NEW page 61 "About this report". Plain-English product primer that sits between the cover/TOC/legend chrome and the Executive Summary, so a forwarded PDF reads correctly to a reader who has never met Urban Pulse. Five labelled blocks: what Urban Pulse is · what makes it different (4 USP bullets) · what's in THIS report (auto-derived from the visible TOC buckets via `PAGE_BY_ID`, so a Mayor 1-pager reads honestly) · why it's useful for YOU (pivoted by `clientType` + `reportPurpose` via `whyUsefulFor()`) · how to read it (live page pointers to §40 legend, §36 glossary, §18 methodology). NEW `src/lib/about-this-report.ts` SINGLE source for the page's copy. Wired into `PROFESSIONAL_ORDER` (now 24pp), `PRELIMINARY_ORDER` (now 19pp), all three `layoutPagesFor` branches, `executiveCutFor` and `COUNCIL_CUT`. `MAYOR_CUT` stays `{1, 29}` — the 1-pager remains a 1-pager. No AI generation, no new data dependencies; the page renders identically across every audit except for the audience-pivoted paragraph and the auto-derived bucket list.
v2026.12.sS8_ai_section_intros2026-05-23Sprint S8 (PR-8 of Report Structure Upgrade) — AI-generated, audit-specific Section Intros & Summaries. NEW `src/lib/section-intros-ai.server.ts` SINGLE source: batched JSON call to `google/gemini-3-flash-preview` produces a `{introBody (≤55 words), summaryBody (≤60 words)}` pair per Professional-spine opener, audience-pivoted via `audienceForVariant` (mayor/planner/analyst). Word caps clamped at sentence boundaries; banned marketing tropes (vibrant/world-class/cutting-edge…) deterministically stripped. Persisted to `report_drafts.sections.sectionIntrosAi[audience][pageId]`. NEW `generateSectionIntros` server fn shim in `narrative.functions.ts` (dynamic import keeps client bundle clean). `loadNarrativeDraftImpl` now returns `sectionIntrosAi` so repeat opens are free. `ReportData.aiSectionPanels?: Record<pageId, {introBody, summaryBody}>` threaded into `<SectionIntro pageId aiPanel>`: AI body renders as italic 'Briefing for this catchment' block above the static 5-field panel; AI summary renders as 'In summary' block below. All 4 currently-wired SectionIntro call sites (pages 16/18/19/36) pass `aiPanel={data.aiSectionPanels?.[n]}`. Silent fallback on AI gateway failure → static `SECTION_INTROS` panel only.
v2026.12.sS7g_methodology_plain_english2026-05-23Sprint S7 Stage G — Plain-English block per indicator. NEW `INDICATOR_PLAIN_ENGLISH: Record<indicatorId, IndicatorPlainEnglish>` sibling map in `src/lib/methodology.ts` carries a 7-field structured restatement of every indicator (`whatItMeasures` · `whyUsed` · `inputsPlain` · `outputs` · `howToRead` · `limitations` · `whereInReport`) derived from each indicator's own `definition` + `parameters` + `uncertainty.description`. The `/methodology` route now renders this 7-row labelled grid first in plain-English mode; the formula + parameter table sits behind a `Show technical detail` toggle. `plainEnglishFor(id)` is the SINGLE accessor; the renderer falls back to the existing glossary one-liner when an indicator has no plain-English row. INDICATORS array + CITATIONS map unchanged (evidence base preserved). Adding a new indicator = extend `INDICATORS` + add ONE row to `INDICATOR_PLAIN_ENGLISH`.
v2026.12.sS7_report_compiler2026-05-22Sprint S7 (PR-7 Wave 2) — Editorial intros + Tables + Export checklist + Post-render PDF QA. Stage C widened `SECTION_INTROS` from 2 to 5 fields (`whatThisSectionDoes`, `whatTheReaderWillFind`, `whyItMatters`, `methodsUsed`, `mainTakeaways`) across all 21 entries; `<SectionIntro>` renders the new panel with a legacy fallback. Stage D added `src/lib/table-registry.ts` SINGLE source of `Table N.` numbering + metadata. Stage A added `src/lib/professional-report-payload.ts` with `EXPORT_CHECKLIST` (18 items × `codePrefixes`) + `evaluateExportChecklist(blockerCodes)`. Stage J re-skinned `<ExportBlockedModal>` to render the 18-point checklist (green ✓ / red ✗ per item, drill-down to matching codes). Stage I added `scripts/qa/pdf-qa.mjs` post-render inspection (broken-glyph patterns, char-density floor/ceiling per page, TOC page-number integrity) as a CI-runnable Node script.
v2026.12.sS6_acceptance_envelope2026-05-22Sprint S6 (PR-6 of Report Structure Upgrade) — Testing & Acceptance Envelope. Updated `scripts/acceptance/fixtures.ts` to reflect the new Professional spine envelope introduced by PR-1 (Introduction & Approach + Key Findings promoted into `PROFESSIONAL_ORDER`). `professional-cut-18p` page-count cap moved from `[16, 20]` → `[18, 24]` (matches the brief's 18–24pp Professional envelope); `preliminary-cut-16p` cap moved from `[14, 18]` → `[14, 22]`. Fixture labels re-tagged Sprint S6 with explanatory comments tying the change to PR-1's spine growth. All 38 fixtures now pass against the post-PR-1..PR-5 codebase (tier ladder, blocker codes, visible-page bounds, and snapshot diff all green). No production code changed — pure test-harness update. Version bump invalidates cached narrative rows so the next report open re-paints against the live methodology version surface.
v2026.12.sS5_export_gate2026-05-22Sprint S5 (PR-5 of Report Structure Upgrade) — Export Gate. NEW `professionalSpineIssues(data, visiblePages)` in `src/lib/qa-gate.ts` is the Professional-mode completeness check that ties PR-2's editorial registries (`SECTION_INTROS`, `PAGE_VISUALS`) and PR-1's spine (`PROFESSIONAL_ORDER` + Methodology/Glossary appendices) to the renderer's actual `visiblePages` set. Three blocker classes fire only when `reportMode === 'professional'`: (a) section-intro presence — every visible page in `PROFESSIONAL_ORDER` that the registry marks as a section opener (`SECTION_INTRO_PAGE_IDS`) MUST have a non-empty `eyebrow` + `body` in `SECTION_INTROS`; (b) figure-caption / figure-source presence — every declared visual in `PAGE_VISUALS[pageId]` whose page is visible MUST carry a non-empty `caption` AND non-empty `source` attribution; (c) appendix presence — `visiblePages` MUST contain page 18 (Methodology) and page 36 (Glossary). Wired into `runQaGate` immediately after `professionalGateIssues`. Non-Professional modes (`preliminary`, `technical_draft`, unset) are structurally unaffected because the gate short-circuits on the mode check. Static ES imports added for the three registry modules — no lazy `require`. NON-breaking — pure additive blocker; pre-PR-2 fixtures that left the registries fully populated stay green; only a Professional export that has lost an intro/caption/source/appendix between PR-2 and now is refused. Version bump invalidates cached narrative rows.
v2026.12.sS4_quality_sweep2026-05-22Sprint S4 (PR-4 of Report Structure Upgrade) — Quality Sweep. POI contradiction fix across pages 10/18 + Data sample card + page-18 ledger row (now emits 'Modelled POI density (live OSM unavailable)' with warn-tone chip when `data.pois.length === 0`). Extended `BLOCKED_STRINGS` with nine new entries (`Audit ledger`, `Snapshot ledger`, `Snapshot confidence`, `No LLM in the loop`, etc. + raw UUID pattern); renderer copy edits remove every active instance.
v2026.12.sS3_toc_integrity2026-05-22Sprint S3 (PR-3 of Report Structure Upgrade) — Pagination Integrity. Rebuilt the §39 Table of Contents in `src/lib/report-template.tsx` so it walks the actual `visiblePages` array IN PHYSICAL ORDER and groups consecutive ids by `PAGE_BY_ID[id].bucket` (single source from `src/lib/page-registry.ts`).
v2026.12.sS2_section_intros2026-05-22Sprint S2 (PR-2) — Section Intros + Figure Registry. Two new SINGLE-source modules wire the editorial scaffolding the Professional Client Report has been missing: (1) `src/lib/section-intros.ts` declares a plain-English standfirst paragraph for every section-opening page in `PROFESSIONAL_ORDER`, keyed by page id, with an `eyebrow` label and a ≤55-word `body` written for an exhausted mayor. (2) `src/lib/figure-registry.ts` declares the visuals each Professional-spine page paints (`PAGE_VISUALS`), assigns deterministic sequential `Figure N.` numbering by walking `PROFESSIONAL_ORDER`, and exposes `figureMetaFor(pageId, primitive, occurrence)` so renderer call sites resolve `{figureNumber, caption, source}` from one place. `Frame` in `src/lib/report-visuals.tsx` (the SINGLE wrapper every named PDF visual extends) gains an optional `figureNumber?: number`; when set, the rendered title is prefixed `Figure {N}. {title}` so external citations stay stable across runs. New `<SectionIntro pageId={n}>` react-pdf component (`src/lib/report-section-intro.tsx`) looks up the intro and paints nothing when the page is not a declared opener. `PROFESSIONAL_ORDER` is now exported from `report-cuts.ts` so the figure registry can derive numbering. Version bump invalidates all cached narrative rows so the next report open picks up the new editorial scaffolding. NON-breaking — additive optional fields throughout; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN13_hedges2026-05-22Sprint N13 (Narrative Quality Upgrade Tier 12) — audience-aware hedge density cap with retry-once-then-deterministic-prune enforcement. Decision-makers discount hedged prose ("may", "could", "potentially", "appears to") and the discount scales with audience: mayors fastest, planners moderately, analysts not at all (they quantify uncertainty with numbers). NEW `src/lib/narrative-hedges.ts` is the SINGLE source of two coupled tables: `HEDGE_CAP` (mayor=1, planner=3, analyst=8 — counts hedge tokens permitted across one section) and `HEDGE_TOKENS` (curated vocabulary spanning single-word modal hedges `may`/`might`/`could`/`possibly`/`potentially`/`perhaps`/`presumably`/`arguably`/`seemingly`/`ostensibly`/`supposedly`/`tentatively`/`conceivably`, vague-magnitude hedges `somewhat`/`fairly`/`rather`/`roughly`/`approximately`/`around`/`about`, verb-form hedges `appears to`/`seems to`/`tends to`/`is likely to`/`is unlikely to`, and multi-word qualifiers `in some cases`/`in many cases`/`to some extent`/`to a degree`/`more or less`/`by and large`). Intentionally excludes `should` (directive, not hedging) and `will` (commitment, not hedging) so the cap doesn't punish real recommendations. Detection via case-insensitive whole-word regex per token (`\b...\b`) so `may` doesn't match `mayor` and `around` doesn't match `ground`. `findHedgeIssue(audience, prose)` returns `{count, cap, hits, exampleSentence}` when `count > cap`; null otherwise. `formatHedgeDirective(issue)` is the retry directive (names the audience, quotes the overshoot count vs cap, lists the worst offenders, and includes an audience-specific tone rule). `pruneHedges(prose, audience)` is the deterministic final-fallback: walks a priority-ordered token list (high-dilution hedges first like `potentially`/`possibly`; vague-magnitude hedges last like `approximately`/`around` because they often precede a real number, so losing them changes meaning least) and removes occurrences until the count drops to the cap, then collapses the whitespace + ` .` / ` ,` artefacts the removal leaves behind. Chained into `runSectionNarrative` AFTER the Sprint N12 citation strip (so a citation rewrite can't reintroduce hedging) and BEFORE the Sprint N7 readability gate (so the readability gate scores de-hedged prose). Same shape as N10 + N12: retry-once-then-deterministic-prune. Retried candidate re-validated against BOTH the brief-wide ±5% numeric guardrail AND the N6 numeric-provenance allow-list so the hedge-rewrite cannot smuggle in new unsupported numbers. Differs from N12: this is a COUNT cap (not a hard zero), and the prune is occurrence-by-occurrence rather than wholesale strip. Adding a new banned hedge = extend `HEDGE_TOKENS` ONLY; cap tuning = edit `HEDGE_CAP` ONLY. Version bump invalidates all cached narrative rows so the next report open re-generates against the hedge-capped pipeline. NON-breaking — additive only; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN12_citations2026-05-22Sprint N12 (Narrative Quality Upgrade Tier 11) — inline `[Source YYYY]`-style citation policy, audience-gated. NEW `src/lib/narrative-citations.ts` is the SINGLE source of two coupled rules: (1) `analyst` cuts MAY use inline bracketed citation tokens drawn from a curated whitelist (`CITATION_TOKENS` — 18 entries spanning the `methodology.ts::CITATIONS` academic anchors plus the Sprint N5 live-anchor vocabulary: `[EEA CNOSSOS-EU 2017]`, `[NASA POWER]`, `[Sentinel-5P TROPOMI]`, `[JRC LISFLOOD 2020]`, `[Copernicus DataSpace]`, `[Copernicus DEM]`, `[Copernicus Urban Atlas 2018]`, `[Copernicus EMS]`, `[ERA5]`, `[Eurostat Urban Audit 2024]`, `[GHSL R2023A]`, `[Mapillary]`, `[Transitland]`, `[Strava Metro]`, `[OSM]`, `[OpenAQ]`, `[WHO 2018]`, `[Moreno 2021]`, `[Jacobs 1961]`, `[Frank 2010]`, `[Ewing & Cervero 2010]`, `[Shannon 1948]`, `[Barron 2014]`); (2) `mayor` and `planner` cuts MUST NOT contain ANY `[…]`-bracketed citation token — they read as jargon and break the plain-English contract enforced by `AUDIENCE_PIVOT.mayor`. Detection via broad `/\[[A-Za-z][^\[\]\n]{0,80}\]/g` regex (catches model-invented variants like `[European Environment Agency 2020]`, not just the whitelist); `findCitationLeak(audience, prose)` returns null for analyst, returns matched tokens (deduplicated, max 8) for mayor/planner. Filters out non-citation brackets: `[1]`-style numeric refs, empty brackets, and bracketed prose > 60 chars. `formatCitationStripDirective(leak)` is the retry directive (quotes the offending tokens back verbatim so the model knows exactly what to remove). `stripCitations(prose)` is the deterministic final-fallback strip (removes the bracketed token + collapses the double-space / ` .` / ` ,` artefacts the removal leaves behind). `formatAnalystCitationDirective()` is the analyst-only user-prompt addendum surfacing a 10-token working subset of the whitelist; encourages — does NOT force — inline citations at most one per paragraph, only where they ground a number a reviewer would re-derive. Chained into `runSectionNarrative` AFTER the Sprint N10 acronym strip (so an acronym rewrite can't reintroduce citations) and BEFORE the Sprint N7 readability gate (so the readability gate scores cleaned prose). Same shape as N10: retry-once-then-deterministic-strip. Retried candidate re-validated against BOTH the brief-wide ±5% numeric guardrail AND the N6 numeric-provenance allow-list so the citation rewrite cannot smuggle in new unsupported numbers. Adding a new permitted citation = extend `CITATION_TOKENS` (+ optionally the surfaced subset in `formatAnalystCitationDirective`) ONLY. Version bump invalidates all cached narrative rows so the next report open re-generates against the citation-gated pipeline. NON-breaking — additive only; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN11_trend_delta2026-05-22Sprint N11 (Narrative Quality Upgrade Tier 10) — prior-period €-driver deltas threaded into the §6 `implementationRoadmap` and `fundingBusinessCase` per-section narratives. Capitalises on the Sprint Q8-tail `AuditTrendPoint.driverCentral` work (which already populates per-driver central €/yr inside `listAuditSnapshots`) by exposing the top-3 movers — ranked by `|currentEur − previousEur|` — to the narrative pipeline. NEW `PlannerEnrichment.trendDelta` (`src/lib/prompts/planner.ts`) carries `{previousElr, currentElr, previousEuroCentral, currentEuroCentral, previousVersion, currentVersion, topMovers[]}`; mirrored in both `EnrichmentSchema` Zod copies (`narrative-core.server.ts` + `narrative.functions.ts`) so the server-fn payload validates the same shape. `snapshotToBrief` emits a `TREND VS PREVIOUS RUN: ELR p→c · €/yr p→c · methodology p→c` line plus a `BIGGEST €-DRIVER MOVERS SINCE PREVIOUS RUN` block with `±€/yr` signed magnitudes per mover. Both `SECTION_PROMPTS.implementationRoadmap.core` and `SECTION_PROMPTS.fundingBusinessCase.core` (`src/lib/prompts/sections.ts`) gain a conditional clause that REQUIRES naming the top mover verbatim when the brief contains the `BIGGEST €-DRIVER MOVERS` line — and explicitly forbids inventing a delta when it does not (so first-run audits read clean). Roadmap ties the top mover to the phase-1 baseline-lock action; Funding frames it as defensibility evidence for the lead bid. The report loader (`audit.$auditId.report.tsx`) derives `sectionTrendDelta` from the trend snapshot points immediately before composing `sectionEnrichment`: driver-id → human-readable name mapped via the current run's `baselineImpact.drivers` so we never invent a label; movers with `|delta| < €1/yr` filtered out; gracefully `undefined` when fewer than two snapshots exist or both lack `driverCentral` (legacy pre-Sprint-23). Existing N6 numeric-provenance allow-list still gates the generated prose so the model cannot quote a mover number absent from the brief. Version bump invalidates all cached narrative rows so the next report open re-generates against the trend-aware roadmap and funding prompts. NON-breaking — additive optional field only; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN10_acronyms2026-05-22Sprint N10 (Narrative Quality Upgrade Tier 9) — audience-aware acronym blocklist with retry-once-then-strip enforcement. Closes the mayor/council acronym leak path: previously `AUDIENCE_PIVOT.acronymPolicy` (`src/lib/prompts/sections.ts`) only advised the model in the system prompt — nothing enforced it. NEW `src/lib/narrative-acronyms.ts` is the SINGLE source of the enforcement layer: `ACRONYM_BLOCKLIST: Record<AudienceKey, string[]>` (mayor bans the full set including indicator acronyms `Lden` / `PM2.5` / `NO₂` / `ELR`, data-pipeline `CNOSSOS` / `LISFLOOD` / `ERA5` / `TROPOMI` / `CDSE`, and finance `CapEx` / `ROI` / `IRR` / `NPV`; planner bans only the data-pipeline / satellite internals; analyst is unrestricted), `ACRONYM_EXPANSIONS` (plain-English replacements like `Lden → "day-evening-night noise"`), `findAcronymIssue(audience, prose)`, `formatAcronymDirective(issue)`, `stripAcronyms(prose, audience)`. Detection is case-sensitive whole-word with literal token matching (handles `PM2.5`, `NO₂`, `GTFS-RT`). Chained into `runSectionNarrative` AFTER N8 close-out (so the close-out rewrite can't reintroduce jargon) and BEFORE N7 readability (so the readability gate scores stripped prose). Same shape as N3: retry-once-then-strip. Retried candidate re-validated against BOTH the brief-wide ±5% numeric guardrail AND the N6 numeric-provenance allow-list so the acronym rewrite cannot smuggle in new unsupported numbers. Adding a new banned acronym = extend `ACRONYM_BLOCKLIST` (+ optionally `ACRONYM_EXPANSIONS`) ONLY. Version bump invalidates all cached narrative rows so the next report open re-generates against the acronym-gated pipeline. NON-breaking — additive only; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN9_delta_lead2026-05-22Sprint N9 (Narrative Quality Upgrade Tier 8) — split the §6 `conclusion` prompt to LEAD with a "what changed since you started reading" delta beat before the existing 7-beat close-out (now ¶2–¶8). Prompt-only edit to `SECTION_PROMPTS.conclusion.core` in `src/lib/prompts/sections.ts`. New ¶1 opens with a one-sentence delta naming what a reader who only scanned the executive summary now knows that they did not before (a risk larger than the headline implied, a peer-city precedent that reframes the verdict, a compounding pair that lifts the €/yr band, or — when the body only confirmed the opening framing — say so plainly), then quotes the CANONICAL VERDICT verbatim and the CANONICAL HEADLINE €/yr band verbatim from the Sprint N6 spine-lock fields so the delta cannot drift. Rest of the prompt is unchanged; the existing 7 beats just shift one slot down. No new section key, no schema migration, no new env vars. Sprint N8 so-what close-out and Sprint N7 readability gate still apply to the new closing paragraph (now ¶8). Version bump invalidates all cached narrative rows so the next report open re-generates against the delta-led conclusion prompt. NON-breaking — additive prompt edit; no €-coefficient changes.
v2026.12.sN8_so_what2026-05-22Sprint N8 (Narrative Quality Upgrade Tier 7) — "So what:" close-out lint on the two §6 sections decision-makers re-read in isolation: `priorityFindings` and `compoundingRisks`. NEW `src/lib/narrative-soWhat.ts` is the SINGLE source: `SO_WHAT_SECTIONS = {priorityFindings, compoundingRisks}`, `SO_WHAT_MARKERS` (e.g. "this means", "bottom line", "without action", "the implication", "decision:"), `hasSoWhatCloseOut(prose)`, `findSoWhatIssue(sectionKey, prose)`, `formatSoWhatDirective(issue)`, and `appendDeterministicSoWhat(prose, enrichment)`. A close-out qualifies when the tail (last paragraph / last 2 sentences) contains a marker phrase OR carries both a € figure AND a directive verb (must / should / act / decide / requires / prioritise). Same chain shape as N3: retry-once-then-fallback. The retried candidate is re-validated against BOTH the brief-wide ±5% numeric guardrail AND the N6 numeric-provenance allow-list so the close-out rewrite cannot smuggle in new unsupported numbers. If the model still refuses to land the plane, a deterministic close-out is appended — built from `PlannerEnrichment.canonicalHeadline` + `canonicalVerdict` (Sprint N6 spine-lock) so it cannot drift from the rest of the report. Chained into `runSectionNarrative` AFTER N3 lint + N6 provenance and BEFORE N7 readability, so the readability gate scores the close-out too. Adding a new close-out-gated section = extend `SO_WHAT_SECTIONS` ONLY. Version bump invalidates all cached narrative rows so the next report open re-generates against the so-what-gated pipeline. NON-breaking — additive only; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN7_readability2026-05-22Sprint N7 (Narrative Quality Upgrade Tier 6) — promotes the existing payload-level `runReadability` (warning-only, P4.22) into an inline retry trigger for the two spine sections busy readers actually finish: `executiveSummary` and `conclusion`. NEW `src/lib/narrative-readability.ts` is the SINGLE source of the per-section readability check: `READABILITY_SENSITIVE_SECTIONS = {executiveSummary, conclusion}`, `READABILITY_FLOOR = 50` (Flesch Reading Ease), deterministic en-GB syllable estimator (`estimateSyllables`), `fleschReadingEase`, `findReadabilityIssue(sectionKey, prose)`, `formatReadabilityDirective(issue)` (rewrite-for-an-exhausted-mayor addendum: ≤18 words/sentence, one-syllable verbs, no parentheticals), and `pickBetterReadability(original, retried)`. Chained into `runSectionNarrative` AFTER the N3 vagueness lint and BEFORE prose is cached. Pattern differs from the surrounding guardrails: retry-once-then-PICK-HIGHER, not retry-once-then-strip — readability is editorial, not factual, so a slightly dense paragraph beats an empty section. The retry candidate is re-checked against BOTH the brief-wide ±5% numeric guardrail AND the N6 numeric-provenance allow-list, so the readability rewrite cannot smuggle in new unsupported numbers. Other sections still trip the payload-level `runReadability` warning at the export gate; only the spine pair retries inline. Version bump invalidates all cached narrative rows so the next report open re-generates against the readability-gated pipeline. NON-breaking — additive only; no €-coefficient changes, no schema migration, no new env vars.
v2026.12.sN6_consensus2026-05-22Sprint N6 (Narrative Quality Upgrade Tier 5) — two new post-emit guardrails on the per-section LLM pipeline. (1) Numeric provenance pass: `runSectionNarrative` now chains `findProvenanceViolations` (`src/lib/narrative-provenance.ts`) immediately after the brief-wide ±5% numeric guardrail and BEFORE the N3 vagueness lint. The provenance pass operates on an explicit curated allow-list (`PlannerEnrichment.allowedNumbers?: number[]`) surfaced by `snapshotToBrief` as an `ALLOWED NUMERIC FACTS:` block, with tight ±1-last-digit / ±2pp / ±2% tolerance — catches transposed digits the existing ±5% check lets through. Same retry-once-then-strip pattern as the surrounding guardrails. (2) Cross-section consensus: `runReportNarrativesImpl` now runs `findConsensusViolations` (`src/lib/narrative-consensus.ts`) after the 13-section fan-out and BEFORE persistence. The check asserts that the four spine sections (`executiveSummary`, `priorityFindings`, `decisionBrief`, `conclusion`) all name the SAME verdict label (one of `TITLES`/`TITLES_6`) and the SAME headline €/yr band. Divergent sections are regenerated once with a `SPINE CONSENSUS LOCK` directive built from `PlannerEnrichment.canonicalVerdict` + `canonicalHeadline`; surviving violations are persisted as `report_drafts.sections.consensusViolations: string[]` for the Engine Room audit trail. Both Zod `EnrichmentSchema` copies (`narrative-core.server.ts` + `narrative.functions.ts`) and the `PlannerEnrichment` type (`planner.ts`) gain `allowedNumbers?`, `canonicalVerdict?`, `canonicalHeadline?` in lock-step. `recommendation.ts` exports `TITLES` so the consensus module can read the 3-rung label set. Version bump invalidates all cached narrative rows so the next report open re-generates against the consensus-locked pipeline. NON-breaking — additive only; no €-coefficient changes, no schema migration (the `report_drafts.sections` jsonb absorbs the new field).
v2026.12.sN5_provenance2026-05-22Sprint N5 (Narrative Quality Upgrade Tier 5) — live-anchor provenance now flows into the §6 methodology narrative. `PlannerEnrichment` gains optional `liveAnchors?: string[]` (mirrored on both `EnrichmentSchema`s in `narrative-core.server.ts` and `narrative.functions.ts`). `snapshotToBrief` emits a `LIVE EVIDENCE ANCHORS FIRED (name each in the methodology section): ...` line when present. The `methodologyApproach` prompt is extended: paragraph 1 MUST add one extra sentence naming each anchor verbatim when the line is present, OR state plainly that the catchment runs on the v0 deterministic surrogate. Prompt also forbids inventing a live anchor that the brief does not list. The studio loader (`audit.$auditId.report.tsx`) derives `liveAnchors` deterministically from the four already-fetched live structures (`liveNoise` → EEA CNOSSOS-EU 2017; `liveHeat` → NASA POWER skin temperature; `liveAir` → Sentinel-5P TROPOMI ± OpenAQ; `liveFlood` → JRC LISFLOOD via Copernicus DataSpace blended with ERA5+DEM or with Copernicus EMS) and threads it into BOTH the section-prose enrichment and the Strategic Synthesis enrichment. Version bump invalidates all cached narrative rows so the next report open re-generates against the provenance-aware methodology prompt. NON-breaking — additive only; no €-coefficient changes, no schema migration.
v2026.12.s32_1_live2026-05-22Sprint 32.1 (live) — replaces both Mobility Pulse TODOs in `getTransitStops` (`src/lib/transit.functions.ts`) with real layered-intelligence pulls. (1) GTFS-Realtime trips/hour: `fetchGtfsTripsPerHour` calls Transitland v2 `/api/v2/rest/stops?bbox=...` for up to 20 stops, then in parallel fans out to `/api/v2/rest/stops/{onestop_id}/departures?next=3600&limit=100` across the top 12 stops, dedupes `trip_id`s, and returns the count == trips/hour for the catchment. Transitland's REST endpoint merges scheduled GTFS with the feed's `urls.realtime_trip_updates` server-side, so the protobuf parse is avoided entirely — keeps the function Worker-runtime safe (no `gtfs-realtime-bindings` / `protobufjs` dep). (2) Strava Metro active-trip share: `getStravaToken` (module-scoped bearer cache, `expires_in - 60s` headroom) → OAuth2 client-credentials POST against `https://www.strava.com/api/v3/oauth/token` → `fetchStravaActiveShare` GETs `https://metro.strava.com/api/v1/aggregate-tiles?bbox=...&period=last-12-months&modes=walk,bike,run`, sums walk + bike + run trip counts across all returned tiles, divides by total trips → clamped `[0,1]` active-trip share. Any upstream failure (token 4xx/5xx, Transitland 4xx/5xx, Strava Metro 4xx/5xx, empty tiles) leaves the optional field unset so `computeMobilityPulse` falls back to the existing stops/km² + mode-diversity + Moreno + POI-density surrogate. When the GTFS-RT anchor fires, `transitLift` lifts up to +3pp at ≥60 trips/hr (Sprint 32.1 surrogate logic preserved); when the Strava anchor fires, `activeShare` is blended 50/50 with the surrogate. `LiveMobilityOverride.source` flips across the existing six-member union accordingly and the `MobilityPulseCard` `ProvenancePill` sourceLabel resolves dynamically. NON-breaking — additive only; output shape preserved end-to-end, no €-coefficient change, no schema migration. Version bump invalidates all cached narrative rows so the next report open re-generates against the live Mobility pipeline.
v2026.12.s35_1_live2026-05-22Sprint 35.1 (live) — replaces the JRC LISFLOOD TODO in `getLiveFlood` with a real Copernicus DataSpace Sentinel Hub Statistical API pipeline. Three env vars gate the path: `CDSE_CLIENT_ID` + `CDSE_CLIENT_SECRET` (OAuth2 client-credentials against the CDSE identity realm) + `CDSE_JRC_PLUVIAL_COLLECTION_ID` (BYOC collection holding the JRC LISFLOOD pluvial flood-depth raster, 60-yr return period). New module-scoped helpers: `getCdseToken` (caches the bearer token for `expires_in - 60s`), `catchmentPolygon` (16-sided ~1.2 km circular ring around the audit pin, scaled by `cos(lat)`), `fetchJrcPluvialMeanDepth` (POSTs an evalscript V3 against the BYOC depth band, P1Y aggregation 2020-now, 30 m grid, takes the catchment-mean), `depthToAnnualLossEurPerResident` (JRC 2020 power-law depth-damage curve fit so `d = 0.30 m → €40/resident/yr` Munich Re NatCat 2023 anchor, capped at €280 to match the surrogate ceiling). Any upstream failure (token 4xx/5xx, Statistical API 4xx/5xx, empty `means` array) leaves `jrcAnnualLoss` null so the ERA5+DEM path (or the v0 surrogate) drives the value without a retry. When the JRC anchor resolves, `computeFloodRisk` blends it 50/50 with the ERA5+DEM envelope (Sprint 35 logic preserved), the `source` flips to `open-meteo-era5+copernicus-dem+jrc-lisflood` (or `copernicus-ems-pluvial+jrc-lisflood` if both ERA5 + DEM also failed), the `FloodRiskCard` `ProvenancePill` switches to 'JRC LISFLOOD + ERA5/DEM' / 'JRC LISFLOOD', and the caveat names the modelled-loss anchor + 60-yr return period. NON-breaking — additive only; output shape preserved end-to-end, no €-coefficient change, no schema migration. Version bump invalidates all cached narrative rows so the next report open re-generates against the live JRC pipeline.
v2026.12.s5a_tail2026-05-22Sprint 5a-tail — wires the dormant POI-density risk-hotspot overlay end-to-end and lands the next P4.17-tail slice (4th registered VISUAL_PRIMITIVE on the default `pageVisuals` map). `RiskHotspotMap` joins `VISUAL_PRIMITIVES` in `src/lib/report-visuals.tsx` as a thin VisualFrame wrapper around the base64 PNG returned by `getRiskHotspotMapPng`. `ReportData` gains optional `riskHotspotMapPng: string | null`. The studio loader (`audit.$auditId.report.tsx`) fetches the hotspot basemap after POIs resolve (passing `ring` + audit pin + `pois.map(p => [p.lng, p.lat])` + `targetSamples: 36`), non-fatal: a Mapbox 4xx/5xx or missing `MAPBOX_TOKEN` logs a console.warn and the page silently omits the overlay. PDF page 23 (Streetscape Vision) renders `<RiskHotspotMap>` immediately after the existing RadarChart so the public-realm verdict reads alongside spatial context. `validateReportPayload` (`src/lib/report-payload.v2.ts`) extends the default `pageVisuals` map with `23: ["RiskHotspotMap"]` so the QA gate auto-enforces the visual under the warning-level `visuals.page_23` check. Two stale deferral comments retired: `src/lib/report-pages.ts` no longer claims a large JSX refactor is deferred (Sprint I-tail closed it); the page-34 trend-snapshot block in `report-template.tsx` no longer claims per-driver delta is deferred (Sprint Q8-tail closed it). NON-breaking — additive only; no €-coefficient changes, no schema migration. `getInterventionFocusMapPng` remains dormant until an interactive package-category selector lands.
v2026.12.sN42026-05-22Sprint N4 (Narrative Quality Upgrade Tier 4) — new `methodologyApproach` section in `src/lib/prompts/sections.ts`. `SectionKey` widens from 12 → 13 keys and `SECTION_KEYS` gains `methodologyApproach` in the second-to-last slot (immediately before `conclusion`). The new prompt instructs the model to write three short paragraphs explaining — in plain English — WHY the indicators in this report fit THIS catchment (paragraph 1: WHAT WAS MEASURED — names the four indicator families and ties each to one observable feature; paragraph 2: HOW WE CALIBRATED — names the peer cohort, the per-metric percentile method, and the confidence-loss reason; paragraph 3: WHAT THIS METHOD CAN AND CANNOT DEFEND — two named defences + two named limits, closing with the literal pointer to the Engine Room). Forbidden patterns ban marketing tropes (`state of the art`, `gold standard`, `industry-leading`, `proprietary algorithm`, `black box`) on top of the vagueness ban list. Orchestrator (`runReportNarrativesImpl`) iterates `SECTION_KEYS` so the new key fans out automatically — no orchestrator edit needed. `report_drafts.sections.sectionProse` is jsonb so the new key persists without a schema migration. Report-loader hydration threshold bumped `>= 6` → `>= 7` to scale with the 13-section count (was 50% of 12, now 54% of 13). NON-breaking — additive only, no €-coefficient changes, no PDF JSX changes, no schema migration. Adding a new section = extend `SectionKey` + `SECTION_KEYS` + `SECTION_PROMPTS` ONLY; never inline section logic at the orchestrator.
v2026.12.sN32026-05-22Sprint N3 (Narrative Quality Upgrade Tier 3) — pre-emit narrative lint. NEW `src/lib/narrative-lint.ts` is the SINGLE source of truth for vagueness + editorial checks. `VAGUE_PHRASES` + `LONG_SENTENCE_WORD_LIMIT` (25 words, no-digit) are the only knobs. `runSectionNarrative` chains lint AFTER the numeric guardrail: retry-once-then-strip; numeric guardrail re-runs on retried prose so both invariants hold. NON-breaking.
v2026.12.sN22026-05-22Sprint N2 (Narrative Quality Upgrade Tier 2) — upgrades the spine narrative model. `PRIMARY_MODEL` switches `openai/gpt-5-mini → openai/gpt-5.4` with `reasoning: { effort: "medium" }`; `FALLBACK_MODEL` switches `google/gemini-3-flash-preview → google/gemini-2.5-pro` on 429/402. New `MODEL_REASONING_EFFORT` table is the SINGLE source of which models accept a `reasoning` parameter; `callGateway` reads from it so the param is omitted cleanly for non-reasoning models. Version bump invalidates cached narrative_cache rows. NON-breaking.
v2026.12.sN1_tail2026-05-22Sprint N1-tail — wires the dormant per-section LLM layer end-to-end in the report loader. `generateSectionNarratives` now auto-fires for `audienceForVariant(variant)` after the planner narrative lands; cached prose hydrates from `loadNarrativeDraft` into `ReportData.narrative.sectionProse` on first paint. Skip when ≥6/12 sections already filled. Failures swallowed with console warning. NON-breaking.
v2026.12.sN12026-05-22Sprint N1 — activates the dormant per-section narrative layer (`src/lib/prompts/sections.ts`). Before this revision the 12 carefully-tuned §6 prompts in `SECTION_PROMPTS` + `audiencePromptFor` were defined but never called; every PDF page outside the executive summary + recommendations was driven by deterministic builders or static caveat strings. New `runSectionNarrative({sectionKey, audience, snapshot, enrichment, confidence})` in `narrative-core.server.ts` is the SINGLE entry for per-section LLM prose — same numeric-guardrail + cache-and-retry loop as `runPlannerNarrative`, but the cache key is `section:<sectionKey>:<promptVersionFor(sectionKey)>:<audience>` so re-tuning one prompt invalidates only its rows (no global `INDICATOR_VERSION` bump needed for prompt-only edits). New `runReportNarrativesImpl({auditId, audience, snapshot, ...})` orchestrator fans out all 12 section calls via `Promise.allSettled` (so a single section failure never breaks the report), persists into `report_drafts.sections.sectionProse[sectionKey][audience]`. New `generateSectionNarratives` server function (`src/lib/narrative.functions.ts`) is the auth-gated shim. `SaveDraftInput` + `loadNarrativeDraftImpl` extend to round-trip `sectionProse`. `ReportData.narrative.sectionProse` is the new optional field renderers can read; the report loader (`audit.$auditId.report.tsx`) auto-fires `generateSectionNarratives` for the active audience after the planner narrative lands, mirroring the existing auto-narrative pattern. Renderer page-by-page consumption ships incrementally in Sprint N1-tail — this revision is the data-pipeline activation. NON-breaking — additive only, no €-coefficient changes, no PDF JSX changes, no schema migration (`report_drafts.sections` is jsonb). All 38/38 acceptance fixtures green.
v2026.11.sI_tail2026-05-22Sprint I-tail — closes the Sprint-I deferral by retiring the layout/cut-table duplication between `src/lib/report-template.tsx` and `src/lib/report-pages.ts`. The renderer now imports `layoutPagesFor` / `executiveCutFor` / `COUNCIL_CUT` / `MAYOR_CUT` / `riskPageOrderFor` from `report-pages.ts` (already the §QA single source of truth for `computeVisiblePages` + `tocCoverage`), and the inline `Record<ReportLayout, number[]>` literals plus per-cut `new Set([…])` definitions inside `pageNumberFor` AND `NeighborhoodReport` are deleted. `riskPageOrder` is preserved as a thin re-export of `riskPageOrderFor` so any out-of-tree consumer keeps working. `executiveCutFor` / `COUNCIL_CUT` / `MAYOR_CUT` are now exported from `report-pages.ts`. Net effect: every layout × cut decision — page-id ordering, deep-link math (`pageNumberFor`), visible-page filtering, and QA-gate ghost-contents / orphan-bucket checks — reads from ONE table; mirror-drift warnings retired. NON-breaking — pure refactor, identical output, no €-coefficient changes, no PDF JSX touched, no schema migration. All 38/38 acceptance fixtures green.
v2026.10.sQ8_tail2026-05-22Sprint Q8-tail — closes the Sprint-Q8 trend-page deferral by widening the snapshot ledger payload with per-driver central €/yr. `AuditTrendPoint` (`src/lib/portfolio.functions.ts`) gains optional `driverCentral: Partial<Record<ImpactDriver["id"], number>>` populated inside `listAuditSnapshots` from `euro.drivers` (omitted entirely when `tryComputeEuro` returns null so the absence is visible vs a misleading `{}`). `ReportData.trend.points[]` (`src/lib/report-template.tsx`) mirrors the optional field; the report loader (`audit.$auditId.report.tsx`) threads it through unchanged. PDF page 34 (Trend Snapshot) replaces its trailing "Per-driver decomposition … land[s] when the snapshot ledger persists driver totals" caveat with a real "Biggest €-driver movers" block — ranks all 10 drivers by `Math.abs(now − prev)`, names the top mover in a one-line headline ("Flood loss widened by €X/yr — the dominant €-driver behind the run-over-run delta above"), and prints a top-3 table (Driver / Prev / Now / Δ, red for widened exposure, accent for narrowed). Gracefully skips when either run is legacy / pre-Sprint-23 (no driverCentral). NON-breaking — additive optional field only; no €-coefficient changes, no schema migration, no `ReportData` shape change beyond the new optional. All 38/38 acceptance fixtures green.
v2026.09.sQ7_tail2026-05-22Sprint Q7-tail — formalises `audienceForVariant` (`src/lib/narrative.functions.ts`) as the SINGLE source of truth for the report-variant → audience-cut mapping. Widened the helper's input type from the 3-literal union (`executive` | `full` | `technical`) to the full 5-literal `ReportVariantInput` (`executive` | `full` | `technical` | `council-brief` | `mayor-brief`) so the renderer no longer falls back to an inline ternary on PDF page exec-summary. `narrative-core.server.ts` now re-exports the helper from the client-safe shim instead of duplicating the mapping; the PDF renderer's exec-summary block (`report-template.tsx` ~L2842) replaces its inline `data.variant === "mayor-brief" || ...` ternary with a single `audienceForVariant(data.variant)` call. NON-breaking — additive only; no €-coefficient changes, no schema migration, no `ReportData` shape change. All 38/38 acceptance fixtures green.
v2026.08.sP4_17_tail2026-05-22Sprint P4.17-tail — first slice of the deferred 14-page mechanical refactor that wires `VISUAL_PRIMITIVES` into pages still shipping inline SVGs/tables. PDF page 24 (Cross-City Benchmark) replaces the inline `Per-metric percentile` two-column View block with the `<PeerBenchmarkChart>` primitive from `src/lib/report-visuals.tsx` — the renderer now inherits the §Module-5 title / caption / legend / source trio + `safeText`-wrapped labels for free, instead of hand-rolling per-metric rows. `validateReportPayload` (`src/lib/report-payload.v2.ts`) extends its default `pageVisuals` map with `24: ["PeerBenchmarkChart"]` so every caller — studio, acceptance harness, future exporters — auto-checks that page 24 ships the mandated visual via the warning-level `visuals.page_24` gate. NON-breaking — additive only. All 38/38 acceptance fixtures green.
v2026.07.sC_tail2026-05-22Sprint C-tail — formalises the §6 Value at Stake headline-format contract on PDF page 16. The renderer already calls `formatVasHeadline(data.economicImpact.total)` at the top of page 16 (replaces the legacy hand-rolled `€{low}–€{high}` template that produced the "€11.4 Working band" / "€3.5MM" glyph-corruption regressions), and `runQaGate` already chains `vasFormatIssues` which emits BLOCKERS when the headline band is missing, has a zero central, is inverted (low > high), or otherwise malformed (low > central, high < central). Sprint C-tail (1) adds `VAS_HEADLINE_FORMAT` to `src/lib/section-shapes.ts` as the documented format string (`"€{central}m per year (range €{low}m–€{high}m)"`), mirroring the `FINAL_RECOMMENDATION_BEATS` / `FINDINGS_FIELDS` documentation pattern — reviewers + future renderers MUST honour it verbatim and adding a band field = edit `ImpactBand` + `formatVasHeadline` + `vasFormatIssues` in lock-step, and (2) versions the contract so a stale snapshot can deep-link to the entry that explains why its VaS prose differs from the live renderer. NON-breaking — additive only; no €-coefficient changes, no PDF JSX touched, no schema migration. All 38/38 acceptance fixtures green.
v2026.06.sB_tail2026-05-22Sprint B-tail — closes the Sprint-B page-rewrite remainder: (a) Mapbox static catchment on Neighbourhood Story (page 51), (b) KpiCard refactor on Performance Dashboard (page 47), (c) Priority Findings §6 six-field row contract on page 52. The renderer already wired (a) via `CatchmentMap` + `data.catchmentMapPng` (Sprint H landmarks pull-through), (b) via `KpiCardGrid` (Sprint P4.6), and (c) via `FindingRow` (Sprint P4.7). Sprint B-tail formalises all three by (1) baking `pageVisuals: { 47: ["KpiCardGrid"], 51: ["CatchmentMap"] }` as the default Module-5 contract inside `validateReportPayload` so every caller — studio, acceptance harness, future report exporters — gets the warning-level visual-presence check automatically (callers passing their own `pageVisuals` map still win), and (2) adding `FINDINGS_FIELDS` to `src/lib/section-shapes.ts` as the documented §6 six-field row contract for Priority Findings (Title / Why it matters / Evidence / Interpretation / Recommended response / Confidence chip), mirroring the `FINAL_RECOMMENDATION_BEATS` documentation pattern. NON-breaking — additive only; no €-coefficient changes, no PDF JSX touched, no schema migration, no new acceptance fixture required (existing 38/38 stay green; the new defaults are warning-level).
v2026.05.s5a2026-05-22Sprint 5a — Spatial overlay infra. NEW `src/lib/spatial.ts` is the SINGLE source of truth for grid sampling (`sampleGrid`), point-in-polygon (`pointInPolygon`), bbox derivation (`bboxOf`), and the 3-band severity colour ramp (`SEVERITY_COLOR` / `severityFromScore`) shared by every surrogate-grid → polygon overlay. NEW `getRiskHotspotMapPng` (`src/lib/risk-hotspot.functions.ts`) samples a √N × √N grid clipped to the audit isochrone, scores each cell on POI proximity (impervious / traffic surrogate), maps to low/med/high, and overlays coloured Mapbox pins on the Mapbox Dark basemap (same style as `getCatchmentMapPng`). NEW `getInterventionFocusMapPng` (`src/lib/intervention-focus.functions.ts`) takes the same grid and shades cells by per-bucket POI proximity weighted to the package category (`active_mobility` / `transit` / `public_realm` / `land_use` / `green_infrastructure`) — never re-classify POI buckets inline. Both server fns are auth-gated via `requireUrbanCatAuth`, cache 32 entries per worker, base64 dataUrl response so react-pdf can embed directly. Renderer + report-loader wiring deferred to Sprint 5a-tail (these fns are dormant until the studio loader threads `ring` + `pois` + `packageCategory` through). NON-breaking — no €-coefficient changes, no PDF JSX touched, no schema migration.
v2026.04.s33_12026-05-22Sprint 33.1 — Streetscape Vision gains a Mapillary v4 + Gemini 2.5 Flash live anchor scaffold. `LiveStreetscapeOverride.source` widens from the single `osm-overpass-parks` literal to a `StreetscapeLiveSource` union ({`osm-overpass-parks`, `mapillary-v4+gemini-2-5-flash`, `osm-overpass-parks+mapillary-v4+gemini-2-5-flash`}); three optional fields (`mapillaryWalkability`, `mapillaryFacadeQuality`, `sampledImageCount`) carry the per-sub-score vision signal. `getLiveStreetscape` (`src/lib/streetscape-vision.functions.ts`) scaffolds the bbox-clipped Mapillary Graph API pull + deterministic ~50-frame sampler + Gemini 2.5 Flash structured-rubric pass (1–5 sidewalk-continuity / shopfront-activation), gated behind `MAPILLARY_CLIENT_TOKEN` until the grid-sampler + Gemini batching land. `computeStreetscapeVision` now blends the Mapillary-derived walkability + façade 50/50 with the existing Jacobs/POI surrogate so a single mis-classified frame can't swing the headline (canopy anchor unchanged — still the OSM Overpass parks pull). Caveat names exactly which anchors fired; StreetscapeVisionCard `ProvenancePill` `sourceLabel` switches dynamically across all four source members. Output shape additive only — no €-coefficient change (Streetscape stays an evidence-only layer), no PDF JSX touched.
v2026.03.s34_12026-05-22Sprint 34.1 — Cross-City Peer Benchmark gains a Eurostat Urban Audit 2024 + GHSL R2023A + Copernicus Urban Atlas live anchor scaffold. `CityBaseline` widens with per-row `source: PeerPanelMember` (`seeded-city-baselines` | `eurostat-urban-audit-2024`); `PeerBenchmark` gains optional `panelSource: PeerPanelSource` (3-member union) + `liveRowCount` for cohort provenance, derived via `derivePeerPanelSource(baselines)`. `getPeerBaselines` (`src/lib/peer-benchmark.functions.ts`) scaffolds the `tryEnrichSprint34_1` step behind `EUROSTAT_URBAN_AUDIT_ENABLED=1` — when the flag flips on, the ~900 EU-city Urban Audit cohort + GHSL R2023A morphology + Copernicus Urban Atlas 2018 fold in with Gemini text-embedding morphological similarity, stamped `source: "eurostat-urban-audit-2024"` so the cohort promotes to the fused literal automatically. Today: dormant scaffold (seeded panel only) — output shape preserved. `PeerBenchmarkCard` popover footer + cohort caption are now dynamic — labels read "Seeded reference panel (25 cities)" / "Eurostat Urban Audit 2024" / fused via `peerPanelLabel(source)`. Adding a new panel = extend `PeerPanelMember` + `PeerPanelSource` + `derivePeerPanelSource` + `peerPanelLabel` — never inline panel copy elsewhere. NON-breaking — additive optional fields only; no €-coefficient change, no PDF JSX touched.
v2026.02.s37_12026-05-22Sprint 37.1 — Housing Affordability gains a Eurostat SILC NUTS-3 + OECD Housing 2024 cross-check. `LiveHousingOverride` adds a `HousingLiveSource` union (`eurostat-silc-nuts3`, `oecd-housing-2024`, `eurostat-silc-nuts3+oecd-housing-2024`) plus optional `tenantRentToIncomePct` / `overburdenedSharePct` / `geography` fields. `getLiveHousing` (`src/lib/housing-affordability.functions.ts`) scaffolds the Eurostat REST `ilc_lvho07a` pull + OECD HM3.1.1 SDMX cross-check, gated on `EUROSTAT_HOUSING_ENABLED=1` (needs the NUTS-3 reverse-geocode lookup to land before flipping the flag); the surrogate stays the default until then. `computeHousingAffordability(snap, live?)` now accepts the override and blends the live RTI 50/50 with the surrogate (clamped to the existing 18..72 physical envelope), preserves amenity composition, and prefers the directly-observed SILC %HCO when supplied. Caveat names the active anchor + retrieval date. `HousingAffordabilityCard` `ProvenancePill` `sourceLabel` is now dynamic across all 4 source members. Output shape additive only — no €-coefficient change, no PDF JSX touched.
v2026.01.s32_12026-05-22Sprint 32.1 — Mobility Pulse gains a GTFS-Realtime trips/hour anchor + a Strava Metro active-trip-share anchor. `LiveMobilityOverride.source` widens to a `MobilityLiveSource` union covering {transitland, osm, transitland+gtfs-rt, transitland+strava-metro, osm+strava-metro, transitland+gtfs-rt+strava-metro} and two optional fields (`gtfsTripsPerHour`, `stravaActiveTripShare`) carry the upstream signals. `getTransitStops` scaffolds a `tryEnrichSprint32_1` step behind `TRANSITLAND_API_KEY` (GTFS-RT TripUpdates aggregate) + `STRAVA_METRO_CLIENT_ID`/`STRAVA_METRO_CLIENT_SECRET` (OAuth2 client-credentials → Metro aggregate-tiles) — both are TODO scaffolds, drop-in once creds arrive. `computeMobilityPulse` lifts transitLift up to +3pp at ≥60 trips/hr and blends the Strava active share 50/50 with the surrogate when supplied; caveat names exactly which anchors fired. MobilityPulseCard ProvenancePill sourceLabel is now dynamic across all six union members. Output shape preserved end-to-end (additive optional fields only); no €-coefficient change.
v2025.12.s35_12026-05-22Sprint 35.1 — Flood & Pluvial Risk gains a JRC LISFLOOD cross-check. `LiveFloodOverride.source` widens from a single literal to {`open-meteo-era5+copernicus-dem`, `open-meteo-era5+copernicus-dem+jrc-lisflood`, `copernicus-ems-pluvial+jrc-lisflood`} and an optional `jrcAnnualLossEurPerResident` (+ `jrcReturnPeriodYr`) carries the JRC modelled-loss anchor. `getLiveFlood` scaffolds a Copernicus DataSpace Statistical API call behind `CDSE_CLIENT_ID`/`CDSE_CLIENT_SECRET`: when creds resolve, the audit catchment is sampled against the JRC LISFLOOD pluvial depth grid + 2020 depth-damage curves and either upgrades an existing ERA5+DEM pull to `open-meteo-era5+copernicus-dem+jrc-lisflood` or lights up as a `copernicus-ems-pluvial+jrc-lisflood` fallback. `computeFloodRisk` blends the JRC anchor 50/50 with the ERA5+DEM envelope so the modelled hazard layer shifts the verdict without a single anomalous cell dominating, caveat names the JRC anchor + return period, and the FloodRiskCard `ProvenancePill` switches between 'JRC LISFLOOD' / 'JRC LISFLOOD + ERA5/DEM' / 'ERA5 + Copernicus DEM' accordingly. Output shape preserved end-to-end (additive optional fields), no €-coefficient change.
v2025.11.s36_12026-05-22Sprint 36.1 — Environmental Noise anchored on EEA CNOSSOS-EU strategic noise maps. `getCnossosNoise` server fn samples the EEA NOISE viewer mosaic_roads_day / mosaic_roads_night ImageServers across a 3×3 grid clipped to the audit isochrone, decodes the U4 pixel encoding into band-centre dB, and returns the 90th-percentile Lden / Lnight when ≥30% sample coverage — facade-exposure proxy, not interior. Below the coverage floor, the v0 deterministic surrogate stays in play (output shape preserved). Audit page + report studio both thread the live sample into `computeNoisePollution(snap, live?)`; `NoisePollution.source` flips to `eea-cnossos-roads-2017` when live, caveat names the sample date + coverage, and the ProvenancePill switches accordingly. 90-day cache in `external_data_cache` keyed by quantised bbox. Output shape preserved end-to-end (additive `live` field only); no €-coefficient change.
v2025.11.s31_12026-05-22Sprint 31.1 — Air Quality gains a Sentinel-5P TROPOMI satellite cross-check. `LiveAirOverride.source` widens from a single literal to {`openaq-v3`, `sentinel-5p-tropomi`, `openaq-v3+tropomi`} and an optional `no2TropomiColumn` (µmol/m², tropospheric NO₂) carries the satellite anchor. `getLiveAir` scaffolds a Copernicus DataSpace Sentinel Hub Statistical API call behind `CDSE_CLIENT_ID`/`CDSE_CLIENT_SECRET`: when creds resolve, the TROPOMI column is fetched and either upgrades an OpenAQ station pull to `openaq-v3+tropomi` or lights up as a `sentinel-5p-tropomi` fallback when no station sits within radius. Output shape preserved end-to-end (additive optional field), no €-coefficient change.
v2025.11.s30_12026-05-22Sprint 30.1 — Heat Island anchored on land-surface temperature. getLiveHeat now pulls NASA POWER `TS` (earth skin temperature, °C, MERRA-2) alongside T2M_MAX/T2M_MIN. TS is the same physical quantity Copernicus Sentinel-3 SLSTR LST reports, so the per-site UHI baseline is now derived from a true LST signal instead of 2-m air temperature. Output shape preserved (`LiveHeatOverride.warmestMonthSkinC` is additive); the existing Copernicus DataSpace credential gate is scaffolded so SLSTR can drop in as a no-code swap when CDSE_CLIENT_ID/SECRET land. Cache `source` bumped to `nasa-power-v2` to invalidate Sprint F payloads on next read.
v2025.10.s72026-05-14Sprint 7 — Live streetscape anchor + clearer 'what we couldn't see'. Streetscape Vision tree-canopy sub-score now anchors on the existing OSM Overpass parks pull (greenSharePct, parkCount) instead of the Moreno enjoying-score proxy. Every surrogate-only risk card (Streetscape, Housing, Mobility-when-no-GTFS) renders a plain-English SurrogateNotice by default — Missing / We used / If live — so non-technical readers see the gap without opening Engine Room. PDF page 32 gains two new groups (Streetscape & public realm, Housing register) covering Mapillary, Eurostat SILC and cadastral layers.
v2025.08.s52026-05-13Sprint 5 — Live flood envelope. Flood & Pluvial Risk swaps the climate-zone rainfall constant for ERA5 reanalysis (Open-Meteo Archive, 5-yr observed 1-h precipitation max) and adds a Copernicus DEM GLO-30 9-point ±500 m local-relief term that lifts (low relief) or dampens (high relief) modeled annual loss within ±15%. Falls back to the v0 surrogate when either upstream is unreachable. 30-day cache.
v2025.07.sQ42026-05-12Sprint Q3 — Grounded narrative v2. Planner brief now carries value-at-stake band, top 3 €-weighted risk drivers, top 5 peer cities, and confidence-loss reasons. Primary model switched to openai/gpt-5-mini (gemini-3-flash-preview kept as 429/402 fallback). A numeric-claim guardrail extracts every number from the model's reply and verifies it appears in the brief verbatim or within ±5% — one strict-directive retry on miss, then strip the offending sentence. Identical inputs now return identical text via a sha256(snapshot + INDICATOR_VERSION + model + kind) cache in narrative_cache.
v2025.05.sQ12026-05-11Sprint Q1 — Risk-aware insight engine. computeInsights now accepts the 7 risk indicators (heat, air, mobility, streetscape, flood, noise, housing) plus the EconomicImpact band so each emitted insight carries an economicShareEur and the Action Plan ranks interventions by € addressed. Conflict-collapse merges noise + housing + gentrification into a single displacement-pressure cluster.
v2025.04.s_live_heat_air2026-05-10Heat Island (v0.1) + Air Quality (v0.1) — deterministic surrogates swapped for live NASA POWER climatology (heat) and OpenAQ v3 station nearest-neighbour pull (air), cached against the audit centroid. Both gracefully fall back to the v0 surrogate when the live source is unreachable, returns no coverage, or the cache is cold.
v2025.03.s36_12026-05-09Environmental Noise (v0.1) — surrogate Lden / Lnight swapped for live CNOSSOS-EU strategic noise-map sample pulled from the EEA NOISE viewer (END 2017 reporting cycle), cached against the audit isochrone.
v2025.02.s372026-05-09score-affectingHousing Affordability & Displacement Risk (v0) — modeled rent-to-income overshoot above the Eurostat 40% housing-cost-overburden threshold added as 10th €-driver and PDF page 27.
v2025.01.s362026-05-09score-affectingEnvironmental Noise (v0) — modeled Lden overshoot above the WHO 2018 road-traffic guideline added as 9th €-driver and PDF page 26.
v2024.12.s352026-05-09score-affectingFlood & Pluvial Risk (v0) — modeled annual-average pluvial-flood loss intensity (€/resident-yr) added as 8th €-driver and PDF page 25.
v2024.11.s342026-05-09Cross-City Peer Benchmark (v0) — top-5 morphological peers from a 25-city z-space panel, surfaced on /audit and PDF page 24.
v2024.10.s332026-05-09Streetscape Vision layer (v0) — public realm quality 1–5 composite (walkability + tree canopy + façade) added as evidence sub-score and PDF page 23.
v2024.09.s322026-05-09score-affectingMobility Pulse layer (v0) — modeled modal split + car-dependency overshoot vs EU SUMP 40% target added as 7th €-driver and PDF page 22.
v2024.08.s312026-05-09score-affectingAir Quality layer (v0) — PM2.5/NO₂ overshoot vs WHO AQG + attributable mortality added as 6th €-driver and PDF page 21.
v2024.07.s302026-05-09score-affectingHeat Island layer (v0) — UHI anomaly + tropical-night + heat-attributable mortality estimates added as 5th €-driver and PDF page 20.
v2024.06.s292026-05-09Spatial diff — interventions now reshape the isochrone; baseline + scenario reach are persisted per snapshot.
v2024.05.s242026-05-09Defensibility pass — confidence engine, provenance footer, methodology + bibliography appendices baked into every PDF.
v2024.04.s232026-04-22Temporal axis + portfolio view — €-at-stake re-derives without re-running OSM.
v2024.03.s222026-04-08Named intervention catalog — 12 entries with CapEx + lead-time + additive deltas.
v2024.02.s212026-03-25score-affectingMonetize the verdict — Annual Value at Stake module (4 drivers, ±20% bands).
v2024.01.s112026-02-14Public methodology baseline — Moreno, Jacobs, ELR, Diversity, SDG 11.2.1.