TW postcode-route gate + JP Overture eval gold (#473, unblocks #294)
#473 asked for two CJK unblocks from Overture: the TW postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.→admin table #294 was parked on, and an
independent Overture-based evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. gold for the shipped JP resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.. Both shipped — but not the way the
issue specced them, because the spec's data premise is false: Overture release 2026-06-17.0 carries
ZERO postcodespostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. for both TW (0/9,732,009) and JP (0/19,587,926) (re-verified on the pinned release
after the 2026-05-20.0 probe in the issue comments; fill-rates.md now carries both rows). What
Overture does carry — 29.3M points with coordinates, admin attribution, and (divisions theme) real
district polygons — supplied the geometry both halves needed.
TW — postcode-route resolution, gate PASS
Keying source (the postal authority, since Overture/GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps. have no TW postcodespostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.): Chunghwa Post's 3-digit postal-code → district table with official district centers (data.gov.tw dataset 25489, OGDL v1; 371 rows, all county-prefixed). The 3-digit code is the admin-granularity key — the "+3" tail is road-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. level, and the full 3+3 file has been account-gated at fpp.post.gov.tw since 2025. Sub-district resolution is therefore out of reach for now (noted, not chased).
Build (scripts/build-postcode-locality-tw.ts → postcode-locality-tw.db, standard
postcode_locality schema — the postcode_area_resolution strategy consumes it unchanged):
official district center → containing Overture division polygon (368 district polygons, fetched
release-pinned by scripts/eval/fetch-tw-division-polygons.ts) → WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. row, tiered:
| tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. | districts |
|---|---|
| district-tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. (county/localadmin) inside polygon | 248 |
| wikidata concordanceconcordanceA joint-decode signal that rewards a parse whose spans form a consistent Who's On First parent-child chain and vetoes contradictory ones — a hard veto for conflicts, a log-space bonus for full agreement. (division.wikidata ↔ WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. wd:id) | 27 |
| Chinese/Overture-en name match inside polygon | 66 |
| name + proximity (JP/KR-style fallback) | 8 |
| containing-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. (regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.) fallback | 22 |
The name-only JP/KR recipe topped out at 63% here: WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.'s county-tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. TW districts carry no
Chinese names at all, and the Kaohsiung/Taichung urban cores are neighbourhood or missing
entirely. The polygon bridge + Overture's en names ("Wanhua District" ↔ WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. "Wanhua") closed most of
the gap; the 22 districts WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. simply has no row for (三民區, 鹽埕區, the Taichung/Tainan directional
districts, offshore islands) map to their containing citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. — true containment, coarser granularity,
honestly recorded in the meta.
Two ladder-ordering findings, both measured (n=3,000, seed 42): name-confirmed district-tiertierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. must outrank bare containment (Zhongshan's WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. point sits inside 中正區 — bare containment alone picks the wrong namesake), and bare containment must outrank the wikidata bridge (wd-first dropped PIP 86.4→85.2% — WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.'s TW wd concordancesconcordanceA joint-decode signal that rewards a parse whose spans form a consistent Who's On First parent-child chain and vetoes contradictory ones — a hard veto for conflicts, a log-space bonus for full agreement. are themselves misattached, e.g. 890468273 "Zhongzheng Qu" carries Keelung's Q712871 while its point sits in Taipei).
Gate (scripts/eval/tw-postcode-route-eval.ts, pre-registered from #288 PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). 1: postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-route
PIP ≥~85%): held-out Overture address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade., query = (district text + 3-digit postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.) against the
shipped admin-global-priority.db + the new table, graded by true point-in-polygon against the
Overture district polygons (WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. TW is point-only — every featurefeatureAn input signal a model conditions on. Beyond the raw tokens, Mailwoman feeds soft features — gazetteer-membership channels and the postcode anchor — that inform predictions without overriding them. in the repo, _pg alts included,
is a Point, so WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. polygons cannot grade this).
| metric | n=3,000 seed 42 | n=1,500 seed 7 |
|---|---|---|
| resolve rate | 100.0% | 100.0% |
| PIP-containment (district) | 86.4% | 86.3% |
| + citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-level containment | 95.1% | 95.1% |
| coord p50 / p90 km | 2.54 / 14.13 | 2.55 / 17.91 |
PASS (86.4% ≥ ~85%, stable across seeds). Failures concentrate exactly where WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. lacks district rows (東區/北區/三民區/南區 …) — a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. gap, not a routing defect; the citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-level containment line is the honest ledger for those. Split note: the builder consumes no Overture address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade. (inputs: postal table, WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations., division polygons), so every sampled point is held-out by construction; the polygon layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is shared between the builder's bridge and the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.'s truth.
address_levels agreement with polygon truth: 98.6% — the NLSC admin attribution and the divisions
geometry corroborate each other.
Convention row: TW (wofWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. 85632403) added to data/conventions/conventions.json and compiled to
conventions.db — postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-route coordinate-first, byte-identical to WORLD_DEFAULT, recorded
explicitly per the #289/#290 pattern. End-to-end verified through the rule engine with the
convention asset attached.
JP — Overture eval gold, divergence investigated
Gold (scripts/eval/build-jp-overture-gold.ts → data/eval/external/jp-overture-gold.jsonl,
3,982 rows): reservoir-sampled Overture JP points (MLIT, 100% OA lineage), municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. gold +
coordinate from Overture, postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. joined from KENALL by (prefecture, municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.) kanji — join
rate 99.5%. Since Overture JP has zero postcodespostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one., the postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.→municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. _pairing still descends
from KEN_ALL (the only JP postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. source in existence here); the independent signals are the
address-weighted sampling frame, the municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. attribution, and the coordinate.
Result (scripts/eval/jp-overture-gold-eval.ts, same backend/query/normalization as
jp-resolver-eval.ts):
| measurement | name-agree |
|---|---|
| shipped number (2026-06-05, KEN_ALL) | 94.9% |
| KEN_ALL harness re-run TODAY | 98.5% |
| Overture gold (this work) | 98.1% |
The raw delta vs the shipped number is +3.2pp — over the pre-registered 2pp band → investigated:
re-running the unchanged KEN_ALL harness against today's shipped DBs gives 98.5%, i.e. the
94.9% is a stale baseline (the admin DB has been rebuilt several times since 2026-06-05 — ancestry
backfill #832/#836, GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps. aliases, coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. expansion). Against the contemporaneous baseline the
Overture gold diverges by -0.4pp — within the band. The two gold sources agree; the shipped JP
resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon.'s current operating point is ~98%, and postcode-locality-jp.db's meta match_rate should
be re-stamped at its next rebuild. Coord p50/p90 vs the Overture point: 4.69 / 13.21 km
(municipalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-centroid scale, as expected).
Refresh-source note (for the convention-table provenance): Overture is NOT viable as a JP
postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. refresh source (0% fill). KEN_ALL (rescued copy at $MAILWOMAN_DATA_ROOT/KEN_ALL_ROME)
remains the only keying source; Overture serves as the independent admin + coordinate gold.
KR — explicitly out of scope
Unchanged from the issue: KR is absent from Overture's addresses theme; Juso remains the blocked path. Noted, not chased.
Artifacts
$MAILWOMAN_DATA_ROOT/wof/postcode-locality-tw.db(new, 1,087 rows, provenance in meta)$MAILWOMAN_DATA_ROOT/wof/dbs-per-country/admin-tw.db(new, 18,597 places, built from whosonfirst-data-admin-tw viabuild-unified-wof.ts, beside the KR/JP siblings)$MAILWOMAN_DATA_ROOT/wof/conventions.db(new — first compiled convention asset, 1 row)$MAILWOMAN_DATA_ROOT/overture/2026-06-17.0/addresses-{tw,jp}.parquet+divisions-tw-admin.jsonl(release-pinned; fill-rates report regenerated with all 22 countries)$MAILWOMAN_DATA_ROOT/tw-postal/district-centroids.xml(Chunghwa Post source file)data/eval/external/jp-overture-gold.jsonl(checked in)
No canonical DB was replaced; every artifact is new beside the canonicals (night-shift policy).