mailwoman 7.2.1 → 7.3.0

package/commands/eval/poi-board.tsx

@@ -0,0 +1,93 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman eval poi-board` — the curated POI query board (spec §3.6, exotic-POI arc). Runs the
+ *   real `createRuntimePipeline({ poiQueryKind: { poiDatabasePath } })` surface against every
+ *   committed fixture and grades the ASSEMBLED answer (matched category + coordinate), not label F1.
+ *
+ *   Floors (spec §3.6, set off the v1 baseline): `overall ≥ 90%`, `abstain = 100%`, `address = 100%`.
+ *   They are graded and printed on EVERY run. Pass `--enforce` to turn a breach into a non-zero exit
+ *   (the CI-gate mode). Without `--enforce` the command stays report-only — it exits 0 on case
+ *   failures, and a non-zero exit means the HARNESS broke (missing fixtures, missing db, a pipeline
+ *   construction error), never a graded case failing.
+ */
+
+import { Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../cli-kit/index.ts"
+import { runPoiBoard } from "../../eval-harness/poi-board.ts"
+
+export const description = "POI query board (spec §3.6) — graded on the assembled answer, v1 report-only"
+
+const OptionsSchema = zod.object({
+	locale: zod
+		.string()
+		.optional()
+		.default("en-US")
+		.describe("Weights package locale for the classifier (default en-US)"),
+	weightsCache: zod
+		.string()
+		.optional()
+		.describe("Package-shaped candidate weights dir (mirrors eval parity --weights-cache)"),
+	fixtures: zod.string().optional().describe("Fixture JSONL override (default: the committed poi-board fixtures)"),
+	db: zod
+		.string()
+		.optional()
+		.describe("Sealed poi.db to query (default <data-root>/poi/poi.db — the gazetteer build poi default)"),
+	resolveDb: zod
+		.string()
+		.optional()
+		.describe("WOF admin shard path(s) for anchor resolution, comma-separated (same as `mailwoman poi --resolve-db`)"),
+	candidateDb: zod
+		.string()
+		.optional()
+		.describe(
+			"Byte-range candidate.db for anchor resolution (same as `mailwoman poi --candidate-db`; wins over --resolve-db)"
+		),
+	json: zod
+		.boolean()
+		.optional()
+		.default(false)
+		.describe("Print the full report as JSON instead of the human-readable table"),
+	enforce: zod
+		.boolean()
+		.optional()
+		.default(false)
+		.describe("Exit non-zero if any pre-registered floor is breached (overall ≥ 90%, abstain/address = 100%)"),
+})
+
+export { OptionsSchema as options }
+
+const EvalPoiBoard: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(
+		async () => {
+			const { report, exitCode } = await runPoiBoard({
+				locale: options.locale,
+				weightsCacheRoot: options.weightsCache,
+				fixturesPath: options.fixtures,
+				db: options.db,
+				resolveDb: options.resolveDb,
+				candidateDb: options.candidateDb,
+				quiet: options.json,
+				enforce: options.enforce,
+			})
+
+			return { report, exitCode }
+		},
+		({ exitCode }) => exitCode
+	)
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	if (options.json && state.status === "done") {
+		return <Text>{JSON.stringify(state.result.report, null, 2)}</Text>
+	}
+
+	// Non-json mode: the runner narrates its table on stdout directly.
+	return null
+}
+
+export default EvalPoiBoard

package/commands/gazetteer/build/poi-brands.tsx

@@ -0,0 +1,91 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman gazetteer build poi-brands` — the POI brand lexicon builder, part 1 of 2 (part 2 wires
+ *   `lookupPOIBrand` into the runtime pipeline; no pipeline wiring here). Thin wiring only: the read +
+ *   aggregate + write logic lives in `gazetteer-pipeline/poi/build-brands.ts`, mirroring `build/poi.tsx`'s
+ *   thin-command style. Reads a BUILT `poi.db` READ-ONLY — never writes one.
+ *
+ *   `writeBrandTable`'s plain `JSON.stringify` doesn't collapse short primitive arrays onto one line the
+ *   way `oxfmt` does (e.g. `"aliases": ["Foo"]` vs a 3-line array) — the process-y bit (shelling out, like
+ *   `poi.tsx`'s own `git rev-parse`) belongs at the command layer, not in the pure/testable builder. Runs
+ *   `oxfmt` on the output here so the emitted file is commit-ready without a manual format pass.
+ */
+
+import { execFileSync } from "node:child_process"
+
+import { Box, Text } from "ink"
+import zod from "zod"
+
+import { type CommandComponent, useCommandTask } from "../../../cli-kit/index.ts"
+import {
+	buildBrandTable,
+	DEFAULT_DOMINANCE,
+	DEFAULT_MIN_ROWS,
+	defaultBrandTableOutPath,
+	defaultPOIDatabasePath,
+	writeBrandTable,
+} from "../../../gazetteer-pipeline/poi/build-brands.ts"
+
+const OptionsSchema = zod.object({
+	db: zod.string().optional().describe("Built poi.db to read. Default <data-root>/poi/poi.db"),
+	out: zod.string().optional().describe("brands.json output path. Default poi-taxonomy/data/brands.json"),
+	minRows: zod.string().optional().describe(`Minimum total rows to keep a brand. Default ${DEFAULT_MIN_ROWS}`),
+	dominance: zod
+		.string()
+		.optional()
+		.describe(
+			`Minimum fraction of a QID's total rows its modal name must cover to qualify — below this the QID is ` +
+				`dropped entirely (systematic mistagging). Default ${DEFAULT_DOMINANCE}`
+		),
+})
+
+export { OptionsSchema as options }
+
+const GazetteerBuildPOIBrands: CommandComponent<typeof OptionsSchema> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const dbPath = options.db ?? defaultPOIDatabasePath()
+		const out = options.out ?? defaultBrandTableOutPath()
+		const minRows = options.minRows ? Number.parseInt(options.minRows, 10) : DEFAULT_MIN_ROWS
+		const dominance = options.dominance ? Number.parseFloat(options.dominance) : DEFAULT_DOMINANCE
+
+		console.error(`▸ reading ${dbPath}`)
+		const table = await buildBrandTable({ dbPath, minRows, dominance })
+
+		console.error(`▸ writing ${out}`)
+		writeBrandTable(table, out)
+		execFileSync("yarn", ["oxfmt", out])
+
+		const top5 = table.brands
+			.slice(0, 5)
+			.map((b, i) => `  ${i + 1}. ${b.name} (${b.wikidata}) — ${b.rows.toLocaleString()} rows`)
+
+		return [
+			`brands.json: ${out} (${table.brands.length.toLocaleString()} brands, min-rows=${minRows}, dominance=${dominance})`,
+			`source: ${table.sourceLayer.name} ${table.sourceLayer.version} (vintage ${table.sourceLayer.sourceVintage})`,
+			"top 5 by rows:",
+			...top5,
+		]
+	})
+
+	if (state.status === "error") return <Text color="red">✗ {state.message}</Text>
+
+	if (state.status === "done") {
+		return (
+			<Box flexDirection="column">
+				{state.result.map((line, i) => (
+					<Text key={i} color={i === 0 ? "green" : undefined}>
+						{i === 0 ? "✓ " : "  "}
+						{line}
+					</Text>
+				))}
+			</Box>
+		)
+	}
+
+	return null // progress streams to stderr until the summary lands
+}
+
+export default GazetteerBuildPOIBrands

package/commands/parse.tsx

@@ -62,7 +62,14 @@ const ParseConfigSchema = zod.object({
 		.optional()
 		.default(false)
 		.describe("In pipeline mode, skip the neural classifier (run normalize + queryShape + kind + resolver only)."),
-	poi: zod.boolean().optional().default(false).describe("Enable poi_query detection (poiQueryKind flag)."),
+	poi: zod
+		.boolean()
+		.optional()
+		.default(true)
+		.describe(
+			"poi_query detection (poiQueryKind flag). DEFAULT-ON since 2026-07-20 (promotion battery: 0/4507 golden " +
+				"misroutes, 6/6 demo presets byte-identical). Pass --no-poi to restore the pre-flag address-only kind classification."
+		),
 	downloadWeights: zod
 		.boolean()
 		.optional()

package/commands/poi.tsx

@@ -28,7 +28,7 @@
 import { existsSync } from "node:fs"
 
 import { Spinner } from "@inkjs/ui"
-import type { POIIntent, POIIntentOutcome } from "@mailwoman/core/pipeline"
+import type { POIIntent, POIIntentOutcome, POIResult } from "@mailwoman/core/pipeline"
 import { NeuralAddressClassifier } from "@mailwoman/neural"
 import { getPOICategory } from "@mailwoman/poi-taxonomy"
 import { createWOFResolver, type Resolver } from "@mailwoman/resolver"
@@ -168,6 +168,20 @@ function formatOverpassBlock(intent: POIIntent): string {
 	return emitOverpassQL(intent)
 }
 
+/**
+ * Compact ancestry suffix, e.g. "· Springfield, IL, US" — locality/region/country entries, coarsest-last (the
+ * hierarchy's own deepest-first order reversed), skipping other placetypes (county, neighbourhood, …) to keep the table
+ * narrow. Empty string when `ancestry` is absent (no reverse geocoder wired) or carries none of those three tiers (e.g.
+ * open-ocean/approximate misses).
+ */
+function formatAncestrySuffix(ancestry: POIResult["ancestry"]): string {
+	if (!ancestry || ancestry.length === 0) return ""
+	const byPlacetype = new Map(ancestry.map((a) => [a.placetype, a.name]))
+	const parts = ["locality", "region", "country"].map((t) => byPlacetype.get(t)).filter((name) => name !== undefined)
+
+	return parts.length > 0 ? ` · ${parts.join(", ")}` : ""
+}
+
 function formatResultsTable(results: NonNullable<Extract<POIIntentOutcome, { type: "intent" }>["results"]>): string[] {
 	if (results.length === 0) return ["(no results)"]
 
@@ -184,7 +198,7 @@ function formatResultsTable(results: NonNullable<Extract<POIIntentOutcome, { typ
 				(r.distanceM !== undefined ? String(Math.round(r.distanceM)) : "-").padStart(10),
 				r.latitude.toFixed(6).padStart(12),
 				r.longitude.toFixed(6).padStart(12),
-			].join("  ")
+			].join("  ") + formatAncestrySuffix(r.ancestry)
 		)
 	}
 

package/default-reverse-geocoder.ts

@@ -0,0 +1,64 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The default read-time WOF reverse geocoder for POI ancestry — the poiQueryKind register row's second
+ *   debt payment (runtime-flags.mdx): `createRuntimePipeline({ poiQueryKind: { poiDatabasePath } })`
+ *   lazily loads this once per process and wires a SYNCHRONOUS adapter into `createPOIExecutor`'s
+ *   `reverseGeocode` dep (the executor's return type carries no `Promise` — see `poi-intent.ts`'s
+ *   `deps.execute`, called synchronously). `WOFReverseGeocoder.reverseGeocodeSync` (added alongside this
+ *   feature) is the real synchronous core the async `reverseGeocode` already wrapped — see
+ *   resolver-wof-sqlite/reverse.ts.
+ *
+ *   `@mailwoman/resolver-wof-sqlite` is an optional peer dep and the admin gazetteer (with its
+ *   `place_bbox` R*Tree, `mailwoman gazetteer build fts`) is a multi-GB build artifact that may not be on
+ *   disk — either gap yields `null` and POI results simply carry no `ancestry` key at all (house
+ *   meaning-of-zero: absence, never an empty array). The polygon sidecar (`wof-polygons.db`) is OPTIONAL
+ *   too; without it every ancestry chain still resolves, just `containment: "approximate"`
+ *   (`WOFReverseGeocoder`'s own centroid-descent fallback).
+ *
+ *   Admin DB resolution mirrors `resolver-backend.ts`'s `wofShardPaths()` — the SAME default
+ *   `@mailwoman/photon`'s and `@mailwoman/nominatim`'s `serve` commands use for their own
+ *   `WOFReverseGeocoder` (`photon/cli.ts`, `nominatim/cli.ts`): first existing shard in the list wins
+ *   (`admin-global-priority.db` first). The polygon sidecar is read from `$MAILWOMAN_WOF_POLYGONS_DB` —
+ *   the same env var `mailwoman reverse` reads (`commands/reverse.tsx`).
+ */
+
+import { existsSync } from "node:fs"
+
+import { $public } from "@mailwoman/core/env"
+import type { WOFReverseGeocoder as WOFReverseGeocoderType } from "@mailwoman/resolver-wof-sqlite"
+
+import { wofShardPaths } from "./resolver-backend.ts"
+
+let cached: Promise<WOFReverseGeocoderType | null> | null = null
+
+/**
+ * Lazy-load + cache the default `WOFReverseGeocoder`. `null` when no admin shard with a `place_bbox` R*Tree is on disk,
+ * or `@mailwoman/resolver-wof-sqlite` can't be resolved (stripped install) — the pipeline then wires no
+ * `reverseGeocode` fn at all, so POI results degrade to no `ancestry` (byte-stable pre-feature behavior). Cached for
+ * the process lifetime (one handle, reused).
+ */
+export function loadDefaultReverseGeocoder(): Promise<WOFReverseGeocoderType | null> {
+	if (!cached) {
+		cached = (async (): Promise<WOFReverseGeocoderType | null> => {
+			try {
+				const adminDBPath = wofShardPaths().filter(existsSync)[0]
+
+				if (!adminDBPath) return null
+				const { WOFReverseGeocoder } = await import("@mailwoman/resolver-wof-sqlite")
+				const polygonDBPath = $public.MAILWOMAN_WOF_POLYGONS_DB
+
+				return new WOFReverseGeocoder({
+					adminDBPath,
+					...(polygonDBPath && existsSync(polygonDBPath) ? { polygonDBPath } : {}),
+				})
+			} catch {
+				return null
+			}
+		})()
+	}
+
+	return cached
+}