Runtime-flag register
The policy (SCOPE, invariant 5): a runtime flag is a measurement instrument, not a home. Every 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. This register is the accounting — a flag with no row here is a smell, and a new flag lands with its row in the same PR.
Enumerated from the option surfaces 2026-07-02 (CreateRuntimePipelineOpts, PipelineOpts,
ClassifierOpts, ResolveOpts, ParseOpts, NeuralAddressClassifierConfig, CreateScorerOpts,
GeocodeDeps, 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., the drop-in CLIs, and the demo cascade). Tuning sub-knobs
(bias scales, gate radii, lookup caps) are listed with their owner flag, not separately.
Default-ON — earned it, or required ship config
| flag | home | since / evidence |
|---|---|---|
spanRescore (+ spanRescoreGateKm 50) | ResolveOpts | #370 — EU @25km +16pp e2e; promoted to default 2026-06-25. false opts out |
hierarchyCompletion | ResolveOpts | #402/#405 — recovers the dropped localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. in dual-role-place addresses |
parentFallback | ResolveOpts | 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. liveness: one retry without the parent constraint on an empty filtered lookup |
placeCountry (soft priorsoft priorOutside knowledge fed to the model or resolver as overridable evidence (a feature, a score term) rather than a hard filter. A focus-country hint becomes an anchor feature; a focus-point becomes a ranking term.) | CreateRuntimePipelineOpts / GeocodeDeps | #244 — coarse-placercoarse-placerA lightweight int8 country classifier (~0.79 MB) that predicts which of a set of target countries an address belongs to, feeding a soft prior into resolver disambiguation. 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. router, in-map routing 64.7 → 85.3%; false disables |
hardPlaceCountry (+ hardCountrySafelist) | 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. / geocode-core | #743/#194 — 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.-guarded HARD 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. filter, default-ON since 4.12.0 (population-first ranking can't be out-scored softly for low-pop localeslocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.) |
bridgePunctuationGaps | classifier config | required ship config since v4.4.0 (requires_bridge) — 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. 60.4 → 89.1; dotted surfaces are 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.-unlabelable |
addressSystemConventions: "auto" | classifier config / scorer | required ship config since v4.3.0 (requires_conventions) — the localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-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.-keyed conventions maskconventions maskA decode-time constraint layer keyed by the model's own address-system detection (the exported locale head): tags that are ungrammatical in the detected system are removed from the Viterbi vocabulary, and the system's postcode shape arms a snap-only repair pass. The first slice forbids USPS street-affix decomposition for French. Same knowledge-outside-the-weights property as the gazetteer anchor — add a codex conventions row, no retrain. |
spanProposer | classifier config | #518 — 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.7 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.-proposal priors; false disables |
strict (fail-closed channel gate) | createScorer | #718 — refuses to grade/serve 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.' with a declared-but-unfed channel (the zero-fill trap) |
normalizeCase | classifier / 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. / GeocodeDeps | #690/#713 — all-caps title-casing; TX localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 90.1 → 99.7, +15% cross-dataset rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data.. Default-ON everywhere since #895 (drift D2 settled 2026-07-02); false restores the raw-case 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. |
adminCoherence | ResolveOpts / GeocodeDeps | #263/#837 + #822 — joint admin-consistency re-pick + explicit-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. coherencecoherenceThe property of a parse whose resolved places form a consistent geographic hierarchy — the resolved locality really does sit inside the resolved region.; bare "CitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy., 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." 54 → 78%. Default-ON everywhere since #895 (drift D1 settled 2026-07-02); false opts out |
Default-OFF — measured, kept as opt-in with a named reason
| flag | home | verdict / blocker |
|---|---|---|
postcodeConsistency (+ gate km) | ResolveOpts | #370 lever A — measured; the promoted spanRescore covers the common case, this stays a lever |
anchorPosterior (+ anchorWeight 2.0) | ResolveOpts | #369 — 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.-anchor country posteriorcountry posteriorA country → probability map (derived from postcodes or the coarse-placer) that re-ranks resolver candidates as a soft prior, never a hard filter. re-rank; superseded on the routing job by the placer, retained for anchor-first experiments |
addressPoints / interpolation (+ calibrations) | ResolveOpts | #476/#483 — rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data./interp tierstierInternal 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.; data-gated, not evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.-gated (per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.; four statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. hosted, #735 is the rollout) — geocode-core enables them wherever shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. exist |
addressPointBboxFallback | ResolveOpts | #247 — 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. intl rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. 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. support |
includeAncestors | ResolveOpts | #404 — response-shape enrichment, consumer's choice |
defaultCountry | ResolveOpts / drop-ins | correct as a USER-expressed restriction (countrycodes=); the v4.16 lesson: never a silent server default — it hard-overrides the placer onto US namesakes |
postcodeRepair / unitRepair | ParseOpts | deterministic repair passes — subject to repair-retirement (#486); each consolidation should shrink them |
enforceWordConsistency | ParseOpts / config | #727 — the per-word BIO vote amplifies over-confidence on byte-soup; ships OFF by research verdict |
fuzzy postcode anchorsanchor inferenceA technique where structured knowledge (postcode locations, gazetteer place names) is injected into the model as soft input features — not as deterministic overrides. The model still decides the final labels, but the anchor signal biases it toward correct admin tags. | anchor extractor | typo/OCR variant matching; off until an OCR-shaped evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. exists |
calibrate | ParseOpts | isotonic calibrators ship in the weights bundlemodel weightsThe learned parameters of the neural classifier, shipped as ONNX files in the @mailwoman/neural-weights-* packages. Weights are locale-specific bundles that include the model, tokenizer, and a model-card.json metadata file.; opt-in at 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., the demo exposes a toggle |
overrides.{anchor,gazetteer,conventions,bridge} | createScorer | deliberate-ablation switches — for evalsevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error., never production (loud warn by design) |
forceFullPipeline | PipelineOpts | debugging aid — disables fast-paths |
arbitrate (+ ruleProposer, resolverBackend, policy registrypolicy registryThe per-component table that decides which classifier (rule or neural) has authority for each address component. The Ship-of-Theseus dial. modes) | PipelineOpts / #478 family | research-only. Built and merged default-OFF; promotion killed by the coordinate gate (#685: arenaarenaA standardized test set probing one capability: libpostal (clean canonical), perturb (noisy and degraded), postal (edge formats). Each arena answers a different question about where rule vs neural wins. +122 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.-wins, coord p50 3.3 → 1069 km). Do not enable outside an A/B harness; revisit only with a coordinate-gated design |
jointReconcile | PipelineOpts | retired as default (#566): 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# geocode precondition on 77–84% of clean US addresses, fixed 0%. Argmax is the default decode; flag kept for A/B only |
Deprecated — delete at the next major
| flag | replacement |
|---|---|
forceJointReconcile | jointReconcile (itself retired) |
cityStateFallback | hierarchyCompletion (alias still honored) |
Known drift (actionable)
- D1 — SETTLED 2026-07-02 (#895):
adminCoherenceis default-ON in coreResolveOpts(was geocode-core-only). #861 landed first, so both runtimes flipped together per the original disposition.falseopts out;geocode-corepropagates an explicitdeps.adminCoherence: falsedownstream so the opt-out survives the new default. - D2 — SETTLED 2026-07-02 (#895):
normalizeCaseis default-ON at the classifier (detection-gated, so mixed-case input is byte-stable either way); 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. factory forwardsundefinedand propagates an explicitfalsepin. The #690 gate numbers (TX localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 90.1 → 99.7 on all-caps) carried the flip. - D3 — CLOSED by #861 (2026-07-02): the demo runs the shared
resolveTree(CandidateResolverBackend), so the 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.-side rows above now apply in the browser. - D4 — stale comment: the demo
_app.tsxstill claims reconcile-runs-since-#427; reconcile was retired (#566). Cleanup rides the next demo touch.