Sprint: where the next coordinate gains live

Defined 2026-06-19, after the v4.11.0 ship (FR-admin-split), the research-romp paper triage (.notes/research-romp-applicability.md), and a 4-turn DeepSeek consult (.agents/skills/deepseek-consult/session-notes-2026-06-19-research-nextsteps.md).

We grade the assembled geocoded coordinate, never labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag.-F1 — the discipline that has paid off all month (the "#566 trap": labelcomponent tagOne of the 33 labels in Mailwoman's address schema — street, locality, region, postcode, house_number, unit, po_box, country, venue, intersection, and others. Each parsed span carries exactly one component tag. wins that never reach the coordinate). This sprint applies that discipline to the question "what do we build next," and the answer is measure before you commit: a single zero-GPU diagnostic routes the entire cycle, with the one strategic choice surfaced for the operator rather than buried in an assumption.

The reframe — what we are NOT doing, and why

The research-romp triage's headline finding was a principled fix for the #727 admin-tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. fragmentation: a spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.-level headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. (GLiNER / Filtered Semi-Markov CRFCRF (Conditional Random Field). A statistical modeling method that predicts structured outputs by modeling dependencies between adjacent labels. Mailwoman uses a linear-chain CRF as the Viterbi decoder at inference time to enforce BIO label consistency — a B-street must be followed by I-street or O, never I-locality.) plus a lower-fertilityfertilityHow many tokenizer pieces it takes to spell a word: fertility 1 means whole words survive tokenization, fertility 3 means they arrive in fragments. High fertility hurts sequence labeling directly — the model has to reassemble a word before it can label it, and fragment boundaries are where labels break. Mailwoman measured this on French street names: accented words splitting at the accent ('René' → '▁Ren' + 'é') caused real geocoding misses, and lowering French fertility was worth a tokenizer revision plus a retrain. multilingual vocabularyvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. (EuroBERT). It is good work and the papers are right. It is also coordinate-invisible. We shipped v4.11.0 carrying the #727 fragmentation with zero coordinate delta; the diacriticdiacriticAn accent mark that modifies a letter (é, ñ, ç). Address normalization must fold diacritics for matching without discarding the information a user typed. break is ~1% of emitted régions, and the 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. already recovers past it. A spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.-headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. + vocabvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it.-prune + full retrain + int8/WASM requantisation is a multi-week architecture overhaul aimed at a defect that does not move the metric we ship on. That is the #566 trap wearing a good-paper disguise.

Decision: the spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.-headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. / tokenizertokenizerThe component that converts a raw address string into a sequence of numeric token IDs the model can process. Mailwoman's tokenizer is a SentencePiece unigram model trained specifically on postal addresses. threadthreadA parallel workstream within a release. Threads compose; they are not sequential milestones like phases. is PARKED as future-enablement for CJK/Cyrillic localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. (where byte-fallback fertilityfertilityHow many tokenizer pieces it takes to spell a word: fertility 1 means whole words survive tokenization, fertility 3 means they arrive in fragments. High fertility hurts sequence labeling directly — the model has to reassemble a word before it can label it, and fragment boundaries are where labels break. Mailwoman measured this on French street names: accented words splitting at the accent ('René' → '▁Ren' + 'é') caused real geocoding misses, and lowering French fertility was worth a tokenizer revision plus a retrain. blocks 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. we don't yet serve), not next-cycle work. If and when we commit to those scripts, the fertilityfertilityHow many tokenizer pieces it takes to spell a word: fertility 1 means whole words survive tokenization, fertility 3 means they arrive in fragments. High fertility hurts sequence labeling directly — the model has to reassemble a word before it can label it, and fragment boundaries are where labels break. Mailwoman measured this on French street names: accented words splitting at the accent ('René' → '▁Ren' + 'é') caused real geocoding misses, and lowering French fertility was worth a tokenizer revision plus a retrain. diagnostic + GLiNER-style headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. come off the shelf.

The decision this sprint resolves

Where does the next coordinate-moving cycle go?

1. Learned 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. reranker (GeoNorm / GBMGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline.-over-candidates) — lifts every already-covered match.
2. 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 — US-rural gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. completeness (SD 62%, VT 31% localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. resolution) and/or multi-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. ingest (AU/ES/IT = zero rows in admin-global-priority.db today).
3. Multi-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. parser shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. — generalize the FR-admin-split win to ES/IT/AU.

These are not equivalent in cost or in who they serve, and the bottleneck differs per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.. We do not guess — we route on a measurement.

Workstream A (first, this sprint): the Three-Gap Matrix diagnostic

One artifact, zero GPU, runs on a laptop. For a held-out evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. set, decompose every error into the gap that caused it, because each gap routes to a different (and mutually exclusive) fix:

For each query: join truth → 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. id (nearest-neighbour + name match). Then —

1. 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 — the true 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. id is not in the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. at all → only data ingest helps; a reranker and a better retrieval are both inert here.
2. recallrecallOf the spans whose gold label is a given tag, the fraction the model found. High recall means few misses. Paired with precision to compute F1.-gap — the true id is in the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. but not in the 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 top-k candidates → fix retrieval (raise k, relax the FTS/trigram threshold), not ranking.
3. ranking-gap — the true id is in top-k but mis-ranked (rank > 1) → this, and only this, is what a reranker can fix. The ranking-gap fraction is the reranker's ceiling.

Run at k = 5 / 10 / 20 (if recallrecallOf the spans whose gold label is a given tag, the fraction the model found. High recall means few misses. Paired with precision to compute F1.-gap shrinks sharply as k grows, retrieval is too restrictive; if flat, the candidate is buried and retrieval needs a different strategy, not a wider beam).

Output schema — one row per locale

field	meaning
locale	us, fr, de, …
query_volume_share	fraction of current query volume (and a second, strategic weighting — see below)
coverage_gap_pct	errors where truth not in gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture.
recall_gap_pct	truth in gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture., not in top-k
ranking_gap_pct	truth in top-k, mis-ranked — the reranker ceiling
parse_blocker_pct	(zero-DB localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. only) parser fails to produce a clean localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.+admin split when truth has one
coverage_blocker_pct	(zero-DB localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. only) 1 − parse_blocker_pct

The zero-DB trick (measure a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. we can't yet resolve, with NO gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture.): for AU/ES/IT, run the parser on public samples (OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. / OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. / synthetic) and compute the admin-split detection rate — does the parser emit a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. and an adjacent admin tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. when the ground truthground truthThe correct answer for an example, used as the standard a prediction is graded against. Mailwoman's ground truth is the hand-labeled golden set; its quality caps achievable accuracy. has both? That isolates "the parser is the blocker (admin-split shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., like FR)" from "the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. is the blocker (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. ingest)" without doing the ingest first.

Routing thresholds

condition	route
coverage_gap_pct > 0.20 AND query_volume_share > 0.05	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 (data ingest)
ranking_gap_pct > 0.10 AND coverage_gap_pct < 0.20	Reranker (learned ranking)
recall_gap_pct > 0.15 AND coverage_gap_pct < 0.20	Retrieval fix (raise k / relax FTS)
parse_blocker_pct > 0.30 (zero-DB localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.)	Parser shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (admin-split, FR template)
coverage_blocker_pct > 0.70 (zero-DB localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.)	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 (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. ingest)

Run US first — highest volume, widest 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. variation (urban vs rural), fastest to compute, and the most informative single routing signal.

The decision rule (apply after the US matrix)

If the ranking-gap fraction (current-volume-weighted) is ≥ 10% of total errors AND the 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 fraction is < 20%, build the reranker. Otherwise expand 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. — US-rural if the 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 dominates there, EU-gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. if the strategic-weighted matrix shows the gap there.

DeepSeek's bet (a prediction to verify, not a fact)

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. wins: US coverage_gap ≈ 12–15%, ranking_gap ≈ 3–5% (reranker ceiling too small to move the US aggregate); EU coverage_gap > 30% → EU gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. ingest is the binding strategic constraint. Flip condition: US ranking_gap ≥ 8% AND the EU parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.-blocker shows the parser already produces clean admin-split on > 60% of ES/IT/AU → the reranker wins (build once, deploy globally; 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. becomes a parallel data track). Consult calibration: trust the structure, test the numbers — these are the numbers the diagnostic exists to check.

Workstream A — RESULT (US, 2026-06-19)

Ran scripts/eval/three-gap-matrix.ts on 10,000 OA-US rows. Faithful query (regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. parentId + 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. + parent-fallback, two-shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. admin + 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.-localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.), coordinate/name bucketing (rank of the right PLACE, not a specific 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. id — the first pass over-counted ranking gaps because 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. carries duplicate ids for one place).

metric (k = 10)	value
correct	97.88%
ranking-gap (reranker ceiling)	0.01%
recallrecallOf the spans whose gold label is a given tag, the fraction the model found. High recall means few misses. Paired with precision to compute F1.-gap	0.06%
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	2.05%
at-rank-1 among covered	100%

Identical at k = 5 / 10 / 20 → the retrieval beam is not the constraint. Route: EXPAND_COVERAGE — the reranker is dead on arrival (ranking-gap 0.01% ≪ the 10% bar). DeepSeek's structural bet (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. > reranker) is confirmed and sharpened: ranking headroom is ~0 (it bet 3–5%), and the US 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 is ~2% on this sample (it bet 12–15%).

The sharpening — what the 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 actually IS. The dumped 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 rows are almost all township / CDP / civil-division granularity, not "rural towns missing from 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.": Monroe Twp, Saylor Twp, Bertram Twp (Iowa civil townships); Barre City vs Barre Town, Essex Town vs Essex Junction Village, Saint Albans City vs Saint Albans Town (VT town/citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy./village splits); Dakota Dunes, Pennco (SD CDPs); Yankton County. OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries.' "citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy." field is frequently a civil township / village / CDP that 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. does not modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' as a locality. So the first, lowest-cost US 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. lever is a granularity/alias mapping (OA-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. → 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. place; CDP/localadmin resolution), NOT 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. re-ingest — the places largely exist, they're modelled at a different granularity.

Honest caveats (do not over-read):

• The OA sample is a 7-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., rural-skewed set (VT/IA/SD/MT + IL/CA/DC, ~1429 each), deliberately over-weighting the hard township statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.. A national, population-weighted 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. number is almost certainly lower (urban volume resolves cleanly: CA/DC/IL 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 ≈ 0–1%).
• Input is clean OA (correct regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. + 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.). Ranking-gap ≈ 0 is measured given clean disambiguating context — which is exactly what a reranker would also have. The consult's reranker-helps-on-ambiguity case (missing 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. / wrong regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.) is not exercised by clean OA; if real traffic is noisier, ranking headroom could be higher. Worth a degraded-input probe before fully closing the reranker door, but on clean data it is unambiguously DOA.

Netneural networkA model made of layers of simple numeric units whose connection strengths (weights) are learned from data. The transformer encoder at Mailwoman's core is a neural network.: for US, do not build a reranker. The coordinate lever is 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., and specifically the township/CDP granularity mapping. Whether US-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. or EU-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. is the sprint's priority is the strategic fork below.

Workstream A — EU parse-blocker result (2026-06-19)

Ran scripts/eval/eu-parse-blocker.ts on the in-repo OA samples (1500 rows/localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., ship-config v4.11.0 parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates., normalizeCase on). The proxy is gated on whether the admin tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. is actually IN the input (the first cut wasn't, and wrongly flagged ES/IT/NL as parser-blocked — OA writes "streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels., 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. localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy." and the provinceregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. is implied by 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., NOT a tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words., so there is nothing to split). Corrected:

localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.	regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.-in-input	admin-split (when in input)	loc-emit → loc-correct	route
FR	n/a (OA omits dépt)	— (v1.8.0 BANBAN (Base Adresse Nationale). France's authoritative open national address register — the highest-quality training source for French addresses, with full component structure. gate: 99.6%)	100% → 97.7%	done
DE	100%	32.7% (drops 67%)	66% → 36.3%	PARSER_SHARD
ES	8.6%	—	98% → 21.3%	parser (localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.) then 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.
IT	1.9%	—	100% → 58.7%	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. + parser polish
NL	2.9%	—	99% → 64.0%	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. + parser polish

The finding overturns the simple "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. wins for EU" narrative — and DeepSeek's "just ingest 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." bet. The binding EU constraint is the PARSER, not (yet) 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.. The modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' emits a localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. almost always (98%+) but gets it right only 21–64% outside FR (vs FR 97.7%, US ~98%). It's en-us-centric; only FR got a dedicated shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. Per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.:

• DE — parser, and it's the cleanest next FR-style win. The regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. is always in the input (Mülsen, Sachsen; Berlin, Berlin) and the parser drops it 67% of the time and drops the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. on the city-statedual-role placeA place that is two placetypes at once — Berlin as both a city and a state, Washington DC as city and district. Resolved using the coincident-roles relation plus hierarchy completion. / City, Region PLZ format (loc-correct 36%). Crucially DE is already in the 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. DB (US/DE/FR) — so a DE admin-split / City,Region shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (the FR template) moves the DE coordinate immediately, no ingest required. Overlaps the known German city-statedual-role placeA place that is two placetypes at once — Berlin as both a city and a state, Washington DC as city and district. Resolved using the coincident-roles relation plus hierarchy completion. work.
• ES — a specific, likely-cheap parser bug. loc-correct 21% because the Spanish streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. keyword CALLE isn't recognized and bleeds into the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. (CALLE HUERTA… → localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. ALLE CA). ES is also zero-DB, so it needs 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. too — but the localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. must parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. first.
• IT / NL — 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. (zero-DB) primary, with modest localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. polish (59% / 64%).

Caveats (loc-correct is a FLOOR): strict normName equality under-counts multi-tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. / bilingual / variant names — ES is additionally depressed by bilingual slash-truth (Sant Vicent del Raspeig/San Vicente del Raspeig); DE by the city-statedual-role placeA place that is two placetypes at once — Berlin as both a city and a state, Washington DC as city and district. Resolved using the coincident-roles relation plus hierarchy completion. drop. The relative ordering (FR ≫ IT/NL > DE > ES) is the trustworthy signal, not the absolute floors. OA samples are clean-ish; real traffic may differ.

Routing implication: the EU multi-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. bet is a bigger, more parser-shaped lift than "ingest 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." — per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. parser readiness gates the coordinate before 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. can pay off. The lowest-friction EU coordinate win is a DE admin-split shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (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. already covers DE; clear, measured parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. gap), directly reusing the FR-admin-split template.

The strategic fork (operator's call — surfaced, not assumed)

Volume-weighting is circular for us. "US is ~65% of queries" is an artifact of what we currently serve (a US-centric modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' + US/DE/FR-only gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture.), not where the strategic value is — mailwoman is positioned as a sovereign, EU-first, multi-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. alternative to Google geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available.. So the matrix is computed twice: current-volume-weighted (optimize the book we have) and EU-strategic-weighted (the book we're trying to win). If the two weightings route to different levers — likely: US says "reranker or US-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.," EU says "gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. ingest" — that divergencedivergenceA training failure where loss descends through warmup, plateaus low for a while, then climbs catastrophically back to its starting magnitude — the model unlearns everything despite no obvious component failure. is the strategic decision, and it is the operator's to make. The diagnostic's job is to make it explicit, not to pick.

Workstream B (conditional, post-diagnostic): the chosen lever

Whichever the matrix routes to. If it's the reranker, the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. is pre-registered now so an in-distribution win cannot fool us (our GBMGBT (Gradient Boosted Trees). A non-linear machine learning model that combines many weak decision trees into a strong predictor. Mailwoman uses a GBT as an optional learned scorer for single-dataset dedup, improving F1 by 5–7 percentage points over the Fellegi-Sunter baseline. record-matcher's TX→CA over-fit + "smokes-mislead-at-scale" scars):

• Leave-one-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.-out / leave-one-regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.-out splits (random splits leak geographic structure).
• Full held-out set, not smokes (the 250-record smoke misled us 3×).
• 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.-ablation as a lie detector: pop-only (baseline) / name-only / hierarchy-only / full. A generalizable signal transfers across held-out statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.; an over-fit one only helps in trainingtrainingThe process of adjusting a model's parameters so its predictions match labeled examples, by repeatedly measuring error and nudging the weights to reduce it. Distinct from inference, when the trained model is run on new input. statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality..
• Pre-register per error class, not aggregate p50 (which conflates the three gaps): right-name- wrong-instance "Springfield" (target ≥ 50% recovery), population-tiebreak (≥ 30%), hierarchy-conflict (≥ 70%, the easiest — the correct 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. is directly observable), 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.-type (< 5%, likely a retrieval fix).
• Cheapest falsifier first: a LightGBM / logistic reranker over existing candidates with cheap featuresfeatureAn 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. (log-pop, 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.-type, Jaro-Winkler, hierarchy-match) — no GPU. If a shallow modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' can't beat the hand-tuned 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. on the ranking-gap subset, a transformerneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' won't either.

If it's 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 or a multi-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row., that's a separate scoping (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. ingest pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. per the existing national-situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. / Overture work; or the FR-admin-split shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. template).

Out of scope / parked

• SpanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.-headattention headOne of several parallel attention computations in a layer, each free to focus on a different kind of relationship between tokens. Their outputs are concatenated — 'multi-head attention'. Mailwoman uses 4 heads. + lower-fertilityfertilityHow many tokenizer pieces it takes to spell a word: fertility 1 means whole words survive tokenization, fertility 3 means they arrive in fragments. High fertility hurts sequence labeling directly — the model has to reassemble a word before it can label it, and fragment boundaries are where labels break. Mailwoman measured this on French street names: accented words splitting at the accent ('René' → '▁Ren' + 'é') caused real geocoding misses, and lowering French fertility was worth a tokenizer revision plus a retrain. vocabvocabularyThe fixed set of tokens a tokenizer can produce. Mailwoman's SentencePiece vocabulary is tens of thousands of subword pieces, with byte fallback for anything outside it. (#727): future-enablement for CJK/Cyrillic, not this sprint. Coordinate-invisible today.
• The enforceWordConsistency decode-fix: already shipped default-OFF; not revived here.
• A transformerneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' reranker: gated behind the cheap LightGBM falsifier showing ranking-gap signal.

Exit criteria

1. The US Three-Gap Matrix is computed (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. / recallrecallOf the spans whose gold label is a given tag, the fraction the model found. High recall means few misses. Paired with precision to compute F1. / ranking, at k = 5/10/20) and the decision rule fires a route.
2. The matrix is re-weighted EU-strategic + the parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates.-blocker proxy is run on FR/DE/ES/IT samples.
3. The reranker-vs-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.-vs-multi-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. route is chosen — with the strategic fork resolved by the operator if the two weightings diverge.
4. DeepSeek's numeric bet is confirmed or refuted against the actual matrix (logged, not hand-waved).

Outcome (2026-06-20): coverage, confirmed at full scale

The route chosen was 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., and the falsification held end-to-end. We built an Overture-divisions gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. for the 15 zero-DB EU localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., folded the ingest into the canonical build (build-unified-wof.ts --overture-countries, commit 8b018366), rebuilt the whole admin DB to a staging path (1.81M 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. + 299k Overture places, one Freeze, integrity_check = ok), and graded the assembled coordinatecoord metricThe primary evaluation metric: distance from the resolved coordinate to the true address point. Measured at percentiles (p50, p90) and as 'within X meters.' Prevents the label-F1 trap where a model scores higher on token labels but geocodes worse. against held-out Overture rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. truth with scripts/eval/eu-coord-direct.ts. No modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' was retrained — the v1.8.0 parser is unchanged.

Coordinate p50 / resolve-rate / localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-name-match, 300 held-out rows each, sorted by p50 (* = already-covered ES/IT/NL control, from the global 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. path):

localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.	resolve	p50 km	p90 km	name-match
LU	69%	0.4	1.0	69%
LV	34%	0.7	52.0	31%
CH	69%	0.7	30.1	55%
HR	83%	0.8	87.4	73%
SK	57%	1.0	2.3	54%
PT	83%	1.4	4.9	76%
IT *	95%	1.5	118.2	82%
NL *	97%	1.5	4.5	59%
SI	55%	1.6	56.1	36%
CZ	71%	1.7	146.1	55%
AT	54%	1.9	109.8	43%
BE	89%	1.9	5.5	85%
PL	82%	2.1	367.4	58%
ES *	95%	2.2	10.5	65%
DK	53%	2.3	12.0	48%
FI	70%	3.4	19.3	68%
NO	53%	7.1	280.7	43%
LT	6%	78.5	226.8	0%

The median coordinate is solved for 14 of 15 — interleaved with the ES/IT/NL control (1.5–2.2 km). Built from the Overture divisions gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. plus the postcode anchoranchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags., zero GPU.

The one outlier is LT, and it's an evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.-data artifact, not a 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: the DB carries 20,960 Lithuanian localities and Vilnius / Kaunas / Klaipėda resolve perfectly, but the LT address localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. field carries settlement-type suffixes (mstl. / m. / k. = miestelis / miestas / kaimas), Lithuanian genitive declension (Rumšiškių vs the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture.'s nominative Rumšiškės), and an LT- 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. prefix — so the held-out strings don't match the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. names. Real LT input would need that normalization (or the modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' to learn it); the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. itself is fine.

The control rows (ES/IT/NL) are unchanged from the global 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. path — the Overture backfill regressed nothing. The remaining levers are resolve-rate (the 34–70% localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.: more 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. 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. on the unresolved fraction) and the p90 tail (wrong-place nametoponymA proper name for a geographic place. collisions — note IT, a covered control, also tails to 118 km, so this is a general 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.-ranking job: population tiebreak / 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. constraint, not specific to the new localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.). Neither is a parser-retrain lever.

The staging DB (admin-global-priority-eu.db) is built and validated; promoting it to the shipped admin-global-priority.db is the gated canonical-DB swap awaiting operator GO.