@mailwoman/codex 9.4.0 → 10.0.0

package/lib/placetype-map.ts

@@ -0,0 +1,157 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Component-tag → resolver-placetype mapping, the equivalence groups a query expands into, and the test
+ *   that tells a widened match from an exact one.
+ */
+
+import type { ComponentTag } from "#component"
+
+/**
+ * Mapping from mailwoman's address-component tags to the resolver's placetype taxonomy.
+ *
+ * PARTIAL on purpose: a tag absent from the map is NOT queried, and the resolver pass leaves its classifier attribution
+ * untouched. Omission is therefore a routing decision, not an oversight.
+ */
+export type PlacetypeMap = Partial<Record<ComponentTag, string>>
+
+/**
+ * The map used when a backend does not supply its own.
+ *
+ * `street` and `house_number` are absent because WOF admin has no rows for them — they resolve through the situs
+ * extracts instead, which are keyed by street, not by placetype.
+ *
+ * The JP tiers are present because the candidate gazetteer keys them: 91.3% of Japanese records carry a kanji or kana
+ * key (49,255 of 53,920), a prefecture is a WOF `region`, a municipality a `locality` (its filter group admits the
+ * `borough` wards and `localadmin`), and a district (大字 / 町名) sits in the `locality` band beside the neighbourhoods.
+ * Measured on 300 JP board rows: with these entries and the JP rungs on the admin ladder, 271 resolve within 15 km;
+ * without them, 0. Only the character-path CJK model emits the tags, so no Latin parse reaches these rows.
+ */
+export const DEFAULT_PLACETYPE_MAP: PlacetypeMap = {
+	country: "country",
+	region: "region",
+	locality: "locality",
+	dependent_locality: "locality",
+	subregion: "county",
+	prefecture: "region",
+	municipality: "locality",
+	district: "locality",
+	// `postcode` (mailwoman tag) maps to WOF's `postalcode` placetype. Resolves only when the
+	// backend has the postcode extract available — `WOFSQLitePlaceLookup` auto-routes `postalcode`
+	// queries to a `postalcode_us` (or similarly-named) extract, falling back to main if absent.
+	postcode: "postalcode",
+}
+
+/**
+ * Where a country's WOF typing of a tier departs from {@link DEFAULT_PLACETYPE_MAP}, the entries that differ. The map
+ * names the tier by tag; WOF names it by placetype, and the two agree for most countries and not for all.
+ *
+ * - **TW** — 鄉鎮市區, the tier below the 縣市 that the parse tags `subregion`, is `locality` or `localadmin` in WOF for 164 of
+ *   the 178 held-out districts the candidate table carries and `county` for 14 (the census in
+ *   `docs/records/evals/2026-09-08-v8-cjk-regs.md` §5). Under the default `county` band `臺北市中正區` reached nothing and
+ *   the admin tier fell to the 縣市. The `locality` group admits `localadmin` too, the rule the JP `municipality` tag
+ *   already relies on, and the exact-type preference in ranking keeps a `locality` row ahead of a same-name
+ *   `localadmin` row.
+ */
+const COUNTRY_PLACETYPE_OVERRIDES: Readonly<Record<string, PlacetypeMap>> = {
+	tw: { subregion: "locality" },
+}
+
+/**
+ * The placetype map for a resolve scoped to `countryCode` (ISO alpha-2, any case): the default map with the country's
+ * overrides applied, or the default map itself when the country has none or is unknown. The identity of the default
+ * object is preserved in that case, so a caller comparing maps to decide whether a second resolve is needed reads
+ * "unchanged" correctly.
+ */
+export function placetypeMapForCountry(countryCode: string | null | undefined): PlacetypeMap {
+	const overrides = countryCode ? COUNTRY_PLACETYPE_OVERRIDES[countryCode.toLowerCase()] : undefined
+
+	return overrides ? { ...DEFAULT_PLACETYPE_MAP, ...overrides } : DEFAULT_PLACETYPE_MAP
+}
+
+/**
+ * Placetype-equivalence groups for lookup FILTERING. WOF splits a single addressing tier across several placetypes, but
+ * an address's span can name ANY of them. A backend that filters to the one "obvious" placetype makes the equivalents
+ * unreachable, so a fuzzy same-name place in the wrong tier wins instead.
+ *
+ * Three tiers are affected (the value of each entry is the set the SQL filter should accept; the FIRST entry is the
+ * canonical/requested type, which extract routing keys off):
+ *
+ * - **`locality`** — `locality` (most cities), `borough` (Brooklyn, the Paris arrondissements, the London boroughs), and
+ *   `localadmin` (FR communes, US towns/townships in New England). Without the group, Brooklyn-the-borough (pop 2.5M)
+ *   was unreachable and the fuzzy "Brooklyn Park, MN" won.
+ * - **`region`** — `region` + `macroregion` (#718). WOF does NOT model every country's top-level civil division as
+ *   `region`: Italian regions (Lombardia, Veneto, Toscana…) are `macroregion` (their PROVINCES are `region`), and the
+ *   post-2016 French régions (Île-de-France) are `macroregion` too. An address's `region` span names exactly those, so
+ *   a `region`-only filter resolved them to NOTHING (confirmed against the IT/FR eval rows). US states / DE
+ *   Bundesländer / ES provincias are genuine `region`, so the EXACT-type match is preferred in ranking (see the
+ *   resolve.ts fallback-quality annotation) — the macro is the recall safety net, not a demotion.
+ * - **`county`** — `county` + `macrocounty` (#718). The `subregion` ComponentTag maps to `county` via
+ *   {@link DEFAULT_PLACETYPE_MAP}; WOF carries `macrocounty` for FR départements-grouping / DE / GB tiers above the
+ *   county. Proactive (no eval row exercises `subregion` today) but symmetric with `region` — biasing to inclusion,
+ *   since a missed resolution costs more than a too-broad candidate (which is QA-visible). Same exact-type preference
+ *   applies.
+ *
+ * This table is the single source of truth for that expansion, shared by every lookup backend
+ * (`@mailwoman/core/resolver-wof-sqlite`, `@mailwoman/core/resolver-wof-wasm`, and the demo's httpvfs lookup) so the
+ * Node and browser resolvers can't drift. Keyed by the REQUESTED placetype. Placetypes without an entry pass through
+ * unchanged — an explicit `placetype: "borough"` query stays narrow.
+ */
+export const PLACETYPE_FILTER_GROUPS: Readonly<Record<string, readonly string[]>> = {
+	locality: ["locality", "borough", "localadmin"],
+	region: ["region", "macroregion"],
+	county: ["county", "macrocounty"],
+}
+
+/**
+ * Expand a placetype filter through {@link PLACETYPE_FILTER_GROUPS}, deduplicated and order-preserving (the first entry
+ * stays first — extract routing keys off it). `null`/`undefined` (no filter) passes through untouched.
+ */
+export function expandPlacetypeFilter(placetypes: null): null
+export function expandPlacetypeFilter(placetypes: readonly string[]): string[]
+export function expandPlacetypeFilter(placetypes: readonly string[] | null): string[] | null
+
+export function expandPlacetypeFilter(placetypes: readonly string[] | null): string[] | null {
+	if (!placetypes) return null
+	const out: string[] = []
+
+	for (const placetype of placetypes) {
+		for (const expanded of PLACETYPE_FILTER_GROUPS[placetype] ?? [placetype]) {
+			if (!out.includes(expanded)) {
+				out.push(expanded)
+			}
+		}
+	}
+
+	return out
+}
+
+/**
+ * Macro/broader-tier members of {@link PLACETYPE_FILTER_GROUPS} — the recall safety net a query may fall through to
+ * when no candidate of the EXACT requested placetype exists (#718). DELIBERATELY scoped to the `macro*` tiers only: the
+ * `locality` group's `borough`/`localadmin` are genuine peers (Brooklyn-the-borough is a first-class locality answer,
+ * #404-class), NOT fallbacks — so they must NOT be deprioritized or annotated. Only `macroregion`/`macrocounty` are a
+ * broader admin tier standing in for a true `region`/`county`.
+ */
+const MACRO_FALLBACK_PLACETYPES: ReadonlySet<string> = new Set(["macroregion", "macrocounty"])
+
+/**
+ * Did `candidatePlacetype` resolve `requestedPlacetype` only via a BROADER admin tier (a macro-type fallback within the
+ * {@link PLACETYPE_FILTER_GROUPS} expansion), rather than the exact type (#718)?
+ *
+ * `region` → `region` is exact (false); `region` → `macroregion` is a fallback (true). Scoped to the `macro*` tiers
+ * (see {@link MACRO_FALLBACK_PLACETYPES}) so the `locality` group's borough/localadmin peers stay exact. The resolver
+ * uses this to (a) prefer an exact-type candidate in ranking and (b) annotate `resolutionQuality: "fallback"` when only
+ * a macro-type matched. A placetype outside the requested group, or any non-macro member, is treated as exact (false).
+ */
+export function isPlacetypeFallback(requestedPlacetype: string, candidatePlacetype: string): boolean {
+	const group = PLACETYPE_FILTER_GROUPS[requestedPlacetype]
+
+	if (!group) return false
+
+	if (candidatePlacetype === requestedPlacetype) return false
+
+	return MACRO_FALLBACK_PLACETYPES.has(candidatePlacetype) && group.includes(candidatePlacetype)
+}

package/lib/postcode/shapes.json

@@ -0,0 +1,80 @@
+{
+	"version": "postcode-shapes-v1",
+	"note": "Postcode SHAPE patterns for detecting postcode-like spans in free text, ordered most-specific to least. Priority IS the array index: a lower index wins an overlap. This is a SHAPE test, not gazetteer membership — see postcode-systems.ts for the per-system membership question. Alphanumeric patterns require UPPERCASE letters, which keeps them off lowercase prose. The regex bodies are written in the subset both JavaScript RegExp and Python re accept, because two runtimes read this file; a row that needs different source text in the two dialects needs a second field and a stated reason, not a loosened comparison.",
+	"shapes": [
+		{
+			"label": "JP-marked",
+			"kind": "designated",
+			"pattern": "(?<=〒\\s?)\\d{3}-\\d{4}\\b",
+			"unicode": true,
+			"javascriptOnly": "Python's `re` refuses a variable-width lookbehind, and `\\s?` makes this one variable-width. Nothing on the Python side compiles this row.",
+			"note": "The digits behind 〒, optionally spaced (〒506-0025, 〒 100-0001). The character path keeps the mark in the text, and on a venue-led line the model has read the digits as a house number. A designated match may overwrite any existing label."
+		},
+		{
+			"label": "GB",
+			"kind": "alnum",
+			"pattern": "\\b[A-Z]{1,2}\\d[A-Z\\d]?\\s+\\d[A-Z]{2}\\b",
+			"note": "Outward + space + inward: SW1A 1AA, EH8 9YL, W1J 9PN, IP13 6SU, B12 8QX."
+		},
+		{
+			"label": "CA",
+			"kind": "alnum",
+			"pattern": "\\b[A-Z]\\d[A-Z]\\s?\\d[A-Z]\\d\\b",
+			"note": "A1A 1A1, space optional: M5V 2T6, H2X 2T6, H3B 1A3."
+		},
+		{
+			"label": "IE",
+			"kind": "alnum",
+			"pattern": "\\b(?:[A-Z]\\d{2}|D6W)\\s+[A-Z\\d]{4}\\b",
+			"note": "Eircode: routing key (letter + 2 digits, or the D6W special) + a 4-alnum unique part — D02 AF30, T12 X70A, F91 Y5CY. Space REQUIRED: a glued 7-alnum blob is too forgeable for the ADD path. No GB collision, because a letter+2-digit GB outward always has a 3-character inward (B12 8QX), never 4."
+		},
+		{
+			"label": "DE",
+			"kind": "alnum",
+			"pattern": "\\bD-\\d{5}\\b",
+			"note": "The D-prefixed form: D-68161."
+		},
+		{
+			"label": "NL",
+			"kind": "alnum",
+			"pattern": "\\b\\d{4}\\s?[A-Z]{2}\\b",
+			"note": "1234 AB / 1234AB — space optional, glued is common. The US \"2737 CA\" collision (a ZIP+4 tail followed by a state) is settled by longest-match-wins, which lets the ZIP+4 claim it."
+		},
+		{
+			"label": "ZIP4",
+			"kind": "numeric",
+			"pattern": "\\b\\d{5}-\\d{4}\\b",
+			"note": "US ZIP+4. A numeric match is eligible only for snapping, never for adding a postcode where the model emitted none."
+		},
+		{
+			"label": "BR",
+			"kind": "numeric",
+			"pattern": "\\b\\d{5}-\\d{3}\\b",
+			"note": "CEP: 70390-100, 95090-020. Without it the generic NUM5 below matched the five-digit head and the trailing-smear clip discarded the sector suffix, so the repair pass truncated a parse the model had got right (repair OFF \"95090-020\", repair ON \"95090\"). The trailing word boundary keeps it off a ZIP+4's first nine characters, since \"94610-2737\" has a digit after \"273\"."
+		},
+		{
+			"label": "JP",
+			"kind": "numeric",
+			"pattern": "\\b\\d{3}-\\d{4}\\b",
+			"note": "100-0001."
+		},
+		{
+			"label": "PT",
+			"kind": "numeric",
+			"pattern": "\\b\\d{4}-\\d{3}\\b",
+			"note": "3060-187."
+		},
+		{
+			"label": "PL",
+			"kind": "numeric",
+			"pattern": "\\b\\d{2}-\\d{3}\\b",
+			"note": "47-400."
+		},
+		{
+			"label": "NUM5",
+			"kind": "numeric",
+			"pattern": "\\b\\d{5}\\b",
+			"note": "The bare 5-digit shape US, FR, DE and ES all share. Last, so every more-specific row above claims its overlap first."
+		}
+	]
+}

package/lib/postcode/shapes.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode SHAPE patterns — which substrings of a line LOOK like a postcode, ordered most-specific
+ *   to least. Priority IS the index: a lower index wins an overlap.
+ *
+ *   The DATA lives in `./shapes.json` so non-TS consumers read the identical record, the
+ *   same arrangement `us/street-suffix.json` has. Two runtimes need this table and both used to
+ *   carry their own typed copy: `@mailwoman/neural`'s postcode repair, and the Python trainer's
+ *   `features/postcode_shapes.py`, which paints the train-side anchor on the spans inference paints.
+ *   Hand-mirrored, they drifted twice — the IE Eircode row was TS-only for a month, the BR CEP row
+ *   for five weeks — and each time the trainer painted one fewer shape than inference, silently.
+ *
+ *   This is a SHAPE test, not a gazetteer-membership test. A bare `68161` matches the US, German,
+ *   French, Spanish and Italian 5-digit shapes; `./systems.ts` answers the membership
+ *   question, and neither module reads the other.
+ *
+ *   REGEX DIALECT. The bodies are written in the subset both JavaScript `RegExp` and Python `re`
+ *   accept, which is what lets one file serve both. A row needing different source text in the two
+ *   dialects needs a second field and a stated reason, not a loosened comparison on either side.
+ */
+
+import postcodeShapeData from "./shapes.json" with { type: "json" }
+
+/**
+ * What a match is eligible to do. `designated` may overwrite any existing label, `alnum` may add a postcode where the
+ * model emitted none, and `numeric` may only snap an existing one — so a numeric shape can never invent a postcode over
+ * a hyphenated house number.
+ */
+export type PostcodeShapeKind = "alnum" | "numeric" | "designated"
+
+/**
+ * One shape: the label it reports, what it is eligible to do, and the compiled pattern.
+ */
+export interface PostcodeShape {
+	readonly label: string
+	readonly kind: PostcodeShapeKind
+	readonly re: RegExp
+}
+
+/**
+ * Every postcode shape, in priority order. Compiled once at module load; each `RegExp` carries the `g` flag because
+ * callers scan a whole line, and `u` as well where the row declares it.
+ */
+export const POSTCODE_SHAPES: readonly PostcodeShape[] = postcodeShapeData.shapes.map((shape) => ({
+	label: shape.label,
+	kind: shape.kind as PostcodeShapeKind,
+	re: new RegExp(shape.pattern, "unicode" in shape && shape.unicode ? "gu" : "g"),
+}))
+
+/**
+ * The record's own version string, so a consumer that vendors a copy can say which revision it holds.
+ */
+export const POSTCODE_SHAPES_VERSION: string = postcodeShapeData.version

package/lib/{postcode-systems.ts → postcode/systems.ts}

@@ -186,8 +186,15 @@ export function isUnitGradePostcodeHit(parsed: string, resolverName: string | un
  * **The JP row is the JP board through the served path** (`jp-served-resolve.run.ts`, 2,000 rows, seed 42): the 586
  * rows carrying a postcode the candidate table keys, graded on the row's own entrance point — the locality-first answer
  * is the municipality centroid, the postcode answer the code's 町域 centroid from the WOF extract.
+ *
+ * **SG** is the limiting case of the tier: a six-digit Singapore postcode names ONE building, so the code's point IS
+ * the address, and the only locality above it is the city-state itself. Measured on a 300-row seeded draw of the
+ * Overture-SG register (`postalcode-sg-overture.db` folded, each row geocoded as `<number> <street> Singapore
+ * <postcode>` and graded on its own point): the postcode point answers 300 of 300 within 1 km (p99 0.16 km);
+ * locality-first answers 185, and the other 115 take the "Singapore" locality centroid (p75 6.30 km, p90 11.43 km, p99
+ * 24.18 km). The postcode point is closer on those 115 and equal on the rest; it is never farther.
  */
-export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE", "JP"])
+export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE", "JP", "SG"])
 
 /**
  * True when this country's area-grade postal code outranks its locality. Absent or unknown country → false, so the

package/lib/us/index.ts

@@ -13,7 +13,7 @@ export * from "#us/floor-designator"
 export * from "#us/military-address"
 export * from "#us/po-box"
 export * from "#us/state"
-export * from "#us/street-directional"
-export * from "#us/street-suffix"
+export * from "#us/street/directional"
+export * from "#us/street/suffix"
 export * from "#us/unit-designator"
 export * from "#us/zipcode"

package/lib/us/po-box.ts

@@ -31,11 +31,37 @@ export const US_PO_BOX_DESIGNATORS = [
 export type USPoBoxDesignator = (typeof US_PO_BOX_DESIGNATORS)[number]
 
 /**
- * Matches a leading PO-box designator + its identifier. Allows "P.O. Box", "PO BOX", "Post Office Box", "Box 12-A",
- * etc. The id is alphanumeric with optional dashes (USPS caller/firm ids exist).
+ * Recognition patterns for {@link US_PO_BOX_DESIGNATORS}. Keeping the surface grammar next to the canonical designator
+ * prevents the exported lexicon and matcher from drifting apart.
  */
-const PO_BOX_RE =
-	/^\s*(?:(p\.?\s*o\.?\s*box)|(post\s+office\s+box)|(firm\s+caller)|(caller)|(drawer)|(lockbox)|(box))\s*#?\s*([\dA-Za-z][\dA-Za-z-]*)\s*$/i
+const PO_BOX_DESIGNATOR_PATTERNS: ReadonlyArray<readonly [USPoBoxDesignator, string]> = [
+	["POST OFFICE BOX", String.raw`post\s+office\s+box`],
+	["PO BOX", String.raw`p\.?\s*o\.?\s*box`],
+	["P O BOX", String.raw`p\.?\s*o\.?\s*box`],
+	["FIRM CALLER", String.raw`firm\s+caller`],
+	["CALLER", "caller"],
+	["DRAWER", "drawer"],
+	["LOCKBOX", "lockbox"],
+	["BOX", "box"],
+]
+
+/**
+ * One standalone matcher per USPS designator. The id is alphanumeric with optional dashes (USPS caller/firm ids exist).
+ */
+const PO_BOX_MATCHERS = PO_BOX_DESIGNATOR_PATTERNS.map(([designator, pattern]) => ({
+	designator,
+	designatorRe: new RegExp(String.raw`^\s*${pattern}\s*$`, "i"),
+	phraseRe: new RegExp(String.raw`^\s*(${pattern})\s*#?\s*([\dA-Za-z][\dA-Za-z-]*)\s*$`, "i"),
+}))
+
+/**
+ * True when `input` is a USPS PO-box designator without its box identifier. This is useful to consumers that compose a
+ * phrase and need to distinguish USPS vocabulary from their own locale-specific aliases (for example, the corpus's
+ * `POB` training variant).
+ */
+export function isUSPoBoxDesignator(input: unknown): input is string {
+	return typeof input === "string" && PO_BOX_MATCHERS.some(({ designatorRe }) => designatorRe.test(input))
+}
 
 /**
  * Type-predicate: does the input look like a standalone PO Box address? Case-insensitive and tolerant of "P.O. Box",
@@ -43,7 +69,7 @@ const PO_BOX_RE =
  * all-caps "PO BOX 123".)
  */
 export function isPOBox(input: unknown): boolean {
-	return typeof input === "string" && PO_BOX_RE.test(input)
+	return matchPOBox(input) !== null
 }
 
 /**
@@ -67,13 +93,14 @@ export interface PoBoxMatch {
  */
 export function matchPOBox(input: unknown): PoBoxMatch | null {
 	if (typeof input !== "string") return null
-	const m = PO_BOX_RE.exec(input)
 
-	if (!m) return null
-	const matched = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? m[6] ?? m[7] ?? "").trim()
-	const id = m[8]!
+	for (const { phraseRe } of PO_BOX_MATCHERS) {
+		const match = phraseRe.exec(input)
+
+		if (match) return { matched: match[1]!.trim(), id: match[2]! }
+	}
 
-	return { matched, id }
+	return null
 }
 
 /**

package/lib/us/{street-directional.ts → street/directional.ts}

@@ -10,7 +10,7 @@
  * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Pub 28 Appendix C1}
  */
 
-import { matchCase } from "#us/street-suffix"
+import { matchCase } from "#us/street/suffix"
 
 /**
  * The 8 directional abbreviations accepted by the USPS. The USPS prefers the abbreviation over the fully-spelled-out

package/lib/us/{street-suffix.ts → street/suffix.ts}

@@ -24,7 +24,7 @@
  * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Street Suffix Abbreviations}
  */
 
-import streetSuffixData from "./street-suffix.json" with { type: "json" }
+import streetSuffixData from "../street-suffix.json" with { type: "json" }
 
 /**
  * Canonical USPS street suffix → list of recognized variants. The first variant in each list is the preferred USPS

package/out/address/format.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string — the inverse of the parser.
+ *
+ *   The order lives in `@mailwoman/codex/address-layouts`, as data. This module is the public surface over
+ *   {@linkcode renderAddress}: {@linkcode formatAddress} is the join, and {@linkcode formatAddressRow} is the join plus
+ *   the tags the layout printed, which is what every corpus adapter actually wants.
+ *
+ *   IT USED TO WRAP A THIRD-PARTY ENGINE, and 229 of this file's 438 lines existed to work around templates written
+ *   against OpenStreetMap's tag vocabulary rather than this project's: a pass that parsed 295 mustache templates at
+ *   module load to discover which of them could render a sub-locality, a second that spliced a missing line back in
+ *   afterwards, a third that removed a connector the template wrote between two slots when one was empty, and a
+ *   translation layer between the two vocabularies. Owning the layouts deletes all four — a layout that declares a
+ *   `dependent_locality` slot needs no interrogation about whether it has one, and a line assembled from present values
+ *   never writes a connector around an absent one.
+ */
+import { type ComponentDict } from "#address/render";
+import type { ComponentTag } from "#component";
+export type { ComponentDict } from "#address/render";
+/**
+ * Options accepted by {@linkcode formatAddress} and {@linkcode formatAddressRow}.
+ */
+export interface FormatAddressOptions {
+    /**
+     * Replace the layout's line breaks with this separator. Default `"\n"`: the envelope form.
+     */
+    separator?: string;
+    /**
+     * Join the lines the way the COUNTRY does, for the single-line form a query or a corpus row takes — `", "` for most,
+     * `" "` for Japan and Korea, and nothing at all for the Chinese-script systems, whose admin run is unseparated.
+     *
+     * It is an option rather than each caller's literal because the literal is wrong outside the anglophone systems:
+     * joining Japan's lines with a comma gives `1-9-1, 丸の内, 千代田区, 東京都 100-0005`, which is the romanized convention
+     * printed backwards. `separator` wins when both are given.
+     */
+    singleLine?: boolean;
+}
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string when the dict is empty, and when no layout names `country` — 55 of the 252 shipped country
+ * records carry no usable skeleton, and answering nothing for one of those reports absence rather than inventing an
+ * order. Throws nothing; a partial dict degrades to the parts the layout can print.
+ */
+export declare function formatAddress(components: ComponentDict, country: string, opts?: FormatAddressOptions): string;
+/**
+ * A rendered address and the components that survived the render.
+ */
+export interface AddressRow {
+    /**
+     * The rendered string.
+     */
+    readonly raw: string;
+    /**
+     * The subset of the input dict the layout PRINTED, with the caller's original values. This is the half a corpus row
+     * needs: a label whose text is not in `raw` cannot be aligned against it.
+     */
+    readonly components: ComponentDict;
+    /**
+     * Tags the dict carried a value for that the layout has no slot for, NAMED rather than silently dropped. France
+     * absorbing a region into its postcode line is the common case.
+     */
+    readonly unplaced: readonly ComponentTag[];
+}
+/**
+ * Render `components` for `country` and report what the layout printed, in one pass.
+ *
+ * Returns null when nothing rendered — an empty dict, a country with no layout, or a dict whose every value falls in a
+ * slot this country omits. Every corpus adapter asked both questions and paid for two renders to get them, then
+ * recovered the alignment by searching the output string for each value; that search cannot tell a component the layout
+ * dropped from one whose value happens to sit inside another — `Paris` inside `Rue de Paris`. The render knows, so the
+ * answer is read rather than inferred.
+ */
+export declare function formatAddressRow(components: ComponentDict, country: string, opts?: FormatAddressOptions): AddressRow | null;
+/**
+ * Which of `components` occur verbatim in `raw`, case- and whitespace-insensitively.
+ *
+ * This is a question about a string somebody else built — a committed golden fixture, a source's own address line — and
+ * it is the WEAKER of the two reconciliations: a substring test cannot tell a component the renderer dropped from one
+ * whose value happens to sit inside another. Anything rendered through a layout should read
+ * {@linkcode formatAddressRow}'s `components` instead, which the render knows rather than infers.
+ */
+export declare function componentsPresentIn(components: ComponentDict, raw: string): ComponentDict;
+//# sourceMappingURL=format.d.ts.map

package/out/address/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../lib/address/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB;AAQD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAEjH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAClC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,UAAU,EAAE,aAAa,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,oBAAyB,GAC7B,UAAU,GAAG,IAAI,CAwBnB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAazF"}

package/out/address/format.js

@@ -0,0 +1,85 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string — the inverse of the parser.
+ *
+ *   The order lives in `@mailwoman/codex/address-layouts`, as data. This module is the public surface over
+ *   {@linkcode renderAddress}: {@linkcode formatAddress} is the join, and {@linkcode formatAddressRow} is the join plus
+ *   the tags the layout printed, which is what every corpus adapter actually wants.
+ *
+ *   IT USED TO WRAP A THIRD-PARTY ENGINE, and 229 of this file's 438 lines existed to work around templates written
+ *   against OpenStreetMap's tag vocabulary rather than this project's: a pass that parsed 295 mustache templates at
+ *   module load to discover which of them could render a sub-locality, a second that spliced a missing line back in
+ *   afterwards, a third that removed a connector the template wrote between two slots when one was empty, and a
+ *   translation layer between the two vocabularies. Owning the layouts deletes all four — a layout that declares a
+ *   `dependent_locality` slot needs no interrogation about whether it has one, and a line assembled from present values
+ *   never writes a connector around an absent one.
+ */
+import { layoutForCountry, lineJoinForCountry } from "#address/layouts/index";
+import { joinRendering, renderAddress } from "#address/render";
+function separatorFor(country, opts) {
+    if (opts.separator !== undefined)
+        return opts.separator;
+    return opts.singleLine ? lineJoinForCountry(country) : "\n";
+}
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string when the dict is empty, and when no layout names `country` — 55 of the 252 shipped country
+ * records carry no usable skeleton, and answering nothing for one of those reports absence rather than inventing an
+ * order. Throws nothing; a partial dict degrades to the parts the layout can print.
+ */
+export function formatAddress(components, country, opts = {}) {
+    return formatAddressRow(components, country, opts)?.raw ?? "";
+}
+/**
+ * Render `components` for `country` and report what the layout printed, in one pass.
+ *
+ * Returns null when nothing rendered — an empty dict, a country with no layout, or a dict whose every value falls in a
+ * slot this country omits. Every corpus adapter asked both questions and paid for two renders to get them, then
+ * recovered the alignment by searching the output string for each value; that search cannot tell a component the layout
+ * dropped from one whose value happens to sit inside another — `Paris` inside `Rue de Paris`. The render knows, so the
+ * answer is read rather than inferred.
+ */
+export function formatAddressRow(components, country, opts = {}) {
+    const layout = layoutForCountry(country);
+    if (!layout)
+        return null;
+    const rendering = renderAddress(layout, components);
+    if (!rendering.placed.length)
+        return null;
+    const raw = joinRendering(rendering, separatorFor(country, opts));
+    if (!raw)
+        return null;
+    const placed = {};
+    for (const tag of rendering.placed) {
+        const value = components[tag];
+        if (value) {
+            placed[tag] = value;
+        }
+    }
+    return { raw, components: placed, unplaced: rendering.unplaced };
+}
+/**
+ * Which of `components` occur verbatim in `raw`, case- and whitespace-insensitively.
+ *
+ * This is a question about a string somebody else built — a committed golden fixture, a source's own address line — and
+ * it is the WEAKER of the two reconciliations: a substring test cannot tell a component the renderer dropped from one
+ * whose value happens to sit inside another. Anything rendered through a layout should read
+ * {@linkcode formatAddressRow}'s `components` instead, which the render knows rather than infers.
+ */
+export function componentsPresentIn(components, raw) {
+    const haystack = raw.toLowerCase().replaceAll(/\s+/g, " ");
+    const out = {};
+    for (const [tag, value] of Object.entries(components)) {
+        if (!value)
+            continue;
+        if (haystack.includes(value.toLowerCase().replaceAll(/\s+/g, " "))) {
+            out[tag] = value;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=format.js.map

package/out/address/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../lib/address/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAsB,MAAM,iBAAiB,CAAA;AAyBlF,SAAS,YAAY,CAAC,OAAe,EAAE,IAA0B;IAChE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAA;IAEvD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB,EAAE,OAAe,EAAE,IAAI,GAAyB,EAAE;IACxG,OAAO,gBAAgB,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAAA;AAC9D,CAAC;AAsBD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC/B,UAAyB,EACzB,OAAe,EACf,IAAI,GAAyB,EAAE;IAE/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAExC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAExB,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAEnD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAEzC,MAAM,GAAG,GAAG,aAAa,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;IAEjE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IAErB,MAAM,MAAM,GAAkB,EAAE,CAAA;IAEhC,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAE7B,IAAI,KAAK,EAAE,CAAC;YACX,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACpB,CAAC;IACF,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAA;AACjE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAyB,EAAE,GAAW;IACzE,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC1D,MAAM,GAAG,GAAkB,EAAE,CAAA;IAE7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,KAAK;YAAE,SAAQ;QAEpB,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,GAAmB,CAAC,GAAG,KAAK,CAAA;QACjC,CAAC;IACF,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC"}