@cliwant/mcp-sam-gov 0.2.1 → 1.0.0

package/dist/census.js

@@ -0,0 +1,576 @@
+/**
+ * US Census Bureau Geocoder — keyless source #22 (ADR-0023). A NEW capability
+ * domain: TERRITORY / GEOSPATIAL — resolve a one-line address (or a lon/lat point)
+ * to its Census GEOGRAPHIES (State, County, Congressional District, Census Tract,
+ * Census Block, Incorporated Place, CBSA/CSA, State Legislative Districts). This is
+ * the geographic backbone of set-aside / place-of-performance analysis: a bidder
+ * needs a location's congressional district + census tract to reason about HUBZone
+ * / Opportunity-Zone eligibility and to file/verify a contract's place-of-performance.
+ *
+ * The GET source on the R2 `DataSource` port: census.ts writes ZERO fetch/coercion/
+ * error/meta code — it REUSES `getJson` / `driftError` / `num`·`str` / `withMeta`,
+ * and COPIES (does NOT import) the ECHO fixed-host SSRF idiom. Fully PUBLIC, KEYLESS
+ * (byte-clean init — NO headers, NO UA; live-verified 2026-07-12).
+ *
+ *   Address → geographies:  https://geocoding.geo.census.gov/geocoder/geographies/onelineaddress
+ *                           ?address=…&benchmark=…&vintage=…&format=json
+ *                           → { result:{ input, addressMatches:[ { matchedAddress,
+ *                                coordinates:{x,y}, tigerLine, addressComponents,
+ *                                geographies:{ …layer keys… } } ] } }
+ *   Point   → geographies:  https://geocoding.geo.census.gov/geocoder/geographies/coordinates
+ *                           ?x=<lon>&y=<lat>&benchmark=…&vintage=…&format=json
+ *                           → { result:{ input:{ location:{x,y}, … }, geographies:{ … } } }
+ *                             (NO addressMatches wrapper — a point resolves to ONE geography set)
+ *
+ * ★ SSRF GUARD (policy① — a verbatim copy of the ECHO fixed-host shape):
+ *   (1) SINGLE fixed host constant `CENSUS_GEO_HOST` — the caller NEVER supplies a host.
+ *   (2) TWO fixed endpoint-path constants (a frozen Set) — the caller NEVER supplies a
+ *       path fragment; there is NO id interpolated into the path (both endpoints are
+ *       query-param-only), so there is no path-segment-injection surface at all. A path
+ *       outside the Set ⇒ invalid_input before any fetch.
+ *   (3) `address`/`x`/`y`/`benchmark`/`vintage`/`format` ride in a module-built
+ *       URLSearchParams (encoded VALUES — an embedded &/=/?/# inside `address` stays
+ *       inside the value, never touching the host/path). `benchmark`/`vintage` are
+ *       enum-whitelisted; `x`/`y` are re-guarded finite-in-range and sent as String().
+ *       `format=json` is ALWAYS module-set (never a caller arg).
+ *   (4) Construct the URL, then ASSERT `new URL(built).hostname === CENSUS_GEO_HOST`
+ *       and `protocol === "https:"` ⇒ invalid_input on mismatch (belt-and-suspenders).
+ *   (5) `redirect:"error"` on every getJson — a 3xx off geocoding.geo.census.gov throws;
+ *       its body is never read.
+ *
+ * ★ HONESTY (load-bearing — 02-truthful-outputs-spec §2.1; ADR-0023 v2 AUTHORITATIVE):
+ *   [B1] The layer mapper resolves each canonical layer by a SUFFIX pattern on the
+ *        layer-key (never a literal versioned key — the key names ROLL: "119th
+ *        Congressional Districts", "2020 Census Blocks", "2024 State Legislative
+ *        Districts - Upper"). It handles >1 KEY PER SUFFIX: a historical vintage
+ *        (live-verified `Census2010_Current`) returns TWO `/Congressional Districts$/`
+ *        keys (113th=GEOID 0102 AND 111th=GEOID 0103 for Montgomery AL — a redistricted
+ *        location with DISTINCT district GEOIDs). Single-pick-and-drop would present one
+ *        as THE district and hide the other — a data-lie by omission. So when >1 key
+ *        matches: pick deterministically (highest leading session/year number), surface
+ *        EVERY matched layerKey (the chosen object + an `alternates[]`), AND emit a
+ *        MANDATORY `_meta` note naming the N keys + the chosen one. NEVER silently drop.
+ *   [M1] The drift-guard is scoped to the FOUR always-present sentinel layers only —
+ *        States, Counties, Census Tracts, Congressional Districts. driftError fires ONLY
+ *        when a sentinel matches ZERO keys while `geographies` is a NON-EMPTY object.
+ *        Optional/vintage-dependent layers (Census Blocks, SLD-Upper/Lower, CBSA/CSA)
+ *        → honest `null` on absence (live-verified: ACS2023_Current omits Census Blocks;
+ *        DC omits SLD-Lower — LEGITIMATE absences, NOT drift).
+ *   [M2] The vintage enum is the UNION of live-valid vintages across the four shipped
+ *        benchmarks (25 distinct — enumerated via /benchmarks + /vintages 2026-07-12),
+ *        so a VALID non-default pair (e.g. Public_AR_Census2020 + Census2020_Census2020,
+ *        live 200) is NOT Zod-rejected. An INVALID (benchmark,vintage) pair LOUD-fails
+ *        at HTTP 400 (the module relies on that backstop) and the tool DISCLOSES that
+ *        vintage must be benchmark-compatible.
+ *   • Genuine-empty is HTTP-200 and is NEVER thrown; a 400/500/outage is NEVER read as
+ *     empty. Address: `addressMatches:[]` ⇒ matches:[], matchCount:0, complete:true.
+ *     Coordinates: `geographies:{}` ⇒ all layers null, matchCount:0, complete:true. An
+ *     invalid/missing benchmark/vintage or a non-numeric coord ⇒ HTTP 400 ⇒ getJson
+ *     THROWS invalid_input; a 5xx/timeout ⇒ THROWS upstream_unavailable.
+ *   • Multi-match (addressMatches.length > 1, live-forced: "100 Main St, Springfield"
+ *     → 7 matches with DISTINCT state/CD geographies) ⇒ surface ALL matches (each with
+ *     its own matchedAddress + geographies) + matchCount + a mandatory note.
+ *   • The RESOLVED benchmark/vintage is echoed in EVERY response (data.vintageResolved
+ *     from result.input.{benchmark.benchmarkName, vintage.vintageName}) + a mandatory
+ *     "Current is a MOVING vintage" note.
+ *   • GEOIDs are `str` (null-never-empty-string). Leading zeros are REAL and MUST
+ *     survive: State "01", County "01101", Tract "01101000200", CD "0102" — `num()`
+ *     would corrupt "01"→1, so a GEOID is NEVER num-coerced.
+ *   • The KILLER caveat, in EVERY response: Census geographies are a NOMINAL input, NOT
+ *     an authoritative HUBZone / Opportunity-Zone / set-aside determination.
+ *   • No fabricated pagination/cursor — both tools are single-shot lookups.
+ *
+ * ★ `tokenizeForDisclosure` (src/disclosure.ts, C110) is DELIBERATELY N/A: the geocoder
+ *   is a STRUCTURED address PARSER, not an Essie whitespace-AND/OR keyword search. A
+ *   multi-word `address` is EXPECTED and is not tokenized into a co-occurrence trap — an
+ *   under-specified address returns a clean genuine-empty (live-verified), not a silent
+ *   broaden. There is NO upstream token-drop to disclose, so this module builds NO
+ *   whitespace-split disclosure note (the lint-invariants disclosure check stays green).
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js —
+// ADR-0005 v2 FIX-C) so the fault suite's num-parity guard resolves the SAME `num`
+// from this module (census.num === coerce.num === echo.num === …). NO local num/str.
+export { num };
+// ─── SSRF core: the single fixed host + two fixed endpoint paths ──
+const CENSUS_GEO_HOST = "geocoding.geo.census.gov";
+const CENSUS_GEO_BASE = `https://${CENSUS_GEO_HOST}/geocoder`;
+// The ONLY two endpoint paths we ever build (frozen constants — the caller never
+// supplies a path fragment; NO id is interpolated into the path). A path outside this
+// Set ⇒ invalid_input (the path-injection guard — mirror ECHO_SERVICES).
+const PATH_ONELINE = "/geographies/onelineaddress"; // address → addressMatches[].geographies
+const PATH_COORDINATES = "/geographies/coordinates"; // lon/lat → geographies
+const CENSUS_PATHS = new Set([
+    PATH_ONELINE,
+    PATH_COORDINATES,
+]);
+// ─── Frozen enums (the Zod source of truth + in-handler re-guard) ──
+// Live-enumerated via /benchmarks (2026-07-12): 4 benchmarks.
+export const CENSUS_BENCHMARKS = [
+    "Public_AR_Current",
+    "Public_AR_ACS2025",
+    "Public_AR_LUCA",
+    "Public_AR_Census2020",
+];
+// [M2] The UNION of live-valid vintages across ALL four benchmarks (live-enumerated
+// via /vintages?benchmark=<b> 2026-07-12 — 25 distinct). The valid vintage set is a
+// (benchmark, vintage) MATRIX, so this enum is intentionally the UNION: it must NOT
+// reject a VALID non-default pair (e.g. Census2020_Census2020, live 200). An INVALID
+// pair fails-closed at HTTP 400 (the module relies on the LOUD 400 backstop).
+export const CENSUS_VINTAGES = [
+    // Public_AR_Current (11)
+    "Current_Current",
+    "Census2010_Current",
+    "ACS2017_Current",
+    "ACS2018_Current",
+    "ACS2019_Current",
+    "Census2020_Current",
+    "ACS2021_Current",
+    "ACS2022_Current",
+    "ACS2023_Current",
+    "ACS2024_Current",
+    "ACS2025_Current",
+    // Public_AR_LUCA (1)
+    "LUCA_Current",
+    // Public_AR_ACS2025 (11)
+    "Current_ACS2025",
+    "Census2010_ACS2025",
+    "ACS2017_ACS2025",
+    "ACS2018_ACS2025",
+    "ACS2019_ACS2025",
+    "Census2020_ACS2025",
+    "ACS2021_ACS2025",
+    "ACS2022_ACS2025",
+    "ACS2023_ACS2025",
+    "ACS2024_ACS2025",
+    "ACS2025_ACS2025",
+    // Public_AR_Census2020 (2)
+    "Census2020_Census2020",
+    "Census2010_Census2020",
+];
+const DEFAULT_BENCHMARK = "Public_AR_Current";
+const DEFAULT_VINTAGE = "Current_Current";
+// ─── Notes (honesty disclosures — ADR-0023 required set) ──────────
+// The KILLER caveat — in EVERY response (§Honesty #4).
+const HUBZONE_OZ_CAVEAT = "Census geographies are a NOMINAL input, NOT an authoritative HUBZone / Opportunity-Zone / set-aside determination. censusTract.geoid is the tract-level identifier used to look up Opportunity-Zone status (Treasury's designated-OZ-tract list), and county/censusTract are inputs to a HUBZone determination (SBA's HUBZone map / qualified-tract & qualified-county lists) — but an authoritative eligibility finding requires those SBA/Treasury sources, not this geocoder.";
+const BENCHMARK_VINTAGE_NOTE = "vintage must be COMPATIBLE with the chosen benchmark (the valid vintage set is a (benchmark, vintage) matrix); an incompatible pair fails-closed with an HTTP 400 (invalid_input), never a silent mis-resolution.";
+const GEOID_STRING_NOTE = "GEOIDs are STRINGS with real leading zeros (State '01', County '01101', Tract '01101000200', CD '0102') — they are never numeric (a leading zero must survive); a missing value is null, never an empty string.";
+// ─── fetch layer (SSRF-guarded; reuses the R2 getJson port) ───────
+/**
+ * GET one Census geocoder endpoint. SSRF guard: `path` ∈ the frozen 2-member Set
+ * (the path-injection guard), params via a module-built URLSearchParams (encoded
+ * values, no host-alteration surface), `format=json` ALWAYS module-set, then the
+ * CONSTRUCTED URL's hostname === CENSUS_GEO_HOST (https) assertion. Sets
+ * `redirect:"error"`; NO headers (keyless — byte-clean init). Reuses errors.ts
+ * retry/timeout/taxonomy (429 → rate_limited; 5xx → upstream_unavailable; 404 →
+ * not_found; 400 → invalid_input — the P6–P10 400s become the thrown error, NEVER a
+ * fake-empty). Returns the parsed JSON (unknown; the caller validates the envelope).
+ */
+export async function censusGet(path, params) {
+    if (!CENSUS_PATHS.has(path)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Census geocoder path ${JSON.stringify(path)} is not one of the two fixed endpoint paths (${PATH_ONELINE} / ${PATH_COORDINATES}) — refusing to fetch (SSRF path guard).`,
+            retryable: false,
+        });
+    }
+    // `format=json` is ALWAYS module-set — never a caller arg (structural guarantee).
+    params.set("format", "json");
+    const url = `${CENSUS_GEO_BASE}${path}?${params.toString()}`;
+    // Belt-and-suspenders: the FIXED host + FIXED path leave nothing to steer the
+    // authority; assert the built URL cannot have been moved off-host.
+    const built = new URL(url);
+    if (built.hostname !== CENSUS_GEO_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed Census URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${CENSUS_GEO_HOST} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+        });
+    }
+    // Shared fetch envelope: keyless ⇒ NO headers key (byte-clean init); redirect:"error";
+    // the label surfaces as ToolError.upstreamEndpoint — host+path only, no token.
+    return getJson(url, { label: "census:" + path, redirect: "error" });
+}
+// The canonical layer specs, resolved by SUFFIX PATTERN (never a literal versioned
+// key). Order = the emitted field order. The FOUR sentinels ([M1]) are marked.
+const LAYER_SPECS = [
+    { field: "state", re: /^States$/, label: "States", sentinel: true },
+    { field: "county", re: /^Counties$/, label: "Counties", sentinel: true },
+    {
+        field: "congressionalDistrict",
+        re: /Congressional Districts$/,
+        label: "Congressional Districts",
+        sentinel: true,
+    },
+    {
+        field: "censusTract",
+        re: /Census Tracts$/,
+        label: "Census Tracts",
+        sentinel: true,
+    },
+    {
+        field: "censusBlock",
+        re: /Census Blocks$/,
+        label: "Census Blocks",
+        sentinel: false,
+    },
+    {
+        field: "place",
+        re: /Incorporated Places$/,
+        label: "Incorporated Places",
+        sentinel: false,
+    },
+    {
+        field: "cbsaOrCsa",
+        re: /Statistical Areas?$/,
+        label: "Statistical Areas (CBSA/CSA)",
+        sentinel: false,
+    },
+    {
+        field: "stateLegislativeUpper",
+        re: /State Legislative Districts - Upper$/,
+        label: "State Legislative Districts - Upper",
+        sentinel: false,
+    },
+    {
+        field: "stateLegislativeLower",
+        re: /State Legislative Districts - Lower$/,
+        label: "State Legislative Districts - Lower",
+        sentinel: false,
+    },
+];
+/** The leading integer of a layer key ("113th …" → 113, "2012 …" → 2012), else -1. */
+function leadingNumber(key) {
+    const m = /^(\d+)/.exec(key.trim());
+    return m ? Number(m[1]) : -1;
+}
+/** Build a GeoLayer from a raw layer key + its first entry (GEOID/NAME are str). */
+function toGeoLayer(layerKey, entry) {
+    return {
+        layerKey,
+        geoid: str(entry.GEOID), // NEVER num — leading zeros must survive ("01" ≠ 1)
+        name: str(entry.NAME),
+    };
+}
+/**
+ * Map a `geographies` object to the STABLE canonical set by SUFFIX pattern, handling
+ * >1 key per suffix ([B1]) and the sentinel drift-guard ([M1]). Returns the mapped
+ * geographies + any multi-key `_meta` notes. `label` scopes the driftError;
+ * `vintageName` names the vintage in the multi-key note.
+ */
+export function mapGeographies(geographies, label, vintageName) {
+    const allKeys = Object.keys(geographies);
+    const nonEmpty = allKeys.length > 0;
+    const geo = {};
+    const notes = [];
+    for (const spec of LAYER_SPECS) {
+        // ALL keys matching this suffix that carry a usable (non-empty array) value.
+        const matched = allKeys.filter((k) => {
+            if (!spec.re.test(k))
+                return false;
+            const v = geographies[k];
+            return Array.isArray(v) && v.length > 0 && typeof v[0] === "object" && v[0] !== null;
+        });
+        if (matched.length === 0) {
+            // [M1] a SENTINEL absent from a NON-EMPTY geographies object ⇒ schema drift
+            // (the four sentinels are live-observed present in EVERY non-empty 200).
+            // Optional layers absent ⇒ honest null (never drift).
+            if (spec.sentinel && nonEmpty) {
+                throw driftError(label, `census: expected sentinel layer "${spec.label}" matched ZERO keys in a non-empty geographies object (keys: ${JSON.stringify(allKeys)}) — treating as schema drift (the layer-key suffix may have changed).`);
+            }
+            geo[spec.field] = null;
+            continue;
+        }
+        // [B1] Deterministic pick: highest leading session/year number, tiebreak by the
+        // key string DESC (so the choice is stable). NEVER silently drop the others.
+        const ordered = [...matched].sort((a, b) => {
+            const na = leadingNumber(a);
+            const nb = leadingNumber(b);
+            if (na !== nb)
+                return nb - na;
+            return a < b ? 1 : a > b ? -1 : 0;
+        });
+        const layers = ordered.map((k) => toGeoLayer(k, geographies[k][0]));
+        const chosen = layers[0];
+        if (layers.length > 1) {
+            const alternates = layers.slice(1);
+            geo[spec.field] = { ...chosen, alternates };
+            // MANDATORY multi-key note ([B1]) — name every matched key + the chosen one.
+            notes.push(`vintage ${vintageName ?? "(unknown)"} returned ${layers.length} "${spec.label}" layers: ${ordered
+                .map((k) => JSON.stringify(k))
+                .join(", ")}; showing "${chosen.layerKey}" (highest session/year) as ${spec.field}, the other ${layers.length - 1} in ${spec.field}.alternates[] — a redistricted location can carry DISTINCT GEOIDs across these, so do NOT treat the shown one as the sole answer.`);
+        }
+        else {
+            geo[spec.field] = chosen;
+        }
+    }
+    return { geo, notes };
+}
+/** Build one curated AddressMatch from a raw addressMatches[i] + its geographies. */
+function buildAddressMatch(m, label, vintageName) {
+    const coordsRaw = (m.coordinates ?? {});
+    const tiger = (m.tigerLine ?? {});
+    const ac = (m.addressComponents ?? {});
+    const g = m.geographies;
+    const geoObj = g !== null && typeof g === "object" && !Array.isArray(g)
+        ? g
+        : {};
+    const { geo, notes } = mapGeographies(geoObj, label, vintageName);
+    // A one-line street from the parsed components (fromAddress + streetName + suffixType).
+    const street = [str(ac.fromAddress), str(ac.streetName), str(ac.suffixType)]
+        .filter((p) => p !== null)
+        .join(" ") || null;
+    return {
+        match: {
+            matchedAddress: str(m.matchedAddress),
+            coordinates: { x: num(coordsRaw.x), y: num(coordsRaw.y) },
+            tigerLineId: str(tiger.tigerLineId),
+            addressComponents: {
+                street,
+                city: str(ac.city),
+                state: str(ac.state),
+                zip: str(ac.zip),
+            },
+            geographies: geo,
+        },
+        notes,
+    };
+}
+/** Echo the RESOLVED benchmark/vintage from result.input (the ACTUAL pair upstream used). */
+function resolvedVintage(input) {
+    const b = (input?.benchmark ?? {});
+    const v = (input?.vintage ?? {});
+    return { benchmark: str(b.benchmarkName), vintage: str(v.vintageName) };
+}
+/** The mandatory "resolved + moving vintage" note (echoes the actual resolved pair). */
+function movingVintageNote(res) {
+    return `Resolved to benchmark ${JSON.stringify(res.benchmark)} / vintage ${JSON.stringify(res.vintage)}. 'Current' is a MOVING vintage — these geographies reflect today's resolution and may change as the Census Bureau refreshes (the same address can return a different tract/CD across cycles); the congressional-district layerKey reflects the current congressional session (redistricting changes it).`;
+}
+// ─── Enum re-guards (belt-and-suspenders behind the server's Zod enums) ──
+function guardBenchmark(benchmark) {
+    if (!CENSUS_BENCHMARKS.includes(benchmark)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid benchmark ${JSON.stringify(benchmark)} — expected one of ${JSON.stringify(CENSUS_BENCHMARKS)}.`,
+            retryable: false,
+        });
+    }
+}
+function guardVintage(vintage) {
+    if (!CENSUS_VINTAGES.includes(vintage)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid vintage ${JSON.stringify(vintage)} — expected one of the ${CENSUS_VINTAGES.length} live-valid vintages (it must also be COMPATIBLE with the chosen benchmark; an incompatible pair fails-closed with a 400).`,
+            retryable: false,
+        });
+    }
+}
+const SOURCE = `${CENSUS_GEO_HOST} via US Census Geocoder (keyless)`;
+// ─── Tool 1: census_geocode_address ───────────────────────────────
+/**
+ * Resolve a one-line US address → its matched address(es) + the Census geographies
+ * that drive set-aside / place-of-performance analysis (congressional district,
+ * census tract, county, state, block). Handles the addressMatches ARRAY (the
+ * multi-match "which location" honesty surface — every match carries its own
+ * matchedAddress + geographies). Disclose-not-refuse: an unmatched address is NOT an
+ * error (matches:[], matchCount:0, complete:true + a note).
+ */
+export async function geocodeAddress(args) {
+    const benchmark = args.benchmark ?? DEFAULT_BENCHMARK;
+    const vintage = args.vintage ?? DEFAULT_VINTAGE;
+    guardBenchmark(benchmark); // re-guard behind Zod (a direct handler call bypasses it)
+    guardVintage(vintage);
+    if (typeof args.address !== "string" || args.address.trim() === "") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: "address is required (a non-empty one-line US address).",
+            retryable: false,
+        });
+    }
+    const params = new URLSearchParams();
+    params.set("address", args.address); // URLSearchParams-encoded VALUE (no param smuggle)
+    params.set("benchmark", benchmark); // ALWAYS sent (REQUIRED — a missing benchmark 400s)
+    params.set("vintage", vintage); // ALWAYS sent (REQUIRED — a missing vintage 400s)
+    const body = await censusGet(PATH_ONELINE, params);
+    const result = body?.result;
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+        throw driftError("census:" + PATH_ONELINE, "census: onelineaddress returned an unexpected shape (missing result object).");
+    }
+    const r = result;
+    const addressMatches = r.addressMatches;
+    if (!Array.isArray(addressMatches)) {
+        throw driftError("census:" + PATH_ONELINE, "census: onelineaddress returned a non-array addressMatches with no error — treating as schema drift (never a fake empty).");
+    }
+    const res = resolvedVintage(r.input);
+    const notes = [movingVintageNote(res), HUBZONE_OZ_CAVEAT, BENCHMARK_VINTAGE_NOTE, GEOID_STRING_NOTE];
+    // Genuine-empty (200 addressMatches:[]) — honest complete:true / matchCount:0 (NOT
+    // an error; DISTINCT from the LOUD 400 of a bad benchmark/vintage).
+    if (addressMatches.length === 0) {
+        notes.push("No address match — the address did not geocode. Verify spelling and add city, state, and ZIP (an under-specified address returns 0, a genuine empty, not an error).");
+        return withMeta({
+            matches: [],
+            matchCount: 0,
+            benchmark,
+            vintage,
+            vintageResolved: res,
+        }, {
+            source: SOURCE,
+            keylessMode: true,
+            returned: 0,
+            totalAvailable: 0,
+            filtersApplied: ["benchmark", "vintage"],
+            filtersDropped: [],
+            fieldsUnavailable: [],
+            notes,
+        });
+    }
+    const matches = [];
+    for (const m of addressMatches) {
+        const built = buildAddressMatch((m ?? {}), "census:" + PATH_ONELINE, res.vintage);
+        matches.push(built.match);
+        for (const n of built.notes)
+            if (!notes.includes(n))
+                notes.push(n);
+    }
+    // Multi-match disclosure (§Honesty #5) — surface ALL matches + matchCount + a note.
+    // NOTE: an upstream cap on addressMatches was NOT observed (live-forced 7 matches for
+    // "100 Main St, Springfield"); no cap has been seen, so complete:true. If a future
+    // cap is found, surface truncated:true.
+    if (matches.length > 1) {
+        notes.push(`${matches.length} addresses matched — the geographies are listed PER match; matchedAddress shows what each resolved to. Refine the address (add ZIP / unit / state) if the intended location is ambiguous.`);
+    }
+    return withMeta({
+        matches,
+        matchCount: matches.length,
+        benchmark,
+        vintage,
+        vintageResolved: res,
+    }, {
+        source: SOURCE,
+        keylessMode: true,
+        returned: matches.length,
+        totalAvailable: matches.length,
+        filtersApplied: ["benchmark", "vintage"],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+// ─── Tool 2: census_geographies_by_coordinates ────────────────────
+/**
+ * Resolve a longitude/latitude point → the Census geographies at that point (no
+ * address parsing). For a caller that already holds coordinates. `x`/`longitude`
+ * (required) and `y`/`latitude` (required) are aliases; the handler coalesces + re-
+ * guards them finite-in-range (belt-and-suspenders behind Zod — a non-finite value ⇒
+ * invalid_input PRE-fetch, 0 fetch, mirroring the LOUD 400 of a non-numeric coord but
+ * caught locally). A point outside any US Census geography ⇒ geographies:{} ⇒ all
+ * layers null, matchCount:0, complete:true + a note (NOT an error).
+ */
+export async function geographiesByCoordinates(args) {
+    const benchmark = args.benchmark ?? DEFAULT_BENCHMARK;
+    const vintage = args.vintage ?? DEFAULT_VINTAGE;
+    guardBenchmark(benchmark);
+    guardVintage(vintage);
+    const xVal = args.x ?? args.longitude;
+    const yVal = args.y ?? args.latitude;
+    if (xVal === undefined || yVal === undefined) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: "both x (longitude) and y (latitude) are required.",
+            retryable: false,
+        });
+    }
+    // Coordinate FINITENESS re-guard (belt-and-suspenders behind the Zod min/max — a live
+    // x=NaN is a misclassified upstream 500 the pre-fetch guard prevents; 0 fetch).
+    if (!Number.isFinite(xVal) || xVal < -180 || xVal > 180) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid x (longitude) ${JSON.stringify(xVal)} — expected a finite number in [-180, 180].`,
+            retryable: false,
+        });
+    }
+    if (!Number.isFinite(yVal) || yVal < -90 || yVal > 90) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Invalid y (latitude) ${JSON.stringify(yVal)} — expected a finite number in [-90, 90].`,
+            retryable: false,
+        });
+    }
+    const params = new URLSearchParams();
+    params.set("x", String(xVal));
+    params.set("y", String(yVal));
+    params.set("benchmark", benchmark);
+    params.set("vintage", vintage);
+    const body = await censusGet(PATH_COORDINATES, params);
+    const result = body?.result;
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+        throw driftError("census:" + PATH_COORDINATES, "census: coordinates returned an unexpected shape (missing result object).");
+    }
+    const r = result;
+    const geographiesRaw = r.geographies;
+    // A missing / non-object (null / array) geographies with no error ⇒ hard drift (an
+    // empty OBJECT {} is a GENUINE out-of-US empty, handled below — NOT drift).
+    if (geographiesRaw === null ||
+        typeof geographiesRaw !== "object" ||
+        Array.isArray(geographiesRaw)) {
+        throw driftError("census:" + PATH_COORDINATES, "census: coordinates returned a non-object geographies with no error — treating as schema drift (never a fake empty).");
+    }
+    const res = resolvedVintage(r.input);
+    const loc = r.input?.location;
+    const coordinates = {
+        x: num(loc?.x) ?? xVal,
+        y: num(loc?.y) ?? yVal,
+    };
+    const notes = [movingVintageNote(res), HUBZONE_OZ_CAVEAT, BENCHMARK_VINTAGE_NOTE, GEOID_STRING_NOTE];
+    const geoObj = geographiesRaw;
+    // Genuine-empty (200 geographies:{}) — an out-of-US point. All canonical layers null,
+    // matchCount:0, complete:true (NOT thrown; DISTINCT from the LOUD 400 of a bad coord).
+    if (Object.keys(geoObj).length === 0) {
+        const empty = {};
+        for (const spec of LAYER_SPECS)
+            empty[spec.field] = null;
+        notes.push("The point is not within a US Census geography (offshore / outside the US) — an honest empty (geographies:{}), not an error.");
+        return withMeta({
+            found: false,
+            coordinates,
+            geographies: empty,
+            benchmark,
+            vintage,
+            vintageResolved: res,
+        }, {
+            source: SOURCE,
+            keylessMode: true,
+            returned: 0,
+            totalAvailable: 0,
+            filtersApplied: ["benchmark", "vintage"],
+            filtersDropped: [],
+            fieldsUnavailable: [],
+            notes,
+        });
+    }
+    const { geo, notes: multiKeyNotes } = mapGeographies(geoObj, "census:" + PATH_COORDINATES, res.vintage);
+    for (const n of multiKeyNotes)
+        if (!notes.includes(n))
+            notes.push(n);
+    return withMeta({
+        found: true,
+        coordinates,
+        geographies: geo,
+        benchmark,
+        vintage,
+        vintageResolved: res,
+    }, {
+        source: SOURCE,
+        keylessMode: true,
+        returned: 1,
+        totalAvailable: 1,
+        filtersApplied: ["benchmark", "vintage"],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+//# sourceMappingURL=census.js.map

package/dist/census.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"census.js","sourceRoot":"","sources":["../src/census.ts"],"names":[],"mappings":"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"}