@mailwoman/kind-classifier 9.4.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,24 +3,20 @@
  * @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"
 import type { NormalizedInputLite, QueryShapeSegmentsView as QueryShapeLike } from "@mailwoman/query-shape"
 
-import { deriveIntentMarkers } from "#intent-markers"
-import { scoreBareToponym, scoreNearMe, scoreRoutePair } from "#intent-rules"
+import { deriveIntentMarkers } from "#intent/markers"
+import { scoreBareToponym, scoreNearMe, scoreRoutePair } from "#intent/rules"
 import { createScorePOICategory, createScorePOIQuery, type POIPhraseLookup } from "#poi"
 import {
 	scoreIntersection,
@@ -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,21 +3,14 @@
  * @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"
 export type { KindClassifierOpts } from "#classify"
-export { deriveIntentMarkers } from "#intent-markers"
-export type { IntentMarkerContext } from "#intent-markers"
-export { nearMeSubject, scoreBareToponym, scoreNearMe, scoreRoutePair } from "#intent-rules"
+export { deriveIntentMarkers } from "#intent/markers"
+export type { IntentMarkerContext } from "#intent/markers"
+export { nearMeSubject, scoreBareToponym, scoreNearMe, scoreRoutePair } from "#intent/rules"
 export { matchPOICategory, matchPOISubject } from "#poi"
 export type { POIPhraseMatch, POIPhraseLookup, POIQuerySpan, POISpatialRelation, POISubjectMatch } from "#poi"
 

package/lib/{intent-markers.ts → intent/markers.ts}

@@ -3,22 +3,21 @@
  * @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"
 import type { NormalizedInputLite } from "@mailwoman/query-shape"
 
-import { nearMeSubject } from "#intent-rules"
+import { nearMeSubject } from "#intent/rules"
 import { matchPOICategory, type POIPhraseLookup } from "#poi"
 
 /**
@@ -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

@@ -0,0 +1,306 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * 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.
+ *
+ * `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.
+ *
+ * `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 { carriesLetter, isDisqualifyingStreetSuffix, MAX_LOCALITY_ONLY_LENGTH, wordsOf } from "#rules"
+/**
+ * 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 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:
+ * 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 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, 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.
+ *
+ * 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
+	"new",
+	"old",
+	"fort",
+	"ft",
+	"port",
+	"lake",
+	"mount",
+	"mt",
+	"north",
+	"south",
+	"east",
+	"west",
+	"upper",
+	"lower",
+	"great",
+	"little",
+	"saint",
+	"st",
+	"st.",
+	// Romance
+	"san",
+	"santa",
+	"santo",
+	"são",
+	"sao",
+	"los",
+	"las",
+	"el",
+	"la",
+	"le",
+	"les",
+	"villa",
+	"rio",
+	"nueva",
+	"nuevo",
+	"puerto",
+	"ciudad",
+	"campo",
+	"monte",
+	"castel",
+	"borgo",
+	// Germanic / Nordic
+	"bad",
+	"sankt",
+	"neu",
+	"alt",
+	"groß",
+	"gross",
+	"klein",
+	"ober",
+	"unter",
+	"nieuw",
+	"oud",
+	"ny",
+	"stor",
+	"lille",
+	"sint",
+	// Definite article as a head — "The Valley" (Anguilla), "The Hague", "The Bottom".
+	"the",
+	// 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",
+	"cape",
+	"isle",
+	"isla",
+	"ilha",
+])
+
+/**
+ * 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",
+	"town",
+	"ville",
+	"village",
+	"borough",
+	"springs",
+	"falls",
+	"beach",
+	"heights",
+	"valley",
+	"island",
+	"islands",
+	"bay",
+	"harbour",
+	"harbor",
+	"park",
+	"hills",
+	"river",
+	"creek",
+	"point",
+	"stadt",
+	"burg",
+])
+
+/**
+ * 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.
+ *
+ * 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 `$`,
+ * 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, 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*$/
+
+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.
+ *
+ * @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, so no bare toponym survives it.
+	if (shape.knownFormats.length) 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"), so one segment or the name is not bare.
+	if ((shape.segments?.length ?? 1) !== 1) return null
+
+	const lowercased = text.toLowerCase()
+
+	if (hasDeicticTail(lowercased)) return null
+
+	const words = wordsOf(text)
+
+	if (!words.length || words.length > MAX_BARE_TOPONYM_WORDS) return null
+
+	for (const word of words) {
+		if (isDisqualifyingStreetSuffix(word)) return null
+	}
+
+	return words
+}
+
+/**
+ * `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 no token between them.
+ *
+ * The known confound is structural and unfixable here.
+ * "Paris London" and "Moscow Idaho" have the same string shape.
+ *
+ * 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.
+ *
+ * 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)
+
+	if (!words || words.length !== 2) return 0
+
+	const [first, second] = [words[0]!.toLowerCase(), words[1]!.toLowerCase()]
+
+	// 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
+
+	if (TOPONYM_TAIL_NOUNS.has(second)) return 0
+
+	return ROUTE_PAIR_CONFIDENCE
+}
+
+/**
+ * `near_me` rule: a subject plus a deictic locator, with no anchor.
+ *
+ * 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 marks where the subject stops.
+	const match = DEICTIC_LOCATOR_TAIL.exec(lowercased) ?? DEICTIC_ADVERB_TAIL.exec(lowercased)
+
+	if (!match) return 0
+
+	return lowercased.slice(0, match.index).trim() ? NEAR_ME_CONFIDENCE : 0
+}
+
+/**
+ * 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()
+	const lowercased = trimmed.toLowerCase()
+	const match = DEICTIC_LOCATOR_TAIL.exec(lowercased) ?? DEICTIC_ADVERB_TAIL.exec(lowercased)
+
+	if (!match) return ""
+
+	return trimmed.slice(0, match.index).trim()
+}