2026-07-14 — v261 promoted (6.1.0); the country 2pp gate, documented as a cosmetic exception
v261 (v2.6.1-span-boundary-full, #727 stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone).-1) is promoted to the shipped neural-weights-en-us
default. It is a clean improvement over v241 on the schema-correct gates, and it trips the golden
countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. 2pp pre-publish gate — which this note documents as a cosmetic exception with the
falsifier evidence that justifies shipping through it. No gate was silently relaxed.
Why v261
| gate | v241 (shipped) | v261 | note |
|---|---|---|---|
| parity streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. (triaged) | 0.3967 | 0.5281 | +13pp — the schema-correct campaign gate |
| parity house_number | 0.7013 | 0.7671 | +7pp |
| parity 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. | 0.9861 | 0.9861 | PASS |
| US regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality.→streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. flips (census /600) | 5 | 2 | boundary-absorption halved (#727 aux 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.) |
| gauntlet regression + metamorphic | PASS | PASS | Dublin bare-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. coordinate pin held |
| golden countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. 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. | 88.6% | 82.0% | −6.6pp — the gate that fired |
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.-boundary aux 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. is 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.-only (off the logitslogitA raw, unnormalized per-label score the model outputs before softmax. Priors and biases are added in logit space, then softmax turns logits into probabilities. path, not exported); the shipped ONNXONNX (Open Neural Network Exchange). An open format for machine learning models that enables interoperability between training frameworks and inference runtimes. Mailwoman ships its trained model as an ONNX file so it can run in Node.js and the browser via onnxruntime. is the plain BIO tagger whose encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). absorbed the boundary pressure. 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. v0.9.0-multisplice.
The country gate exception (#1104) — falsifier evidence
The −6.6pp golden countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. 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. fired the 2pp pre-publish gate. A falsifier (DeepSeek session 019f5f2c) split the 224 golden countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.-gold rows into 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.-admin hierarchy vs real-postal:
- 220 of 224 are 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.-admin hierarchy rows —
country, region, localitywith a leading long-form countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. and/or a transliterated non-Latin localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. (e.g. "United StatesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. of America, Wyoming, Лорейн"). These are 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. hierarchy strings, not addresses anyone types. - Only 4 are real-postal. On the real-postal subset, and on 300 real no-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. rows (precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1.):
| 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.' | real-postal countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. 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. | halluc. (300 real no-countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. rows) |
|---|---|---|
| v241 (shipped) | 3/4 | 0.7% |
| v257 | 3/4 | 0.7% |
| v261 | 3/4 | 0.7% |
Identical across the whole fragment lineage. The −6.6pp is entirely on the non-postal 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.-admin distribution; on real addresses countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. 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. AND precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. are unchanged. The gate over-weighted a slice that is 98% synthetic hierarchy rows. Promoting v261 does not regress countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. on production input.
The permanent fix (in progress)
CountrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is a closed, enumerable class (~250 surfaces, in @mailwoman/codex COUNTRY_SURFACE_FORMS).
PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. handles it as a position-independent DICTIONARY phrase-lookup (WhosOnFirstClassifier), not a
learned tag — i.e. countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. is atlas, not grammar. The right permanent fix (per the consult) is a
countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head.-lexicon soft-feed channel mirroring the existing 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. channel, which recovers
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.-admin/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. countrycountryThe top-level address component (an ISO country). Closed-vocabulary, so it is best handled by a deterministic matcher feeding a proposal rather than a retrained model head. without a data counterweight. That work is tracked on the
feat/country-lexicon-channel branch and docs/superpowers/plans/2026-07-14-country-lexicon-channel.md.
Data counterweight iterations (v290 tail rows +0.9pp, v291 leading rows +0.4pp) confirmed diminishing returns — expected, since teaching a grammar to memorize a lexicon is the wrong tool. v2.9.2 (built, not trained) is retained only as future channel 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. signal.