@mailwoman/codex 9.3.0 → 10.0.0

package/lib/jp/index.ts

@@ -9,5 +9,6 @@
  */
 
 export * from "#jp/address-unit"
+export * from "#jp/municipality-register"
 export * from "#jp/postal-code"
 export * from "#jp/prefecture"

package/lib/jp/municipality-register.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The towns whose own name carries the city marker 市 (shi) before the town suffix 町 / 村 (chō / son).
+ *
+ *   A Japanese municipality span closes at 市 in the ordinary case (`富山市`, `神戸市西区`), and a character model
+ *   learns that boundary from 1,700 cities. A town whose NAME contains 市 defeats it: `中新川郡上市町` reads as the
+ *   city `上市` plus a district beginning with 町. Over the 1,892 municipalities in Japan Post's KEN_ALL list the
+ *   shape has six members, so the boundary is stated here rather than learned — a positive attestation from the
+ *   postal register, consumed after decode by `@mailwoman/neural`'s JP municipality repair. Two of the six (`上市町`,
+ *   `下市町`) put 市 immediately before the suffix, the boundary the model closes at; the other four are listed for the same
+ *   repair so an early close inside them is also repaired.
+ */
+
+import { completeFromRegister } from "#register-completion"
+
+/**
+ * One town from Japan Post's KEN_ALL municipality list whose own name contains 市.
+ */
+export interface JapaneseInnerShiTown {
+	/**
+	 * The prefecture, as written (`富山県`).
+	 */
+	prefecture: string
+	/**
+	 * The county (郡) the town belongs to, as the postal form writes it before the town.
+	 */
+	county: string
+	/**
+	 * The town's own name with its suffix (`上市町`).
+	 */
+	town: string
+}
+
+/**
+ * The six towns, from KEN_ALL (1,892 municipalities). Ordered by prefecture code.
+ */
+export const JP_INNER_SHI_TOWNS: readonly JapaneseInnerShiTown[] = [
+	{ prefecture: "北海道", county: "余市郡", town: "余市町" },
+	{ prefecture: "栃木県", county: "芳賀郡", town: "市貝町" },
+	{ prefecture: "富山県", county: "中新川郡", town: "上市町" },
+	{ prefecture: "山梨県", county: "西八代郡", town: "市川三郷町" },
+	{ prefecture: "奈良県", county: "吉野郡", town: "下市町" },
+	{ prefecture: "兵庫県", county: "神崎郡", town: "市川町" },
+]
+
+/**
+ * Every surface a municipality span may legitimately close on for these towns: the postal form with the county
+ * (`中新川郡上市町`) and the bare town (`上市町`).
+ */
+export const JP_INNER_SHI_TOWN_NAMES: readonly string[] = JP_INNER_SHI_TOWNS.flatMap((t) => [t.county + t.town, t.town])
+
+/**
+ * The characters a municipality surface must absorb from what follows it to become one of the register's names, or null
+ * when no name extends it. `following` is the text after the surface; the answer is a prefix of it. A surface that
+ * already IS a register name answers null: nothing to absorb.
+ */
+export function jpMunicipalityCompletion(surface: string, following: string): string | null {
+	return completeFromRegister(JP_INNER_SHI_TOWN_NAMES, surface, following)
+}

package/lib/kr/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Korean address system as the road-name address register (도로명주소) writes it: the 시군구 register the
+ *   decode-time boundary repair reads.
+ */
+
+export * from "#kr/sigungu-register"

package/lib/kr/sigungu-register.ts

@@ -0,0 +1,294 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The Korean 시군구 (si / gun / gu: the second administrative tier) as the road-name address register writes them,
+ *   each under its 시/도 (the first tier). 249 pairs over 226 distinct names; a compound city is
+ *   one name (`성남시분당구`), the way the register keys it. 세종특별자치시 has no second tier and is absent.
+ *
+ *   Why a register: a character model closes a `subregion` span where the training set taught it names end, and a
+ *   name it never saw (`해운대구`, held out of the training corpus by the board's design and unseen by the shipped
+ *   model for the same reason) closes early, at `해` or `해운대`. The register states every boundary outright, so the
+ *   decode-time repair in `@mailwoman/neural` extends a run to the one name the following characters spell.
+ *
+ *   Source: 행정안전부 (Ministry of the Interior and Safety), 도로명주소 (juso.go.kr), 공공누리 제1유형 (KOGL Type 1):
+ *   attribution required; commercial use, derivatives and redistribution permitted.
+ */
+
+import { completeFromRegister } from "#register-completion"
+
+/**
+ * One second-tier unit under its first-tier region, both as the register writes them.
+ */
+export interface KoreanSigungu {
+	region: string
+	city: string
+}
+
+/**
+ * The register: every (시/도, 시군구) pair the road-name address register carries, in register order.
+ */
+export const KR_SIGUNGU: readonly KoreanSigungu[] = [
+	{ region: "강원도", city: "강릉시" },
+	{ region: "강원도", city: "고성군" },
+	{ region: "강원도", city: "동해시" },
+	{ region: "강원도", city: "삼척시" },
+	{ region: "강원도", city: "속초시" },
+	{ region: "강원도", city: "양구군" },
+	{ region: "강원도", city: "양양군" },
+	{ region: "강원도", city: "영월군" },
+	{ region: "강원도", city: "원주시" },
+	{ region: "강원도", city: "인제군" },
+	{ region: "강원도", city: "정선군" },
+	{ region: "강원도", city: "철원군" },
+	{ region: "강원도", city: "춘천시" },
+	{ region: "강원도", city: "태백시" },
+	{ region: "강원도", city: "평창군" },
+	{ region: "강원도", city: "홍천군" },
+	{ region: "강원도", city: "화천군" },
+	{ region: "강원도", city: "횡성군" },
+	{ region: "경기도", city: "가평군" },
+	{ region: "경기도", city: "고양시덕양구" },
+	{ region: "경기도", city: "고양시일산동구" },
+	{ region: "경기도", city: "고양시일산서구" },
+	{ region: "경기도", city: "과천시" },
+	{ region: "경기도", city: "광명시" },
+	{ region: "경기도", city: "광주시" },
+	{ region: "경기도", city: "구리시" },
+	{ region: "경기도", city: "군포시" },
+	{ region: "경기도", city: "김포시" },
+	{ region: "경기도", city: "남양주시" },
+	{ region: "경기도", city: "동두천시" },
+	{ region: "경기도", city: "부천시" },
+	{ region: "경기도", city: "성남시분당구" },
+	{ region: "경기도", city: "성남시수정구" },
+	{ region: "경기도", city: "성남시중원구" },
+	{ region: "경기도", city: "수원시권선구" },
+	{ region: "경기도", city: "수원시영통구" },
+	{ region: "경기도", city: "수원시장안구" },
+	{ region: "경기도", city: "수원시팔달구" },
+	{ region: "경기도", city: "시흥시" },
+	{ region: "경기도", city: "안산시단원구" },
+	{ region: "경기도", city: "안산시상록구" },
+	{ region: "경기도", city: "안성시" },
+	{ region: "경기도", city: "안양시동안구" },
+	{ region: "경기도", city: "안양시만안구" },
+	{ region: "경기도", city: "양주시" },
+	{ region: "경기도", city: "양평군" },
+	{ region: "경기도", city: "여주시" },
+	{ region: "경기도", city: "연천군" },
+	{ region: "경기도", city: "오산시" },
+	{ region: "경기도", city: "용인시기흥구" },
+	{ region: "경기도", city: "용인시수지구" },
+	{ region: "경기도", city: "용인시처인구" },
+	{ region: "경기도", city: "의왕시" },
+	{ region: "경기도", city: "의정부시" },
+	{ region: "경기도", city: "이천시" },
+	{ region: "경기도", city: "파주시" },
+	{ region: "경기도", city: "평택시" },
+	{ region: "경기도", city: "포천시" },
+	{ region: "경기도", city: "하남시" },
+	{ region: "경기도", city: "화성시" },
+	{ region: "경상남도", city: "거제시" },
+	{ region: "경상남도", city: "거창군" },
+	{ region: "경상남도", city: "고성군" },
+	{ region: "경상남도", city: "김해시" },
+	{ region: "경상남도", city: "남해군" },
+	{ region: "경상남도", city: "밀양시" },
+	{ region: "경상남도", city: "사천시" },
+	{ region: "경상남도", city: "산청군" },
+	{ region: "경상남도", city: "양산시" },
+	{ region: "경상남도", city: "의령군" },
+	{ region: "경상남도", city: "진주시" },
+	{ region: "경상남도", city: "창녕군" },
+	{ region: "경상남도", city: "창원시마산합포구" },
+	{ region: "경상남도", city: "창원시마산회원구" },
+	{ region: "경상남도", city: "창원시성산구" },
+	{ region: "경상남도", city: "창원시의창구" },
+	{ region: "경상남도", city: "창원시진해구" },
+	{ region: "경상남도", city: "통영시" },
+	{ region: "경상남도", city: "하동군" },
+	{ region: "경상남도", city: "함안군" },
+	{ region: "경상남도", city: "함양군" },
+	{ region: "경상남도", city: "합천군" },
+	{ region: "경상북도", city: "경산시" },
+	{ region: "경상북도", city: "경주시" },
+	{ region: "경상북도", city: "고령군" },
+	{ region: "경상북도", city: "구미시" },
+	{ region: "경상북도", city: "군위군" },
+	{ region: "경상북도", city: "김천시" },
+	{ region: "경상북도", city: "문경시" },
+	{ region: "경상북도", city: "봉화군" },
+	{ region: "경상북도", city: "상주시" },
+	{ region: "경상북도", city: "성주군" },
+	{ region: "경상북도", city: "안동시" },
+	{ region: "경상북도", city: "영덕군" },
+	{ region: "경상북도", city: "영양군" },
+	{ region: "경상북도", city: "영주시" },
+	{ region: "경상북도", city: "영천시" },
+	{ region: "경상북도", city: "예천군" },
+	{ region: "경상북도", city: "울릉군" },
+	{ region: "경상북도", city: "울진군" },
+	{ region: "경상북도", city: "의성군" },
+	{ region: "경상북도", city: "청도군" },
+	{ region: "경상북도", city: "청송군" },
+	{ region: "경상북도", city: "칠곡군" },
+	{ region: "경상북도", city: "포항시남구" },
+	{ region: "경상북도", city: "포항시북구" },
+	{ region: "광주광역시", city: "광산구" },
+	{ region: "광주광역시", city: "남구" },
+	{ region: "광주광역시", city: "동구" },
+	{ region: "광주광역시", city: "북구" },
+	{ region: "광주광역시", city: "서구" },
+	{ region: "대구광역시", city: "남구" },
+	{ region: "대구광역시", city: "달서구" },
+	{ region: "대구광역시", city: "달성군" },
+	{ region: "대구광역시", city: "동구" },
+	{ region: "대구광역시", city: "북구" },
+	{ region: "대구광역시", city: "서구" },
+	{ region: "대구광역시", city: "수성구" },
+	{ region: "대구광역시", city: "중구" },
+	{ region: "대전광역시", city: "대덕구" },
+	{ region: "대전광역시", city: "동구" },
+	{ region: "대전광역시", city: "서구" },
+	{ region: "대전광역시", city: "유성구" },
+	{ region: "대전광역시", city: "중구" },
+	{ region: "부산광역시", city: "강서구" },
+	{ region: "부산광역시", city: "금정구" },
+	{ region: "부산광역시", city: "기장군" },
+	{ region: "부산광역시", city: "남구" },
+	{ region: "부산광역시", city: "동구" },
+	{ region: "부산광역시", city: "동래구" },
+	{ region: "부산광역시", city: "부산진구" },
+	{ region: "부산광역시", city: "북구" },
+	{ region: "부산광역시", city: "사상구" },
+	{ region: "부산광역시", city: "사하구" },
+	{ region: "부산광역시", city: "서구" },
+	{ region: "부산광역시", city: "수영구" },
+	{ region: "부산광역시", city: "연제구" },
+	{ region: "부산광역시", city: "영도구" },
+	{ region: "부산광역시", city: "중구" },
+	{ region: "부산광역시", city: "해운대구" },
+	{ region: "서울특별시", city: "강남구" },
+	{ region: "서울특별시", city: "강동구" },
+	{ region: "서울특별시", city: "강북구" },
+	{ region: "서울특별시", city: "강서구" },
+	{ region: "서울특별시", city: "관악구" },
+	{ region: "서울특별시", city: "광진구" },
+	{ region: "서울특별시", city: "구로구" },
+	{ region: "서울특별시", city: "금천구" },
+	{ region: "서울특별시", city: "노원구" },
+	{ region: "서울특별시", city: "도봉구" },
+	{ region: "서울특별시", city: "동대문구" },
+	{ region: "서울특별시", city: "동작구" },
+	{ region: "서울특별시", city: "마포구" },
+	{ region: "서울특별시", city: "서대문구" },
+	{ region: "서울특별시", city: "서초구" },
+	{ region: "서울특별시", city: "성동구" },
+	{ region: "서울특별시", city: "성북구" },
+	{ region: "서울특별시", city: "송파구" },
+	{ region: "서울특별시", city: "양천구" },
+	{ region: "서울특별시", city: "영등포구" },
+	{ region: "서울특별시", city: "용산구" },
+	{ region: "서울특별시", city: "은평구" },
+	{ region: "서울특별시", city: "종로구" },
+	{ region: "서울특별시", city: "중구" },
+	{ region: "서울특별시", city: "중랑구" },
+	{ region: "울산광역시", city: "남구" },
+	{ region: "울산광역시", city: "동구" },
+	{ region: "울산광역시", city: "북구" },
+	{ region: "울산광역시", city: "울주군" },
+	{ region: "울산광역시", city: "중구" },
+	{ region: "인천광역시", city: "강화군" },
+	{ region: "인천광역시", city: "계양구" },
+	{ region: "인천광역시", city: "남구" },
+	{ region: "인천광역시", city: "남동구" },
+	{ region: "인천광역시", city: "동구" },
+	{ region: "인천광역시", city: "부평구" },
+	{ region: "인천광역시", city: "서구" },
+	{ region: "인천광역시", city: "연수구" },
+	{ region: "인천광역시", city: "옹진군" },
+	{ region: "인천광역시", city: "중구" },
+	{ region: "전라남도", city: "강진군" },
+	{ region: "전라남도", city: "고흥군" },
+	{ region: "전라남도", city: "곡성군" },
+	{ region: "전라남도", city: "광양시" },
+	{ region: "전라남도", city: "구례군" },
+	{ region: "전라남도", city: "나주시" },
+	{ region: "전라남도", city: "담양군" },
+	{ region: "전라남도", city: "목포시" },
+	{ region: "전라남도", city: "무안군" },
+	{ region: "전라남도", city: "보성군" },
+	{ region: "전라남도", city: "순천시" },
+	{ region: "전라남도", city: "신안군" },
+	{ region: "전라남도", city: "여수시" },
+	{ region: "전라남도", city: "영광군" },
+	{ region: "전라남도", city: "영암군" },
+	{ region: "전라남도", city: "완도군" },
+	{ region: "전라남도", city: "장성군" },
+	{ region: "전라남도", city: "장흥군" },
+	{ region: "전라남도", city: "진도군" },
+	{ region: "전라남도", city: "함평군" },
+	{ region: "전라남도", city: "해남군" },
+	{ region: "전라남도", city: "화순군" },
+	{ region: "전라북도", city: "고창군" },
+	{ region: "전라북도", city: "군산시" },
+	{ region: "전라북도", city: "김제시" },
+	{ region: "전라북도", city: "남원시" },
+	{ region: "전라북도", city: "무주군" },
+	{ region: "전라북도", city: "부안군" },
+	{ region: "전라북도", city: "순창군" },
+	{ region: "전라북도", city: "완주군" },
+	{ region: "전라북도", city: "익산시" },
+	{ region: "전라북도", city: "임실군" },
+	{ region: "전라북도", city: "장수군" },
+	{ region: "전라북도", city: "전주시덕진구" },
+	{ region: "전라북도", city: "전주시완산구" },
+	{ region: "전라북도", city: "정읍시" },
+	{ region: "전라북도", city: "진안군" },
+	{ region: "제주특별자치도", city: "서귀포시" },
+	{ region: "제주특별자치도", city: "제주시" },
+	{ region: "충청남도", city: "계룡시" },
+	{ region: "충청남도", city: "공주시" },
+	{ region: "충청남도", city: "금산군" },
+	{ region: "충청남도", city: "논산시" },
+	{ region: "충청남도", city: "당진시" },
+	{ region: "충청남도", city: "보령시" },
+	{ region: "충청남도", city: "부여군" },
+	{ region: "충청남도", city: "서산시" },
+	{ region: "충청남도", city: "서천군" },
+	{ region: "충청남도", city: "아산시" },
+	{ region: "충청남도", city: "예산군" },
+	{ region: "충청남도", city: "천안시동남구" },
+	{ region: "충청남도", city: "천안시서북구" },
+	{ region: "충청남도", city: "청양군" },
+	{ region: "충청남도", city: "태안군" },
+	{ region: "충청남도", city: "홍성군" },
+	{ region: "충청북도", city: "괴산군" },
+	{ region: "충청북도", city: "단양군" },
+	{ region: "충청북도", city: "보은군" },
+	{ region: "충청북도", city: "영동군" },
+	{ region: "충청북도", city: "옥천군" },
+	{ region: "충청북도", city: "음성군" },
+	{ region: "충청북도", city: "제천시" },
+	{ region: "충청북도", city: "증평군" },
+	{ region: "충청북도", city: "진천군" },
+	{ region: "충청북도", city: "청주시상당구" },
+	{ region: "충청북도", city: "청주시서원구" },
+	{ region: "충청북도", city: "청주시청원구" },
+	{ region: "충청북도", city: "청주시흥덕구" },
+	{ region: "충청북도", city: "충주시" },
+]
+
+/**
+ * Every 시군구 name a `subregion` span may close on.
+ */
+export const KR_SIGUNGU_NAMES: readonly string[] = [...new Set(KR_SIGUNGU.map((s) => s.city))]
+
+/**
+ * The characters a `subregion` surface must absorb from what follows it to become a register name, or null.
+ */
+export function krSubregionCompletion(surface: string, following: string): string | null {
+	return completeFromRegister(KR_SIGUNGU_NAMES, surface, following)
+}

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."
+		}
+	]
+}