Scope — what mailwoman is now

Declared 2026-07-02 (#886, Track 5 of the 2026-07-01 trajectory review). This page supersedes the v1 implementation plan as the orientation entry point. The old plan declared "US + France, Japanese as a stress test" — the project it describes shipped, worked, and outgrew it. This is the map that matches the territory; when reality moves again, this page moves with it or it becomes the next lie.

For what the system is — the calibrated-sequence-labeler + 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. division of labor — read What Mailwoman is. This page is about what it covers and the rules that hold each claim to evidence.

Two workstreams, not one

1. The geocoder — the staged pipeline (normalizenormalizeStage 1 of the runtime pipeline: deterministic input preprocessing (Unicode NFC, punctuation normalization, whitespace collapse). Returns a NormalizedInput with an offsetMap that maps normalized positions back to the raw input. → 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. → resolve → coordinate), the drop-in API surfaces (@mailwoman/{nominatim,photon,libpostal} + annotations), the browser runtime, 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./demo stack. The daily queue is epic #488.
2. Record matchingrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring. / entity resolutionrecord matchingThe process of determining whether two database records refer to the same real-world entity. Mailwoman's matcher uses a geocode-first approach (match the resolved place, not the address string) with Fellegi-Sunter probabilistic scoring. — geocode-first matching of messy records to resolved places (formatter / record / match / registry; Fellegi–Sunter + the gated GBTGBT (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. scorer). Its own epics: #598, #602, #603, #615, #625, #655. It grew inside the parser's roadmap; it is hereby a first-class workstream, not a footnote.

Locales, in tiers

The measured list, not the aspirational one. "Trained exposure" means rows in the shipped recipe's country_weights; a localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. is only claimed when a coordinate-graded evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists for it.

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.	LocaleslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.	What backs the claim
1 — first-class, floor-gated	US, FR	Golden-dev per-tag floors in the gate spec + real-OOD slices; the parity scorecard. FR coordinate (n=3000, quad shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. set, #920): resolve 100%, resolved-p90 6.6 km (was 65.3% / 109.5 km pre-wiring)
2 — trained + coordinate-paneled	IT, PT, PL, AT, CZ, DE, AU, BE, ES, NL, CH, HR, DK, FI	Per-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. coord panels on the shipped v5.1.0 pair + the #920 quad shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. set (PRs #922/#923, 2026-07-02; 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. collapsed the cross-localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. namesake tail). n=1000 each: ES 100%/1.05 km, NL 100%/0.05 km (block-level Dutch 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 #924 retry ladder — p90res 0.71 km), FI 100%/2.17, PL 100%/2.45, CZ 99.8%/1.80, HR 99.8%/2.40, SK 99.2%/1.55, SI 97.5%/1.84, CH 91.9%/0.70, DK 91.4%/1.02, BE 87.8%/2.05 (n=640); resolved-p90 ≤10 km everywhere. Signed p50 trades + composition notes in gate-v193/RESULTS.md. The browser demo carries the same 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. since the 2026-07-03a 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. (PR #931)
3 — trained exposure, thinly measured	NO, SE	NO n=1000 (quad): resolve 92.7%, resolved-p50 3.04 km, p90res 40.9 km (was 86.9%/454 km pre-#920) — residual is 75 namesake + 73 unresolved rows, row-read pending. SE n=173 (low power): 83.8%/4.47 km, p90res 113 km (SE folded into the tail shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. 2026-07-03 — namesake 18→8, clean PASS). Claims beyond that: unverified
4 — diacriticdiacriticAn accent mark that modifies a letter (é, ñ, ç). Address normalization must fold diacritics for matching without discarding the information a user typed. splice, SHIPPED v5.1.0	CZ, PL, SK, SI	The #884 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. splice, shipped 2026-07-02 as the coordinated 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.' + 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. bump: wrong-citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. roughly halved in all four at n=1k, US byte-identical; residual is #897
5 — 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.-route 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.-route resolution (Geographic Rule Engine); no parser 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. claim
Blocked / queued	SE as localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. 17 (#202, license), GB/IE/SE/HU/RO corpuscorpusThe BIO-labeled training data used to train Mailwoman's neural classifier. Assembled from real sources (OpenAddresses, National Address Database) and synthetic shards (boundary stress, order variants, negative space). Managed by @mailwoman/corpus. via 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. (#733, share-alike gate), KR (no adopted open path)	External constraints, each with a check-back owner — not engineering-blocked

Standing localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. rule: SATISFIED 2026-07-02 — the coordinated bump shipped as v5.1.0, so the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. freeze is lifted and new shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. train against the spliced 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. (the #901 campaign is the vehicle). Any future splice runs under the #900 codepoint-overlap safety gate. CJK-family localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. route through the CharCNN path (scaffolding committed, deferred), not 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. splicing.

The standing invariants

These are the disciplines the trajectory review said not to change, plus the two added at the 2026-07-02 re-anchor. They are gates, not virtues:

1. Grade 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., 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 alone. 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. metrics are a drift backstop, re-anchored on a cadence: every 5 promotes, or any promote that lowers a gate floor, triggers a full per-tag re-score (rule + procedure in CONTRIBUTING_MODEL_WORK; ledger append is automated).
2. The demo is the geocoder. The browser cascade must run the shared 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. passes (#861) and must not silently trail the released 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.' (#203's class — enforce structurally, in the release train, not by memory). A win that doesn't reach the demo is discounted to zero.
3. Pre-registered gates; falsified levers get reverted, not shipped. The config is the contract; gate revisions are written, attributed, and operator-approved.
4. Repair retirement (#486): every post-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.' patch shrinks at each consolidation. Decode-time overrides are scaffolding with a kill date.
5. Runtime flags are instruments, not homes. A default-off 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. exists to be measured. At each consolidation it either earns default-on with a gate result, stays explicitly experimental with a named blocker, or is retired. The accounting lives in the runtime-flag register — a flag with no register row is a smell.

Where the live roadmap lives

• The queue: project board (epic #488) for the geocoder; the record-matching epics above for workstream 2.
• The record: dated evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. reports under docs/articles/evals/ (latest full re-score: the parity scorecard), per-release rows in Releases & capabilities, the score ledger evals/scores-by-version.json.
• The phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). directory is historical. phases/* and the dated architecture specs are design records — read them for rationale, never for current stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality..