@cenogram/mcp-server 0.5.0 → 0.11.0

package/dist/formatters.js

@@ -254,7 +254,7 @@ export function formatMarketOverview(stats) {
 export function formatPriceStats(rows, location) {
     if (rows.length === 0) {
         return location
-            ? `No price statistics found for "${location}". Note: this endpoint only covers residential units (apartments). Use list_locations to find valid location names.`
+            ? `No price statistics found for "${location}". Note: this endpoint only covers residential units (apartments), and matches on name only. Call list_locations(search=...) to confirm the name is a valid RCN district (rcn_district).`
             : "No price statistics available.";
     }
     const header = location
@@ -291,7 +291,7 @@ export function formatHistogram(bins) {
 }
 export function formatParcelResults(res, query) {
     if (res.results.length === 0) {
-        return `No parcels found matching "${query}".`;
+        return `No parcels found matching "${query}". This searches the parcels we hold, which are near-complete coverage of the cadastral register rather than the whole of it, so a miss is more likely a recent change or a mistyped prefix than evidence that no such parcel exists — ${CORPUS_COVERAGE_HINT}${formatCorpusCoverage(res.corpus_coverage)}`;
     }
     const lines = [`Found ${res.results.length} parcels matching "${query}":\n`];
     for (const [i, p] of res.results.entries()) {
@@ -301,11 +301,180 @@ export function formatParcelResults(res, query) {
         lines.push(`${i + 1}. ${p.parcel_id ?? "(parcel number requires a paid plan)"}`);
         lines.push(`   District: ${district} | Area: ${area} | Location: ${location}`);
     }
+    return lines.join("\n") + formatCorpusCoverage(res.corpus_coverage);
+}
+const PARCEL_IDENTITY_WITHHELD = "(parcel number requires a paid plan)";
+const CORPUS_COVERAGE_HINT = "looking the parcel up by its FULL cadastral id (resolve_parcel) goes down a different path that can confirm and add a parcel we do not yet hold.";
+const COVERAGE_UNMEASURED_FALLBACK = "we hold near-complete coverage of the cadastral register, though not the whole of it and not live, " +
+    "and how much of it this query covers is not measured. Read the answer above as what we hold, not " +
+    "as what is there.";
+function finiteOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function coverageScopeLabel(counties) {
+    if (counties === 1)
+        return "this county";
+    if (counties != null && counties > 1)
+        return `these ${counties.toLocaleString("en-US")} counties`;
+    return "the counties this query addresses";
+}
+function coveragePctLabel(held, source, reported) {
+    const exact = (held / source) * 100;
+    if (held > 0 && exact < 0.05)
+        return "<0.1%";
+    if (held < source && exact >= 99.95)
+        return ">99.9%";
+    return `${(reported ?? exact).toFixed(1)}%`;
+}
+export function formatCorpusCoverage(cov) {
+    if (!cov)
+        return "";
+    const asOf = typeof cov.as_of === "string" ? cov.as_of.split("T")[0] : null;
+    const held = finiteOrNull(cov.held_parcels);
+    const source = finiteOrNull(cov.source_parcels);
+    if (held != null && source != null && source > 0) {
+        if (held >= source)
+            return "";
+        const scope = coverageScopeLabel(finiteOrNull(cov.counties));
+        const pct = coveragePctLabel(held, source, finiteOrNull(cov.held_pct));
+        const stamp = asOf ? `, measured ${asOf}` : "";
+        return `\n\nCOVERAGE: we hold ${held.toLocaleString("en-US")} of the ${source.toLocaleString("en-US")} parcels the cadastral register lists for ${scope} (${pct}${stamp}). A short or empty list above reflects that, not the land.`;
+    }
+    const note = typeof cov.note === "string" && cov.note.trim().length > 0
+        ? cov.note.trim()
+        : COVERAGE_UNMEASURED_FALLBACK;
+    const stamp = asOf ? ` Our latest coverage measurement is dated ${asOf}.` : "";
+    return `\n\nCOVERAGE: ${note}${stamp}`;
+}
+function collectPositions(node, out) {
+    if (!Array.isArray(node))
+        return;
+    if (node.length >= 2 && typeof node[0] === "number" && typeof node[1] === "number") {
+        out.push([node[0], node[1]]);
+        return;
+    }
+    for (const child of node)
+        collectPositions(child, out);
+}
+function outlineCentre(geometry) {
+    if (!geometry)
+        return null;
+    const positions = [];
+    collectPositions(geometry.coordinates, positions);
+    if (positions.length === 0)
+        return null;
+    let minLng = Infinity, maxLng = -Infinity, minLat = Infinity, maxLat = -Infinity;
+    for (const [lng, lat] of positions) {
+        if (lng < minLng)
+            minLng = lng;
+        if (lng > maxLng)
+            maxLng = lng;
+        if (lat < minLat)
+            minLat = lat;
+        if (lat > maxLat)
+            maxLat = lat;
+    }
+    return { lat: (minLat + maxLat) / 2, lng: (minLng + maxLng) / 2 };
+}
+function formatParcelAddress(p) {
+    if (p.street == null || p.street === "")
+        return null;
+    const approx = p.address_source === "approx_high" || p.address_source === "approx_low";
+    const tag = approx ? " [street approximate — derived, not from the record]" : "";
+    return [p.street, p.building_number].filter(Boolean).join(" ") + tag;
+}
+export function formatParcelList(res, scope, creditsRefunded = false) {
+    if (res.data.length === 0) {
+        const lines = [
+            `No parcels found for ${scope}. The filter is valid; nothing matched it AMONG THE PARCELS WE HOLD, which are near-complete coverage of the cadastral register rather than the whole of it. So this is not evidence that the area has no parcels.`,
+        ];
+        if (creditsRefunded)
+            lines.push("The tokens for this call were refunded — an unmatched street page costs nothing.");
+        const streets = res.suggestions?.streets ?? [];
+        const numbers = res.suggestions?.building_numbers ?? [];
+        if (streets.length > 0) {
+            lines.push("Close street names on record here — matching is case- and accent-insensitive but does not inflect, so retry with one of these, each a ready next call:");
+            for (const s of streets)
+                lines.push(`  - street="${s}"`);
+        }
+        if (numbers.length > 0) {
+            lines.push("The street is on record but that number is not; these are the numbers held on it, in the compound form the register uses — retry with one of them:");
+            for (const n of numbers)
+                lines.push(`  - buildingNumber="${n}"`);
+        }
+        if (streets.length === 0 && numbers.length === 0) {
+            lines.push("Widening the area or dropping a surface filter is the next step.");
+        }
+        lines.push(CORPUS_COVERAGE_HINT);
+        return lines.join("\n") + formatCorpusCoverage(res.corpus_coverage);
+    }
+    const lines = [`Found ${res.data.length} parcel${res.data.length === 1 ? "" : "s"} for ${scope}:\n`];
+    for (const [i, p] of res.data.entries()) {
+        const district = p.district ?? "Unknown";
+        const location = p.lat != null && p.lng != null
+            ? `${p.lat.toFixed(4)}°N, ${p.lng.toFixed(4)}°E`
+            : "no outline held";
+        lines.push(`${i + 1}. ${p.parcel_id ?? PARCEL_IDENTITY_WITHHELD}`);
+        lines.push(`   District: ${district} | Location: ${location}`);
+        const address = formatParcelAddress(p);
+        if (address)
+            lines.push(`   Address: ${address}`);
+    }
+    if (res.pagination.has_more && res.pagination.next_cursor) {
+        lines.push(`\nMore parcels match than are shown. Pass cursor="${res.pagination.next_cursor}" to get the next page (the value is opaque — pass it back unchanged).`);
+    }
+    else if (res.pagination.has_more) {
+        lines.push(`\nMore parcels match than are shown, but no cursor came back — narrow the filter instead of paging.`);
+    }
+    lines.push(`\nNo outline and no surface on these rows: call list_parcels_in_area with includeGeometry=true (or a polygon) for outlines, or get_parcel_report for one parcel in full.`);
+    return lines.join("\n") + formatCorpusCoverage(res.corpus_coverage);
+}
+export function formatStreetList(res, q, scope) {
+    if (res.data.length === 0) {
+        return `No street name in ${scope} matches "${q}". The scope is valid and nothing we hold there contains that fragment — two different things can put you here, and this answer cannot tell them apart:\n`
+            + `  1. We hold no street addresses in this area at all. Coverage follows the addresses themselves and is thin outside towns, so rural parcels are often there while their streets are not — for one of those, resolve_parcel with the precinct name and the parcel number is the way in, not a street.\n`
+            + `  2. There is genuinely no such street here.\n`
+            + `Matching is case- and accent-insensitive but does not inflect, so pass the name in the nominative ('karmelicka' or 'Karmelicką' both find 'Karmelicka', but 'Karmelickiej' does not).`;
+    }
+    const lines = [
+        `${res.data.length} street name${res.data.length === 1 ? "" : "s"} in ${scope} matching "${q}":\n`,
+    ];
+    for (const row of res.data) {
+        const tag = row.address_source === "approx" ? " [approximate — derived, not from the record]" : "";
+        lines.push(`  - ${row.street}${tag}`);
+    }
+    lines.push("\nUntagged names are on record; tagged ones we worked out for parcels the record left without a street. " +
+        "Any of these can be passed to list_parcels_in_area as street= inside the same scope.");
+    if (res.pagination.has_more) {
+        lines.push(`More names match than are shown (the answer is capped at ${res.pagination.limit}). Type more of the name — there is no second page.`);
+    }
     return lines.join("\n");
 }
+export function formatParcelFeatures(res, scope) {
+    if (res.features.length === 0) {
+        return `No parcels found in ${scope}. The area is valid and holds no parcel WE CAN PLACE THERE — coverage is near-complete but not the whole cadastral register and not live, so read this as "we have nothing mapped here", not as "there is nothing here". ${CORPUS_COVERAGE_HINT}${formatCorpusCoverage(res.corpus_coverage)}`;
+    }
+    const lines = [`Found ${res.features.length} parcel${res.features.length === 1 ? "" : "s"} in ${scope}:`];
+    if (res.truncated) {
+        lines.push(`TRUNCATED — more of the parcels we hold match than the limit returns, and the ones below are an arbitrary subset, not the first, nearest or largest. Read this as a sample of the area, never as its parcel list. A smaller area returns everything WE HOLD there, which is not the same as every parcel there: coverage is near-complete but not the whole cadastral register and not live.`);
+    }
+    lines.push("");
+    for (const [i, f] of res.features.entries()) {
+        const district = f.properties.district ?? "Unknown";
+        const centre = outlineCentre(f.geometry);
+        const where = centre ? `${centre.lat.toFixed(4)}°N, ${centre.lng.toFixed(4)}°E` : "unknown";
+        lines.push(`${i + 1}. ${f.properties.parcel_id ?? PARCEL_IDENTITY_WITHHELD}`);
+        lines.push(`   District: ${district} | Outline centre: ${where}`);
+        lines.push(`   Outline (GeoJSON, WGS84): ${f.geometry ? JSON.stringify(f.geometry) : "not returned"}`);
+    }
+    return lines.join("\n") + formatCorpusCoverage(res.corpus_coverage);
+}
 export function formatParcelResolve(res) {
+    if (res.coverage === "not_computed") {
+        return "The lookup could not be completed, so this says nothing about whether the parcel exists (the credit is refunded). Best next step: pass the full cadastral id in parcelId — that path does not go through the name at all. A retry helps only if a live confirmation timed out; it will not change the answer for a name carried by very many precincts.";
+    }
     if (res.coverage === "not_covered" || res.matches.length === 0) {
-        return "No parcel matched. The identifier or 'name + number' is not in our cadastral copy (the credit is refunded). Check the spelling of the locality name, or use search_parcels to look up a parcel id by prefix.";
+        return "No parcel matched (the credit is refunded). Two different causes, and with near-complete coverage the first is now the common one: the name may be spelled differently than the register spells it (for 'name + number' it is matched against the gmina name and the cadastral precinct (obręb) name, exactly), OR we do not hold the parcel — coverage is near-complete but not the whole cadastral register and not live, so a discovery lookup can still miss a parcel that exists. This is not a confirmation that the parcel does not exist. Passing the FULL cadastral id in parcelId goes down a different path that can confirm and add a parcel we do not yet hold." + formatCorpusCoverage(res.corpus_coverage);
     }
     const lines = [`Found ${res.matches.length} parcel${res.matches.length === 1 ? "" : "s"}:\n`];
     for (const [i, m] of res.matches.entries()) {
@@ -322,7 +491,8 @@ export function formatParcelResolve(res) {
     if (res.as_of) {
         lines.push(`\nCadastral copy as of ${res.as_of.split("T")[0]}.`);
     }
-    return lines.join("\n");
+    lines.push(`\nQuery cost: 0 API tokens — resolving a parcel is free.`);
+    return lines.join("\n") + formatCorpusCoverage(res.corpus_coverage);
 }
 function formatSpatialFeature(f) {
     return formatTransactionCore({
@@ -355,6 +525,37 @@ export function formatSpatialResults(res) {
     }
     return lines.join("\n");
 }
+export function formatBuildingAge(age) {
+    if (age == null)
+        return "";
+    const works = age.last_works_year != null ? `; later works ${age.last_works_year}` : "";
+    const clause = (body) => `construction year not established: ${body}${works}`;
+    switch (age.status) {
+        case "estimated": {
+            if (age.year_from == null || age.year_to == null) {
+                return clause("an estimate came back without the interval it has to carry, so there is no honest year to state");
+            }
+            const range = age.year_from === age.year_to ? `${age.year_from}` : `${age.year_from}-${age.year_to}`;
+            const point = age.year_point != null ? `, point estimate ~${age.year_point} (least certain)` : "";
+            const conf = age.confidence ? `, ${age.confidence} confidence in the permit match (not in the year)` : "";
+            return `built range ${range}${point} [estimate from permit records, not a registry date${conf}]${works}`;
+        }
+        case "older_than_register":
+            return clause("no construction record for this land falls inside our coverage, which starts in 2016 — the works may predate it, or the land may have been renumbered since");
+        case "ambiguous_permits":
+        case "ambiguous_buildings":
+        case "ambiguous_both":
+            return clause("construction records for this land could not be tied to this specific building");
+        case "no_parcel_key":
+            return clause("this land has no cadastral identifier to match records against");
+        case "not_applicable":
+            return clause("this building has no outline we can place on the land");
+        case "not_computed":
+            return clause("the lookup could not be completed for this request — retrying later may return one");
+        default:
+            return clause("the answer came back in a form this client version does not recognise — a newer client may be able to state it");
+    }
+}
 export function formatBuildingBreakdown(res) {
     const { data, truncated } = res;
     if (data.length === 0) {
@@ -380,6 +581,9 @@ export function formatBuildingBreakdown(res) {
         }
         if (b.match_confidence)
             cells.push(`match confidence: ${b.match_confidence}`);
+        const age = formatBuildingAge(b.age_estimate);
+        if (age)
+            cells.push(age);
         lines.push(`${i + 1}. ${cells.join(" | ")}`);
     });
     if (truncated) {
@@ -498,6 +702,155 @@ export function formatLandslideBreakdown(res) {
     lines.push("", "Note: based on official landslide-hazard maps (1:10,000 scale). An intersection means the parcel overlaps a mapped hazard area, not that the parcel itself is a landslide.");
     return lines.join("\n");
 }
+const PROTECTION_RANK_LABEL = {
+    1: "national park",
+    2: "nature reserve",
+    3: "Natura 2000",
+    4: "landscape park",
+    5: "protected landscape",
+    6: "a minor protection form, or a buffer zone",
+};
+const BUILDING_RESTRICTION_NOTE = {
+    statutory_ban: "a build ban that follows directly from the Nature Protection Act (national parks and reserves), with statutory exceptions — not a ruling on any specific project",
+    conditional: "no blanket statutory ban; restrictions depend on the act that established the area",
+};
+const NATURE_EMPTY_MESSAGE = {
+    covered_no_data: "No forest within 2 km and no protected natural area overlaps this transaction's parcels (or the id was not found). An empty result is never a statement that building is allowed — this layer does not cover local zoning plans, planning-permission decisions or areas under designation.",
+    not_covered: "This layer holds no nature reference data for these parcels yet, so nothing was checked. That is NOT a finding that there is no forest nearby and no protected natural area here — it means the check could not be made. The credit for this call is refunded; try again later.",
+    unknown: "No forest or protected-area signal was returned for this transaction's parcels. This response does not distinguish 'checked, nothing found' from 'not checked' (the id may also be unknown), so do not read it as a finding that there is no forest or protected area — and never as a statement that building is allowed.",
+};
+export function formatNatureBreakdown(res) {
+    const { data, truncated } = res;
+    if (data.length === 0) {
+        const key = res.coverage === "covered_no_data" || res.coverage === "not_covered" ? res.coverage : "unknown";
+        return NATURE_EMPTY_MESSAGE[key];
+    }
+    const lines = [
+        `Per-parcel nature breakdown (${data.length} parcel${data.length === 1 ? "" : "s"} with a forest or protected-area signal):`,
+        "",
+    ];
+    data.forEach((r, i) => {
+        const cells = [];
+        const dist = r.forest_distance_m != null ? Number(r.forest_distance_m) : null;
+        if (dist != null && Number.isFinite(dist)) {
+            if (dist === 0) {
+                const ov = r.forest_overlap_pct != null ? Number(r.forest_overlap_pct) : null;
+                cells.push(`forest: overlaps the parcel${ov != null && Number.isFinite(ov) ? ` (${Math.round(ov)}% of area)` : ""}`);
+            }
+            else {
+                cells.push(`forest: ${dist} m away`);
+            }
+        }
+        if (r.protection_rank != null) {
+            const label = PROTECTION_RANK_LABEL[r.protection_rank] ?? `protection rank ${r.protection_rank}`;
+            cells.push(`protection: ${label}`);
+            if (r.building_restriction) {
+                const note = BUILDING_RESTRICTION_NOTE[r.building_restriction];
+                cells.push(`build restriction: ${r.building_restriction}${note ? ` (${note})` : ""}`);
+            }
+            if (r.protected_overlap_pct != null) {
+                const p = Number(r.protected_overlap_pct);
+                if (Number.isFinite(p))
+                    cells.push(`${Math.round(p)}% of the parcel under protection`);
+            }
+            if (Array.isArray(r.protected_areas) && r.protected_areas.length > 0) {
+                const labels = r.protected_areas.map((a) => a.name ?? a.form).filter((x) => !!x);
+                if (labels.length > 0)
+                    cells.push(`areas: ${labels.join("; ")}`);
+            }
+        }
+        lines.push(`${i + 1}. ${cells.join(" | ")}`);
+    });
+    if (truncated) {
+        lines.push("", "Showing the first 500 parcels (the transaction is linked to more).");
+    }
+    lines.push("", "Note: forest_distance_m is the nearest forest within 2 km (0 = the parcel overlaps forest). building_restriction names the SOURCE of the restriction (statute vs the act that established the area), not the outcome of any permitting case; an empty result is never a statement that building is allowed — this layer does not cover local zoning plans, planning-permission decisions or areas under designation. A buffer zone around a park or reserve IS reported, as form 'buffer_zone' at rank 6, and never as a statutory ban. Forest coverage is mainly publicly-managed land, so private forests may be incomplete.");
+    return lines.join("\n");
+}
+const MINERAL_CLASS_NOTE = {
+    subsidence: "extraction with surface deformation — the actual mining-damage risk",
+    surface: "open-pit working — mostly local impact (neighbourhood, noise)",
+    fluid: "borehole extraction — usually no surface deformation, but a concession and zones still apply",
+    other: "mineral not classified",
+};
+const SUBSURFACE_NOTE = "Note: a mining terrain is a legally defined zone of anticipated mining influence; its mapped location is approximate — an intersection is an advisory signal to verify with the competent mining-supervision authority (named per terrain as the oversight authority), not a legal determination. Some terrains with status 'active' carry a valid_until already in the past, because the register entry can lag behind the expiry of a concession. A groundwater reservoir's extent alone imposes NO restriction; a restriction would come only from an established protection zone, which is not published here. Absence of a match is never asserted as 'safe': the mining register covers concession areas, so historic or shallow workings may not appear, and an absent reservoir does not mean there is no groundwater beneath the parcel.";
+function subsurfacePct(v) {
+    if (v == null)
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? Math.round(n) : null;
+}
+export function formatSubsurfaceBreakdown(res) {
+    const { data, truncated } = res;
+    if (data.length === 0) {
+        return "No mapped mining terrain or major groundwater reservoir overlaps this transaction's parcels (or the id was not found). Absence of mapped data is never asserted as 'safe' — the mining register covers concession areas, so historic or shallow workings may not appear.";
+    }
+    const lines = [
+        `Per-parcel subsurface breakdown (${data.length} parcel${data.length === 1 ? "" : "s"} overlapping a mining terrain or a major groundwater reservoir):`,
+        "",
+    ];
+    let n = 0;
+    for (const r of data) {
+        const cells = [];
+        if (r.mining_status) {
+            const cls = r.mineral_class ?? null;
+            const clsNote = cls ? MINERAL_CLASS_NOTE[cls] : undefined;
+            const pct = subsurfacePct(r.mining_overlap_pct);
+            cells.push(`mining terrain: ${r.mining_status}${cls ? `, ${cls}${clsNote ? ` (${clsNote})` : ""}` : ""}${pct != null ? `, ${pct}% of the parcel in the terrain` : ""}`);
+            if (Array.isArray(r.mining_terrains) && r.mining_terrains.length > 0) {
+                const labels = r.mining_terrains
+                    .map((t) => {
+                    const parts = [];
+                    if (t.name)
+                        parts.push(t.name);
+                    if (t.oversight_authority)
+                        parts.push(`oversight: ${t.oversight_authority}`);
+                    if (t.valid_until)
+                        parts.push(`valid until ${t.valid_until}`);
+                    if (t.revoked_on)
+                        parts.push(`revoked ${t.revoked_on}`);
+                    return parts.length > 0 ? parts.join(", ") : null;
+                })
+                    .filter((s) => !!s);
+                if (labels.length > 0)
+                    cells.push(`terrains: ${labels.join("; ")}${r.mining_terrains_capped ? " (list reached the 5-entry cap)" : ""}`);
+            }
+        }
+        if (r.groundwater_status) {
+            const pct = subsurfacePct(r.groundwater_overlap_pct);
+            cells.push(`groundwater reservoir: ${r.groundwater_status} (reservoir extent only — not a restriction)${pct != null ? `, ${pct}% of the parcel in the reservoir` : ""}`);
+            if (Array.isArray(r.groundwater_bodies) && r.groundwater_bodies.length > 0) {
+                const labels = r.groundwater_bodies
+                    .map((b) => {
+                    const parts = [];
+                    if (b.number != null)
+                        parts.push(`no. ${b.number}`);
+                    if (b.name)
+                        parts.push(b.name);
+                    if (b.documented_year != null)
+                        parts.push(`documented ${b.documented_year}`);
+                    if (b.depth_from_m != null)
+                        parts.push(`from ${b.depth_from_m} m`);
+                    if (b.medium_type)
+                        parts.push(b.medium_type);
+                    return parts.length > 0 ? parts.join(", ") : null;
+                })
+                    .filter((s) => !!s);
+                if (labels.length > 0)
+                    cells.push(`reservoirs: ${labels.join("; ")}${r.groundwater_bodies_capped ? " (list reached the 5-entry cap)" : ""}`);
+            }
+        }
+        if (cells.length === 0)
+            continue;
+        n += 1;
+        lines.push(`${n}. ${cells.join(" | ")}`);
+    }
+    if (truncated) {
+        lines.push("", "Showing the first 500 parcels (the transaction is linked to more).");
+    }
+    lines.push("", SUBSURFACE_NOTE);
+    return lines.join("\n");
+}
 const SURROUNDINGS_CATEGORIES = [
     { key: "cemetery_distance_m", label: "cemetery", radiusLabel: "1 km" },
     { key: "landfill_distance_m", label: "landfill (waste disposal)", radiusLabel: "3 km" },
@@ -505,6 +858,8 @@ const SURROUNDINGS_CATEGORIES = [
     { key: "industrial_area_distance_m", label: "industrial/storage area", radiusLabel: "1 km" },
     { key: "industrial_plant_distance_m", label: "large industrial plant", radiusLabel: "3 km" },
     { key: "livestock_farm_distance_m", label: "intensive livestock farm", radiusLabel: "3 km" },
+    { key: "power_line_hv_distance_m", label: "high-voltage overhead power line", radiusLabel: "1 km" },
+    { key: "power_line_ehv_distance_m", label: "extra-high-voltage overhead power line", radiusLabel: "1 km" },
 ];
 export function formatSurroundings(res) {
     const { data, truncated } = res;
@@ -520,7 +875,7 @@ export function formatSurroundings(res) {
             lines.push(`${i + 1}. not assessed yet — this plot has not been evaluated (no statement either way)`);
             return;
         }
-        const cells = SURROUNDINGS_CATEGORIES.map(({ key, label, radiusLabel }) => {
+        const cells = SURROUNDINGS_CATEGORIES.filter(({ key }) => key in r).map(({ key, label, radiusLabel }) => {
             const raw = r[key];
             const dist = raw == null ? null : Number(raw);
             if (dist == null || !Number.isFinite(dist)) {
@@ -537,6 +892,64 @@ export function formatSurroundings(res) {
     }
     return lines.join("\n");
 }
+const ROADS_NOTE = "Note: access_indicator is geometric evidence measured from carriageway centrelines in reference road-network data. It does NOT determine legal access and says nothing about easements or rights of way, which are recorded in the land register and are not published here. Distances are approximate and measured from the plot boundary; a public road and a road of any kind are searched within 500 m, a motorway/expressway/dual-carriageway (a traffic-nuisance proxy, not access) within 3 km. A null distance means nothing of that kind within that radius — never a guarantee of absence.";
+const ROAD_INDICATOR_GLOSS = {
+    likely: "access likely",
+    uncertain: "access uncertain",
+    unlikely: "access unlikely",
+};
+function roadCells(r) {
+    const cells = [];
+    const indicator = typeof r.access_indicator === "string" ? r.access_indicator : null;
+    cells.push(indicator ? ROAD_INDICATOR_GLOSS[indicator] ?? `access ${indicator}` : "access not classified");
+    if (typeof r.access_rule_version === "number")
+        cells.push(`rule v${r.access_rule_version}`);
+    const pub = toNum(r.public_road_distance_m);
+    const edge = toNum(r.public_road_edge_distance_m);
+    if (pub == null) {
+        cells.push("public road: none within 500 m");
+    }
+    else {
+        const kind = [r.public_road_category, r.public_road_class].filter((x) => typeof x === "string");
+        const edgePart = edge != null ? `, ~${Math.round(edge)} m to the carriageway edge` : "";
+        cells.push(`public road: ~${Math.round(pub)} m${kind.length > 0 ? ` (${kind.join(", ")})` : ""}${edgePart}`);
+        if (r.public_road_at_grade === false)
+            cells.push("that road crosses on a viaduct or in a tunnel");
+    }
+    const any = toNum(r.any_road_distance_m);
+    cells.push(any == null ? "any road: none within 500 m" : `any road: ~${Math.round(any)} m`);
+    const major = toNum(r.major_road_distance_m);
+    cells.push(major == null ? "major road: none within 3 km" : `major road: ~${Math.round(major)} m`);
+    return cells;
+}
+export function formatRoads(res) {
+    const { data, truncated } = res;
+    if (data.length === 0) {
+        return "No road-access data is available for this transaction (no linked plots, or the id was not found).";
+    }
+    const lines = [
+        `Per-parcel road access (${data.length} plot${data.length === 1 ? "" : "s"}; distances from the plot boundary, "~" = approximate):`,
+        "",
+    ];
+    data.forEach((r, i) => {
+        if (!r.assessed) {
+            lines.push(`${i + 1}. not assessed yet — this plot has not been evaluated (no statement either way)`);
+            return;
+        }
+        lines.push(`${i + 1}. ${roadCells(r).join(" | ")}`);
+    });
+    if (truncated) {
+        lines.push("", "Showing the first 500 plots (the transaction is linked to more).");
+    }
+    const dates = data
+        .map((r) => r.source_as_of)
+        .filter((d) => typeof d === "string" && d.length > 0)
+        .sort();
+    if (dates.length > 0)
+        lines.push("", `Reference road-network snapshot as of ${dates[0]} (oldest of the plots shown).`);
+    lines.push("", ROADS_NOTE);
+    return lines.join("\n");
+}
 const TRANSIT_COVERAGE_NOTE = "Note: distances are from open public-transport schedules (GTFS format); coverage is cities and national rail, not every rural area. A mode missing above means no stop of that mode was found within its distance cap — never read as 'no public transport access'.";
 export function formatTransitBreakdown(res) {
     const { data, truncated } = res;
@@ -565,7 +978,7 @@ export function formatTransitBreakdown(res) {
     lines.push("", TRANSIT_COVERAGE_NOTE);
     return lines.join("\n");
 }
-const PERMITS_EMPTY_NOTE = "No positively-resolved building permit or works notification is on record for this transaction's parcels (or the id was not found). The register covers cases resolved since 2016, matched by the parcel's current identifier — an empty list is never a statement that nothing was ever planned.";
+const PERMITS_EMPTY_NOTE = "No building permit or works notification is on record for this transaction's parcels (or the id was not found). Permits are held once a decision has been issued, and notifications only where they were accepted without objection; cases registered since 2016 are matched by the parcel's current identifier — an empty list is never a statement that nothing was ever planned.";
 export function formatPermitsBreakdown(res) {
     const { data, truncated } = res;
     if (data.length === 0) {
@@ -765,6 +1178,74 @@ export function formatLocationHierarchy(items, parent) {
     }
     return lines.join("\n");
 }
+const SEARCH_LEVEL_ORDER = {
+    voivodeship: 0,
+    county: 1,
+    municipality: 2,
+    precinct: 3,
+};
+const SEARCH_LEVEL_LABEL = {
+    voivodeship: "Voivodeships",
+    county: "Counties",
+    municipality: "Municipalities",
+    precinct: "Precincts",
+};
+function searchCallsForItem(it) {
+    const code = it.code;
+    const calls = [
+        `search_transactions(teryt="${code}")`,
+        `list_parcels_in_area(teryt="${code}")`,
+    ];
+    if (it.level === "county" || it.level === "municipality") {
+        calls.push(`list_locations(parent="${code}")`);
+    }
+    if (it.level !== "precinct") {
+        calls.push(`get_demographics(teryt="${code}")`);
+    }
+    if (it.level === "county" || it.level === "municipality") {
+        calls.push(`get_infrastructure_signals(teryt="${code}")`);
+    }
+    if (it.rcn_district) {
+        calls.push(`search_transactions(location="${it.name}")`);
+        calls.push(`compare_locations(districts="${it.name},…")`);
+        calls.push(`get_price_statistics(location="${it.name}")`);
+    }
+    return calls;
+}
+export function formatLocationSearch(items, rcnOnly, query) {
+    const lines = [`Location search for "${query}":`, ""];
+    const byLevel = new Map();
+    for (const it of items) {
+        const bucket = byLevel.get(it.level) ?? [];
+        bucket.push(it);
+        byLevel.set(it.level, bucket);
+    }
+    const levels = [...byLevel.keys()].sort((a, b) => (SEARCH_LEVEL_ORDER[a] ?? 99) - (SEARCH_LEVEL_ORDER[b] ?? 99));
+    for (const level of levels) {
+        lines.push(`${SEARCH_LEVEL_LABEL[level] ?? level}:`);
+        for (const it of byLevel.get(level)) {
+            const typeSuffix = it.typeName ? ` (${it.typeName})` : "";
+            const parentSuffix = it.parent_name ? `, ${it.parent_name}` : "";
+            lines.push(`  ${it.code} - ${it.name}${typeSuffix}${parentSuffix}`);
+            for (const call of searchCallsForItem(it)) {
+                lines.push(`      ${call}`);
+            }
+        }
+        lines.push("");
+    }
+    if (rcnOnly.length > 0) {
+        lines.push("RCN district names without a TERYT code:");
+        for (const name of rcnOnly) {
+            lines.push(`  - ${name}`);
+            lines.push(`      search_transactions(location="${name}")`);
+        }
+        lines.push("");
+    }
+    if (items.length === 50) {
+        lines.push("Showing the first 50 matches — type more letters to narrow the search.");
+    }
+    return lines.join("\n").trimEnd();
+}
 export function formatCompareResults(res) {
     const districts = Object.keys(res);
     if (districts.length === 0) {
@@ -1067,6 +1548,49 @@ export function formatPriceSpreadLocations(r) {
     }
     return lines.join("\n");
 }
+const FLOOD_RISK_LOCATIONS_PATH = "flood-risk/locations";
+export function formatFloodRisk(r) {
+    const q = r.quality;
+    const sev = r.result.by_severity;
+    const lines = [`Flood-hazard exposure — ${r.location.name}`, ""];
+    lines.push(r.result.flood_share_pct != null
+        ? `Share in a mapped flood-hazard zone: ${r.result.flood_share_pct}% of assessed transactions`
+        : `Share: N/A (coverage: ${q.coverage})`);
+    if (sev.low != null || sev.medium != null || sev.high != null) {
+        lines.push("");
+        lines.push("Transactions by severity (return period):");
+        lines.push(`  High (~1-in-10-year): ${formatNumber(sev.high ?? 0)}`);
+        lines.push(`  Medium (~1-in-100-year): ${formatNumber(sev.medium ?? 0)}`);
+        lines.push(`  Low (~1-in-500-year): ${formatNumber(sev.low ?? 0)}`);
+    }
+    lines.push("");
+    lines.push(`Assessed transactions: ${r.inputs.assessed_sample_n != null ? formatNumber(r.inputs.assessed_sample_n) : "N/A"} (all-time)`);
+    lines.push(`Coverage: ${q.coverage} | Confidence: ${q.confidence}${q.stale ? " | transaction data lags publication" : ""}`);
+    if (q.as_of)
+        lines.push(`Transaction data as of: ${q.as_of}`);
+    const visibleNotes = q.notes.filter((n) => !n.includes(FLOOD_RISK_LOCATIONS_PATH));
+    if (visibleNotes.length > 0) {
+        lines.push("", "Notes:");
+        for (const n of visibleNotes)
+            lines.push(`  - ${n}`);
+    }
+    return lines.join("\n");
+}
+export function formatFloodRiskLocations(r) {
+    const { data, meta } = r;
+    if (data.length === 0) {
+        return "No flood-risk-covered locations match.";
+    }
+    const dateSuffix = meta.snapshot_date ? `, data from ${meta.snapshot_date}` : "";
+    const lines = [
+        `Flood-risk coverage — ${meta.total} location${meta.total === 1 ? "" : "s"}${dateSuffix}`,
+        "",
+    ];
+    for (const loc of data) {
+        lines.push(`- ${loc.location} (teryt ${loc.county_code}, ${loc.voivodeship}, ${loc.type}) — n=${formatNumber(loc.assessed_sample_n)}, ${loc.confidence} confidence`);
+    }
+    return lines.join("\n");
+}
 function valuationCompLine(c) {
     const parts = [`${formatNumber(c.distance_m)} m`, c.transaction_date, formatArea(c.area_m2), `${formatPLN(c.price_per_m2)}/m²`];
     if (c.market_type)
@@ -1131,6 +1655,15 @@ function fourStateGloss(coverage) {
         default: return coverage;
     }
 }
+function stringList(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function landClassHeadline(useNames, soilClasses) {
+    return [
+        useNames.length ? useNames.join(", ") : null,
+        soilClasses.length ? `soil class ${soilClasses.join(", ")}` : null,
+    ].filter(Boolean).join("; ");
+}
 function toNum(v) {
     if (v == null)
         return null;
@@ -1165,6 +1698,19 @@ function reportSectionDetail(name, s) {
             const risk = typeof s.landslide_risk === "string" ? s.landslide_risk : null;
             return risk ? LANDSLIDE_RISK_NOTE[risk] ?? risk : "";
         }
+        case "subsurface": {
+            if (!covered)
+                return "";
+            const parts = [];
+            const mining = typeof s.mining_status === "string" ? s.mining_status : null;
+            const mineral = typeof s.mineral_class === "string" ? s.mineral_class : null;
+            if (mining)
+                parts.push(`mining terrain ${mining}${mineral ? ` (${mineral})` : ""}`);
+            const gw = typeof s.groundwater_status === "string" ? s.groundwater_status : null;
+            if (gw)
+                parts.push(`groundwater reservoir ${gw}`);
+            return parts.join("; ");
+        }
         case "surroundings": {
             if (!covered)
                 return "";
@@ -1180,6 +1726,21 @@ function reportSectionDetail(name, s) {
                 return "no mapped nuisance object within range";
             return dists.slice(0, 3).map(([k, m]) => `${k} ${Math.round(m)} m`).join(", ");
         }
+        case "roads": {
+            if (!covered)
+                return "";
+            const indicator = typeof s.access_indicator === "string" ? s.access_indicator : null;
+            if (!indicator)
+                return "";
+            const edge = toNum(s.public_road_edge_distance_m);
+            const pub = toNum(s.public_road_distance_m);
+            const gloss = ROAD_INDICATOR_GLOSS[indicator] ?? indicator;
+            if (edge != null)
+                return `${gloss} (~${Math.round(edge)} m to the nearest public road's carriageway edge)`;
+            if (pub != null)
+                return `${gloss} (nearest public road ~${Math.round(pub)} m)`;
+            return `${gloss} (no public road within 500 m)`;
+        }
         case "transit": {
             if (!covered)
                 return "";
@@ -1204,7 +1765,16 @@ function reportSectionDetail(name, s) {
             if (!covered)
                 return "";
             const rows = Array.isArray(s.data) ? s.data : [];
-            return `${rows.length} building(s) on the parcel`;
+            const ages = rows
+                .map((r) => r.age_estimate?.status)
+                .filter((x) => x != null);
+            const dated = ages.filter((x) => x === "estimated").length;
+            const agePart = ages.length === 0
+                ? ""
+                : dated === 0
+                    ? "; construction year not established for any of them"
+                    : `; construction year estimated for ${dated} of ${ages.length} (estimate from permit records, not a registry date)`;
+            return `${rows.length} building(s) on the parcel${agePart}`;
         }
         case "permits": {
             if (!covered)
@@ -1219,6 +1789,27 @@ function reportSectionDetail(name, s) {
             const pct = toNum(s.pct_of_parcel);
             return area != null ? `${formatArea(area)} eligible${pct != null ? ` (${pct}% of parcel)` : ""}` : "";
         }
+        case "land_class": {
+            if (!covered)
+                return "";
+            const note = typeof s.legal_note === "string" ? s.legal_note : null;
+            const head = landClassHeadline(stringList(s.use_names), stringList(s.soil_classes));
+            return [head || null, note].filter(Boolean).join(" — ");
+        }
+        case "nature": {
+            if (!covered)
+                return "";
+            const rank = toNum(s.protection_rank);
+            const dist = toNum(s.forest_distance_m);
+            const parts = [];
+            if (rank != null) {
+                const label = PROTECTION_RANK_LABEL[rank] ?? `protection rank ${rank}`;
+                parts.push(s.building_restriction === "statutory_ban" ? `${label} (statutory build ban)` : label);
+            }
+            if (dist != null)
+                parts.push(dist === 0 ? "overlaps forest" : `forest ${Math.round(dist)} m`);
+            return parts.join(", ");
+        }
         default:
             return "";
     }
@@ -1253,23 +1844,27 @@ function reportBillingFooter(billing) {
     const reason = why[billing.rule] ?? billing.rule;
     return `Billing: ${billing.charged} charged, ${billing.refunded} refunded — ${reason}`;
 }
-const REPORT_LAYER_ORDER = [
+export const REPORT_LAYER_ORDER = [
     ["flood", "Flood risk"],
     ["heritage", "Heritage listing"],
     ["landslide", "Landslide risk"],
+    ["subsurface", "Subsurface constraints"],
     ["surroundings", "Nuisance surroundings"],
     ["transit", "Public transport"],
     ["planning", "Planning (general plan)"],
     ["buildings", "Buildings"],
     ["permits", "Building activity"],
     ["farmland", "Agricultural land"],
+    ["land_class", "Land use & soil class"],
+    ["nature", "Nature (forest & protected areas)"],
+    ["roads", "Road access"],
 ];
 export function formatParcelReport(res) {
     const p = res.parcel;
     const id = p.parcel_id ?? p.parcel_key ?? "(parcel id requires a paid plan)";
     if (res.coverage !== "covered") {
         const head = res.coverage === "not_covered"
-            ? `Parcel ${id} could not be resolved — it is not in our cadastral copy.`
+            ? `Parcel ${id} could not be resolved — we do not hold it. Coverage is near-complete but not the whole cadastral register and not live, so this is not a finding that the parcel does not exist.`
             : res.billing.rule === "disabled"
                 ? `The composite report is temporarily unavailable for parcel ${id}.`
                 : `Parcel ${id} could not be resolved right now (a live lookup did not finish — retry).`;
@@ -1292,6 +1887,8 @@ export function formatParcelReport(res) {
     const sections = res.sections;
     for (const [key, label] of REPORT_LAYER_ORDER) {
         const s = sections[key];
+        if (s == null)
+            continue;
         const detail = reportSectionDetail(key, s);
         lines.push(`- ${label}: ${fourStateGloss(s.coverage)}${detail ? ` — ${detail}` : ""}`);
     }
@@ -1344,3 +1941,44 @@ export function formatParcelReport(res) {
     lines.push("", "---", reportBillingFooter(res.billing));
     return lines.join("\n");
 }
+export function formatParcelLandClass(res) {
+    const id = res.parcel.parcel_id ?? res.parcel.parcel_key ?? res.parcel.id ?? "(identifier withheld)";
+    const asOfDay = typeof res.as_of === "string" ? res.as_of.split("T")[0] : null;
+    if (res.coverage === "not_computed") {
+        return `The classification lookup for parcel ${id} could not be completed, so this says nothing about what is recorded for it (the tokens are refunded). Retry shortly.`;
+    }
+    if (res.coverage === "not_covered") {
+        const why = res.note ? ` ${res.note}` : "";
+        return `No land-use or soil-quality classification is available for parcel ${id} (the tokens are refunded). Either the county does not publish one, or we hold no classification for this parcel.${why}`;
+    }
+    if (res.coverage === "covered_no_data") {
+        const asOf = asOfDay ? ` (county data as of ${asOfDay})` : "";
+        return `The county publishes the classification, but parcel ${id} has no entry in it${asOf}. That is a checked negative, not a gap in coverage: it says nothing about what the land is, only that the county's dataset holds no entry for this parcel — and it is billed as an answer.`;
+    }
+    if (res.coverage !== "covered") {
+        return `The classification for parcel ${id} came back in a state this client does not recognise (${String(res.coverage)}); it says nothing about what is recorded for the parcel.`;
+    }
+    const useNames = stringList(res.use_names);
+    const soilClasses = stringList(res.soil_classes);
+    const useCodes = stringList(res.use_codes);
+    const lines = [`Land-use and soil-quality classification: ${id}`];
+    const headline = landClassHeadline(useNames, soilClasses);
+    if (headline)
+        lines.push(headline);
+    if (useCodes.length > 0)
+        lines.push(`Use codes: ${useCodes.join(", ")}`);
+    lines.push(`Protected soil grade (I-III) present: ${res.protected_class_present ? "yes" : "no"}`);
+    lines.push(`Inside a city's administrative boundary: ${res.in_city == null ? "could not be determined from the parcel id" : res.in_city ? "yes" : "no"}`);
+    lines.push("", "Categories and grades are listed as sets: the source records no area for any of them, so this cannot say which prevails on the parcel.");
+    if (res.legal_note) {
+        lines.push("", `Re-designation: ${res.legal_note}`);
+    }
+    if (res.legal_state_as_of) {
+        lines.push(`Legal state verified as of ${res.legal_state_as_of}.`);
+    }
+    if (asOfDay)
+        lines.push(`Classification data as of ${asOfDay}.`);
+    if (res.note)
+        lines.push("", res.note);
+    return lines.join("\n");
+}