@mailwoman/kind-classifier 10.0.0 → 10.1.0

package/README.md

@@ -1,11 +1,11 @@
 # @mailwoman/kind-classifier
 
-**Stage 2.5 of the Mailwoman runtime pipeline** — query kind classification.
+This package is **stage 2.5 of the Mailwoman runtime pipeline**, which classifies
+the query kind.
 
-Categorizes an input into one of seven `QueryKind`s by composing rule-based
-scorers over the `QueryShape` output. Returns possibilities (alternatives)
-alongside the top pick so the coordinator can fall back when the winning kind
-isn't actionable.
+It assigns an input to one of seven `QueryKind`s by combining rule-based scorers
+over the `QueryShape` output. It returns alternatives alongside the top pick, so
+the coordinator can fall back when the winning kind is not actionable.
 
 ```ts
 import { classifyKind } from "@mailwoman/kind-classifier"
@@ -51,18 +51,19 @@ locale-hint → kind-classifier → phrase-grouper → classifier → ...
 
 ## Design
 
-- **Pure functions, no ML.** Rule-based v1; a trained classifier is deferred.
+- **Pure functions without ML.** Version 1 is rule-based, and a trained
+  classifier is deferred.
 - **Returns alternatives.** The coordinator might skip a `locality_only` parse
-  and fall back to a `vague` handler — the alternatives list makes that possible.
+  and fall back to a `vague` handler, which the alternatives list makes possible.
 - **Consumes `QueryShape` + `LocaleHint`** from the two preceding stages.
 
 ## Related
 
-- [`@mailwoman/query-shape`](../query-shape) — feeds structural data into this stage
-- [`@mailwoman/locale-hint`](../locale-hint) — feeds locale context
-- [`@mailwoman/phrase-grouper`](../phrase-grouper) — Stage 2.7, next in the pipeline
-- [Staged Pipeline Contract](https://github.com/sister-software/mailwoman/blob/main/docs/engineering/reference/STAGES.mdx)
+- [`@mailwoman/query-shape`](../query-shape): supplies structural data to this stage.
+- [`@mailwoman/locale-hint`](../locale-hint): supplies locale context.
+- [`@mailwoman/phrase-grouper`](../phrase-grouper): stage 2.7, next in the pipeline.
+- [Staged Pipeline Interface](https://github.com/sister-software/mailwoman/blob/main/docs/records/plan/reference/STAGES.mdx)
 
 ## License
 
-[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)
+[AGPL-3.0-only](https://www.gnu.org/licenses/AGPL-3.0.html)

package/lib/classify.ts

@@ -3,17 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `classifyKind` — entry point for Stage 2.5 (kind classification).
+ * `classifyKind` is the entry point for Stage 2.5 (kind classification), composing the per-kind rules
+ * from `rules.ts` and `intent-rules.ts` and returning alternatives sorted by confidence.
  *
- *   Composes the per-kind rules from `rules.ts` and `intent-rules.ts` and picks the winner. Returns
- *   alternatives sorted by confidence so the coordinator can offer fallback paths when the top kind
- *   isn't actionable.
- *
- *   Per the project's "possibilities not constraints" principle, every kind that fires above 0
- *   surfaces in `alternatives` — the caller decides whether to act on the top kind only or consider
- *   runner-ups. The ROAD_TO_V9 §4 intent vocabulary leans on that: `bare_toponym` and `route_pair`
- *   are scored below their structural incumbent precisely so they land in `alternatives`, where they
- *   inform the markers without moving the routing decision.
+ * Per the project's "possibilities not constraints" principle, every kind that fires above 0 surfaces
+ * in `alternatives` and the caller decides whether to act on the top kind only: `bare_toponym` and
+ * `route_pair` are scored below their structural incumbent precisely so they land in `alternatives`,
+ * where they inform the markers without moving the routing decision.
  */
 
 import type { LocaleHint, QueryIntentMarker, QueryKind, QueryKindResult } from "@mailwoman/core/pipeline"
@@ -45,9 +41,9 @@ const SCORERS: ReadonlyArray<KindScorer> = [
 	{ kind: "postcode_only", score: scorePostcodeOnly },
 	{ kind: "locality_only", score: scoreLocalityOnly },
 	{ kind: "structured_address", score: scoreStructuredAddress },
-	// ROAD_TO_V9 §4. Ordinary members of the same list — intent is vocabulary, not a stage. `bare_toponym` and
-	// `route_pair` are scored under `locality_only` on purpose (see `intent-rules.ts`), so their position here is
-	// cosmetic; the sort below is what decides.
+	// Intent is vocabulary rather than a stage.
+	// The sort below decides, so `bare_toponym` and `route_pair` sit here cosmetically
+	// and are scored under `locality_only` on purpose (see `intent-rules.ts`).
 	{ kind: "bare_toponym", score: scoreBareToponym },
 	{ kind: "route_pair", score: scoreRoutePair },
 	{ kind: "near_me", score: scoreNearMe },
@@ -55,8 +51,8 @@ const SCORERS: ReadonlyArray<KindScorer> = [
 ]
 
 /**
- * Rank a scored list and shape it into a verdict. Shared by the lexicon-free and lexicon-wired paths so the two cannot
- * drift in how they break ties or build `alternatives`.
+ * Rank a scored list into a verdict, shared by the lexicon-free and lexicon-wired paths
+ * so the two cannot drift in how they break ties or build `alternatives`.
  */
 function rank(scored: Array<{ kind: QueryKind; confidence: number }>): QueryKindResult {
 	scored.sort((a, b) => b.confidence - a.confidence)
@@ -71,14 +67,14 @@ function rank(scored: Array<{ kind: QueryKind; confidence: number }>): QueryKind
 }
 
 /**
- * Every kind whose verdict carries `intentMarkers`. Checked before the marker builder runs so the hot path — a
- * structured address, where none of these fire — pays one set membership test per kind and nothing else.
+ * Every kind whose verdict includes `intentMarkers`, checked before the marker builder
+ * so the hot path pays one set membership test per kind.
  */
-const MARKER_BEARING_KINDS: ReadonlySet<QueryKind> = new Set<QueryKind>(["route_pair", "near_me", "poi_category"])
+const MARKER_KINDS: ReadonlySet<QueryKind> = new Set<QueryKind>(["route_pair", "near_me", "poi_category"])
 
 /**
- * Attach markers to a verdict, or return it untouched. Separate from {@link rank} because the lexicon-wired path needs
- * to merge `poi_query`/`poi_category` in first.
+ * Attach markers to a verdict or return it untouched, separate from {@link rank}
+ * because the lexicon-wired path merges `poi_query`/`poi_category` in first.
  */
 function withIntentMarkers(
 	verdict: QueryKindResult,
@@ -88,7 +84,7 @@ function withIntentMarkers(
 ): QueryKindResult {
 	const kinds = [{ kind: verdict.kind, confidence: verdict.confidence }, ...verdict.alternatives]
 
-	if (!kinds.some((k) => MARKER_BEARING_KINDS.has(k.kind))) return verdict
+	if (!kinds.some((k) => MARKER_KINDS.has(k.kind))) return verdict
 
 	const intentMarkers: QueryIntentMarker[] = deriveIntentMarkers(kinds, { input, poiLexicon, locale })
 
@@ -98,8 +94,8 @@ function withIntentMarkers(
 }
 
 /**
- * Classify the query shape into a `QueryKind`. Synchronous + pure — produces the same result for the same `(input,
- * shape)` pair.
+ * Classify the query shape into a `QueryKind`, synchronously and purely,
+ * producing the same result for the same `(input, shape)` pair.
  */
 export function classifyKindSync(input: NormalizedInputLite, shape: QueryShapeLike): QueryKindResult {
 	const scored = SCORERS.map((s) => ({ kind: s.kind, confidence: s.score(input, shape) })).filter(
@@ -110,9 +106,8 @@ export function classifyKindSync(input: NormalizedInputLite, shape: QueryShapeLi
 }
 
 /**
- * Async variant matching the runtime-pipeline's `classifyKind` contract.
- *
- * The locale parameter is accepted for future locale-aware rules (Japanese honorifics, etc.) but not currently used.
+ * Async variant matching the runtime pipeline's `classifyKind` interface;
+ * `_locale` is accepted for future locale-aware rules but currently unused.
  */
 export async function classifyKind(
 	input: NormalizedInputLite,
@@ -127,16 +122,19 @@ export async function classifyKind(
  */
 export interface KindClassifierOpts {
 	/**
-	 * POI phrase lexicon (spec §3.1). When present, `poi_query` and `poi_category` scorers join the rule set — injected,
-	 * never imported, so this package stays dictionary-free. Absent → the returned classifier is behaviorally identical
-	 * to {@link classifyKind}.
+	 * POI phrase lexicon (spec §3.1); when present the `poi_query`
+	 * and `poi_category` scorers join the rule set.
+	 *
+	 * They are injected rather than imported so this package stays dictionary-free.
+	 * When absent, the returned classifier behaves identically to {@link classifyKind}.
 	 */
 	poiLexicon?: POIPhraseLookup
 }
 
 /**
- * Build a kind classifier. Without opts this is exactly the default {@link classifyKind}; with a `poiLexicon` it
- * additionally scores `poi_query` + `poi_category` (ROAD_TO_V9 §4.4) and merges them into the ranked result.
+ * Build a kind classifier that is exactly {@link classifyKind} without options,
+ * or that additionally scores `poi_query` + `poi_category` (ROAD_TO_V9 §4.4)
+ * and merges them into the ranked result when given a `poiLexicon`.
  */
 export function createKindClassifier(
 	opts: KindClassifierOpts = {}
@@ -153,9 +151,10 @@ export function createKindClassifier(
 
 		if (poiConfidence <= 0 && categoryConfidence <= 0) return base
 
-		// Re-rank over the union rather than special-casing "did POI beat the base?". The base verdict's own
-		// alternatives are preserved, which is what keeps `bare_toponym` / `route_pair` visible to the marker builder
-		// even when a POI kind takes the top slot.
+		// Re-ranking over the union rather than special-casing whether POI beat the
+		// base preserves the base's own alternatives.
+		// Those keep `bare_toponym`/`route_pair` visible to the marker builder even
+		// when a POI kind takes the top slot.
 		const merged: Array<{ kind: QueryKind; confidence: number }> = [
 			{ kind: base.kind, confidence: base.confidence },
 			...base.alternatives,

package/lib/index.ts

@@ -3,14 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `@mailwoman/kind-classifier` — Stage 2.5 of the runtime pipeline.
- *
- *   Categorize inputs into one of eight `QueryKind`s by composing rule-based scorers over the
- *   QueryShape sub-system's output. Pure functions, no ML, no place-name dictionaries. Returns
- *   possibilities (alternatives) alongside the top pick so the coordinator can fall back when the
- *   winning kind isn't actionable.
- *
- *   See `docs/engineering/reference/STAGES.md` § Stage 2.5 for the contract.
+ *   Stage 2.5 classifier: compose rule-based scorers over QueryShape and return a top kind with alternatives.
  */
 
 export { classifyKind, classifyKindSync, createKindClassifier } from "#classify"

package/lib/intent/markers.ts

@@ -3,16 +3,15 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Marker derivation for the ROAD_TO_V9 §4 intent vocabulary. Pure, synchronous, and the ONLY place
- *   the classifier turns a fired rule into something a caller reads.
+ * Marker derivation for the ROAD_TO_V9 §4 intent vocabulary. This code is pure and synchronous. It is the only place the
+ * classifier turns a fired rule into something a caller reads.
  *
- *   Three of the four intent kinds can raise their marker here, from the string alone. The fourth —
- *   `bare_toponym`'s `declared_ambiguity` — cannot: its trigger is the dominance margin of the
- *   RESOLVED candidate list, which does not exist yet at Stage 2.5. That one is raised by
- *   `mailwoman/query-intent.ts` after the resolve, against the measured 0.5-log10 threshold. The split is
- *   deliberate and it is why this module never emits `declared_ambiguity`: a marker that asserted
- *   ambiguity from the string alone would be declaring that every bare city name is ambiguous, which
- *   is false 89.1% of the time (the measured table behind `DECISIVE_MARGIN_LOG10`).
+ * Three of the four intent kinds can raise their marker here from the string by itself. The fourth,
+ * Stage 2.5 cannot raise `bare_toponym`'s `declared_ambiguity` from the string by itself.
+ * Its trigger is the dominance margin of the resolved candidate list. `mailwoman/query-intent.ts` raises it
+ * after the resolve against `DECISIVE_MARGIN_LOG10`. This module therefore never emits
+ * `declared_ambiguity`, since a marker asserting ambiguity from the string by itself would declare every
+ * bare city name ambiguous.
  */
 
 import type { QueryIntentMarker, QueryKind } from "@mailwoman/core/pipeline"
@@ -27,22 +26,22 @@ import { matchPOICategory, type POIPhraseLookup } from "#poi"
 export interface IntentMarkerContext {
 	input: NormalizedInputLite
 	/**
-	 * The injected POI lexicon, when one was wired. Absent → no `poi_category` marker can be built, which is consistent
-	 * because the kind cannot fire without it either.
+	 * The injected POI lexicon when one was wired.
+	 *
+	 * Absent means no `poi_category` marker can be built, consistent with the
+	 * kind not firing without it either.
 	 */
 	poiLexicon?: POIPhraseLookup
 	locale?: string
 }
 
 /**
- * Build the advisories for one classified query.
+ * Build the advisories for one classified query, taking the full verdict — top plus alternatives —
+ * because two of the four intent kinds live in `alternatives` by design (see `intent-rules.ts`).
  *
- * `kinds` is the FULL verdict — top plus alternatives — because two of the four intent kinds live in `alternatives` by
- * design (see `intent-rules.ts`). Reading only the top kind would make them invisible, which is the mistake this
- * signature exists to prevent.
- *
- * Returns `[]` when no intent kind fired. Callers surface that empty array rather than dropping the field: an empty
- * array is the classifier stating it looked.
+ * @returns `[]` when no intent kind fired.
+ * Callers surface that empty array rather than dropping the field, because an
+ * empty array is the classifier stating it looked.
  */
 export function deriveIntentMarkers(
 	kinds: ReadonlyArray<{ kind: QueryKind; confidence: number }>,
@@ -52,8 +51,8 @@ export function deriveIntentMarkers(
 	const markers: QueryIntentMarker[] = []
 
 	if (fired.has("route_pair")) {
-		// Whitespace-only split, not `wordsOf`: `route_pair` inputs are comma-free by construction (a comma
-		// disqualifies the kind), and the tokens are re-joined verbatim into the message.
+		// Whitespace-only split rather than `wordsOf`, because `route_pair` inputs are
+		// comma-free by construction and the tokens are re-joined verbatim into the message.
 		const tokens = ctx.input.normalized.trim().split(/\s+/)
 
 		markers.push({
@@ -64,8 +63,11 @@ export function deriveIntentMarkers(
 			evidence: {
 				tokens,
 				/**
-				 * Both readings, named. The order is stable (pair first, then the admin reading) so a consumer can index it; it
-				 * is NOT a ranking, and nothing downstream reads it as one.
+				 * Both readings, listed.
+				 *
+				 * The order is stable: pair first, then the admin reading.
+				 * A consumer can index it.
+				 * This order does not rank the entries.
 				 */
 				interpretations: ["two_toponyms", "locality_with_admin_context"],
 			},
@@ -83,9 +85,10 @@ export function deriveIntentMarkers(
 			evidence: {
 				subject,
 				/**
-				 * THE PLUG POINT, named but not wired (ROAD_TO_V9 §4.4 scopes v9 to classification). Photon's `/api` already
-				 * accepts `lat`/`lon` location-bias params — `photon/` is the eventual consumer of this marker, and this string
-				 * is the note that says where it plugs in.
+				 * The plug point is documented but not wired.
+				 *
+				 * `photon/` is the eventual consumer.
+				 * Its `/api` already accepts `lat`/`lon` location-bias params.
 				 */
 				focusParameter: "photon:lat/lon",
 			},

package/lib/intent/rules.ts

@@ -3,63 +3,59 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   ROAD_TO_V9 §4 — the query-INTENT rules. Same contract as `rules.ts` (a `(input, shape) => number`
- *   in [0, 1], 0 when the rule does not fire) and the same bitter-lesson invariant: universal
- *   structural patterns and bounded linguistic categories only, never a place-name dictionary. The
- *   one lexicon these kinds consult — the POI synonym table — is INJECTED, exactly as `poi.ts`
- *   already does it.
+ * ROAD_TO_V9 §4 — the query-intent rules, with the same `(input, shape) => number` interface as
+ * `rules.ts` and the same bitter-lesson invariant: universal structural patterns and bounded linguistic
+ * categories only, never a place-name dictionary, with the POI synonym table injected exactly as
+ * `poi.ts` does it.
  *
- *   ## Why two of these three deliberately lose
+ * `bare_toponym` and `route_pair` score below the structural kind that already owns their population
+ * (`locality_only`, 0.85), so they surface in `QueryKindResult.alternatives` and never as the top kind.
+ * The top kind is the only thing the coordinator routes on, so pinning it is what makes these additions
+ * answer-neutral on the bare-city-name register. Their intent travels on the marker.
  *
- *   `bare_toponym` and `route_pair` are scored BELOW the structural kind that already owns their
- *   population (`locality_only`, 0.85). They therefore surface in `QueryKindResult.alternatives` and
- *   never as the top kind. That is not timidity — it is the D-rule discharge. The top kind is the
- *   only thing the coordinator routes on (`deriveInputMode`, `canShortCircuit`, the POI branch), so
- *   pinning it is what makes these additions provably answer-neutral on the bare-city-name register,
- *   which is the single largest population in map search. The intent they carry travels on the
- *   marker instead, where it is advisory by construction.
- *
- *   `near_me` DOES win its top slot (0.91), because there is no incumbent worth preserving: a query
- *   ending "near me" is not a locality and answering it as one is the bug.
+ * `near_me` does win its top slot (0.91), because there is no incumbent worth preserving: a query
+ * ending "near me" is not a locality.
  */
 
 import type { NormalizedInputLite, QueryShapeSegmentsView as QueryShapeLike } from "@mailwoman/query-shape"
 
-import { isDisqualifyingStreetSuffix, MAX_LOCALITY_ONLY_LENGTH, wordsOf } from "#rules"
+import { carriesLetter, isDisqualifyingStreetSuffix, MAX_LOCALITY_ONLY_LENGTH, wordsOf } from "#rules"
 /**
- * `locality_only` scores 0.85. Both refinement kinds sit under it by a whole confidence step so no float-comparison
- * accident can flip the top slot, and so the gap reads as deliberate to the next person.
+ * Both refinement kinds sit a whole confidence step below `locality_only`'s 0.85
+ * so no float-comparison accident can flip the top slot.
  */
 const BARE_TOPONYM_CONFIDENCE = 0.84
 
 /**
- * Lower still, and for a second reason on top of the ranking discipline: a route pair is a HYPOTHESIS about a query
- * whose competing reading (locality + region) is more common in this corpus. The number states that.
+ * Lower still for a second reason beyond the ranking discipline.
+ *
+ * A route pair is a hypothesis whose competing reading (locality + region) is more common in this corpus.
  */
 const ROUTE_PAIR_CONFIDENCE = 0.55
 
 /**
- * Above `landmark`'s venue ceiling (0.88) and above `poi_query`'s anchored band (0.90), because a deictic tail is a
- * stronger signal than either shape heuristic: nothing else in the vocabulary explains why "me" is at the end of the
- * string.
+ * Above `landmark`'s venue ceiling (0.88) and above `poi_query`'s anchored band (0.90),
+ * because a deictic tail is a stronger signal than either shape heuristic:
+ * no other rule explains why "me" ends the string.
  */
 const NEAR_ME_CONFIDENCE = 0.91
 
 /**
- * Word ceiling for a single bare toponym. Four covers the long tail that actually exists as one place name ("Newcastle
- * upon Tyne", "Sault Sainte Marie", "Las Palmas de Gran Canaria"); past it the input is carrying more than a name.
+ * Word ceiling for a single bare toponym: four covers the long tail that exists as one
+ * place name ("Newcastle upon Tyne", "Sault Sainte Marie", "Las Palmas de Gran Canaria"),
+ * and past it the input contains more than a name.
  */
 const MAX_BARE_TOPONYM_WORDS = 4
 
 /**
- * Toponymic HEAD particles — the bounded linguistic category that makes a multi-token string ONE place name.
- *
- * Same justification, and the same boundary, as `@mailwoman/phrase-grouper`'s `PLACE_NAME_PARTICLES` (which covers the
- * INFIX glue: `de`, `am`, `aan den`). This set covers the PREFIX heads, and it exists for exactly one job: keeping
- * `route_pair` off "New York", "San Francisco", "Fort Worth" and their kin. It is a closed morphological class, not a
- * gazetteer — growing it with actual place names is the wrong move, and the pressure for that belongs on the resolver.
+ * Toponymic head particles — the bounded linguistic category that makes a multi-token
+ * string one place name, with the same boundary as `@mailwoman/phrase-grouper`'s
+ * `PLACE_NAME_PARTICLES` (which covers the infix glue `de`, `am`, `aan den`) and the one
+ * job of keeping `route_pair` off "New York", "San Francisco", "Fort Worth" and their kin.
  *
- * Case-folded on read, because lowercase is the primary user register and "new york" is the same query.
+ * It is a closed morphological class rather than a gazetteer, so growing it
+ * with actual place names is the wrong move.
+ * It is case-folded on read, because "new york" is the same query.
  */
 const TOPONYM_HEAD_PARTICLES: ReadonlySet<string> = new Set([
 	// English
@@ -122,9 +118,10 @@ const TOPONYM_HEAD_PARTICLES: ReadonlySet<string> = new Set([
 	"sint",
 	// Definite article as a head — "The Valley" (Anguilla), "The Hague", "The Bottom".
 	"the",
-	// Generic toponymic heads outside the Latin/Germanic families, added because the 306-case corpus MEASURED them
-	// (see `mailwoman/test/kind-intent-invariance.test.ts`): each is a common noun in its own language — Semitic "tel"
-	// (mound), Malay "kuala" (confluence), Khmer "phnom" (hill) — that heads a place name the way "mount" does.
+	// Generic toponymic heads outside the Latin/Germanic families, each a common
+	// noun in its own language — Semitic "tel" (mound), Malay "kuala" (confluence),
+	// Khmer "phnom" (hill) — that heads a place name the way "mount" does.
+	// `mailwoman/test/kind-intent-invariance.test.ts` covers them.
 	"tel",
 	"kuala",
 	"phnom",
@@ -135,11 +132,9 @@ const TOPONYM_HEAD_PARTICLES: ReadonlySet<string> = new Set([
 ])
 
 /**
- * Generic toponymic TAIL nouns — the other half of the same bounded morphological class. "Belize City", "George Town",
- * "Cape Town", "Palm Springs": a place name whose last token is a settlement/landform generic is ONE name, not two.
- *
- * Measured additions, same as the heads above: `city`, `town` and `valley` each came off a real corpus row that was
- * forking wrongly.
+ * Generic toponymic tail nouns — the other half of the same bounded morphological
+ * class, so a place name whose last token is a settlement/landform generic
+ * ("Belize City", "George Town", "Palm Springs") is one name rather than two.
  */
 const TOPONYM_TAIL_NOUNS: ReadonlySet<string> = new Set([
 	"city",
@@ -167,53 +162,54 @@ const TOPONYM_TAIL_NOUNS: ReadonlySet<string> = new Set([
 ])
 
 /**
- * Deictic locator tails — "near me", "nearby", "around here", "in my area".
+ * Deictic locator tails — "near me", "nearby", "around here", "in my area" —
+ * the bounded class `preposition + a reference to the asker`, where `me`, `here`,
+ * `my <noun>` are function words rather than places.
  *
- * The class is `preposition + a reference to the ASKER`, which is why it is bounded and why it is safe: `me`, `here`,
- * `my <noun>` are function words, not places. Anchored to the END of the string (`$`) on purpose — the whole point of
- * the kind is that the query names no anchor, so anything AFTER the locator is an anchor and disqualifies it.
+ * Anchored to the end of the string (`$`) on purpose: the query names no anchor,
+ * so anything after the locator is an anchor and disqualifies it.
  *
- * Linear by construction: every alternative begins with a required literal, and the only quantifiers are bounded `\s+`
- * runs BETWEEN two required literals or trailing before `$`. No unbounded-whitespace-then-literal prefix, which is the
- * `js/polynomial-redos` shape (see the `ANCHOR_SEPARATOR` docstring in `poi.ts` for the same analysis).
+ * Linear by construction: every alternative begins with a required literal and the only
+ * quantifiers are bounded `\s+` runs between two required literals or trailing before `$`,
+ * with no unbounded-whitespace-then-literal prefix (the `js/polynomial-redos` shape).
+ * `ANCHOR_SEPARATOR` in `poi.ts` uses the same analysis.
  */
 const DEICTIC_LOCATOR_TAIL =
 	/\b(?:near|close\s+to|next\s+to|around|by|closest\s+to|nearest\s+to)\s+(?:me|us|here|my\s+(?:location|position|area|place|house|home))\s*$/
 
 /**
- * The adverbial half of the same class — no preposition, the deixis is baked into the word.
+ * The adverbial half of the same class, where the deixis is baked into the word
+ * rather than introduced by a preposition.
  */
 const DEICTIC_ADVERB_TAIL =
 	/\b(?:nearby|near\s?by|close\s+by|around\s+here|in\s+my\s+(?:area|neighborhood|neighbourhood))\s*$/
 
-/**
- * True when the input carries a deictic locator tail in EITHER form.
- */
 function hasDeicticTail(lowercased: string): boolean {
 	return DEICTIC_LOCATOR_TAIL.test(lowercased) || DEICTIC_ADVERB_TAIL.test(lowercased)
 }
 
 /**
- * The conditions `bare_toponym` and `route_pair` share: no address grammar of any kind, one segment, alpha throughout.
+ * The conditions `bare_toponym` and `route_pair` share: no address grammar of any kind,
+ * one segment, alpha throughout.
  *
- * Returns the word list when the input clears them, `null` when it does not. Deliberately a SUPERSET of
- * `scoreLocalityOnly`'s conditions (which admit two segments), so `bare_toponym` is a strict refinement of
- * `locality_only` and can never fire where `locality_only` did not — the property `intent-rules.test.ts` asserts and
- * the reason the ranking discipline above is enough to keep the top kind pinned.
+ * @returns the word list when the input clears them, `null` when it does not.
+ * The conditions are deliberately a superset of `scoreLocalityOnly`'s, so `bare_toponym` is
+ * a strict refinement of `locality_only` and can never fire where `locality_only` did not.
  */
 function bareNameWords(input: NormalizedInputLite, shape: QueryShapeLike): string[] | null {
 	const text = input.normalized.trim()
 
 	if (!text || text.length > MAX_LOCALITY_ONLY_LENGTH) return null
 
-	// A recognized postcode/known format IS address grammar. Nothing bare survives this.
+	// A recognized postcode/known format is address grammar, so no bare toponym survives it.
 	if (shape.knownFormats.length) return null
 
-	// `alpha` excludes every house number and every postcode by construction — the cheapest available statement of
-	// "no address grammar", and it costs no lexicon.
-	if (shape.characterClass !== "alpha") return null
+	// `alpha` excludes every house number and postcode by construction, the cheapest statement of
+	// "no address grammar"; it is silent about whether a name is present, so the letter test stands
+	// beside it because `foldInputClass` answers `alpha` for input carrying no classified token.
+	if (shape.characterClass !== "alpha" || !carriesLetter(text)) return null
 
-	// A comma is the admin-context marker ("Paris, FR"). One segment, or the name is not bare.
+	// A comma is the admin-context marker ("Paris, FR"), so one segment or the name is not bare.
 	if ((shape.segments?.length ?? 1) !== 1) return null
 
 	const lowercased = text.toLowerCase()
@@ -232,27 +228,28 @@ function bareNameWords(input: NormalizedInputLite, shape: QueryShapeLike): strin
 }
 
 /**
- * `bare_toponym` rule: a single coherent place-name carrying no address grammar.
- *
- * Feeds the declared-ambiguity path. The rule itself asserts nothing about WHICH place — that is the resolver's
- * question, and `mailwoman/query-intent.ts` is where the answer's dominance margin decides whether the ambiguity gets
- * declared.
+ * `bare_toponym` rule: a single coherent place-name carrying no address grammar, feeding the
+ * declared-ambiguity path without asserting which place — that is the resolver's question,
+ * decided by the answer's dominance margin in `mailwoman/query-intent.ts`.
  */
 export function scoreBareToponym(input: NormalizedInputLite, shape: QueryShapeLike): number {
 	return bareNameWords(input, shape) ? BARE_TOPONYM_CONFIDENCE : 0
 }
 
 /**
- * `route_pair` rule: exactly two toponym-shaped tokens with nothing between them.
+ * `route_pair` rule: exactly two toponym-shaped tokens with no token between them.
+ *
+ * The known confound is structural and unfixable here.
+ * "Paris London" and "Moscow Idaho" have the same string shape.
  *
- * **The known confound is structural and unfixable here.** "Paris London" and "Moscow Idaho" are the same string shape
- * — two bare capitalized words — and separating them needs to know that Idaho is a region, which is a gazetteer fact,
- * not a structural one. The hard-slice board's 18 `comma_free` rows are that population, and they fire this rule. That
- * is the reason ROAD_TO_V9 §4.3 specifies **classification + a declared fork, never a router**: both readings are named
- * in the marker, neither wins, and the resolver keeps answering exactly as it did.
+ * A classifier needs gazetteer knowledge that Idaho is a region to distinguish them.
+ * ROAD_TO_V9 §4.3 therefore specifies classification plus a declared fork.
  *
- * The one class that IS separable structurally is the two-token SINGLE name — "New York", "Fort Worth", "San Francisco"
- * — because those carry a toponymic head particle. That guard is what keeps the fork off the common case.
+ * Both readings appear in the marker, neither wins and the resolver keeps its existing answer.
+ *
+ * The structurally separable class is a two-token single name ("New York", "Fort Worth")
+ * with a toponymic head particle.
+ * That guard keeps the fork off the common case.
  */
 export function scoreRoutePair(input: NormalizedInputLite, shape: QueryShapeLike): number {
 	const words = bareNameWords(input, shape)
@@ -261,8 +258,8 @@ export function scoreRoutePair(input: NormalizedInputLite, shape: QueryShapeLike
 
 	const [first, second] = [words[0]!.toLowerCase(), words[1]!.toLowerCase()]
 
-	// Reduplication — "Pago Pago", "Baden-Baden", "Walla Walla", "Bora Bora". Nobody travels from a place to itself,
-	// so a repeated token is a universal single-name signal and needs no lexicon at all.
+	// Reduplication — "Pago Pago", "Baden-Baden", "Walla Walla" — is a universal single-name
+	// signal that needs no lexicon, because a route from a place to itself is invalid.
 	if (first === second) return 0
 
 	if (TOPONYM_HEAD_PARTICLES.has(first) || TOPONYM_HEAD_PARTICLES.has(second)) return 0
@@ -275,16 +272,16 @@ export function scoreRoutePair(input: NormalizedInputLite, shape: QueryShapeLike
 /**
  * `near_me` rule: a subject plus a deictic locator, with no anchor.
  *
- * Requires a non-empty subject before the locator, so a bare "near me" stays with the `landmark` leaders rule rather
- * than claiming to be a category search with a missing focus point.
+ * A non-empty subject is required, so a bare "near me" stays with the `landmark` leaders rule.
  */
 export function scoreNearMe(input: NormalizedInputLite, _shape: QueryShapeLike): number {
 	const lowercased = input.normalized.trim().toLowerCase()
 
 	if (!hasDeicticTail(lowercased)) return 0
 
-	// The subject is everything before the locator. `hasDeicticTail` already anchored the match to the end, so the
-	// first match index is where the subject stops.
+	// The subject is everything before the locator.
+	// `hasDeicticTail` already anchored the match to the end, so the first match
+	// index marks where the subject stops.
 	const match = DEICTIC_LOCATOR_TAIL.exec(lowercased) ?? DEICTIC_ADVERB_TAIL.exec(lowercased)
 
 	if (!match) return 0
@@ -293,8 +290,10 @@ export function scoreNearMe(input: NormalizedInputLite, _shape: QueryShapeLike):
 }
 
 /**
- * The subject of a `near_me` query — the category or thing the asker wants, with the locator stripped. Empty string
- * when the rule would not have fired. Used to build the marker's evidence, never to route.
+ * The subject of a `near_me` query is the requested category or thing with the locator stripped.
+ *
+ * It is empty when the rule would not have fired.
+ * The subject builds marker evidence and never a route.
  */
 export function nearMeSubject(input: NormalizedInputLite): string {
 	const trimmed = input.normalized.trim()