mailwoman 4.6.0 → 4.7.0

package/out/commands/geocode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geocode.d.ts","sourceRoot":"","sources":["../../commands/geocode.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAQH,OAAO,GAAG,MAAM,KAAK,CAAA;AAOrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAOrD,QAAA,MAAM,eAAe,6BAA4E,CAAA;AACjG,OAAO,EAAE,eAAe,IAAI,IAAI,EAAE,aAAa,IAAI,OAAO,EAAE,CAAA;AAE5D,QAAA,MAAM,aAAa;;;;;;;;;;;;qBAyDjB,CAAA;AAkHF,QAAA,MAAM,cAAc,EAAE,gBAAgB,CAAC,OAAO,aAAa,EAAE,OAAO,eAAe,CAgClF,CAAA;AAED,eAAe,cAAc,CAAA"}

package/out/commands/geocode.js

@@ -0,0 +1,214 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman geocode "<address>" [flags]` — end-to-end street-level geocoder.
+ *
+ *   Pipeline:
+ *     1. Parse the address with the neural classifier (same path as `parse` command).
+ *     2. Resolve admin hierarchy via `createWofResolver(WofSqlitePlaceLookup)`.
+ *     3. Augment with per-state address-point (situs) + interpolation shards, selected from
+ *        the resolved region. Both are optional — absent shards degrade gracefully to admin-only.
+ *     4. Extract the best available coordinate + resolution tier from the resolved tree and emit
+ *        a flat geocode result object.
+ *
+ *   Resolution tiers (best → worst):
+ *     - `address_point`  — exact situs coordinate from the address-points shard
+ *     - `interpolated`   — house-number estimate from the interpolation shard
+ *     - `admin`          — admin centroid from the WOF gazetteer
+ *
+ *   Exit-code contract:
+ *     - 0  successful geocode (including admin-only degradation when shards are absent)
+ *     - 1  bad arguments, missing required DB, or fatal parse/resolve error
+ */
+import { Spinner } from "@inkjs/ui";
+import { createWofResolver } from "@mailwoman/core/resolver";
+import { NeuralAddressClassifier } from "@mailwoman/neural";
+import { Text } from "ink";
+import { setImmediate } from "node:timers/promises";
+import { useEffect, useState } from "react";
+import zod from "zod";
+import { geocodeAddress, ShardProvider, } from "../geocode-core.js";
+import { resolverDefaultCountry } from "./parse.js";
+// ---------------------------------------------------------------------------
+// CLI contract — args + options
+// ---------------------------------------------------------------------------
+const ArgumentsSchema = zod.array(zod.string().describe("A formatted postal address to geocode"));
+export { ArgumentsSchema as args, OptionsSchema as options };
+const OptionsSchema = zod.object({
+    locale: zod
+        .string()
+        .regex(/^[a-z]{2}(-[A-Z]{2})?$/u, "Expected a BCP-47 tag like en-US or fr-FR")
+        .optional()
+        .default("en-US")
+        .describe("Locale tag matching a weights package (en-US, fr-FR). Default en-US."),
+    defaultCountry: zod
+        .string()
+        .optional()
+        .describe("ISO-3166 country to scope the WOF resolver. Defaults from --locale's region subtag (en-US → US). " +
+        "Pass 'none' to disable the country filter."),
+    resolveDb: zod
+        .string()
+        .optional()
+        .describe("Path to a WOF admin SQLite distribution. Defaults to $MAILWOMAN_WOF_DB; errors if neither is set."),
+    dataRoot: zod
+        .string()
+        .optional()
+        .default("/mnt/playpen/mailwoman-data")
+        .describe("Root directory for per-state address-point and interpolation shards. " +
+        "Shards are expected at <dataRoot>/address-points/address-points-us-<state>.db " +
+        "and <dataRoot>/interpolation/interpolation-us-<state>.db. Default: /mnt/playpen/mailwoman-data."),
+    addressPointsDb: zod
+        .string()
+        .optional()
+        .describe("Explicit path to an address-points (situs) SQLite shard. Bypasses the per-state shard selection " +
+        "from the resolved region. Use when you already know the right shard or are testing a specific file."),
+    interpolationDb: zod
+        .string()
+        .optional()
+        .describe("Explicit path to an interpolation SQLite shard. Bypasses the per-state shard selection. " +
+        "Use when you already know the right shard or are testing a specific file."),
+    interpCalibration: zod
+        .number()
+        .optional()
+        .default(1.7)
+        .describe("Conformal calibration multiplier for the interpolation tier's reported uncertainty_m (#374). " +
+        "The raw half-segment radius covers only ~72% of true errors; the default 1.7 (Travis-County " +
+        "calibration, 2026-06-14) lifts that to a ~90% bound. Pass 1 to report the raw heuristic radius."),
+    format: zod
+        .enum(["json", "text"])
+        .optional()
+        .default("json")
+        .describe('Output format. "json" (default) emits a machine-readable object; "text" prints a human summary.'),
+});
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+function resolveWofPath(options) {
+    const path = options.resolveDb ?? process.env["MAILWOMAN_WOF_DB"];
+    if (!path) {
+        throw new Error("geocode needs a WOF admin SQLite path. Set $MAILWOMAN_WOF_DB or pass --resolve-db <path>. " +
+            "Build one with `mailwoman-wof-build-slim` + `mailwoman-wof-build-fts`.");
+    }
+    return path;
+}
+// ---------------------------------------------------------------------------
+// Core geocode logic
+// ---------------------------------------------------------------------------
+async function runGeocode(input, options) {
+    // Resolve the WOF admin path FIRST — it's the most common missing prerequisite and the cheapest to
+    // check, so surface that error before the (slower) weights load. (Order matters for the CLI contract:
+    // a missing WOF DB must report the WOF error even when the weights are also absent.)
+    const wofPath = resolveWofPath(options);
+    // Load the neural classifier (required for street-level; weights must be present).
+    let classifier;
+    try {
+        classifier = await NeuralAddressClassifier.loadFromWeights({ locale: options.locale });
+    }
+    catch {
+        throw new Error("geocode requires the neural weights. Install @mailwoman/neural-weights-en-us (or pass --locale with installed weights).");
+    }
+    // Open the WOF admin resolver + the situs/interpolation shard provider.
+    let mod;
+    try {
+        mod = await import("@mailwoman/resolver-wof-sqlite");
+    }
+    catch {
+        throw new Error("geocode requires `@mailwoman/resolver-wof-sqlite` to be installed. " +
+            "Run `npm install @mailwoman/resolver-wof-sqlite` and try again.");
+    }
+    const lookup = new mod.WofSqlitePlaceLookup({ databasePath: wofPath });
+    const shardProvider = new ShardProvider(mod, options.dataRoot);
+    // Explicit --address-points-db / --interpolation-db flags override per-state selection (testing a
+    // specific file); an unset tier still falls back to the region-derived per-state shard.
+    const explicitAp = options.addressPointsDb ? new mod.AddressPointSqliteLookup(options.addressPointsDb) : undefined;
+    const explicitIp = options.interpolationDb ? new mod.StreetInterpolator({ dbPath: options.interpolationDb }) : undefined;
+    const shards = explicitAp || explicitIp
+        ? (slug) => {
+            const base = explicitAp && explicitIp ? {} : shardProvider.for(slug);
+            return { addressPoints: explicitAp ?? base.addressPoints, interpolation: explicitIp ?? base.interpolation };
+        }
+        : shardProvider.for;
+    try {
+        const resolver = createWofResolver(lookup);
+        const result = await geocodeAddress(input, {
+            classifier,
+            resolver,
+            shards,
+            defaultCountry: resolverDefaultCountry(options) || undefined,
+            interpCalibration: options.interpCalibration,
+        });
+        return options.format === "text" ? formatText(result) : JSON.stringify(result, null, 2);
+    }
+    finally {
+        explicitAp?.close();
+        explicitIp?.close();
+        shardProvider.close();
+        lookup.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Text formatter
+// ---------------------------------------------------------------------------
+function formatText(result) {
+    const lines = [];
+    lines.push(`input:            ${result.input}`);
+    lines.push(`resolution_tier:  ${result.resolution_tier}`);
+    if (result.lat != null && result.lon != null) {
+        lines.push(`coordinate:       ${result.lat.toFixed(6)}, ${result.lon.toFixed(6)}`);
+    }
+    else {
+        lines.push(`coordinate:       (unresolved)`);
+    }
+    if (result.uncertainty_m != null) {
+        lines.push(`uncertainty_m:    ${result.uncertainty_m}`);
+    }
+    if (result.locality)
+        lines.push(`locality:         ${result.locality}`);
+    if (result.region)
+        lines.push(`region:           ${result.region}`);
+    if (result.postcode)
+        lines.push(`postcode:         ${result.postcode}`);
+    if (result.hierarchy.length > 0) {
+        lines.push("hierarchy:");
+        for (const h of result.hierarchy) {
+            const coord = h.lat != null ? ` (${h.lat.toFixed(4)}, ${h.lon.toFixed(4)})` : "";
+            const id = h.placeId ? ` [${h.placeId}]` : "";
+            lines.push(`  ${h.tag.padEnd(20)} ${h.value}${id}${coord}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// React command component
+// ---------------------------------------------------------------------------
+const GeocodeCommand = ({ args, options }) => {
+    const [output, setOutput] = useState();
+    const [error, setError] = useState();
+    useEffect(() => {
+        if (error) {
+            setImmediate().then(() => process.exit(1));
+        }
+    }, [error]);
+    useEffect(() => {
+        const input = args[0];
+        if (!input || input.trim().length === 0) {
+            setError("geocode requires a positional address argument  (e.g. mailwoman geocode \"350 5th Ave, New York, NY\")");
+            return;
+        }
+        runGeocode(input.trim(), options)
+            .then(setOutput)
+            .catch((err) => setError(err.message));
+    }, [args, options]);
+    if (error) {
+        return _jsx(Text, { color: "red", children: error });
+    }
+    if (!output) {
+        return _jsx(Spinner, {});
+    }
+    return _jsx(Text, { children: output });
+};
+export default GeocodeCommand;
+//# sourceMappingURL=geocode.js.map

package/out/commands/geocode.js.map

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

package/out/commands/reverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reverse.d.ts","sourceRoot":"","sources":["../../commands/reverse.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,GAAG,MAAM,KAAK,CAAA;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAErD,QAAA,MAAM,eAAe,6BAEuE,CAAA;AAE5F,QAAA,MAAM,aAAa;;;;;;;qBAqBjB,CAAA;AAEF,OAAO,EAAE,eAAe,IAAI,IAAI,EAAE,aAAa,IAAI,OAAO,EAAE,CAAA;AA+E5D,QAAA,MAAM,cAAc,EAAE,gBAAgB,CAAC,OAAO,aAAa,EAAE,OAAO,eAAe,CA6ClF,CAAA;AAED,eAAe,cAAc,CAAA"}

package/out/commands/reverse.js

@@ -0,0 +1,143 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman reverse <lat> <lon>` — resolve a WGS-84 coordinate to its containing admin hierarchy
+ *   via the WofReverseGeocoder (#484).
+ *
+ *   Falls back to the MAILWOMAN_WOF_ADMIN_DB / MAILWOMAN_WOF_POLYGONS_DB env vars when the
+ *   corresponding flags are absent.  Prints a JSON object with the resolved hierarchy and the
+ *   containment kind (polygon | approximate) so callers can gauge result quality.
+ *
+ *   Exit-code contract:
+ *   - 0  successful reverse-geocode (including "open ocean" empty-hierarchy)
+ *   - 1  bad arguments or DB path missing / wrong
+ */
+import { Spinner } from "@inkjs/ui";
+import { Text } from "ink";
+import { setImmediate } from "node:timers/promises";
+import { useEffect, useState } from "react";
+import zod from "zod";
+const ArgumentsSchema = zod
+    .array(zod.string())
+    .describe("Positional args: <lat> <lon> — WGS-84 decimal degrees (e.g. 40.7128 -74.0060).");
+const OptionsSchema = zod.object({
+    adminDb: zod
+        .string()
+        .optional()
+        .describe("Path to the admin gazetteer SQLite DB (must carry the package-built place_bbox R*Tree). " +
+        "Defaults to $MAILWOMAN_WOF_ADMIN_DB."),
+    polygonsDb: zod
+        .string()
+        .optional()
+        .describe("Path to the polygon sidecar DB (wof-polygons.db, table polygons(id, geom)). " +
+        "Without it every result is containment: approximate. " +
+        "Defaults to $MAILWOMAN_WOF_POLYGONS_DB."),
+    format: zod
+        .enum(["json", "text"])
+        .optional()
+        .default("json")
+        .describe('Output format. "json" emits a machine-readable object; "text" prints a human-readable hierarchy.'),
+});
+export { ArgumentsSchema as args, OptionsSchema as options };
+function resolveAdminDbPath(options) {
+    const path = options.adminDb ?? process.env["MAILWOMAN_WOF_ADMIN_DB"];
+    if (!path) {
+        throw new Error("reverse needs an admin DB path. Set $MAILWOMAN_WOF_ADMIN_DB or pass --admin-db <path>. " +
+            "Build one with `mailwoman-wof-build-fts <path-to-wof.db>` after building the WOF SQLite " +
+            "distribution with `mailwoman-wof-build-slim`.");
+    }
+    return path;
+}
+function resolvePolygonsDbPath(options) {
+    return options.polygonsDb ?? process.env["MAILWOMAN_WOF_POLYGONS_DB"];
+}
+async function runReverse(lat, lon, options) {
+    let mod;
+    try {
+        mod = await import("@mailwoman/resolver-wof-sqlite");
+    }
+    catch {
+        throw new Error("reverse requires `@mailwoman/resolver-wof-sqlite` to be installed. " +
+            "Run `npm install @mailwoman/resolver-wof-sqlite` and try again.");
+    }
+    const adminDbPath = resolveAdminDbPath(options);
+    const polygonDbPath = resolvePolygonsDbPath(options);
+    const geocoder = new mod.WofReverseGeocoder({ adminDbPath, polygonDbPath });
+    try {
+        const result = await geocoder.reverseGeocode(lat, lon);
+        if (options.format === "text") {
+            const lines = [];
+            lines.push(`containment: ${result.containment}`);
+            if (result.hierarchy.length === 0) {
+                lines.push("(no admin hierarchy — point may be in open ocean or outside the gazetteer coverage)");
+            }
+            else {
+                for (const place of result.hierarchy) {
+                    const distStr = place.distanceKm !== undefined ? ` (~${place.distanceKm.toFixed(1)} km from centroid)` : "";
+                    lines.push(`  ${place.placetype.padEnd(16)} ${place.name} [wof:${place.id}]${distStr}`);
+                }
+            }
+            return lines.join("\n");
+        }
+        // JSON: emit a tidy object — the full hierarchy array + containment at the top level.
+        return JSON.stringify({
+            lat,
+            lon,
+            containment: result.containment,
+            hierarchy: result.hierarchy.map((p) => ({
+                id: p.id,
+                name: p.name,
+                placetype: p.placetype,
+                country: p.country,
+                lat: p.lat,
+                lon: p.lon,
+                ...(p.distanceKm !== undefined ? { distanceKm: p.distanceKm } : {}),
+            })),
+        }, null, 2);
+    }
+    finally {
+        geocoder.close();
+    }
+}
+const ReverseCommand = ({ args, options }) => {
+    const [output, setOutput] = useState();
+    const [error, setError] = useState();
+    useEffect(() => {
+        if (error) {
+            setImmediate().then(() => process.exit(1));
+        }
+    }, [error]);
+    useEffect(() => {
+        const rawLat = args[0];
+        const rawLon = args[1];
+        if (!rawLat || !rawLon) {
+            setError("reverse requires two positional arguments: <lat> <lon>  (e.g. mailwoman reverse 40.7128 -74.0060)");
+            return;
+        }
+        const lat = Number(rawLat);
+        const lon = Number(rawLon);
+        if (!Number.isFinite(lat) || Math.abs(lat) > 90) {
+            setError(`Invalid latitude ${JSON.stringify(rawLat)} — must be a number in [-90, 90].`);
+            return;
+        }
+        if (!Number.isFinite(lon) || Math.abs(lon) > 180) {
+            setError(`Invalid longitude ${JSON.stringify(rawLon)} — must be a number in [-180, 180].`);
+            return;
+        }
+        runReverse(lat, lon, options)
+            .then(setOutput)
+            .catch((err) => setError(err.message));
+    }, [args, options]);
+    if (error) {
+        return _jsx(Text, { color: "red", children: error });
+    }
+    if (!output) {
+        return _jsx(Spinner, {});
+    }
+    return _jsx(Text, { children: output });
+};
+export default ReverseCommand;
+//# sourceMappingURL=reverse.js.map

package/out/commands/reverse.js.map

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

package/out/commands/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../commands/serve.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,OAAO,GAAG,MAAM,KAAK,CAAA;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AA2HrD,eAAO,MAAM,OAAO;;;;qBAAqB,CAAA;AAEzC,QAAA,MAAM,YAAY;;;;sBAAmD,CAAA;AAErE,eAAe,YAAY,CAAA"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../commands/serve.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,OAAO,GAAG,MAAM,KAAK,CAAA;AACrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AA8HrD,eAAO,MAAM,OAAO;;;;qBAAqB,CAAA;AAEzC,QAAA,MAAM,YAAY;;;;sBAAmD,CAAA;AAErE,eAAe,YAAY,CAAA"}

package/out/commands/serve.js

@@ -14,7 +14,7 @@ import * as process from "node:process";
 import { fileURLToPath } from "node:url";
 import { useEffect, useState } from "react";
 import zod from "zod";
-import { AddressRouter, ResolveRouter } from "../server/index.js";
+import { AddressRouter, GeocodeRouter, HealthRouter, ResolveRouter } from "../server/index.js";
 const ClusterManager = ({ options: { cpus = availableParallelism() }, }) => {
     const [workers, setWorkers] = useState();
     useEffect(() => {
@@ -71,8 +71,11 @@ const WorkerStatus = ({ worker }) => {
 const ChildThread = ({ options: { port, host } }) => {
     useEffect(() => {
         const app = express();
-        app.use(express.json());
+        // 2mb body cap accommodates a full /api/batch (up to MAILWOMAN_BATCH_MAX addresses).
+        app.use(express.json({ limit: "2mb" }));
+        app.use(HealthRouter);
         app.use(AddressRouter);
+        app.use(GeocodeRouter);
         app.use(ResolveRouter);
         // `mailwoman/server/static/` lives next to the compiled `mailwoman/out/commands/serve.js`,
         // so resolve relative to this file rather than relying on a repo-root path builder that

package/out/commands/serve.js.map

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

package/out/data-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-release.d.ts","sourceRoot":"","sources":["../data-release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExD,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAYhF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAClC,MAAM,GAAG,IAAI,CAQf"}

package/out/data-release.js

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Versioned data-artifact addressing + atomic switchover (#485 piece 4). Shard DBs are addressed as
+ *   `<family>/<family>-us-<slug>-<version>.db`, with a `releases.json` manifest at the data root
+ *   pinning each family to its current version. So a new build publishes ALONGSIDE the old, flipping
+ *   the manifest (one atomic file write) cuts traffic over, and the build provenance (the version)
+ *   travels in the filename — "what data is deployed" is a read of one JSON.
+ *
+ *   Back-compat: with no manifest (or a family unlisted) resolution falls back to the legacy
+ *   unversioned `<family>-us-<slug>.db`, so the current national build output works unchanged.
+ *
+ *   Example `releases.json`:
+ *     { "address-points": "2026-05-20.0", "interpolation": "TIGER2023" }
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** Read `<dataRoot>/releases.json`. Returns null (legacy mode) when absent or malformed. */
+export function readReleaseManifest(dataRoot) {
+    try {
+        const raw = JSON.parse(readFileSync(`${dataRoot}/releases.json`, "utf8"));
+        if (!raw || typeof raw !== "object")
+            return null;
+        const out = {};
+        for (const [family, version] of Object.entries(raw)) {
+            if (typeof version === "string" && version)
+                out[family] = version;
+        }
+        return Object.keys(out).length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a shard's on-disk path: the manifest-pinned `<family>-us-<slug>-<version>.db` when present,
+ * else the legacy unversioned `<family>-us-<slug>.db`, else null if neither exists.
+ */
+export function resolveShardPath(dataRoot, family, slug, manifest) {
+    const version = manifest?.[family];
+    if (version) {
+        const versioned = `${dataRoot}/${family}/${family}-us-${slug}-${version}.db`;
+        if (existsSync(versioned))
+            return versioned;
+    }
+    const legacy = `${dataRoot}/${family}/${family}-us-${slug}.db`;
+    return existsSync(legacy) ? legacy : null;
+}
+//# sourceMappingURL=data-release.js.map

package/out/data-release.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-release.js","sourceRoot":"","sources":["../data-release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAKlD,4FAA4F;AAC5F,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IACnD,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,QAAQ,gBAAgB,EAAE,MAAM,CAAC,CAAY,CAAA;QACpF,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QAChD,MAAM,GAAG,GAAwB,EAAE,CAAA;QACnC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAA8B,CAAC,EAAE,CAAC;YAChF,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAA;QAClE,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;IAChD,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC/B,QAAgB,EAChB,MAAc,EACd,IAAY,EACZ,QAAoC;IAEpC,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,OAAO,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,GAAG,QAAQ,IAAI,MAAM,IAAI,MAAM,OAAO,IAAI,IAAI,OAAO,KAAK,CAAA;QAC5E,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAA;IAC5C,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,MAAM,IAAI,MAAM,OAAO,IAAI,KAAK,CAAA;IAC9D,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1C,CAAC"}

package/out/geocode-core.d.ts.map

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

package/out/geocode-core.js

@@ -0,0 +1,225 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Shared street-level geocode cascade — the reusable core behind the `geocode` CLI command AND the
+ *   server's `/api/geocode` + `/api/batch` endpoints (#485). One implementation of the cascade, so the
+ *   CLI and the service never drift.
+ *
+ *   Cascade (the eval-validated path — 98.8% within 100m on the non-circular Travis holdout):
+ *     1. RAW neural parse (`classifier.parse`, postcodeRepair). NOT the runtime pipeline — its
+ *        reconcile stage merges street INTO house_number, dropping the street node the coordinate
+ *        tiers need (#566).
+ *     2. Read the parsed region → pick the per-state situs + interpolation shards.
+ *     3. `resolveTree` with the coordinate tiers wired (additive; admin-only when shards absent).
+ *     4. Extract the best coordinate + resolution tier (address_point > interpolated > admin).
+ *
+ *   The cascade depends on a {@link ShardResolver} — a `(stateSlug) => { addressPoints?, interpolation? }`
+ *   function — so the CLI (honoring its explicit `--address-points-db` flags) and the server (a cached
+ *   {@link ShardProvider}) supply shards their own way without the core knowing how.
+ */
+import { existsSync } from "node:fs";
+import { readReleaseManifest, resolveShardPath } from "./data-release.js";
+/** Lowercase 2-letter state slug from a parsed region value / resolver name, else null. */
+export function regionToStateSlug(regionValue, resolverName) {
+    for (const candidate of [regionValue, resolverName]) {
+        if (!candidate)
+            continue;
+        const trimmed = candidate.trim();
+        if (/^[A-Za-z]{2}$/.test(trimmed))
+            return trimmed.toLowerCase();
+    }
+    return null;
+}
+/** Walk a (parsed or resolved) tree for its region → the per-state shard slug (e.g. `"tx"`), else null. */
+export function regionSlugFromTree(tree) {
+    let regionValue = null;
+    let regionResolverName = null;
+    const stack = [...tree.roots];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node.tag === "region" && !regionValue) {
+            regionValue = node.value.trim() || null;
+            regionResolverName = node.metadata?.["resolver_name"] ?? null;
+        }
+        stack.push(...node.children);
+    }
+    return regionToStateSlug(regionValue, regionResolverName);
+}
+/** Per-state situs shard path under `<dataRoot>/address-points/`, or null if the slug/file is absent. */
+export function selectAddressPointsDb(dataRoot, stateSlug) {
+    if (!stateSlug)
+        return null;
+    const candidate = `${dataRoot}/address-points/address-points-us-${stateSlug}.db`;
+    return existsSync(candidate) ? candidate : null;
+}
+/** Per-state interpolation shard path under `<dataRoot>/interpolation/`, or null if absent. */
+export function selectInterpolationDb(dataRoot, stateSlug) {
+    if (!stateSlug)
+        return null;
+    const candidate = `${dataRoot}/interpolation/interpolation-us-${stateSlug}.db`;
+    return existsSync(candidate) ? candidate : null;
+}
+/**
+ * Opens + CACHES per-state situs/interpolation lookups so a batch geocoding many addresses in one
+ * state opens that state's (possibly multi-GB) shards once, not once per row. Versioned-data aware
+ * (#485): paths resolve through the `releases.json` manifest (legacy unversioned fallback), and
+ * {@link reload} performs a zero-downtime atomic switchover when a new version is published. Call
+ * {@link close} when done to release every cached handle.
+ */
+export class ShardProvider {
+    #factory;
+    #dataRoot;
+    #cache = new Map();
+    /** Previous-generation handles, retired by reload() and closed on the NEXT reload (one-gen grace). */
+    #retired = [];
+    #manifest;
+    constructor(factory, dataRoot) {
+        this.#factory = factory;
+        this.#dataRoot = dataRoot;
+        this.#manifest = readReleaseManifest(dataRoot);
+    }
+    #open(stateSlug) {
+        const apPath = resolveShardPath(this.#dataRoot, "address-points", stateSlug, this.#manifest);
+        const ipPath = resolveShardPath(this.#dataRoot, "interpolation", stateSlug, this.#manifest);
+        const ap = apPath ? new this.#factory.AddressPointSqliteLookup(apPath) : undefined;
+        const ip = ipPath ? new this.#factory.StreetInterpolator({ dbPath: ipPath }) : undefined;
+        return { addressPoints: ap, interpolation: ip, _ap: ap, _ip: ip, apPath, ipPath };
+    }
+    for = (stateSlug) => {
+        if (!stateSlug)
+            return {};
+        let entry = this.#cache.get(stateSlug);
+        if (!entry) {
+            entry = this.#open(stateSlug);
+            this.#cache.set(stateSlug, entry);
+        }
+        return { addressPoints: entry.addressPoints, interpolation: entry.interpolation };
+    };
+    /** The current data-release versions ({@link readReleaseManifest}), or null in legacy mode. */
+    versions() {
+        return this.#manifest ? { ...this.#manifest } : null;
+    }
+    /**
+     * Re-read the manifest and atomically swap any cached shard whose resolved path changed. New
+     * requests see the new version immediately; the old handles are RETIRED and closed on the next
+     * reload (one-generation grace — safe because find() is synchronous, so no in-flight query can
+     * still hold a handle once a request yields). Returns the new version map.
+     */
+    reload() {
+        for (const h of this.#retired)
+            h.close();
+        this.#retired = [];
+        this.#manifest = readReleaseManifest(this.#dataRoot);
+        for (const [slug, old] of this.#cache) {
+            const apPath = resolveShardPath(this.#dataRoot, "address-points", slug, this.#manifest);
+            const ipPath = resolveShardPath(this.#dataRoot, "interpolation", slug, this.#manifest);
+            if (apPath === old.apPath && ipPath === old.ipPath)
+                continue; // unchanged — keep the open handle
+            this.#cache.set(slug, this.#open(slug));
+            if (old._ap)
+                this.#retired.push(old._ap);
+            if (old._ip)
+                this.#retired.push(old._ip);
+        }
+        return this.versions();
+    }
+    close() {
+        for (const e of this.#cache.values()) {
+            e._ap?.close();
+            e._ip?.close();
+        }
+        for (const h of this.#retired)
+            h.close();
+        this.#cache.clear();
+        this.#retired = [];
+    }
+}
+/**
+ * Run the full street-level cascade on one address and return the structured geocode result. Always
+ * returns a result (admin tier even with no coordinate shards). Throws only on a fatal parse/resolve
+ * error — callers doing batch work should catch per-row.
+ */
+export async function geocodeAddress(input, deps) {
+    const tree = await deps.classifier.parse(input, { postcodeRepair: true });
+    const stateSlug = regionSlugFromTree(tree);
+    const { addressPoints, interpolation } = deps.shards?.(stateSlug) ?? {};
+    const opts = {};
+    if (deps.defaultCountry)
+        opts.defaultCountry = deps.defaultCountry;
+    if (addressPoints)
+        opts.addressPoints = addressPoints;
+    if (interpolation) {
+        opts.interpolation = interpolation;
+        if (deps.interpCalibration && deps.interpCalibration !== 1) {
+            opts.interpolationRadiusCalibration = deps.interpCalibration;
+        }
+    }
+    const resolved = await deps.resolver.resolveTree(tree, opts);
+    return extractGeocodeResult(input, resolved);
+}
+/**
+ * Walk the resolved tree and extract the geocode result: the street node's address-point /
+ * interpolation coordinate (whichever tier won), else the best admin centroid (locality → region →
+ * country).
+ */
+export function extractGeocodeResult(input, tree) {
+    const allNodes = [];
+    const flatten = (nodes) => {
+        for (const n of nodes) {
+            allNodes.push(n);
+            flatten(n.children);
+        }
+    };
+    flatten(tree.roots);
+    const streetNode = allNodes.find((n) => n.tag === "street");
+    let lat = null;
+    let lon = null;
+    let tier = "admin";
+    let uncertaintyM = null;
+    if (streetNode?.metadata?.["resolution_tier"] === "address_point") {
+        const ap = streetNode.metadata["address_point"];
+        if (ap) {
+            lat = ap.lat;
+            lon = ap.lon;
+            tier = "address_point";
+            uncertaintyM = 1; // Floor: situs point is essentially exact.
+        }
+    }
+    if (tier !== "address_point" && streetNode?.metadata?.["resolution_tier"] === "interpolated") {
+        const ip = streetNode.metadata["interpolated_point"];
+        if (ip) {
+            lat = ip.lat;
+            lon = ip.lon;
+            tier = "interpolated";
+            uncertaintyM = streetNode.metadata["uncertainty_m"] ?? null;
+        }
+    }
+    if (tier === "admin") {
+        const adminPriority = ["locality", "dependent_locality", "region", "country"];
+        for (const tag of adminPriority) {
+            const node = allNodes.find((n) => n.tag === tag && n.lat != null && n.lon != null);
+            if (node) {
+                lat = node.lat;
+                lon = node.lon;
+                break;
+            }
+        }
+    }
+    const locality = allNodes.find((n) => n.tag === "locality" || n.tag === "dependent_locality")?.value?.trim() || null;
+    const region = allNodes.find((n) => n.tag === "region")?.value?.trim() || null;
+    const postcode = allNodes.find((n) => n.tag === "postcode")?.value?.trim() || null;
+    const HIERARCHY_TAGS = ["locality", "dependent_locality", "subregion", "region", "country"];
+    const hierarchy = allNodes
+        .filter((n) => HIERARCHY_TAGS.includes(n.tag) && (n.lat != null || n.placeId))
+        .sort((a, b) => HIERARCHY_TAGS.indexOf(a.tag) - HIERARCHY_TAGS.indexOf(b.tag))
+        .map((n) => ({
+        tag: n.tag,
+        value: n.value.trim(),
+        ...(n.lat != null ? { lat: n.lat, lon: n.lon } : {}),
+        ...(n.placeId ? { placeId: n.placeId } : {}),
+    }));
+    return { input, lat, lon, resolution_tier: tier, uncertainty_m: uncertaintyM, locality, region, postcode, hierarchy };
+}
+//# sourceMappingURL=geocode-core.js.map

package/out/geocode-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geocode-core.js","sourceRoot":"","sources":["../geocode-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEpC,OAAO,EAA4B,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAqDnG,2FAA2F;AAC3F,MAAM,UAAU,iBAAiB,CAChC,WAAsC,EACtC,YAAuC;IAEvC,KAAK,MAAM,SAAS,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,SAAS;YAAE,SAAQ;QACxB,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAA;QAChC,IAAI,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,OAAO,CAAC,WAAW,EAAE,CAAA;IAChE,CAAC;IACD,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,2GAA2G;AAC3G,MAAM,UAAU,kBAAkB,CAAC,IAAiB;IACnD,IAAI,WAAW,GAAkB,IAAI,CAAA;IACrC,IAAI,kBAAkB,GAAkB,IAAI,CAAA;IAC5C,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAG,CAAA;QACzB,IAAI,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,WAAW,EAAE,CAAC;YAC3C,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,IAAI,CAAA;YACvC,kBAAkB,GAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,eAAe,CAAwB,IAAI,IAAI,CAAA;QACtF,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC7B,CAAC;IACD,OAAO,iBAAiB,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAA;AAC1D,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,SAAwB;IAC/E,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAA;IAC3B,MAAM,SAAS,GAAG,GAAG,QAAQ,qCAAqC,SAAS,KAAK,CAAA;IAChF,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;AAChD,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,SAAwB;IAC/E,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAA;IAC3B,MAAM,SAAS,GAAG,GAAG,QAAQ,mCAAmC,SAAS,KAAK,CAAA;IAC9E,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAA;AAChD,CAAC;AAgBD;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IAChB,QAAQ,CAAoB;IAC5B,SAAS,CAAQ;IACjB,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAA;IACpD,sGAAsG;IACtG,QAAQ,GAA6B,EAAE,CAAA;IACvC,SAAS,CAA4B;IAErC,YAAY,OAA2B,EAAE,QAAgB;QACxD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;QACvB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,SAAS,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IAC/C,CAAC;IAED,KAAK,CAAC,SAAiB;QACtB,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QAC5F,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QAC3F,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAClF,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACxF,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;IAClF,CAAC;IAEQ,GAAG,GAAkB,CAAC,SAAS,EAAE,EAAE;QAC3C,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,CAAA;QACzB,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;YAC7B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;QAClC,CAAC;QACD,OAAO,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,CAAA;IAClF,CAAC,CAAA;IAED,+FAA+F;IAC/F,QAAQ;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IACrD,CAAC;IAED;;;;;OAKG;IACH,MAAM;QACL,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,CAAC,CAAC,KAAK,EAAE,CAAA;QACxC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;QAClB,IAAI,CAAC,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QACpD,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YACvF,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YACtF,IAAI,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,MAAM,KAAK,GAAG,CAAC,MAAM;gBAAE,SAAQ,CAAC,mCAAmC;YAChG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;YACvC,IAAI,GAAG,CAAC,GAAG;gBAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACxC,IAAI,GAAG,CAAC,GAAG;gBAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACzC,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAA;IACvB,CAAC;IAED,KAAK;QACJ,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,CAAA;YACd,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,CAAA;QACf,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ;YAAE,CAAC,CAAC,KAAK,EAAE,CAAA;QACxC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;QACnB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;IACnB,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAa,EAAE,IAAiB;IACpE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAA;IACzE,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;IAC1C,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;IAEvE,MAAM,IAAI,GAAgB,EAAE,CAAA;IAC5B,IAAI,IAAI,CAAC,cAAc;QAAE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAA;IAClE,IAAI,aAAa;QAAE,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;IACrD,IAAI,aAAa,EAAE,CAAC;QACnB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;QAClC,IAAI,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,iBAAiB,KAAK,CAAC,EAAE,CAAC;YAC5D,IAAI,CAAC,8BAA8B,GAAG,IAAI,CAAC,iBAAiB,CAAA;QAC7D,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC5D,OAAO,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,IAAiB;IACpE,MAAM,QAAQ,GAAkB,EAAE,CAAA;IAClC,MAAM,OAAO,GAAG,CAAC,KAA6B,EAAE,EAAE;QACjD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAChB,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;QACpB,CAAC;IACF,CAAC,CAAA;IACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAEnB,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAA;IAE3D,IAAI,GAAG,GAAkB,IAAI,CAAA;IAC7B,IAAI,GAAG,GAAkB,IAAI,CAAA;IAC7B,IAAI,IAAI,GAAmB,OAAO,CAAA;IAClC,IAAI,YAAY,GAAkB,IAAI,CAAA;IAEtC,IAAI,UAAU,EAAE,QAAQ,EAAE,CAAC,iBAAiB,CAAC,KAAK,eAAe,EAAE,CAAC;QACnE,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,eAAe,CAA6C,CAAA;QAC3F,IAAI,EAAE,EAAE,CAAC;YACR,GAAG,GAAG,EAAE,CAAC,GAAG,CAAA;YACZ,GAAG,GAAG,EAAE,CAAC,GAAG,CAAA;YACZ,IAAI,GAAG,eAAe,CAAA;YACtB,YAAY,GAAG,CAAC,CAAA,CAAC,2CAA2C;QAC7D,CAAC;IACF,CAAC;IAED,IAAI,IAAI,KAAK,eAAe,IAAI,UAAU,EAAE,QAAQ,EAAE,CAAC,iBAAiB,CAAC,KAAK,cAAc,EAAE,CAAC;QAC9F,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,oBAAoB,CAA6C,CAAA;QAChG,IAAI,EAAE,EAAE,CAAC;YACR,GAAG,GAAG,EAAE,CAAC,GAAG,CAAA;YACZ,GAAG,GAAG,EAAE,CAAC,GAAG,CAAA;YACZ,IAAI,GAAG,cAAc,CAAA;YACrB,YAAY,GAAI,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAwB,IAAI,IAAI,CAAA;QACpF,CAAC;IACF,CAAC;IAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACtB,MAAM,aAAa,GAA0B,CAAC,UAAU,EAAE,oBAAoB,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAA;QACpG,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAA;YAClF,IAAI,IAAI,EAAE,CAAC;gBACV,GAAG,GAAG,IAAI,CAAC,GAAI,CAAA;gBACf,GAAG,GAAG,IAAI,CAAC,GAAI,CAAA;gBACf,MAAK;YACN,CAAC;QACF,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GACb,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,CAAC,CAAC,GAAG,KAAK,oBAAoB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAA;IACpG,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAA;IAC9E,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAA;IAElF,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,oBAAoB,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAA;IAC3F,MAAM,SAAS,GAAG,QAAQ;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC;SAC7E,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;SAC7E,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACZ,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE;QACrB,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,GAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC,CAAC,CAAA;IAEJ,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AACtH,CAAC"}

package/out/server/GeocodeRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GeocodeRouter.d.ts","sourceRoot":"","sources":["../../server/GeocodeRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAuB,MAAM,EAAE,MAAM,SAAS,CAAA;AAyNrD,eAAO,MAAM,aAAa,EAAE,MAAiB,CAAA"}

package/out/server/GeocodeRouter.js

@@ -0,0 +1,210 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Street-level geocoding endpoints (#485, piece 1):
+ *     - `POST /api/geocode` — `{ address }` → one {@link GeocodeResult} (parse → situs → interp → admin).
+ *     - `POST /api/batch`   — `{ addresses: string[] }` → results in input order, BOUNDED concurrency,
+ *       PER-ROW error isolation (one bad address never fails the batch — it gets an `{ error }` slot).
+ *
+ *   Runs the SAME cascade as the `geocode` CLI (`mailwoman/geocode-core.ts`), so the service and the
+ *   CLI never drift. Deps (classifier + resolver + a cached {@link ShardProvider}) are lazy-loaded
+ *   ONCE on first hit and reused; the per-state shard cache means a batch hitting many CA addresses
+ *   opens CA's situs shard once, not per row.
+ */
+import { createWofResolver } from "@mailwoman/core/resolver";
+import { Router } from "express";
+import { existsSync } from "node:fs";
+import { geocodeAddress, regionSlugFromTree, ShardProvider, } from "../geocode-core.js";
+import { recordGeocode } from "./metrics.js";
+/** Default per-state shard root + interp calibration — mirror the CLI defaults. */
+const DATA_ROOT = process.env["MAILWOMAN_DATA_ROOT"] ?? "/mnt/playpen/mailwoman-data";
+const INTERP_CALIBRATION = 1.7;
+/** Bounded concurrency for `/api/batch`. Override with MAILWOMAN_BATCH_CONCURRENCY. */
+const BATCH_CONCURRENCY = Math.max(1, Number(process.env["MAILWOMAN_BATCH_CONCURRENCY"] ?? "8"));
+/** Hard cap on batch size — a guardrail against unbounded request bodies. */
+const BATCH_MAX = Math.max(1, Number(process.env["MAILWOMAN_BATCH_MAX"] ?? "1000"));
+function wofPaths() {
+    const env = process.env["MAILWOMAN_WOF_DB"];
+    if (env)
+        return env.split(",").map((p) => p.trim()).filter(Boolean);
+    return ["/mnt/playpen/mailwoman-data/wof/admin-global-priority.db", "/mnt/playpen/mailwoman-data/wof/postalcode-us.db"].filter((p) => existsSync(p));
+}
+let depsPromise = null;
+async function getDeps() {
+    if (depsPromise)
+        return depsPromise;
+    depsPromise = (async () => {
+        let neuralMod;
+        let resolverMod;
+        try {
+            neuralMod = await import("@mailwoman/neural");
+            resolverMod = await import("@mailwoman/resolver-wof-sqlite");
+        }
+        catch {
+            console.error("GeocodeRouter: @mailwoman/neural + @mailwoman/resolver-wof-sqlite are required");
+            return null;
+        }
+        const paths = wofPaths();
+        if (paths.length === 0) {
+            console.error("GeocodeRouter: no WOF DBs found — set MAILWOMAN_WOF_DB");
+            return null;
+        }
+        const classifier = await neuralMod.NeuralAddressClassifier.loadFromWeights({ locale: "en-US" });
+        const backend = new resolverMod.WofSqlitePlaceLookup({ databasePath: paths.length === 1 ? paths[0] : paths });
+        const resolver = createWofResolver(backend);
+        const shards = new ShardProvider(resolverMod, DATA_ROOT);
+        return { classifier, resolver, shards, defaultCountry: "US" };
+    })();
+    return depsPromise;
+}
+function oneGeocode(deps, address) {
+    return geocodeAddress(address, {
+        classifier: deps.classifier,
+        resolver: deps.resolver,
+        shards: deps.shards.for,
+        defaultCountry: deps.defaultCountry,
+        interpCalibration: INTERP_CALIBRATION,
+    });
+}
+const DEPS_UNAVAILABLE = {
+    error: "Geocoder not available. Install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and set MAILWOMAN_WOF_DB.",
+};
+const singleHandler = async (req, res) => {
+    const address = typeof req.body?.address === "string" ? req.body.address.trim() : "";
+    if (!address) {
+        res.status(400).json({ error: "Missing `address` (string)" });
+        return;
+    }
+    const deps = await getDeps();
+    if (!deps) {
+        res.status(503).json(DEPS_UNAVAILABLE);
+        return;
+    }
+    const t0 = performance.now();
+    try {
+        const result = await oneGeocode(deps, address);
+        recordGeocode(performance.now() - t0, result.resolution_tier);
+        res.status(200).json(result);
+    }
+    catch (err) {
+        recordGeocode(performance.now() - t0, "error");
+        res.status(500).json({ error: `geocode error: ${err instanceof Error ? err.message : String(err)}` });
+    }
+};
+const batchHandler = async (req, res) => {
+    const addresses = req.body?.addresses;
+    if (!Array.isArray(addresses) || addresses.some((a) => typeof a !== "string")) {
+        res.status(400).json({ error: "Body must be `{ addresses: string[] }`" });
+        return;
+    }
+    if (addresses.length === 0) {
+        res.status(200).json({ results: [] });
+        return;
+    }
+    if (addresses.length > BATCH_MAX) {
+        res.status(413).json({ error: `Batch too large: ${addresses.length} > ${BATCH_MAX} (MAILWOMAN_BATCH_MAX)` });
+        return;
+    }
+    const deps = await getDeps();
+    if (!deps) {
+        res.status(503).json(DEPS_UNAVAILABLE);
+        return;
+    }
+    const inputs = addresses.map((a) => a.trim());
+    const results = new Array(inputs.length);
+    // Bounded-concurrency worker pool over a shared cursor — results land in input order; a thrown
+    // row is isolated to its own slot. The shard cache makes same-state rows cheap after the first.
+    let cursor = 0;
+    const worker = async () => {
+        for (let i = cursor++; i < inputs.length; i = cursor++) {
+            const input = inputs[i];
+            const t0 = performance.now();
+            try {
+                const result = await oneGeocode(deps, input);
+                recordGeocode(performance.now() - t0, result.resolution_tier);
+                results[i] = result;
+            }
+            catch (err) {
+                recordGeocode(performance.now() - t0, "error");
+                results[i] = { input, error: err instanceof Error ? err.message : String(err) };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(BATCH_CONCURRENCY, inputs.length) }, worker));
+    res.status(200).json({ results });
+};
+/**
+ * `POST /api/resolve-tree` — the resolver-service endpoint that `RemoteResolver` (core) calls. Accepts
+ * an already-parsed `{ tree, opts? }`, selects this region's situs/interpolation shards (the data lives
+ * here, not on the caller), runs the FULL cascade, and returns `{ tree }`. This is what lets a
+ * stateless parser node geocode at street level against a shared resolver service.
+ */
+const resolveTreeHandler = async (req, res) => {
+    const tree = req.body?.tree;
+    if (!tree || !Array.isArray(tree.roots)) {
+        res.status(400).json({ error: "Body must be `{ tree: AddressTree, opts?: ResolveOpts }`" });
+        return;
+    }
+    const incomingOpts = (req.body?.opts ?? {});
+    const deps = await getDeps();
+    if (!deps) {
+        res.status(503).json(DEPS_UNAVAILABLE);
+        return;
+    }
+    const t0 = performance.now();
+    try {
+        const { addressPoints, interpolation } = deps.shards.for(regionSlugFromTree(tree));
+        const opts = {
+            ...incomingOpts,
+            defaultCountry: incomingOpts.defaultCountry ?? deps.defaultCountry,
+            ...(addressPoints ? { addressPoints } : {}),
+            ...(interpolation
+                ? { interpolation, interpolationRadiusCalibration: incomingOpts.interpolationRadiusCalibration ?? INTERP_CALIBRATION }
+                : {}),
+        };
+        const resolved = await deps.resolver.resolveTree(tree, opts);
+        // Best-effort tier metric: read the street node's stamped tier (matches the geocode path).
+        const street = resolved.roots.flatMap((r) => collectStreetTier(r)).find(Boolean);
+        recordGeocode(performance.now() - t0, street ?? "admin");
+        res.status(200).json({ tree: resolved });
+    }
+    catch (err) {
+        recordGeocode(performance.now() - t0, "error");
+        res.status(500).json({ error: `resolve-tree error: ${err instanceof Error ? err.message : String(err)}` });
+    }
+};
+/** Pull the street node's resolution tier (if any) for the metric — mirrors extractGeocodeResult. */
+function collectStreetTier(node) {
+    const out = [];
+    if (node.tag === "street") {
+        const tier = node.metadata?.["resolution_tier"];
+        if (tier === "address_point" || tier === "interpolated")
+            out.push(tier);
+    }
+    for (const child of node.children)
+        out.push(...collectStreetTier(child));
+    return out;
+}
+/**
+ * `POST /api/reload` — versioned data switchover (#485). Re-reads `releases.json` and atomically swaps
+ * any per-state shard whose pinned version changed (zero-downtime, one-generation grace on the old
+ * handles). Call this after publishing a new shard build to cut traffic over without a restart. Returns
+ * the new version map. (Deploy-only; gate it behind your ingress — no auth here by design, per #485.)
+ */
+const reloadHandler = async (_req, res) => {
+    const deps = await getDeps();
+    if (!deps) {
+        res.status(503).json(DEPS_UNAVAILABLE);
+        return;
+    }
+    const versions = deps.shards.reload();
+    res.status(200).json({ reloaded: true, versions });
+};
+export const GeocodeRouter = Router();
+GeocodeRouter.post("/api/geocode", singleHandler);
+GeocodeRouter.post("/api/batch", batchHandler);
+GeocodeRouter.post("/api/resolve-tree", resolveTreeHandler);
+GeocodeRouter.post("/api/reload", reloadHandler);
+//# sourceMappingURL=GeocodeRouter.js.map

package/out/server/GeocodeRouter.js.map

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

package/out/server/HealthRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealthRouter.d.ts","sourceRoot":"","sources":["../../server/HealthRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAuB,MAAM,EAAE,MAAM,SAAS,CAAA;AA6ErD,eAAO,MAAM,YAAY,EAAE,MAAiB,CAAA"}

package/out/server/HealthRouter.js

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Operational endpoints (#485 observability):
+ *     - `GET /health`  — "what's deployed, in one curl": model-card name/version/locale + which WOF
+ *       gazetteer and how many per-state situs/interpolation shards are on disk. LIGHTWEIGHT — reads
+ *       JSON + counts files, never loads the model, never throws (health must answer even when broken).
+ *     - `GET /metrics` — the live geocode metrics snapshot (latency percentiles + per-tier counts).
+ */
+import { Router } from "express";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { readReleaseManifest } from "../data-release.js";
+import { metricsSnapshot } from "./metrics.js";
+const DATA_ROOT = process.env["MAILWOMAN_DATA_ROOT"] ?? "/mnt/playpen/mailwoman-data";
+const startedAt = Date.now();
+/** Best-effort model-card read: env override → installed weights package → dev-tree fallback. */
+function readModelCard() {
+    const candidates = [];
+    if (process.env["MAILWOMAN_MODEL_CARD"])
+        candidates.push(process.env["MAILWOMAN_MODEL_CARD"]);
+    try {
+        candidates.push(createRequire(import.meta.url).resolve("@mailwoman/neural-weights-en-us/model-card.json"));
+    }
+    catch {
+        /* package not resolvable from here — fall through */
+    }
+    candidates.push("neural-weights-en-us/model-card.json");
+    for (const p of candidates) {
+        try {
+            if (existsSync(p))
+                return JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            /* unreadable / malformed — try the next candidate */
+        }
+    }
+    return null;
+}
+/** Count canonical per-state shards (`<prefix>-us-<2-letter>.db`) in a data subdir; 0 if absent. */
+function countShards(subdir, prefix) {
+    try {
+        const re = new RegExp(`^${prefix}-us-[a-z]{2}\\.db$`);
+        return readdirSync(`${DATA_ROOT}/${subdir}`).filter((f) => re.test(f)).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function wofPaths() {
+    const env = process.env["MAILWOMAN_WOF_DB"];
+    const paths = env
+        ? env.split(",").map((p) => p.trim()).filter(Boolean)
+        : ["/mnt/playpen/mailwoman-data/wof/admin-global-priority.db", "/mnt/playpen/mailwoman-data/wof/postalcode-us.db"];
+    return paths.filter((p) => existsSync(p));
+}
+const healthHandler = (_req, res) => {
+    const card = readModelCard();
+    res.status(200).json({
+        status: "ok",
+        uptime_s: Math.round((Date.now() - startedAt) / 1000),
+        model: card
+            ? {
+                name: card["name"],
+                version: card["version"],
+                locale: card["locale"],
+                labels: Array.isArray(card["labels"]) ? card["labels"].length : undefined,
+                format: card["format"],
+            }
+            : null,
+        data: {
+            data_root: DATA_ROOT,
+            // Versioned-switchover provenance (#485): the releases.json pin, or null in legacy mode.
+            versions: readReleaseManifest(DATA_ROOT),
+            wof_dbs: wofPaths(),
+            situs_states: countShards("address-points", "address-points"),
+            interpolation_states: countShards("interpolation", "interpolation"),
+        },
+    });
+};
+const metricsHandler = (_req, res) => {
+    res.status(200).json(metricsSnapshot());
+};
+export const HealthRouter = Router();
+HealthRouter.get("/health", healthHandler);
+HealthRouter.get("/metrics", metricsHandler);
+//# sourceMappingURL=HealthRouter.js.map

package/out/server/HealthRouter.js.map

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

package/out/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/out/server/index.js

@@ -4,5 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 export * from "./AddressRouter.js";
+export * from "./GeocodeRouter.js";
+export * from "./HealthRouter.js";
 export * from "./ResolveRouter.js";
 //# sourceMappingURL=index.js.map

package/out/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/out/server/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../server/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAaxD,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,GAAG,IAAI,CAarF;AAQD,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QACR,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAA;QACrC,UAAU,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;QACzE,eAAe,EAAE,MAAM,CAAA;KACvB,CAAA;CACD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,IAAI,eAAe,CAmBjD;AAED,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAQ5C"}

package/out/server/metrics.js

@@ -0,0 +1,74 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   In-process geocode metrics (#485 observability). Dependency-free: monotonic counters per
+ *   resolution tier + a bounded reservoir of recent latencies for percentile estimation. The issue
+ *   asks to MEASURE the SLO targets (p99 ≤ 100ms admin, ≤ 250ms with situs) rather than invent them —
+ *   this is the instrument. Surfaced by `GET /metrics`; reset on process restart (no persistence —
+ *   scrape it).
+ */
+/** Recent-latency reservoir size. ~2k samples gives stable p99 without unbounded memory. */
+const MAX_SAMPLES = 2048;
+const latencies = [];
+let writeIdx = 0;
+const tierCounts = { address_point: 0, interpolated: 0, admin: 0 };
+let total = 0;
+let errors = 0;
+const startedAt = Date.now();
+/** Record one completed geocode: its wall-clock latency and which tier produced it (or `"error"`). */
+export function recordGeocode(latencyMs, tier) {
+    total++;
+    if (tier === "error") {
+        errors++;
+    }
+    else {
+        tierCounts[tier]++;
+    }
+    if (latencies.length < MAX_SAMPLES) {
+        latencies.push(latencyMs);
+    }
+    else {
+        latencies[writeIdx] = latencyMs;
+        writeIdx = (writeIdx + 1) % MAX_SAMPLES;
+    }
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.min(sorted.length - 1, Math.floor(p * sorted.length));
+    return Math.round(sorted[idx] * 100) / 100;
+}
+/** Current metrics snapshot — sorted-reservoir percentiles + counters. */
+export function metricsSnapshot() {
+    const sorted = [...latencies].sort((a, b) => a - b);
+    return {
+        uptime_s: Math.round((Date.now() - startedAt) / 1000),
+        geocode: {
+            total,
+            errors,
+            tiers: { ...tierCounts },
+            latency_ms: sorted.length
+                ? {
+                    p50: percentile(sorted, 0.5),
+                    p90: percentile(sorted, 0.9),
+                    p99: percentile(sorted, 0.99),
+                    max: Math.round(sorted[sorted.length - 1] * 100) / 100,
+                }
+                : null,
+            latency_samples: sorted.length,
+        },
+    };
+}
+/** Test-only reset of all counters + the reservoir. */
+export function __resetMetricsForTest() {
+    latencies.length = 0;
+    writeIdx = 0;
+    tierCounts.address_point = 0;
+    tierCounts.interpolated = 0;
+    tierCounts.admin = 0;
+    total = 0;
+    errors = 0;
+}
+//# sourceMappingURL=metrics.js.map

package/out/server/metrics.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailwoman",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Utilities for working with contacts for email, phone, and postal addresses.",
   "license": "AGPL-3.0-only",
   "contributors": [
@@ -33,13 +33,13 @@
   "dependencies": {
     "@fragaria/address-formatter": "^6.7.1",
     "@inkjs/ui": "^2.0.0",
-    "@mailwoman/classifiers": "4.6.0",
-    "@mailwoman/core": "4.6.0",
-    "@mailwoman/kind-classifier": "4.6.0",
-    "@mailwoman/locale-gate": "4.6.0",
-    "@mailwoman/normalize": "4.6.0",
-    "@mailwoman/phrase-grouper": "4.6.0",
-    "@mailwoman/query-shape": "4.6.0",
+    "@mailwoman/classifiers": "4.7.0",
+    "@mailwoman/core": "4.7.0",
+    "@mailwoman/kind-classifier": "4.7.0",
+    "@mailwoman/locale-gate": "4.7.0",
+    "@mailwoman/normalize": "4.7.0",
+    "@mailwoman/phrase-grouper": "4.7.0",
+    "@mailwoman/query-shape": "4.7.0",
     "change-case": "^5.4.4",
     "express": "^5.2.1",
     "geojson": "^0.5.0",