@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/lib/gis-sources.js

@@ -0,0 +1,392 @@
+/**
+ * GIS data source metadata — provenance, reliability, and caveats.
+ *
+ * Each GIS tool response includes a `source_metadata` block drawn from
+ * these definitions. The goal is to make data quality and upstream
+ * limitations visible to callers, not hidden behind a clean API surface.
+ */
+export const GIS_SOURCES = {
+    "open-meteo-elevation": {
+        id: "open-meteo-elevation",
+        name: "Open-Meteo Elevation API",
+        provider: "Open-Meteo / Copernicus EU-DEM",
+        licence: "Copernicus Licence (free, attribution required)",
+        url: "https://open-meteo.com/en/docs/elevation-api",
+        api_key_required: false,
+        coverage: "Global (EU-DEM ~30m resolution over Europe)",
+        update_frequency: "Static dataset, updated infrequently",
+        reliability: "high",
+        caveats: [
+            "Resolution is ~30m — fine for site-level screening, not parcel-level",
+            "Slope/aspect derived from a 3x3 grid around the point (Horn's method)",
+            "Urban areas and steep valleys may have elevation artefacts",
+        ],
+        attribution: "Data: Copernicus EU-DEM via Open-Meteo",
+    },
+    "overpass-osm": {
+        id: "overpass-osm",
+        name: "Overpass API (OpenStreetMap)",
+        provider: "OpenStreetMap contributors",
+        licence: "ODbL (Open Data Commons Open Database License)",
+        url: "https://wiki.openstreetmap.org/wiki/Overpass_API",
+        api_key_required: false,
+        coverage: "Global — but completeness varies by region",
+        update_frequency: "Near-real-time (OSM edits propagate within minutes to hours)",
+        reliability: "medium",
+        caveats: [
+            "Public endpoints can be slow or rate-limited under load",
+            "Substation and line tagging is volunteer-maintained — some assets may be missing or incorrectly tagged",
+            "Voltage values are often absent or imprecise for lower-voltage infrastructure",
+            "Three fallback endpoints are used, but all can be degraded simultaneously",
+        ],
+        attribution: "Data: OpenStreetMap contributors (ODbL)",
+    },
+    "natural-england": {
+        id: "natural-england",
+        name: "Natural England Open Data Geoportal",
+        provider: "Natural England / ArcGIS Online",
+        licence: "OGL v3 (Open Government Licence)",
+        url: "https://naturalengland-defra.opendata.arcgis.com/",
+        api_key_required: false,
+        coverage: "England only (not Scotland, Wales, or Northern Ireland)",
+        update_frequency: "Updated periodically — typically monthly to quarterly",
+        reliability: "medium",
+        caveats: [
+            "Covers England only — Scotland (NatureScot) and Wales (NRW) use separate services",
+            "ArcGIS field names and service slugs can change between service versions",
+            "Individual layers may be temporarily unavailable while the service is updated",
+            "Bounding-box queries may return features that only partially intersect the search area",
+        ],
+        attribution: "Contains Natural England data. Contains Ordnance Survey data. Crown copyright and database rights.",
+    },
+    "eea-natura2000": {
+        id: "eea-natura2000",
+        name: "EEA Natura 2000 Protected Sites",
+        provider: "European Environment Agency / ArcGIS REST",
+        licence: "EEA public environmental data access",
+        url: "https://bio.discomap.eea.europa.eu/arcgis/rest/services/ProtectedSites/Natura2000_Dyna_WM/MapServer",
+        api_key_required: false,
+        coverage: "EU Natura 2000 network coverage via EEA protected sites service",
+        update_frequency: "Updated when EEA refreshes Natura 2000 releases",
+        reliability: "medium",
+        caveats: [
+            "Covers Natura 2000 protected sites only, not the full set of national planning designations in each EU country",
+            "Site type codes are simplified into birds or habitats directive groupings for fast screening",
+            "This is a coarse screening layer, not a legal boundary determination or permitting decision",
+            "ArcGIS service structure and field names can change between publishing cycles",
+        ],
+        attribution: "Contains European Environment Agency Natura 2000 protected sites data.",
+    },
+    "natural-england-alc": {
+        id: "natural-england-alc",
+        name: "Natural England Agricultural Land Classification",
+        provider: "Natural England / ArcGIS Online",
+        licence: "OGL v3 (Open Government Licence)",
+        url: "https://naturalengland-defra.opendata.arcgis.com/",
+        api_key_required: false,
+        coverage: "England only, with patchy detailed-survey coverage and provisional fallback",
+        update_frequency: "Updated periodically — typically monthly to quarterly",
+        reliability: "medium",
+        caveats: [
+            "Detailed post-1988 surveys are incomplete, so many locations fall back to provisional ALC",
+            "Provisional Grade 3 does not distinguish 3a from 3b, so BMV status can be uncertain",
+            "England only — there is no equivalent coverage in this tool yet for Scotland, Wales, or Northern Ireland",
+            "ArcGIS field names and service slugs can change between service versions",
+        ],
+        attribution: "Contains Natural England Agricultural Land Classification data. Contains Ordnance Survey data. Crown copyright and database rights.",
+    },
+    "ea-flood-map": {
+        id: "ea-flood-map",
+        name: "Environment Agency Flood Map for Planning",
+        provider: "Environment Agency / DEFRA ArcGIS",
+        licence: "Open Government Licence v3",
+        url: "https://environment.data.gov.uk/dataset/04532375-a198-476e-985e-0579a0a11b47",
+        api_key_required: false,
+        coverage: "England only for Flood Map for Planning layers",
+        update_frequency: "Updated periodically as national and local flood models are refreshed",
+        reliability: "medium",
+        caveats: [
+            "England only — separate services are needed for Scotland, Wales, and Northern Ireland",
+            "Flood Map for Planning is for development screening, not property-level flood advice",
+            "Flood Zone 2 should be interpreted together with Flood Zone 3 and flood storage areas",
+            "ArcGIS service structure and field names can change between publishing cycles",
+        ],
+        attribution: "Contains Environment Agency information licensed under the Open Government Licence v3.0.",
+    },
+    "corine-land-cover": {
+        id: "corine-land-cover",
+        name: "CORINE Land Cover 2018",
+        provider: "European Environment Agency / Copernicus Land Monitoring Service",
+        licence: "Copernicus Land Monitoring Service (free, attribution required)",
+        url: "https://land.copernicus.eu/pan-european/corine-land-cover/clc2018",
+        api_key_required: false,
+        coverage: "EU27 member states plus EEA/EFTA countries. Great Britain not covered (UK withdrew after CLC 2012).",
+        update_frequency: "Static — CLC 2018 is the most recent release; next update expected as CLC 2024",
+        reliability: "high",
+        caveats: [
+            "Minimum mapping unit is 25 hectares — small parcels may not appear",
+            "Great Britain is not covered; use get_agricultural_land for England instead",
+            "Classification is based on 2018 satellite imagery; recent land-use changes will not be reflected",
+            "ArcGIS service structure or field names may change between EEA publishing cycles",
+        ],
+        attribution: "Contains CORINE Land Cover 2018 data from the Copernicus Land Monitoring Service, " +
+            "© European Environment Agency (EEA).",
+    },
+    "neso-gsp-lookup": {
+        id: "neso-gsp-lookup",
+        name: "NESO GSP-Gnode Region Lookup",
+        provider: "National Energy System Operator (NESO)",
+        licence: "NESO Open Data Licence",
+        url: "https://api.neso.energy/dataset/2810092e-d4b2-472f-b955-d8bea01f9ec0",
+        api_key_required: false,
+        coverage: "Great Britain Grid Supply Point regions",
+        update_frequency: "Updated infrequently — GSP boundaries change rarely",
+        reliability: "high",
+        caveats: [
+            "Uses nearest-GSP by haversine distance, not polygon containment — an approximation",
+            "GSP coordinates are centroid-like reference points, not precise boundary anchors",
+            "Some GSP names may not match TEC register connection site names exactly",
+            "Coverage is GB only — does not include Northern Ireland or offshore",
+        ],
+        attribution: "Contains data from the National Energy System Operator (NESO) GSP-Gnode lookup.",
+    },
+    "neso-tec-register": {
+        id: "neso-tec-register",
+        name: "NESO Transmission Entry Capacity Register",
+        provider: "National Energy System Operator (NESO)",
+        licence: "NESO Open Data Licence",
+        url: "https://api.neso.energy/api/3/action/package_show?id=transmission-entry-capacity-tec-register",
+        api_key_required: false,
+        coverage: "Great Britain transmission-level connection register. Covers TEC-holding projects, not the full DNO queue.",
+        update_frequency: "Twice weekly",
+        reliability: "high",
+        caveats: [
+            "Transmission-level signal only — it is not a GB-wide DNO headroom or flexibility map",
+            "Register entries reflect contracted TEC positions and project statuses, not guaranteed connection availability",
+            "Connection site names in the register may not match local substation naming exactly",
+            "Projects can appear multiple times because staged or technology-split agreements are still being refined by NESO",
+        ],
+        attribution: "Contains data from the National Energy System Operator (NESO) TEC register.",
+    },
+    "pvgis": {
+        id: "pvgis",
+        name: "PVGIS (Photovoltaic Geographical Information System)",
+        provider: "European Commission Joint Research Centre",
+        licence: "Free access, no key required",
+        url: "https://re.jrc.ec.europa.eu/pvg_tools/",
+        api_key_required: false,
+        coverage: "Europe, Africa, parts of Asia and Americas",
+        update_frequency: "Updated with new satellite data roughly annually",
+        reliability: "high",
+        caveats: [
+            "Optimal tilt angle sometimes returns 0 for UK latitudes — appears to be a PVGIS default",
+            "Monthly averages are long-term climatological values, not current-year",
+            "Coastal and mountainous sites may differ from the grid-cell average",
+        ],
+        attribution: "Data: PVGIS, European Commission Joint Research Centre",
+    },
+};
+export const GIS_HEALTH_CHECKS = [
+    {
+        source_id: "open-meteo-elevation",
+        url: "https://api.open-meteo.com/v1/elevation?latitude=51.5&longitude=-0.1",
+        method: "GET",
+        timeout_ms: 10_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (!Array.isArray(json.elevation) || json.elevation.length === 0) {
+                    return "Response missing elevation array";
+                }
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "overpass-osm",
+        url: "https://overpass-api.de/api/interpreter",
+        method: "POST",
+        body: `data=${encodeURIComponent('[out:json][timeout:10];node["power"="substation"](around:1000,51.5,-0.1);out count;')}`,
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (!Array.isArray(json.elements)) {
+                    return "Response missing elements array";
+                }
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "natural-england",
+        url: "https://services.arcgis.com/JJzESW51TqeY9uat/arcgis/rest/services/SSSI_England/FeatureServer/0/query?where=1%3D1&resultRecordCount=1&outFields=NAME&returnGeometry=false&f=json",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (json.error)
+                    return `ArcGIS error: ${json.error.message ?? "unknown"}`;
+                if (!Array.isArray(json.features))
+                    return "Response missing features array";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "eea-natura2000",
+        url: "https://bio.discomap.eea.europa.eu/arcgis/rest/services/ProtectedSites/Natura2000_Dyna_WM/MapServer/0/query?where=1%3D1&resultRecordCount=1&outFields=SITECODE%2CSITENAME%2CSITETYPE&returnGeometry=false&f=json",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (json.error)
+                    return `ArcGIS error: ${json.error.message ?? "unknown"}`;
+                if (!Array.isArray(json.features))
+                    return "Response missing features array";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "natural-england-alc",
+        url: "https://services.arcgis.com/JJzESW51TqeY9uat/arcgis/rest/services/Agricultural_Land_Classification_Post_1988/FeatureServer/0/query?where=1%3D1&resultRecordCount=1&outFields=ALC_GRADE&returnGeometry=false&f=json",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (json.error)
+                    return `ArcGIS error: ${json.error.message ?? "unknown"}`;
+                if (!Array.isArray(json.features))
+                    return "Response missing features array";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "corine-land-cover",
+        url: "https://image.discomap.eea.europa.eu/arcgis/rest/services/Corine/CLC2018_WM/MapServer/0/query?geometry=2.35%2C48.85&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=Code_18&returnGeometry=false&resultRecordCount=1&f=json",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (json.error)
+                    return `ArcGIS error: ${json.error.message ?? "unknown"}`;
+                if (!Array.isArray(json.features))
+                    return "Response missing features array";
+                const code = json.features[0]?.attributes?.Code_18;
+                if (typeof code !== "string" || code.length === 0)
+                    return "Response missing Code_18 value";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "ea-flood-map",
+        url: "https://environment.data.gov.uk/KB6uNVj5ZcJr7jUP/ArcGIS/rest/services/Flood_Map_for_Planning/FeatureServer/1/query?where=1%3D1&resultRecordCount=1&outFields=layer,type&returnGeometry=false&f=json",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (json.error)
+                    return `ArcGIS error: ${json.error.message ?? "unknown"}`;
+                if (!Array.isArray(json.features))
+                    return "Response missing features array";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "neso-gsp-lookup",
+        url: "https://api.neso.energy/dataset/2810092e-d4b2-472f-b955-d8bea01f9ec0/resource/bbe2cc72-a6c6-46e6-8f4e-48b879467368/download/gsp_gnode_directconnect_region_lookup.csv",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            if (!body.includes("gsp_id"))
+                return "Response missing gsp_id column header";
+            return null;
+        },
+    },
+    {
+        source_id: "neso-tec-register",
+        url: "https://api.neso.energy/api/3/action/datastore_search?resource_id=17becbab-e3e8-473f-b303-3806f43a6a10&limit=1",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (!json.success)
+                    return json.error?.message ?? "NESO API reported failure";
+                if (!Array.isArray(json.result?.records))
+                    return "Response missing records array";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+    {
+        source_id: "pvgis",
+        url: "https://re.jrc.ec.europa.eu/api/v5_3/PVcalc?lat=51.5&lon=-0.1&peakpower=1&loss=14&outputformat=json",
+        method: "GET",
+        timeout_ms: 15_000,
+        validate: (status, body) => {
+            if (status !== 200)
+                return `HTTP ${status}`;
+            try {
+                const json = JSON.parse(body);
+                if (!json.outputs)
+                    return "Response missing outputs field";
+                return null;
+            }
+            catch {
+                return "Response is not valid JSON";
+            }
+        },
+    },
+];

package/dist/lib/natural-england.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Natural England ArcGIS REST API client for querying GB protected area layers.
+ *
+ * Queries the Natural England Open Data Geoportal (ArcGIS Online hosted feature services)
+ * for environmental designations: SSSIs, SACs, SPAs, Ramsar sites, National Parks, and AONBs.
+ *
+ * All endpoints are free, require no API key, and are published under OGL v3.
+ * Attribution: © Natural England copyright. Contains Ordnance Survey data © Crown copyright.
+ */
+export interface ConstraintLayerConfig {
+    readonly slug: string;
+    readonly constraintType: string;
+    readonly nameField: string;
+    readonly areaField: string | null;
+}
+export declare const GB_PROTECTED_AREA_LAYERS: readonly ConstraintLayerConfig[];
+export interface ConstraintFeature {
+    name: string;
+    type: string;
+    area_ha: number | null;
+    source: string;
+}
+/**
+ * Query a single Natural England ArcGIS feature layer for protected areas
+ * intersecting a bounding box around the given point.
+ */
+export declare function queryLayer(layer: ConstraintLayerConfig, lat: number, lon: number, radiusKm: number): Promise<ConstraintFeature[]>;

package/dist/lib/natural-england.js

@@ -0,0 +1,105 @@
+/**
+ * Natural England ArcGIS REST API client for querying GB protected area layers.
+ *
+ * Queries the Natural England Open Data Geoportal (ArcGIS Online hosted feature services)
+ * for environmental designations: SSSIs, SACs, SPAs, Ramsar sites, National Parks, and AONBs.
+ *
+ * All endpoints are free, require no API key, and are published under OGL v3.
+ * Attribution: © Natural England copyright. Contains Ordnance Survey data © Crown copyright.
+ */
+import { guardArcGisFields } from "./schema-guard.js";
+const NE_ARCGIS_BASE = "https://services.arcgis.com/JJzESW51TqeY9uat/arcgis/rest/services";
+export const GB_PROTECTED_AREA_LAYERS = [
+    {
+        slug: "SSSI_England",
+        constraintType: "sssi",
+        nameField: "NAME",
+        areaField: "MEASURE",
+    },
+    {
+        slug: "Special_Areas_of_Conservation_England",
+        constraintType: "sac",
+        nameField: "SAC_NAME",
+        areaField: "SAC_AREA",
+    },
+    {
+        slug: "Special_Protection_Areas_England",
+        constraintType: "spa",
+        nameField: "SPA_NAME",
+        areaField: "SPA_AREA",
+    },
+    {
+        slug: "Ramsar_England",
+        constraintType: "ramsar",
+        nameField: "NAME",
+        areaField: "AREA",
+    },
+    {
+        slug: "National_Parks_England",
+        constraintType: "national_park",
+        nameField: "NAME",
+        areaField: "MEASURE",
+    },
+    {
+        slug: "Areas_of_Outstanding_Natural_Beauty_England",
+        constraintType: "aonb",
+        nameField: "NAME",
+        areaField: "STAT_AREA",
+    },
+];
+/**
+ * Build a WGS84 bounding box string from a point and radius.
+ * Returns "xmin,ymin,xmax,ymax" suitable for ArcGIS REST envelope queries.
+ */
+function buildEnvelopeGeometry(lat, lon, radiusKm) {
+    const latDelta = radiusKm / 111.32;
+    const lonDelta = radiusKm / (111.32 * Math.cos(lat * (Math.PI / 180)));
+    return `${lon - lonDelta},${lat - latDelta},${lon + lonDelta},${lat + latDelta}`;
+}
+/**
+ * Query a single Natural England ArcGIS feature layer for protected areas
+ * intersecting a bounding box around the given point.
+ */
+export async function queryLayer(layer, lat, lon, radiusKm) {
+    const base = `${NE_ARCGIS_BASE}/${layer.slug}/FeatureServer/0/query`;
+    const url = new URL(base);
+    const p = url.searchParams;
+    p.set("where", "1=1");
+    p.set("geometry", buildEnvelopeGeometry(lat, lon, radiusKm));
+    p.set("geometryType", "esriGeometryEnvelope");
+    p.set("inSR", "4326");
+    p.set("spatialRel", "esriSpatialRelIntersects");
+    const fields = [layer.nameField];
+    if (layer.areaField)
+        fields.push(layer.areaField);
+    p.set("outFields", fields.join(","));
+    p.set("returnGeometry", "false");
+    p.set("resultRecordCount", "20");
+    p.set("f", "json");
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Natural England API returned ${response.status} for ${layer.constraintType}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`Natural England API error for ${layer.constraintType}: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const features = json.features ?? [];
+    const expectedFields = [layer.nameField];
+    if (layer.areaField)
+        expectedFields.push(layer.areaField);
+    guardArcGisFields(features, expectedFields, `Natural England ${layer.constraintType.toUpperCase()}`);
+    return features.map((f) => {
+        const attrs = f.attributes ?? {};
+        const areaRaw = layer.areaField ? attrs[layer.areaField] : null;
+        return {
+            name: String(attrs[layer.nameField] ?? "Unknown"),
+            type: layer.constraintType,
+            area_ha: typeof areaRaw === "number" ? Math.round(areaRaw * 100) / 100 : null,
+            source: "natural-england",
+        };
+    });
+}

package/dist/lib/neso-gsp.d.ts

@@ -0,0 +1,18 @@
+export interface GspRegion {
+    gsp_id: string;
+    gsp_name: string;
+    region_id: string;
+    region_name: string;
+}
+export interface GspLookupResult extends GspRegion {
+    distance_km: number;
+}
+/**
+ * Find the nearest GSP to a given lat/lon using haversine distance.
+ * Returns the nearest GSP within `radiusKm` (default 50), or null if none found.
+ *
+ * This is a nearest-GSP approximation, not polygon containment.
+ */
+export declare function lookupGspRegion(lat: number, lon: number, radiusKm?: number): Promise<GspLookupResult | null>;
+/** Reset cache — exposed for tests. */
+export declare function resetGspCacheForTests(): void;

package/dist/lib/neso-gsp.js

@@ -0,0 +1,113 @@
+import { TtlCache, TTL } from "./cache.js";
+const cache = new TtlCache();
+const NESO_GSP_CSV_URL = "https://api.neso.energy/dataset/2810092e-d4b2-472f-b955-d8bea01f9ec0/resource/bbe2cc72-a6c6-46e6-8f4e-48b879467368/download/gsp_gnode_directconnect_region_lookup.csv";
+const CACHE_KEY = "neso-gsp-lookup:csv";
+const DEFAULT_RADIUS_KM = 50;
+/** Haversine distance in km between two WGS84 points. */
+function haversineKm(lat1, lon1, lat2, lon2) {
+    const R = 6371;
+    const dLat = (lat2 - lat1) * (Math.PI / 180);
+    const dLon = (lon2 - lon1) * (Math.PI / 180);
+    const a = Math.sin(dLat / 2) ** 2 +
+        Math.cos(lat1 * (Math.PI / 180)) *
+            Math.cos(lat2 * (Math.PI / 180)) *
+            Math.sin(dLon / 2) ** 2;
+    return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/**
+ * Parse the NESO GSP-Gnode lookup CSV into structured records.
+ * Expects columns including: gsp_id, gsp_name, gsp_lat, gsp_lon, region_id, region_name.
+ * Column order is detected from the header row.
+ */
+function parseCsv(csvText) {
+    const lines = csvText.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    if (lines.length < 2)
+        return [];
+    const headers = lines[0].split(",").map((h) => h.trim().toLowerCase());
+    const colIndex = (name) => {
+        const idx = headers.indexOf(name);
+        return idx;
+    };
+    const iGspId = colIndex("gsp_id");
+    const iGspName = colIndex("gsp_name");
+    const iGspLat = colIndex("gsp_lat");
+    const iGspLon = colIndex("gsp_lon");
+    const iRegionId = colIndex("region_id");
+    const iRegionName = colIndex("region_name");
+    if (iGspId === -1 || iGspName === -1 || iGspLat === -1 || iGspLon === -1) {
+        throw new Error("NESO GSP CSV missing required columns. Expected: gsp_id, gsp_name, gsp_lat, gsp_lon. " +
+            `Found headers: ${headers.join(", ")}`);
+    }
+    const records = [];
+    const seen = new Set();
+    for (let i = 1; i < lines.length; i++) {
+        const cols = lines[i].split(",").map((c) => c.trim());
+        const gspId = cols[iGspId] ?? "";
+        const gspName = cols[iGspName] ?? "";
+        const lat = parseFloat(cols[iGspLat] ?? "");
+        const lon = parseFloat(cols[iGspLon] ?? "");
+        if (!gspId || Number.isNaN(lat) || Number.isNaN(lon))
+            continue;
+        // Deduplicate by gsp_id (multiple gnodes can map to the same GSP)
+        if (seen.has(gspId))
+            continue;
+        seen.add(gspId);
+        records.push({
+            gsp_id: gspId,
+            gsp_name: gspName,
+            lat,
+            lon,
+            region_id: iRegionId !== -1 ? (cols[iRegionId] ?? "") : "",
+            region_name: iRegionName !== -1 ? (cols[iRegionName] ?? "") : "",
+        });
+    }
+    return records;
+}
+async function fetchGspRecords() {
+    const cached = cache.get(CACHE_KEY);
+    if (cached)
+        return cached;
+    const response = await fetch(NESO_GSP_CSV_URL);
+    if (!response.ok) {
+        throw new Error(`NESO GSP lookup CSV fetch failed: HTTP ${response.status}`);
+    }
+    const csvText = await response.text();
+    const records = parseCsv(csvText);
+    if (records.length === 0) {
+        throw new Error("NESO GSP lookup CSV returned no valid records");
+    }
+    cache.set(CACHE_KEY, records, TTL.STATIC_DATA);
+    return records;
+}
+/**
+ * Find the nearest GSP to a given lat/lon using haversine distance.
+ * Returns the nearest GSP within `radiusKm` (default 50), or null if none found.
+ *
+ * This is a nearest-GSP approximation, not polygon containment.
+ */
+export async function lookupGspRegion(lat, lon, radiusKm = DEFAULT_RADIUS_KM) {
+    const records = await fetchGspRecords();
+    let nearest = null;
+    let nearestDist = Infinity;
+    for (const record of records) {
+        const dist = haversineKm(lat, lon, record.lat, record.lon);
+        if (dist < nearestDist) {
+            nearestDist = dist;
+            nearest = record;
+        }
+    }
+    if (!nearest || nearestDist > radiusKm) {
+        return null;
+    }
+    return {
+        gsp_id: nearest.gsp_id,
+        gsp_name: nearest.gsp_name,
+        region_id: nearest.region_id,
+        region_name: nearest.region_name,
+        distance_km: Math.round(nearestDist * 100) / 100,
+    };
+}
+/** Reset cache — exposed for tests. */
+export function resetGspCacheForTests() {
+    cache.clear();
+}

package/dist/lib/overpass.d.ts

@@ -0,0 +1,13 @@
+/** Exposed for testing only. */
+export declare function _getOverpassState(): Readonly<{
+    windowTimestamps: readonly number[];
+    inFlight: number;
+    queueLength: number;
+    maxConcurrent: number;
+    maxPerWindow: number;
+    windowMs: number;
+    requestTimeoutMs: number;
+}>;
+/** Exposed for testing: reset internal state between test runs. */
+export declare function _resetOverpassState(): void;
+export declare function fetchOverpassJson<T>(query: string): Promise<T>;