mailwoman 9.1.0 → 9.2.0

package/README.md

@@ -147,8 +147,6 @@ const parse = createRuntimePipeline({
 await parse("350 5TH AVE, NEW YORK, NY 10118", {
 	locale: "en-US", // assert a locale instead of detecting it
 	hardPlaceCountry: true, // confine resolution to a confidently-detected country (default: on)
-	jointReconcile: false, // beam-search decode instead of argmax (default: off)
-	arbitrate: false, // union the neural parse with the legacy rule parse (default: off)
 })
 ```
 
@@ -166,13 +164,29 @@ mailwoman parse "350 5th Ave, New York, NY 10118" --resolve --resolve-db ./wof.s
 mailwoman geocode "1600 Amphitheatre Pkwy, Mountain View, CA 94043"
 ```
 
-Programmatically, build a `WofSqlitePlaceLookup` backend (from
+Programmatically, build a `WOFSQLitePlaceLookup` backend (from
 `@mailwoman/resolver-wof-sqlite`), pass it to `createWOFResolver` (from `@mailwoman/resolver`),
 and hand the resolver to `createRuntimePipeline({ classifier, resolver })`. The resolved
 `result.tree` roots then carry a `wof:id` and coordinate. See
-[Getting started → Adding resolution](https://mailwoman.sister.software/docs/developers/get-started/install-and-first-parse)
+[Getting started → Adding resolution](https://mailwoman.ai/docs/developers/get-started/install-and-first-parse)
 for the worked example.
 
+### Which place the coordinate comes from
+
+When nothing finer than an administrative centroid resolved, result assembly walks a ladder and takes the first rung that has a coordinate. That ladder is **not fixed** — it leads with the postcode when the postcode is the finer thing, and with the locality otherwise:
+
+```
+GB unit / NL PC6 / CA urban LDU   →   postcode, locality, dependent_locality, region, country
+Germany                            →   postcode, locality, dependent_locality, region, country
+everything else                    →   locality, dependent_locality, postcode, region, country
+```
+
+Both routes to the first arm live in `@mailwoman/codex` and are read by `@mailwoman/resolver`'s `adminLadderForNodes`. The second arm is the #945 convention, adopted for France where one _code postal_ often spans several communes.
+
+The distinction is a fact about a country's **administrative** geography rather than its postal system, and code length does not predict it — France and Germany are both five digits and disagree. Germany's Gemeinden are large enough that Berlin is a single locality, so its PLZ is finer by a wide margin: on 2,997 OpenAddresses rows the coordinate p50 goes 5.84 km → 1.24 km, better on every percentile including p99, and the within-5-km population doubles.
+
+Membership is earned by a full-panel measurement, never by a shape that looks tight. See [`@mailwoman/codex`](../codex) for the tier table and what each member measured.
+
 ## Architecture
 
 Mailwoman's runtime pipeline is a staged coordinator:
@@ -209,8 +223,8 @@ package is the umbrella that wires them together as a single `npm install`.
 
 ## Related
 
-- [Documentation & blog](https://mailwoman.sister.software)
-- [What Mailwoman Is](https://mailwoman.sister.software/docs/developers/get-started/what-mailwoman-is)
+- [Documentation & blog](https://mailwoman.ai)
+- [What Mailwoman Is](https://mailwoman.ai/docs/developers/get-started/what-mailwoman-is)
 - [GitHub](https://github.com/sister-software/mailwoman)
 
 ## License

package/admin-coherence.ts

@@ -0,0 +1,322 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Admin-coherence verdicts (#1717 stage 1) — after a geocode resolves, compare the PARSED admin
+ *   qualifiers (`region`, `country`) against what the winning candidate's resolved ancestry actually
+ *   says, and report a per-component verdict. FLAG-ONLY: nothing reads these verdicts to rank,
+ *   re-pick, or gate — they exist so a board run can count how often the resolver's answer ignores a
+ *   qualifier the parse got right (`Weimar, Thüringen` → Weimar TX), and how often the winner
+ *   carries no ancestry to check at all (the `unverifiable` count).
+ *
+ *   Per-component verdicts, never one scalar (the Google-confirmation-levels / USPS-DPV pattern):
+ *
+ *   - `confirmed` — the qualifier matches a winner-ancestry node of its class under the shared
+ *     name fold ({@link normalizeLocalityForKey}, the same fold candidate.db's `name_key` is built
+ *     with — build side and check side agree by construction), or the winner IS that qualifier's
+ *     own resolution (a region-tagged winner confirms the region qualifier by identity —
+ *     containment degenerates to self).
+ *   - `contradicted` — the winner's ancestry HAS a node of that class and none of them fold-match
+ *     the parsed value.
+ *   - `unstated` — the parse produced no such qualifier. The common case, and not a problem: most
+ *     queries simply don't name a region or country.
+ *   - `unverifiable` — the parse produced the qualifier but the winner carries NO ancestry of that
+ *     class to check against. Report it faithfully; folding it into either decided verdict would
+ *     hide exactly the gap #1717 wants measured.
+ *
+ *   STATED BOUNDS (v1 is fold-equality only — do not read more into a verdict than this):
+ *
+ *   - Cross-language variant forms are NOT bridged: `Thüringen` folds to `thuringen`, the stored
+ *     exonym `Thuringia` to `thuringia`, so a variant-form match the gazetteer could vouch for
+ *     still reads `contradicted`. Bridging it needs a candidate.db alias probe, which would pull
+ *     the SQLite lookup machinery into this pure module — deliberately skipped.
+ *   - The only normalizers consulted beyond the fold are the codex tables, because they are pure
+ *     and already in-house: {@link matchCountry} (surface form / alpha-2 / alpha-3 → country) and
+ *     {@link matchSubdivision} (US state + CA province code ↔ name). So `IL` confirms against
+ *     `Illinois` and `Deutschland` against a DE winner, but an uncurated endonym (`Alemania`)
+ *     against a DE winner reads `contradicted` — the module never silently over-claims a match it
+ *     cannot derive.
+ *   - The region verdict additionally carries the MISLABEL BRIDGE: a region slot holding a COUNTRY
+ *     name ("Batumi, Georgia" parses region="Georgia") confirms against the winner's country-class
+ *     evidence, because containment holds and `contradicted` would misdescribe the geography. It
+ *     runs after the region band, is monotone (`contradicted`/`unverifiable` → `confirmed` is the
+ *     only movement it can cause), and inherits the pure-codex bound above — parsed "Russia"
+ *     against an RU winner still reads `contradicted`, because codex holds only "Russian
+ *     Federation" for RU and the module never over-claims.
+ *
+ *   The winner's checkable ancestry arrives as the resolver's `metadata.ancestors` stamp (#404 —
+ *   the geocode path opts in by default, and both backends serve it when their artifact carries an
+ *   ancestors table: the FTS shard's `ancestors`, candidate.db's `candidate_ancestor` sidecar),
+ *   while country-class ancestry is nearly always available via the `resolver_country` stamp.
+ *   `unverifiable` remains the faithful verdict wherever the stamp is absent — an artifact
+ *   predating the sidecar, a shard-fed winner with no recorded ancestry, or a caller that opted
+ *   out.
+ */
+
+import { countrySurfaceForms, ISO2_TO_NAME, matchCountry } from "@mailwoman/codex/country"
+import { REGION_CLASS_PLACETYPES, regionKeys } from "@mailwoman/resolver-wof-sqlite/region-keys"
+import { normalizeLocalityForKey } from "@mailwoman/resolver-wof-sqlite/street-normalize"
+
+/**
+ * One admin-coherence verdict. See the module docstring for the exact meaning of each — in particular, `unverifiable`
+ * is an absence-of-evidence claim about the WINNER, never about the parse.
+ */
+type AdminCoherenceVerdict = "confirmed" | "contradicted" | "unstated" | "unverifiable"
+
+/**
+ * The per-component verdicts. Both members are always present when the report exists (the `intent_markers` discipline:
+ * state the empty case — `unstated` IS the explicit "no qualifier" claim, so an optional member would be a second way
+ * to say the same thing). The report as a whole is what's optional: absent means the geocode resolved no winner to
+ * check against.
+ */
+export interface AdminCoherenceReport {
+	region: AdminCoherenceVerdict
+	country: AdminCoherenceVerdict
+}
+
+/**
+ * The parsed admin qualifiers — the raw spans off the address tree's `region` / `country` nodes (the parse view, not
+ * the resolved view). Empty / whitespace-only reads as absent.
+ */
+export interface ParsedAdminQualifiers {
+	region?: string | undefined
+	country?: string | undefined
+}
+
+/**
+ * One link of the winner's containment lineage, as the resolver stamped it (`metadata.ancestors`, the #404 opt-in) — a
+ * structural slice of `@mailwoman/core`'s `Ancestor`.
+ */
+interface AdminAncestor {
+	placetype: string
+	name: string
+}
+
+/**
+ * The winning candidate, reduced to what the check reads: its own component tag (for the self-confirmation case), the
+ * resolver-stamped ISO 3166-1 alpha-2 (`resolver_country` — the one piece of country-class ancestry the candidate
+ * backend always carries), and the stamped ancestor chain when a backend supplied one.
+ */
+export interface AdminCoherenceWinner {
+	tag: string
+	countryCode?: string | undefined
+	ancestry?: readonly AdminAncestor[] | undefined
+}
+
+/**
+ * Fold both sides of every name comparison through the shared candidate.db `name_key` normalizer — one function, both
+ * sides, so the check can never disagree with the index it's checking against.
+ *
+ * The region-side expansion ({@link regionKeys}) and the region band ({@link REGION_CLASS_PLACETYPES}) moved DOWN to
+ * `@mailwoman/resolver-wof-sqlite/region-keys` when the #1717 stage-2 containment re-rank became their second consumer
+ * — the dependency points that way, and the #861 rule wants one function, not a mirrored copy.
+ */
+function foldKey(name: string): string {
+	return normalizeLocalityForKey(name)
+}
+
+/**
+ * The comparable keys a country-class value expands to: its own fold, plus — when {@link matchCountry} recognizes it —
+ * an `iso2:` channel key and the folds of the canonical name and curated surface forms, so `Deutschland`, `DEU`, `DE`
+ * and `Germany` all meet in one key set regardless of which side spelled which.
+ */
+function countryKeys(value: string): Set<string> {
+	const keys = new Set([foldKey(value)])
+	const match = matchCountry(value)
+
+	if (match) {
+		keys.add(`iso2:${match.iso2}`)
+
+		if (match.canonical) {
+			keys.add(foldKey(match.canonical))
+		}
+
+		for (const form of countrySurfaceForms(match.iso2)) {
+			keys.add(foldKey(form))
+		}
+	}
+
+	return keys
+}
+
+function intersects(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+	for (const key of a) {
+		if (b.has(key)) return true
+	}
+
+	return false
+}
+
+/**
+ * The winner's COUNTRY-class evidence keys: the resolver-stamped alpha-2 expanded through the codex tables into every
+ * spelling the check can vouch for, plus any country-placetype ancestors. One assembly, two consumers — the country
+ * verdict compares against it, and the region verdict's mislabel bridge (below) does too, so the two verdicts can never
+ * disagree about what counts as country-class evidence.
+ */
+function winnerCountryKeys(winner: AdminCoherenceWinner): Set<string> {
+	const winnerKeys = new Set<string>()
+	const iso = winner.countryCode?.trim().toUpperCase() || undefined
+
+	if (iso) {
+		winnerKeys.add(`iso2:${iso}`)
+		winnerKeys.add(foldKey(iso))
+		const canonical = ISO2_TO_NAME.get(iso)
+
+		if (canonical) {
+			winnerKeys.add(foldKey(canonical))
+		}
+
+		for (const form of countrySurfaceForms(iso)) {
+			winnerKeys.add(foldKey(form))
+		}
+	}
+
+	for (const ancestor of winner.ancestry ?? []) {
+		if (ancestor.placetype !== "country") continue
+
+		for (const key of countryKeys(ancestor.name)) {
+			winnerKeys.add(key)
+		}
+	}
+
+	return winnerKeys
+}
+
+function regionVerdict(parsedRegion: string | undefined, winner: AdminCoherenceWinner): AdminCoherenceVerdict {
+	const parsed = parsedRegion?.trim()
+
+	if (!parsed) return "unstated"
+
+	// The winner IS a region resolution — the qualifier is the thing that resolved, so containment
+	// degenerates to identity. The resolver's own binding (alias-aware, unlike the fold) is the
+	// match evidence here; re-checking it under fold-equality would misread every alias hit as a
+	// contradiction.
+	if (winner.tag === "region") return "confirmed"
+
+	const regionAncestors = (winner.ancestry ?? []).filter((a) => REGION_CLASS_PLACETYPES.has(a.placetype))
+	const iso = winner.countryCode?.trim().toUpperCase() || undefined
+	const parsedKeys = regionKeys(parsed, iso)
+
+	for (const ancestor of regionAncestors) {
+		if (intersects(parsedKeys, regionKeys(ancestor.name, iso))) return "confirmed"
+	}
+
+	// The mislabel bridge: the region SLOT sometimes holds a COUNTRY name — "Moscow, Russia" parses
+	// region="Russia", "Batumi, Georgia" parses region="Georgia" (the shape the flag's own first
+	// triage counted at ~4 of 16 contradictions). Containment still holds when the winner's
+	// country-class evidence matches the qualifier, so `contradicted` would be the wrong claim about
+	// the geography. Checked AFTER the region band (a genuine region match never depends on it) and
+	// monotone by construction: it can only move `contradicted`/`unverifiable` → `confirmed`.
+	if (intersects(countryKeys(parsed), winnerCountryKeys(winner))) return "confirmed"
+
+	return regionAncestors.length ? "contradicted" : "unverifiable"
+}
+
+function countryVerdict(parsedCountry: string | undefined, winner: AdminCoherenceWinner): AdminCoherenceVerdict {
+	const parsed = parsedCountry?.trim()
+
+	if (!parsed) return "unstated"
+
+	if (winner.tag === "country") return "confirmed"
+
+	const winnerKeys = winnerCountryKeys(winner)
+
+	if (!winnerKeys.size) return "unverifiable"
+
+	return intersects(countryKeys(parsed), winnerKeys) ? "confirmed" : "contradicted"
+}
+
+/**
+ * Assess the parsed admin qualifiers against the winning candidate. Pure — no I/O, no lookup, no side effects; call it
+ * once at result assembly, only when a winner exists (no winner → no report, absence meaning "nothing resolved to check
+ * against").
+ */
+export function assessAdminCoherence(
+	parsed: ParsedAdminQualifiers,
+	winner: AdminCoherenceWinner
+): AdminCoherenceReport {
+	return {
+		region: regionVerdict(parsed.region, winner),
+		country: countryVerdict(parsed.country, winner),
+	}
+}
+
+/**
+ * A resolved-tree node slice the assembly adapter reads — structurally satisfied by `@mailwoman/core`'s `AddressNode`,
+ * declared locally so the pure module carries no decoder import.
+ */
+export interface AdminCoherenceSourceNode {
+	tag: string
+	value: string
+	metadata?: Record<string, unknown> | undefined
+}
+
+/**
+ * The assembly-point adapter: derive the parsed qualifiers (the `region` / `country` node spans — the parse view) and
+ * the winner's checkable ancestry (the `resolver_country` stamp + any `metadata.ancestors` chain) off the resolved
+ * tree's nodes, and return a spreadable result fragment. `winner` is the admin-ladder pick; `fallbackWinner` is the
+ * primary resolved node the street-backed tiers report instead (the resolution context the coordinate was scoped by).
+ * No winner at all → an empty fragment: the `admin_coherence` field stays ABSENT, which is a different claim from
+ * `unverifiable` (nothing resolved, so there was no candidate to check).
+ */
+export function adminCoherenceField(
+	nodes: readonly AdminCoherenceSourceNode[],
+	winner: AdminCoherenceSourceNode | undefined,
+	fallbackWinner: AdminCoherenceSourceNode | undefined
+): { admin_coherence?: AdminCoherenceReport } {
+	const picked = winner ?? fallbackWinner
+
+	if (!picked) return {}
+
+	const report = assessAdminCoherence(
+		{
+			region: nodes.find((n) => n.tag === "region")?.value?.trim() || undefined,
+			country: nodes.find((n) => n.tag === "country")?.value?.trim() || undefined,
+		},
+		{
+			tag: picked.tag,
+			countryCode: (picked.metadata?.["resolver_country"] as string | undefined)?.trim() || undefined,
+			// The resolver's #404 stamp — present when the geocode path opted in AND the backend's
+			// artifact carries an ancestors table; its absence is what the verdicts report as
+			// `unverifiable`.
+			ancestry: picked.metadata?.["ancestors"] as readonly AdminAncestor[] | undefined,
+		}
+	)
+
+	return { admin_coherence: report }
+}
+
+/**
+ * A node tree shaped like the decoder's `AddressNode` — structural rather than imported, so this module stays free of
+ * the decoder dependency.
+ */
+export interface AdminCoherenceTreeNode extends AdminCoherenceSourceNode {
+	children: readonly AdminCoherenceTreeNode[]
+}
+
+/**
+ * Coherence for a fork-to-entity answer (#1724): a forked answer carries a verdict like any other resolved answer --
+ * absence means "nothing resolved to check", and something did. The entity offers a country and no ancestor chain, so a
+ * stated region grades `unverifiable` rather than going silently unchecked.
+ */
+export function forkedEntityCoherenceField(
+	roots: readonly AdminCoherenceTreeNode[],
+	entity: { name: string; country: string }
+): { admin_coherence?: AdminCoherenceReport } {
+	const nodes: AdminCoherenceSourceNode[] = []
+	const stack: AdminCoherenceTreeNode[] = [...roots]
+
+	while (stack.length) {
+		const n = stack.pop()!
+
+		nodes.push({ tag: n.tag, value: n.value, metadata: n.metadata })
+		stack.push(...n.children)
+	}
+
+	return adminCoherenceField(
+		nodes,
+		{ tag: "venue", value: entity.name, metadata: { resolver_country: entity.country } },
+		undefined
+	)
+}

package/api-engine.ts

@@ -28,25 +28,26 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 
-import type { BatchRow, GeocodeOutcome, HealthData, MailwomanAPIEngine, ResolveTreeOutcome } from "@mailwoman/api"
+import type {
+	BatchResultEntry,
+	GeocodeCallback,
+	GeocodeOutcome,
+	HealthData,
+	MailwomanAPIEngine,
+	ResolveTreeOutcome,
+} from "@mailwoman/api"
 import { recordTimed } from "@mailwoman/api-kit"
 import { decodeAsTuples, decodeAsXML } from "@mailwoman/core"
 import type { AddressTree } from "@mailwoman/core/decoder"
 import { $public } from "@mailwoman/core/env"
-import { tryParsingJSON } from "@mailwoman/core/objects"
+import { isPresent, tryParsingJSON } from "@mailwoman/core/objects"
 import { deriveInputMode } from "@mailwoman/core/pipeline"
 import { classifyKindSync } from "@mailwoman/kind-classifier"
 import { computeQueryShape } from "@mailwoman/query-shape"
 import { createWOFResolver, type Resolver, type ResolveOpts } from "@mailwoman/resolver"
 
 import { readReleaseManifest } from "./data-release.ts"
-import {
-	geocodeAddress,
-	type GeocodeClassifier,
-	type GeocodeResult,
-	regionSlugFromTree,
-	ShardProvider,
-} from "./geocode-core.ts"
+import { geocodeAddress, type GeocodeClassifier, regionSlugFromTree, ShardProvider } from "./geocode-core.ts"
 import { INTERP_RADIUS_CALIBRATION, interpCalibrationForRegion } from "./interp-calibration.ts"
 import {
 	buildNoGazetteerMessage,
@@ -81,7 +82,7 @@ function wofPaths(): string[] {
 		return env
 			.split(",")
 			.map((p) => p.trim())
-			.filter(Boolean)
+			.filter(isPresent)
 
 	return wofShardPaths().filter((p) => existsSync(p))
 }
@@ -120,7 +121,7 @@ function readModelCard(): Record<string, unknown> | null {
 		/* package not resolvable from here — fall through */
 	}
 
-	candidates.push("neural-weights-en-us/model-card.json")
+	candidates.push("packages/neural-weights-en-us/model-card.json")
 
 	for (const p of candidates) {
 		try {
@@ -188,7 +189,7 @@ function oneGeocode(
 	deps: GeocodeDepsBundle,
 	address: string,
 	inputMode?: "fragmented" | "formatted"
-): Promise<GeocodeResult> {
+): Promise<GeocodeOutcome> {
 	return geocodeAddress(address, {
 		classifier: deps.classifier,
 		resolver: deps.resolver,
@@ -295,11 +296,11 @@ export async function createServeEngine(): Promise<ServeEngine> {
 	// Candidate backend → country-agnostic default (demo's global, population-first behavior); a per-request `country`
 	// still scopes. FTS backend keeps the US default. (#170) A candidate DB alone (no WOF admin shard) is a valid boot
 	// configuration — `createResolverBackend` prefers it over `wofPaths` — so the preflight gate below checks BOTH,
-	// mirroring the drop-ins' `!candidateDb && wofPaths.length === 0` gate rather than `GeocodeRouter`'s WOF-only check.
+	// mirroring the drop-ins' `!candidateDB && wofPaths.length === 0` gate rather than `GeocodeRouter`'s WOF-only check.
 	// This gate governs geocode/batch/resolveTree/reload ONLY — `parse` is already wired above and unaffected.
-	const candidateDb = resolveCandidateDBPath()
+	const candidateDB = resolveCandidateDBPath()
 
-	if (!paths.length && !candidateDb) {
+	if (!paths.length && !candidateDB) {
 		console.error("createServeEngine: no WOF DBs found — set MAILWOMAN_WOF_DB or MAILWOMAN_CANDIDATE_DB")
 
 		return { engine: { parse, health }, preflight: { ok: false, message: buildPreflightMessage() } }
@@ -308,13 +309,12 @@ export async function createServeEngine(): Promise<ServeEngine> {
 	const backend = createResolverBackend(resolverMod, { wofPaths: paths })
 	const resolver = createWOFResolver(backend)
 	const shards = new ShardProvider(resolverMod, DATA_ROOT)
-	const deps: GeocodeDepsBundle = { classifier, resolver, shards, defaultCountry: candidateDb ? undefined : "US" }
+	const deps: GeocodeDepsBundle = { classifier, resolver, shards, defaultCountry: candidateDB ? undefined : "US" }
 
 	// Route records the whole-call metric already (`@mailwoman/api`'s `routes.ts`) — the engine records nothing extra
 	// here. Ported from `GeocodeRouter`'s `singleHandler`. The cast mirrors `@mailwoman/api/routes.ts`'s established
 	// "documented wire shape looser than the domain type" idiom — `GeocodeOutcome` is a deliberately loose passthrough.
-	const geocode: MailwomanAPIEngine["geocode"] = async (address, opts) =>
-		(await oneGeocode(deps, address, opts?.inputMode)) as unknown as GeocodeOutcome
+	const geocode: GeocodeCallback = async (address, opts) => oneGeocode(deps, address, opts?.inputMode)
 
 	// Sequential loop — results land in input order; a thrown row is isolated to its own
 	// `{ input, error }` slot. Rows are trimmed here (the route passes the raw validated array through).
@@ -329,7 +329,7 @@ export async function createServeEngine(): Promise<ServeEngine> {
 		// Decision A endpoint default: batch rows are the record register.
 		const inputMode = opts?.inputMode ?? "formatted"
 		const inputs = addresses.map((a) => a.trim())
-		const results: BatchRow[] = new Array<BatchRow>(inputs.length)
+		const results: BatchResultEntry[] = new Array<BatchResultEntry>(inputs.length)
 
 		for (let i = 0; i < inputs.length; i++) {
 			const input = inputs[i]!
@@ -338,7 +338,7 @@ export async function createServeEngine(): Promise<ServeEngine> {
 			try {
 				const result = await oneGeocode(deps, input, inputMode)
 				recordTimed(performance.now() - t0, result.resolution_tier)
-				results[i] = result as unknown as GeocodeOutcome
+				results[i] = result
 			} catch (error) {
 				recordTimed(performance.now() - t0, "error")
 				results[i] = { input, error: error instanceof Error ? error.message : String(error) }

package/autocomplete-core.ts

@@ -0,0 +1,97 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Framework-free FST autocomplete shared by CLI and library-facing adapters.
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+
+import { $public } from "@mailwoman/core/env"
+import { CommandError } from "@mailwoman/core/scripting/command"
+import { dataRootPath } from "@mailwoman/core/utils"
+
+/**
+ * Resolve the FST artifact from an explicit flag, environment, or the application data directory.
+ *
+ * The filename is LOWERCASE on both halves of the locale tag, because that is what the builder writes
+ * (`gazetteer-pipeline/fst.ts`'s artifact list). A `fst-en-US.bin` default resolves to nothing on every machine, and
+ * the command reports it as a missing artifact rather than as a name it got wrong.
+ */
+export function resolveFSTPath(explicitPath?: string): string {
+	return explicitPath ?? $public.MAILWOMAN_FST_BIN ?? dataRootPath("wof", "fst-per-locale", "fst-en-us.bin")
+}
+
+/**
+ * One ranked FST completion.
+ */
+export interface AutocompleteEntry {
+	name: string
+	placetype: string
+	wofID: number
+	referential: number
+	encyclopedic?: number
+	completionTokens: string[]
+}
+
+/**
+ * Load an FST artifact and return ranked prefix completions.
+ */
+export async function runAutocomplete(
+	prefix: string,
+	opts: { fstPath: string; limit?: number }
+): Promise<AutocompleteEntry[]> {
+	if (!existsSync(opts.fstPath)) {
+		throw new CommandError(
+			`FST binary not found at ${opts.fstPath}.\n` +
+				"Pass --fst <path>, set $MAILWOMAN_FST_BIN, or build it with `mailwoman gazetteer build fst`."
+		)
+	}
+
+	let buffer: Buffer
+
+	try {
+		buffer = readFileSync(opts.fstPath)
+	} catch (error) {
+		throw new CommandError(`Failed to read FST binary at ${opts.fstPath}`, { cause: error })
+	}
+
+	const [{ deserializeFST }, { autocomplete }] = await Promise.all([
+		import("@mailwoman/resolver-wof-sqlite/fst-serialize"),
+		import("@mailwoman/resolver-wof-sqlite/fst-autocomplete"),
+	])
+
+	let matcher
+
+	try {
+		matcher = deserializeFST(buffer)
+	} catch (error) {
+		throw new CommandError(`Malformed FST binary at ${opts.fstPath}`, { cause: error })
+	}
+
+	return autocomplete(matcher, prefix, { maxSuggestions: opts.limit ?? 10 }).suggestions.map((suggestion) => ({
+		name: suggestion.name,
+		placetype: suggestion.placetype,
+		wofID: suggestion.wofID,
+		referential: suggestion.referential,
+		...(suggestion.encyclopedic === undefined ? {} : { encyclopedic: suggestion.encyclopedic }),
+		completionTokens: suggestion.completionTokens,
+	}))
+}
+
+/**
+ * Render ranked completions for a terminal.
+ */
+export function formatAutocomplete(entries: readonly AutocompleteEntry[]): string {
+	if (!entries.length) return "(no completions)"
+
+	return entries
+		.map((entry, index) => {
+			const completion = entry.completionTokens.length ? ` [+${entry.completionTokens.join(" ")}]` : ""
+			const encyclopedic = entry.encyclopedic === undefined ? "" : `, enc:${entry.encyclopedic.toFixed(4)}`
+
+			return `${String(index + 1).padStart(2)}. ${entry.name}${completion}  (${entry.placetype}, wof:${entry.wofID}, ref:${entry.referential.toFixed(4)}${encyclopedic})`
+		})
+		.join("\n")
+}

package/cli-kit/dropin.ts

@@ -18,7 +18,7 @@
  *   three drop-ins already declare `mailwoman` as a dependency, so landing the whole thing here adds
  *   no dependency to anyone.
  *
- *   WHY IT IS NOT IN `cli-kit/index.ts`: that barrel is the Pastel/Ink toolkit for
+ *   WHY IT IS NOT IN `cli-kit/index.ts`: that barrel is the Ink toolkit for
  *   `mailwoman/commands/*` and imports `ink` + `react`. The drop-ins are plain `parseArgs` scripts
  *   that render no UI, and `npx @mailwoman/libpostal serve` should not pay for a TUI runtime to
  *   start an HTTP server. Hence a standalone module with its own `mailwoman/cli-kit/dropin`
@@ -99,7 +99,7 @@ export interface GazetteerPaths {
 	/**
 	 * The candidate gazetteer (worldwide resolution), when one was found.
 	 */
-	candidateDb: string | undefined
+	candidateDB: string | undefined
 	/**
 	 * The WOF admin FTS shards that exist on disk.
 	 */
@@ -127,13 +127,13 @@ export function resolveGazetteerOrExit(candidateDBFlag: string | undefined): Gaz
 	// Candidate gazetteer = worldwide resolution (population-first ranking + global coverage + the FTS5-trigram typo
 	// fallback). --candidate-db, else $MAILWOMAN_CANDIDATE_DB, else the `<data-root>/wof/candidate.db` convention
 	// path. Absent → the admin FTS shards.
-	const candidateDb = resolveCandidateDBPath(candidateDBFlag)
+	const candidateDB = resolveCandidateDBPath(candidateDBFlag)
 
-	if (!candidateDb && !wofPaths.length) {
+	if (!candidateDB && !wofPaths.length) {
 		fail(buildNoGazetteerMessage({ dataRoot: mailwomanDataRoot(), docsPath: GAZETTEER_DOCS_PATH }))
 	}
 
-	return { adminDBPath: wofPaths[0], candidateDb, wofPaths }
+	return { adminDBPath: wofPaths[0], candidateDB, wofPaths }
 }
 
 /**
@@ -147,11 +147,11 @@ export function corsBannerLine(cors: boolean): string {
  * The `wof:` + `resolver:` lines of a geocoding drop-in's startup banner — which gazetteer the process actually opened,
  * and (when it fell back to admin-only) the flag that widens it.
  */
-export function gazetteerBannerLines({ adminDBPath, candidateDb }: GazetteerPaths): string[] {
+export function gazetteerBannerLines({ adminDBPath, candidateDB }: GazetteerPaths): string[] {
 	return [
 		`  wof: ${adminDBPath ?? "(none found — set MAILWOMAN_WOF_DB)"}`,
-		candidateDb
-			? `  resolver: candidate gazetteer (worldwide) — ${candidateDb}`
+		candidateDB
+			? `  resolver: candidate gazetteer (worldwide) — ${candidateDB}`
 			: `  resolver: admin-only (US-optimized) — point --candidate-db / $MAILWOMAN_CANDIDATE_DB at a candidate gazetteer for worldwide`,
 	]
 }

package/cli-kit/index.ts

@@ -5,3 +5,6 @@
  */
 
 export * from "./shared.ts"
+export * from "./metadata.ts"
+export * from "../cli-native/spec.ts"
+export { CommandError } from "@mailwoman/core/scripting/command"

package/cli-kit/metadata.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+export interface CommandArgumentMetadata {
+	name: string
+	description?: string
+	default?: string
+}
+
+/**
+ * Attach CLI presentation metadata to a positional-argument schema.
+ *
+ * The encoded description remains readable by the transitional schema adapter. Native commands express positionals
+ * directly in `CommandSpec` and do not need this helper.
+ */
+export function argument(config: CommandArgumentMetadata): string {
+	return `__mailwoman_argument_config__${JSON.stringify(config)}`
+}