Re-gating joint-reconcile after the #565 grouper fix
2026-06-14. We retired joint-reconcile to argmax (#566) after an audit found it broke 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. + house-number geocode precondition on 77–84% of clean US addresses. The root cause — the phrase grouperphrase grouperStage 2.7 of the runtime pipeline: proposes coherent input units (street phrase, locality phrase, postcode, etc.) with structural kind hypotheses. Decouples boundary discovery from type classification so the classifier answers 'what type?' not 'where?' bundling the house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. into 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. phrase — was then fixed (#565). This report answers the obvious follow-up: now that the destructive mechanism is gone, does reconcile earn its way back as the default (or at least FR-scoped, the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. #427 claimed it helped)? Graded on the assembled 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. in both modes, the answer is no. #565 repaired the structural break, but reconcile is still strictly worse than argmax on tag values — worst on the exact localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. it was supposed to help. Argmax stays the default; the parked re-promotion decision is resolved as "keep retired."
Why we re-gated
The retirement was a de-promotion under fire — the geocoder needed a clean streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. and a separate house number, reconcile was merging them, so we flipped the default to argmax and moved on. But two things left the door open:
- The #427 claim that joint-reconcile helped FR/EU. If true, retiring it would cost those localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. something, and an FR-scoped re-promotion via the policy registrypolicy registryThe per-component table that decides which classifier (rule or neural) has authority for each address component. The Ship-of-Theseus dial. might be the right shape.
- The #565 grouper fix removed the specific mechanism (house-number bundling) that the retirement audit blamed for the 77–84% precondition break. With that gone, reconcile might now be neutral-or- better.
So the question is sharp and worth a real measurement: run the 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. with jointReconcile: true
and see whether it beats-or-matches argmax (jointReconcile: false, the #566 default) — on FR without
regressing US — grading the assembled 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., never raw neural. Grading raw neural is the mistake
that hid the original regression for months; we do not repeat it.
What we measured
Two harnesses, both comparing the assembled runtime 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. in argmax mode vs reconcile mode (same
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., same grouper, only the jointReconcile flag differs):
scripts/eval/reconcile-regate.mjs— per-tag 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. on golden v0.1.2, US and FR graded separately.scripts/eval/reconcile-precondition-regate.mjs— the share of rows that keep a separatestreet+house_number+postcode(the geocoder precondition), on the Travis/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. holdout (/tmp/ood-truth.jsonl, n=1965). This holdout is the same non-circular real-points file used in the retirement audit — E-911 / parcelparcelA property polygon or record carrying a situs (site) address and often a separate owner mailing address. County GIS parcel aggregations are a training source for address-point variety and situs-vs-owner divergence.-centroid provenance, disjoint from 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. and from grouper tuning, so the precondition number is not gamed.
Per-tag recall — reconcile is worse, everywhere it isn't flat
US — golden v0.1.2, n=2956 addresses
| tag | argmax | reconcile | Δ (rec − argmax) |
|---|---|---|---|
| house_number | 99.8% | 99.5% | −0.3pp |
| streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. | 95.3% | 92.9% | −2.4pp |
| localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. | 97.7% | 95.9% | −1.8pp |
| regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. | 55.7% | 56.2% | +0.5pp |
| 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. | 72.2% | 72.7% | +0.5pp |
| 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. | 95.2% | 95.0% | −0.2pp |
| unitunitA subdivision of a building — apartment, suite, floor — that refines a street address. Mailwoman's unit component; a designator plus identifier forms a subpremise. | 100.0% | 100.0% | +0.0pp |
FR — golden v0.1.2, n=1551 addresses
| tag | argmax | reconcile | Δ (rec − argmax) |
|---|---|---|---|
| house_number | 83.0% | 84.8% | +1.8pp |
| streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. | 79.4% | 65.7% | −13.7pp |
| localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. | 80.2% | 76.5% | −3.6pp |
| regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. | 17.4% | 10.5% | −6.8pp |
| 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. | 63.9% | 63.4% | −0.5pp |
| 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. | 100.0% | 100.0% | +0.0pp |
US has no offsetting win — streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. regresses 2.4pp, localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 1.8pp, everything else flat. FR is the damning column: reconcile takes streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. from 79.4% to 65.7% (−13.7pp), with localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. and regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. also down. Its only gain anywhere is FR house_number (+1.8pp). The localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. #427 said reconcile helps is the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. it hurts most.
Precondition — #565 worked, but reconcile still isn't at parity
Travis/OA holdout, n=1965 (predominantly Austin TX)
| mode | streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.+HN+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. preserved | reconcile BREAKS (argmax had it, lost it) | reconcile FIXES |
|---|---|---|---|
| argmax | 1965 (100.0%) | — | — |
| reconcile | 1854 (94.4%) | 111 (5.6%) | 0 (0.0%) |
This is the good news and the verdict in one table. The #565 fix is real: the precondition break
collapsed from the retirement audit's 77–84% to 5.6%. But argmax preserves the precondition on
100% of these rows; reconcile still drops 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. to null on 5.6%, and fixes nothing argmax
missed. The break pattern is consistent — multi-word residential streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.:
7425 Marble Ridge Drive, Austin, TX 78747 argmax: st=Marble… reconcile: st=null
11407 Saddle Mountain Trail, Austin, TX 78739 argmax: st=Saddle… reconcile: st=null
5712 Sunny Vista Drive, Austin, TX 78749 argmax: st=Sunny… reconcile: st=null
The mechanism
#565 fixed the grouper's house-number bundling — the structural break that the retirement blamed. What
this re-gate shows is that reconcile's harm was never only structural. By merging tokenstokenOne 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. into one
candidate 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. rather than selecting the neural argmax, reconcile destroys internal streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.
structure that argmax keeps intact. On FR that is the Rue de la <X> / Chemin du <X> prefix +
particle + core pattern — the merge collapses it and 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. value falls apart (−13.7pp). On US
multi-word residential streetsstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. it drops 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. entirely (the 5.6% precondition break). Argmax avoids
both failure modes for the same reason: it commits to 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.''s per-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. decision instead of
re-deriving 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. from phrase proposals. This is design-level behavior of the reconcile path, not a
second bundling bug to patch.
Verdict — keep reconcile retired
Both gates fail. Reconcile loses tag-value accuracy on US and FR with no localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. where it wins overall,
and it still breaks the geocoder precondition on 5.6% of rows where argmax never does. There is no slice
— not even FR — where re-promotion is 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.-positive. Argmax stays the default. Joint-reconcile remains
opt-in (jointReconcile: true) and undefaulted; this report is the record of why. The #427 "reconcile
helps FR" claim was an artifact of grading raw neural — the same blind spot that hid the original
regression.
Independent of the reconcile decision, the argmax-FR streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. ceiling of 79.4% is its own open question (and the FR streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels./regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. 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. generally) — that is a 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.' + FR-grouper matter, not a reconcile one, and is left to the FR parity track. Worth capturing as a learning item; not a prerequisite for this verdict.
Resolved parked decision
Re-promote reconcile + scope — resolved: no. Keep retired (argmax default). Evidence: this report. Concurred by an independent review (DeepSeek, 2026-06-14).
Reproduce
yarn compile
node scripts/eval/reconcile-regate.mjs data/eval/golden/v0.1.2/us.jsonl data/eval/golden/v0.1.2/fr.jsonl
node scripts/eval/reconcile-precondition-regate.mjs /tmp/ood-truth.jsonl
See also: 2026-06-14-reconcile-retirement.md (the de-promotion
that prompted this re-gate).