Word-consistency heal: re-diagnosis, contract fix, ship default-ON (night-3)

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.': v264 (v6.3.0 shipped weightsparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values.) — no retrain; every change is decode-side library code. Change set: PR #1132. Gate revision (explicit): the parity gate now grades the ship-config 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. (heal ON, --no-word-consistency for pre-heal continuity). Floors untouched.

What was wrong

The per-word BIO consistency heal (neural/word-consistency.ts, built for #727) was shelved default-OFF at the 2026-06-19 gate: streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. −12.6 on the adversarial golden, attributed to "the confidence-weighted vote amplifies noise on byte-soup rows," with a confidence-gated variant named as the path to a clean win.

Night-3 re-diagnosis: the regression was two defects in the heal, not vote noise —

1. Contract bug. The vote re-decoded words whose piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). already AGREED in type whenever local type-mass preferred another type, silently overriding viterbiViterbi decodingA dynamic programming algorithm that finds the most likely sequence of hidden states (labels) given a sequence of observations (token emissions). Mailwoman uses Viterbi over a linear-chain CRF to produce globally coherent BIO label sequences from per-token model scores.'s global decision. Single-piece ▁Broadway (B-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.) flipped to O; all-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. Gamle rewrote to localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.. The module docstring had always claimed "a word whose piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). already agree is left byte-identical" — the code only honored that when the vote happened to agree. Now enforced structurally: the vote runs ONLY on words whose piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). disagree in type.
2. Grouping bug. Punctuation continuation piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). joined the preceding word's vote group (Ave + , — the comma piece carries no ▁ sentinel), and their O mass manufactured a fake intra-word disagreement that killed the real 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.. This is the whole ordinal-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. golden class (1st Ave, ND: the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. dies at the comma, not at the ordinal). Fixed by splitOnPunctuation: punctuation-only piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). separate vote groups like whitespace — which also rescues slash compounds (Unit 12/345 keeps unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. ≠ house_number).

A minMeanConfidence floor (the hypothesized fix) was implemented and measured 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.-negative on the fragment-heavy parity 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. — fragment rows are low-confidence but heal correctly. It ships as an unused opt. skipByteFallbackWords (raw <0xNN> piecesECE (Expected Calibration Error). A metric that measures how well a model's confidence scores align with its actual accuracy. Lower is better. Mailwoman's held-out ECE drops from 0.067 (raw) to 0.0035 (calibrated). void the vote premise) is part of the ship default.

Measurements

Gate bars (config-canonical, unchanged): parity floors house_number ≥ 0.97 / 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.97 / streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. ≥ 0.90; golden 2pp per-tag promote gate; demo presets 6/6.

Golden per-locale-f1 (dev us/fr/adversarial, v264, anchor+gazetteer fed)

file	macro F1macro F1The unweighted average of per-class F1 scores — treats every class equally. Mailwoman's primary label-level eval metric. off → on	streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. F1 off → on
us	48.0 → 48.3	82.0 → 82.2
fr	42.2 → 51.5	90.8 → 91.8
adversarial	66.0 → 66.5	85.7 → 85.7

The historical −12.6 streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. regression is not just neutralized — every file improves or holds.

Parity floors (triaged corpus, 321 live, canonical eval parity)

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.	off	on (ship)	floor	verdict
house_number	0.7671	0.8082	0.97	FAIL (arc target)
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.9722	0.9861	0.97	PASS
streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.	0.5431	0.5730	0.90	FAIL (arc target)

Golden error-analysis (2pp promote gate): PASS

Worst regression 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. −0.4pp (n=245, noise); gains localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. +1.9, venuevenueA named, non-address place — a business, building, park, or stadium. Mailwoman's free-text point-of-interest component, added as a Tier 2 fine label. +1.0, po_boxPO boxA numbered mailbox at a post office used as a delivery address instead of a physical street location. Mailwoman tags it as the po_box component; structurally the same family as a subpremise. +3.7; exact-match 24.5% → 25.5%. Full tables: scratchpad/ea-wc-{off,on}.md (session artifacts).

Demo presets (eval-model): PASS

6/6 both modes, zero grouper-auditgrouper-auditA validation pass checking that phrase-grouper spans are internally consistent — no overlaps, no contradictions with BIO structural rules. Audit errors must be zero on a shipping model. nodes. The Pier 39 unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise.-tag quirk (conf 0.03) is pre-existing v264 behavior — identical with the heal off.

Diacritic locales (parity subset, heal ON — the "visibility, not regression" check)

localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.	streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-tag exact	resolve-localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.
CZ	2/3	3/3
PL	5/6	2/2
PT	5/8	2/2
RO	4/5	3/3
SK	1/1	1/1

The citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. never resolves wrong; only the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. surface string misses. Confirms the night-2 hypothesis that prior splice-era wins were measured on resolve while the new parity metric measures surface exactness. Residual PT/RO cases are byte-fallback words the heal deliberately skips — the splice 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 stands (smaller than night-2 believed).

Scope

Decode-side only: no 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. change, no #378 SLO impact, browser runtime shares the classifier. Ship sites: core/pipeline/runtime-pipeline.ts (safeClassify) + mailwoman/geocode-core.ts (parseForGeocode), via the shared WORD_CONSISTENCY_SHIP_DEFAULT constant. The 2026-06-19 gate history is preserved in the module docstring with the corrected attribution.