Query Shape — Cheap Structural Priors

Captures the design intent for the QueryShape sub-system, a 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 + 2.5 addition to the 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. (the-staged-pipeline). Bitter-lesson-safe because it recognizes what shape an input has, not which strings are localities.

Status

• Conceived: 2026-05-22 design conversation.
• Decision: commit to the sub-system; bundle as @mailwoman/query-shape. Pure functions, no ML.
• Implementation phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary).: not yet opened. Will land alongside 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 + 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.5 work in the staged-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. rollout.
• Cross-references: concepts/the-staged-pipeline, concepts/addresses-that-break-geocoders, reference/ARCHITECTURE.

Bitter-lesson framing test

Mailwoman v1 (PeliasPeliasAn open-source geocoder, Mailwoman's spiritual predecessor. lineage) hit the long-tail trap by using rules to encode place knowledge: dictionaries of 50K citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. names, hand-curated stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. abbreviation tables, 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.-specific keyword sets. Every new localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. meant a new dictionary, and the maintenance burden compounded.

The QueryShape sub-system intentionally avoids that trap by restricting itself to universal structural patterns — what character classescharacter classA token's character category — digit, alpha, CJK, Cyrillic, Arabic, mixed — used by the query-shape stage as a structural signal for locale and kind inference. the 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. are, where the punctuation is, whether a substring matches a known 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. regex. The localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-test:

Would this code change if Mailwoman added a 50th localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.?

Primitive	Adds per new localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.	Verdict
Character classcharacter classA token's character category — digit, alpha, CJK, Cyrillic, Arabic, mixed — used by the query-shape stage as a structural signal for locale and kind inference. detector	Nothing	universal
Segmentation grammar	~5 lines of localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. punctuation rules	bounded
Known-format regex set	~1 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. pattern	bounded
User-location prior	Nothing	universal

Compare to v1's 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.-based localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. classifier (~50K place namestoponymA proper name for a geographic place. per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.). That is the long-tail explosion this sub-system explicitly does not bring back.

QueryShape data structure

interface QueryShape {
	/** Dominant character class of the whole input. */
	characterClass: "numeric" | "alpha" | "alphanumeric" | "cjk" | "cyrillic" | "arabic" | "mixed"

	/** Per-token character class. */
	tokenClasses: TokenClass[]

	/** Punctuation-bounded segments, locale-aware. */
	segments: Segment[]

	/** Known-format regex hits (US ZIP, UK postcode, FR postcode, etc.). */
	knownFormats: KnownFormatHit[]

	totalLength: number
	whitespacePattern: "single" | "double" | "tab" | "mixed" | "none"
}

interface TokenClass {
	span: Span
	class: "digit" | "alpha" | "mixed" | "punct" | "cjk" | "cyrillic" | "arabic"
	length: number
}

interface Segment {
	span: Span
	body: string
	index: number // position in the segment list
	separator: "comma" | "newline" | "tab" | "whitespace" | "japanese-style" | null
}

interface KnownFormatHit {
	format:
		| "us_zip" // \d{5}
		| "us_zip4" // \d{5}-\d{4}
		| "uk_postcode" // SW1A 1AA pattern
		| "fr_postcode" // \d{5} with French context
		| "ca_postcode" // A1A 1A1 pattern
		| "de_postcode"
		| "jp_postcode" // \d{3}-\d{4}
		| "po_box" // PO Box / BP pattern
	span: Span
	confidence: number
}

Compute time: microseconds. No ML. Runs on every input before 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)..

Four primitives

1. Meta queries (character class)

Pure-character analysis of the input. Cheap, deterministic, language-agnostic. Examples:

Input	Character classcharacter classA token's character category — digit, alpha, CJK, Cyrillic, Arabic, mixed — used by the query-shape stage as a structural signal for locale and kind inference. signal
"10118"	pure-digit, length 5 → strong 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. prior
"10118-1234"	digit-hyphen-digit, length 10 → US ZIP+4 prior
"SW1A 1AA"	letter-digit-letter pattern → UK 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. prior
"NYC NY"	all-alpha, very short → likely localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-only query
"東京駅"	all CJK → script signal + likely landmark/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.
"دبي"	all Arabic → script signal
"350 5th Ave, New York, NY 10118"	mixed alphanumeric + 3 commas → structured address

These signals feed 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 (locale gatelocale gateStage 2 of the runtime pipeline: rule-based locale detection from the query shape's script and known-format signals. Returns a LocaleHint with the top candidate and alternatives, surfacing disagreement with an explicit --locale flag.) and 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.5 (kind classifierkind classifierStage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy.) as priors.

2. Phrasification (segmentation)

Punctuation-bounded chunking. Currently 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). re-learns segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. structure from punctuation 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.; making it explicit gives downstream stagesstageOne 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). a free structural prior.

Three uses, in order of complexity:

1. As encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). input 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. — segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.-id 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. concatenated to the input embeddingembeddingA vector of numbers representing a token (or other item) so that similar items sit near each other in vector space. The first thing the model does is turn each token into an embedding.. Cheap; no architecture change.
2. As attentionattentionThe core mechanism inside a transformer encoder. Each token's representation is updated by looking at every other token, with learned weights deciding how much each one matters. mask — let 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. within a segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. attend strongly to each other, weakly across. Modest architecture change.
3. As per-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. kind hint — segment[3] is 5-digit-numeric → postcode-prior for this segment only. 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.5 emits per-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. QueryShape; encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). gets per-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. priors.

LocalelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-dependence is bounded. Commas segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. in US/FR/UK; whitespace segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. in JP; honorifics in Korean. The punctuation grammar itself is localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-aware 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).-1 normalization, but the output is an abstract Segment[] that downstream stagesstageOne 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). consume uniformly. Each new localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. adds ~5 lines of segmentation rules, not 50K dictionary entries.

3. Known-format detection

A bounded set of universal 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. and well-known-format regexes:

• US ZIP / ZIP+4
• UK 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.
• FR 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. (5 digits with French context)
• CA 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. (A1A 1A1)
• DE 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.
• 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. (\d3-\d4)
• 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. / BP variants

When a known-format pattern matches with high confidence AND the user-location prior agrees, 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.5 can route directly to 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). 6 (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.), skipping 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). entirely. This is a measurable browser-side win — ~5 ms encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). inferenceinferenceRunning the trained model on new input to get predictions, as opposed to training, which produces the model. In Mailwoman that means a small transformer encoder reads an address string and classifies every token — house number, street, locality, region, postcode, and the rest. A Who's On First gazetteer can feed soft location hints into the pass, but the model makes the final call on every label. Where a generative model writes text token by token, Mailwoman's output is a retrieval-augmented token classification: one label per input piece. + ~25 MB 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.' load saved per call for the trivial cases.

⚠ Fast paths are advisory, not authoritative. "10118" could be a partial typed input ("10118 Maple St" mid-keystroke). Every fast path must:

• Honor a force_full_pipeline?: boolean option (default false)
• Apply a conservative confidence floor before short-circuiting
• Still report alternatives in the result, not collapse to one answer

If autocomplete or streaming-input workflows ever break because fast-paths short-circuited prematurely, the confidence floor was too low.

4. User physical location

External signal joining the input-side priors. Goes into 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). 6 (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.) scoring:

score(candidate) = match × population_prior × regional_prior_from_language × regional_prior_from_user_location

All four factors are soft priorssoft 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.. The TX-IP user typing "Paris" in French input gets a tie between Paris-FR and Paris-TX; structural cues (stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. abbreviation, 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. shape, etc.) break it. None of the priors hard-filter — that would violate the project's stated "possibilities, not constraints" principle (reference/CONTEXT.md).

API shape (optional input):

interface ResolveOpts {
	userLocation?:
		| { lat: number; lon: number } // precise (GPS, IP-geolocated)
		| { country: string } // coarse (CDN region, user setting)
		| { region: string; country: string } // medium (US state)
}

Where this lands in the pipeline

QueryShape is computed once, at the boundary between 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). 1 and 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, and passed to the rest of 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. as additional context. It is not its own 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). — it is a shared data structure that StagesstageOne 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, 2.5, 3 (optional), and 6 all consume.

Packaging decision

Bundle as a single workspace package:

packages/query-shape/
├── src/
│   ├── character-class.ts        # token-level + input-level classification
│   ├── segmentation.ts           # punctuation-grammar-aware chunking
│   ├── known-formats.ts          # postcode + PO-box regex set
│   ├── compute.ts                # entry point: (input, locale?) → QueryShape
│   └── types.ts                  # the QueryShape interface
├── test/
└── package.json

Zero ML. Zero npm dependencies beyond what @mailwoman/core already pulls. Tiny (< 100 KB compiled). Reusable in browser and Node.

Locality soft prior (v0.5.2 extension)

Added 2026-05-25 after diagnosing demo preset localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy./regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. confusion (DEMO_PRESET_DIAGNOSIS.md).

The existing buildEmissionPriors path applies logitlogitA raw, unnormalized per-label score the model outputs before softmax. Priors and biases are added in logit space, then softmax turns logits into probabilities. boosts for known-format hits (e.g., 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. regex → B-postcode). The localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 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. extends this: when an unambiguous 2-letter regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. abbreviation is detected (e.g., DC, NY, CA), preceding 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. that match a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. entry at the detected localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. receive a +2.0 logitlogitA raw, unnormalized per-label score the model outputs before softmax. Priors and biases are added in logit space, then softmax turns logits into probabilities. boost toward B-locality / I-locality.

New field on QueryShape:

regionAbbreviations?: Array<{ start: number; span: string }>

Detection is a single regex per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. (/,\s*[A-Z]{2}\b/ for en-us), same cost as 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.-format detection. The WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. verification is the safety constraint — only bias 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. that are verified localities, not every preceding 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..

This passes the bitter-lesson framing test: the regex is localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for.-bounded, not a 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.. The WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. check is a safety rail that prevents over-biasing non-localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. 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. like "Pennsylvania" (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.) in the same address.

Open questions for implementation

These are decisions to make when the implementation phasephaseA milestone in the implementation plan (Foundation, Corpus, Training, Integration, and forward-looking phases). Distinct from stage (runtime pipeline) and tier (model vocabulary). opens; recording so they aren't re-derived from scratch.

1. Where does QueryShape get computed? Eagerly 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.-entry (always pay the microseconds cost), or lazily on first downstream consumer (some inputs may not need it)? Recommend eagerly — it's cheaper to compute than to threaded-lazy-evaluate.
2. Known-format regex set extensibility? Hardcoded vs. registerable. Recommend hardcoded for v1 (the 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. set rarely changes) and re-evaluate if community adapters want to register 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.-specific formats.
3. Confidence threshold for fast-path routing? Pick conservatively (~0.95) and tune from real-world data. Failure mode of too-low is catastrophic (wrong answer instead of full 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.); failure mode of too-high is just slower inferenceinferenceRunning the trained model on new input to get predictions, as opposed to training, which produces the model. In Mailwoman that means a small transformer encoder reads an address string and classifies every token — house number, street, locality, region, postcode, and the rest. A Who's On First gazetteer can feed soft location hints into the pass, but the model makes the final call on every label. Where a generative model writes text token by token, Mailwoman's output is a retrieval-augmented token classification: one label per input piece..
4. SegmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.-id as encoderencoderThe part of a transformer that turns input tokens into contextualized vector representations. Mailwoman's classifier is a small encoder-only transformer (~30M parameters). 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. — additive or concatenated? Concatenated to input embeddingsembeddingA vector of numbers representing a token (or other item) so that similar items sit near each other in vector space. The first thing the model does is turn each token into an embedding. is simplest and avoids architecture change. Decide when 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). retrain happens.
5. How does QueryShape interact with LocaleDetector? The detector probably uses QueryShape.characterClass + QueryShape.tokenClasses as input featuresfeatureAn 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.. Suggests LocaleDetector runs after QueryShape.compute(). Document this dependency.

What this is not

• Not the 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.. Place-name lookup lives in 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). 6 / 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.. QueryShape never asks "is this a citylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. name?".
• Not the kind classifierkind classifierStage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy.. The kind classifierkind classifierStage 2.5 of the runtime pipeline: categorizes the input into one of seven query kinds (structured_address, postcode_only, locality_only, intersection, po_box, landmark, vague) so the coordinator can route to the right parsing strategy. (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.5) consumes QueryShape but is itself a separate component that may or may not use ML.
• Not a replacement for 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).. Trivial inputs short-circuit; structured inputs still hit the full 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..
• Not free of localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. concerns. Segmentation grammar and the known-format set both grow per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for., but they grow at O(1) per localelocaleThe combination of language and country an address comes from. en-US and fr-FR are the locales Mailwoman ships weights for. rather than O(N place namestoponymA proper name for a geographic place.).

See also

• concepts/the-staged-pipeline — the runtime stagesstageOne 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). this slots into
• concepts/addresses-that-break-geocoders — the failure-mode catalogue that motivated this
• reference/CONTEXT.md — the bitter-lesson framing and the "possibilities not constraints" principle
• reference/ARCHITECTURE.md — the broader system shape; QueryShape fits between tokenization and classification