2026-07-17 — v3.10.1: the #727 span head on the ship recipe (8k), and the k-best headroom is real
Night-4 of the #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).-2 arc (plan #1134), step 4: 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. 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. arc. The phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-1 probes (v3.0.0→v3.0.1) proved a trained semi-Markov 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. scorer beats flat-BIO decode, but on the v257 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. and as a standalone 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.. This run answers the integration question — does that 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. survive being folded into the SHIPPED v381 recipe (v0.11.0-no-fragment 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., all the ship channels), and how much k-best headroom does it actually expose for the phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c 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. rerank?
The recipe
v3.10.1-span-ship-8k.yaml = the shipped v381 (v6.5.0) recipe + the semi-Markov 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. scorer
(use_span_scorer, span_dim 128, max_span 8, span_loss_weight 0.5) with its own optimizeroptimizerThe component that decides how to update parameters from the gradient — Adam/AdamW being the common choice, adding momentum and per-parameter scaling on top of plain gradient descent. param
group (span_head_learning_rate 1e-3; the encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). stays at 1e-5 — the phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-1 lesson). Trained as a
2k probe, then RESUMED (not init_from — 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. is the capability being grown) from
step-002000 to 8000. A P3 all-caps augment (augment_upper_case_prob 0.15) rode along as a passenger.
Same 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. + 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. as v381 → every F1 comparison below is valid.
Reads — all pre-registered
| read | v381 (base) | v3.10.1 8k | verdict |
|---|---|---|---|
| golden us micro / exact | 86.9 / 66.2 | 86.9 / 66.3 | GUARD PASS (byte-stable) |
| golden fr micro / exact | 90.1 / 75.4 | 90.0 / 75.4 | GUARD PASS (noise) |
| seg@1 (parity 267, starvedstarvedA tag with too little training representation to learn — near-zero F1 — because the corpus adapter never emits examples of it (intersection tags sat at 0% until an intersection synthesizer existed).) | 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.@1 0.558 | 0.588 | GATE PASS (+3.0pp) |
| oracle@5 (parity 267) | — | 0.7865 | +6.4pp over v301's 0.7228 |
| all-caps raw-case exact (P3) | 48.3 | 48.0 | FAIL (inert, −0.3pp vs +5pp bar) |
train_loss 18.6→1.31; val macro_f1 0.6937 (= the 2k's 0.6936 — the 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. path is untouched, 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. is a purely additional output).
What the numbers say
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. integrates at zero 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.-path cost. golden us/fr micro identical to v381, exact ±0.1pp. 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. scorer is a new output 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.; the BIO path 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.' already shipped is byte-stable. There is nothing to "promote" on the 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. side — and nothing to lose.
The k-best headroom is real and large. oracle@5 0.7865 vs seg@1 0.588 = 0.1985 of streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.@1 sitting in ranks 2–5, recoverable by a reranker that never touches 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.'. oracle@3 is already 0.745 — most of the headroom is in the top 3. This is the empirical foundation the whole 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).-2 arc rested on (the plan cited oracle@10 0.749); the 8k ship-recipe 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.' exceeds it (oracle@5 alone 0.786), and beats the phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-1 v301 substrate by 6.4pp.
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. plateaus by 2k. seg@1 was 0.603 at 2k, 0.588 at 8k (−1.1pp, noise); oracle@5 likewise saturates. The extra 6k steps refined train_loss (1.49→1.31) but not the decode gate — the same 2k≈8k plateau the B4b digit arc hit. The 8k is the "complete" run (lowest lossloss functionA number measuring how wrong the model's predictions are on a batch of examples. Training minimizes it. Mailwoman's loss combines per-token negative log-likelihood with the CRF sequence loss., clean schedule) and the better-provenance substrate, but 2k would have served equally on the decode metrics.
P3 all-caps is inert — closed. The augment failed its +5pp bar at 2k AND at 8k (48.0 vs 48.3 both times). More steps didn't help; the augment does not teach all-caps robustness at rate 0.15. The #690 title-case shim stays (worth +12.4pp raw-case today). A separate higher-rate probe is the only open path, and it's the operator's call — this augment, as configured, is a measured negative.
Status — substrate, not a ship
This 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.' ships nowhere on its own. 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. is dormant until phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c wires the k-best
decode + the name-evidence rerank (docs/superpowers/specs/2026-07-17-727-phase4c-street-name-evidence.md).
The 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. path is byte-stable, so there is no BIO regression to gate and no promote decision to make
tonight. What this run produces is the phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c decode substrate: an int8 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.' that exports
span_scores + the semi-crf-transitions.json sidecar (the export_onnx path was extended tonight
to emit it), staged at scratchpad/v3101-cache + the checkpointcheckpointA saved snapshot of the model weights and optimizer state during training. Mailwoman saves a checkpoint periodically so training can resume after a GPU hang. on the 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. volume.
The measured chain now runs end to end: trained 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. → k-best decode (PR #1154) → oracle@5
0.786 headroom → name-evidence rerank (phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4b: +18.5pp bare-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. on the FR fragment board,
148 fixes / 3 breaks). Every link is measured; none is promoted. PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c (build
StreetLocalityEvidence, wire the rerank behind a flag, re-run the full promote battery WITH the
rerank active) is the next arc, gated on #1154 merging and the operator ratifying the spec.
Artifacts
- Config:
corpus-python/src/mailwoman_train/configs/v3.10.1-span-ship-8k.yaml(RESUME v3.10.0 2k → 8k). - CheckpointcheckpointA saved snapshot of the model weights and optimizer state during training. Mailwoman saves a checkpoint periodically so training can resume after a GPU hang.:
output-v3100-span-ship-probe-s42/checkpoints/step-008000(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. volume). - int8 + sidecar:
output-v3100-span-ship-probe-s42/model-int8.onnx+semi-crf-transitions.json. - Grade instruments:
scratchpad/grade-v3101.sh,oracle-read-v3101.mjs,eval_seg_at_1.py.
Correction: the name-evidence rerank, re-measured on THIS model (not the v301 proxy)
PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4b measured the name-evidence rerank on the v301 phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-1 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. (the only 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. 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.' then exported). Re-running the FR fragment board (n=1600) on the v3.10.1 8k substrate — 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.' phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c will actually decode — corrects the headline:
| class | v301-proxy seg@1 → rerank | v3.10.1 8k seg@1 → rerank |
|---|---|---|
| bare-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.675 → 0.860 (+18.5) | 0.905 → 0.950 (+4.5) |
| date-name | 0.100 → 0.182 (+8.2) | 0.403 → 0.570 (+16.7) |
| streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-particle | 0.802 → 0.860 (+5.8) | 0.925 → 0.945 (+2.0) |
| streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-housenumber | 0.897 → 0.922 (+2.5) | 0.932 → 0.940 (+0.8) |
| overall | 0.619 → 0.706 (+8.7) | 0.791 → 0.851 (+6.0) |
96 fixes / 3 breaks (32:1, cleaner than the proxy's 10:1). The ship-recipe 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. (all channels
- v0.11.0 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. + 8k) is FAR stronger at rank-1 than the bare v257 phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-1 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. — seg@1 0.791 vs 0.619 — so it leaves less recoverable headroom (146 vs 202 recoverable rows). The rerank still earns its keep (+6.0pp, 32:1), but the value has MOVED: bare-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. is nearly solved by 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.' itself (0.905), and date-name is now the primary beneficiary (+16.7pp — the class 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.' still finds hardest). The proxy's "+18.5pp bare-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels." was a weak-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.' artifact; verify on the substrate you'll ship. PhasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).-4c is still worth building, but its pitch is date-name + the long tail, not bare-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels..