@mailwoman/kind-classifier 9.0.0 → 9.2.0

package/classify.ts

@@ -5,15 +5,20 @@
  *
  *   `classifyKind` — entry point for Stage 2.5 (kind classification).
  *
- *   Composes the per-kind rules from `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.
+ *   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.
+ *   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.
  */
 
-import { createScorePOIQuery, type POIPhraseLookup } from "./poi.ts"
+import { deriveIntentMarkers } from "./intent-markers.ts"
+import { scoreBareToponym, scoreNearMe, scoreRoutePair } from "./intent-rules.ts"
+import { createScorePOICategory, createScorePOIQuery, type POIPhraseLookup } from "./poi.ts"
 import {
 	scoreIntersection,
 	scoreLandmark,
@@ -24,7 +29,14 @@ import {
 	scoreVague,
 	scoreVenueLandmark,
 } from "./rules.ts"
-import type { LocaleHint, NormalizedInputLite, QueryKind, QueryKindResult, QueryShapeLike } from "./types.ts"
+import type {
+	LocaleHint,
+	NormalizedInputLite,
+	QueryIntentMarker,
+	QueryKind,
+	QueryKindResult,
+	QueryShapeLike,
+} from "./types.ts"
 
 interface KindScorer {
 	kind: QueryKind
@@ -38,30 +50,70 @@ 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.
+	{ kind: "bare_toponym", score: scoreBareToponym },
+	{ kind: "route_pair", score: scoreRoutePair },
+	{ kind: "near_me", score: scoreNearMe },
 	{ kind: "vague", score: scoreVague },
 ]
 
 /**
- * Classify the query shape into a `QueryKind`. Synchronous + pure — produces the same result for the same `(input,
- * shape)` pair.
+ * 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`.
  */
-export function classifyKindSync(input: NormalizedInputLite, shape: QueryShapeLike): QueryKindResult {
-	const scored = SCORERS.map((s) => ({ kind: s.kind, confidence: s.score(input, shape) })).filter(
-		(s) => s.confidence > 0
-	)
-
+function rank(scored: Array<{ kind: QueryKind; confidence: number }>): QueryKindResult {
 	scored.sort((a, b) => b.confidence - a.confidence)
 
 	const top = scored[0] ?? { kind: "vague" as QueryKind, confidence: 0.3 }
-	const alternatives = scored.slice(1).map((s) => ({ kind: s.kind, confidence: s.confidence }))
 
 	return {
 		kind: top.kind,
 		confidence: top.confidence,
-		alternatives,
+		alternatives: scored.slice(1).map((s) => ({ kind: s.kind, confidence: s.confidence })),
 	}
 }
 
+/**
+ * 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.
+ */
+const MARKER_BEARING_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.
+ */
+function withIntentMarkers(
+	verdict: QueryKindResult,
+	input: NormalizedInputLite,
+	poiLexicon?: POIPhraseLookup,
+	locale?: string
+): QueryKindResult {
+	const kinds = [{ kind: verdict.kind, confidence: verdict.confidence }, ...verdict.alternatives]
+
+	if (!kinds.some((k) => MARKER_BEARING_KINDS.has(k.kind))) return verdict
+
+	const intentMarkers: QueryIntentMarker[] = deriveIntentMarkers(kinds, { input, poiLexicon, locale })
+
+	if (!intentMarkers.length) return verdict
+
+	return { ...verdict, intentMarkers }
+}
+
+/**
+ * Classify the query shape into a `QueryKind`. Synchronous + pure — produces 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(
+		(s) => s.confidence > 0
+	)
+
+	return withIntentMarkers(rank(scored), input)
+}
+
 /**
  * Async variant matching the runtime-pipeline's `classifyKind` contract.
  *
@@ -80,16 +132,16 @@ export async function classifyKind(
  */
 export interface KindClassifierOpts {
 	/**
-	 * POI phrase lexicon (spec §3.1). When present, a `poi_query` scorer joins 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, `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}.
 	 */
 	poiLexicon?: POIPhraseLookup
 }
 
 /**
  * Build a kind classifier. Without opts this is exactly the default {@link classifyKind}; with a `poiLexicon` it
- * additionally scores `poi_query` and merges it into the ranked result.
+ * additionally scores `poi_query` + `poi_category` (ROAD_TO_V9 §4.4) and merges them into the ranked result.
  */
 export function createKindClassifier(
 	opts: KindClassifierOpts = {}
@@ -99,25 +151,29 @@ export function createKindClassifier(
 	if (!poiLexicon) return classifyKind
 
 	return async (input, shape, locale): Promise<QueryKindResult> => {
+		const localeTag = locale?.locale
 		const base = classifyKindSync(input, shape)
-		const poiConfidence = createScorePOIQuery(poiLexicon, locale?.locale)(input, shape)
+		const poiConfidence = createScorePOIQuery(poiLexicon, localeTag)(input, shape)
+		const categoryConfidence = createScorePOICategory(poiLexicon, localeTag)(input, shape)
 
-		if (poiConfidence <= 0) return base
+		if (poiConfidence <= 0 && categoryConfidence <= 0) return base
 
-		if (poiConfidence > base.confidence) {
-			return {
-				kind: "poi_query",
-				confidence: poiConfidence,
-				alternatives: [{ kind: base.kind, confidence: base.confidence }, ...base.alternatives],
-			}
-		}
+		// 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.
+		const merged: Array<{ kind: QueryKind; confidence: number }> = [
+			{ kind: base.kind, confidence: base.confidence },
+			...base.alternatives,
+		]
 
-		// The literal needs the contextual element type — a bare array literal widens `kind` to string.
-		const poiAlternative: { kind: QueryKind; confidence: number } = { kind: "poi_query", confidence: poiConfidence }
+		if (poiConfidence > 0) {
+			merged.push({ kind: "poi_query", confidence: poiConfidence })
+		}
 
-		return {
-			...base,
-			alternatives: [...base.alternatives, poiAlternative].toSorted((a, b) => b.confidence - a.confidence),
+		if (categoryConfidence > 0) {
+			merged.push({ kind: "poi_category", confidence: categoryConfidence })
 		}
+
+		return withIntentMarkers(rank(merged), input, poiLexicon, localeTag)
 	}
 }

package/index.ts

@@ -15,8 +15,11 @@
 
 export { classifyKind, classifyKindSync, createKindClassifier } from "./classify.ts"
 export type { KindClassifierOpts } from "./classify.ts"
-export { matchPOISubject } from "./poi.ts"
-export type { POIPhraseMatch, POIPhraseLookup, POISubjectMatch } from "./poi.ts"
+export { deriveIntentMarkers } from "./intent-markers.ts"
+export type { IntentMarkerContext } from "./intent-markers.ts"
+export { nearMeSubject, scoreBareToponym, scoreNearMe, scoreRoutePair } from "./intent-rules.ts"
+export { matchPOICategory, matchPOISubject } from "./poi.ts"
+export type { POIPhraseMatch, POIPhraseLookup, POIQuerySpan, POISpatialRelation, POISubjectMatch } from "./poi.ts"
 
 export {
 	scoreIntersection,
@@ -26,6 +29,16 @@ export {
 	scorePostcodeOnly,
 	scoreStructuredAddress,
 	scoreVague,
+	scoreVenueLandmark,
 } from "./rules.ts"
 
-export type { LocaleHint, NormalizedInputLite, QueryKind, QueryKindResult, QueryShapeLike } from "./types.ts"
+export { QueryIntentCode } from "./types.ts"
+
+export type {
+	LocaleHint,
+	NormalizedInputLite,
+	QueryIntentMarker,
+	QueryKind,
+	QueryKindResult,
+	QueryShapeLike,
+} from "./types.ts"

package/intent-markers.ts

@@ -0,0 +1,110 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ *
+ *   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 cut. 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`).
+ */
+
+import { nearMeSubject } from "./intent-rules.ts"
+import { matchPOICategory, type POIPhraseLookup } from "./poi.ts"
+import type { NormalizedInputLite, QueryIntentMarker, QueryKind } from "./types.ts"
+
+/**
+ * Context the marker builder needs beyond the scored kinds.
+ */
+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.
+	 */
+	poiLexicon?: POIPhraseLookup
+	locale?: string
+}
+
+/**
+ * Build the advisories for one classified query.
+ *
+ * `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.
+ */
+export function deriveIntentMarkers(
+	kinds: ReadonlyArray<{ kind: QueryKind; confidence: number }>,
+	ctx: IntentMarkerContext
+): QueryIntentMarker[] {
+	const fired = new Set<QueryKind>(kinds.map((k) => k.kind))
+	const markers: QueryIntentMarker[] = []
+
+	if (fired.has("route_pair")) {
+		const tokens = ctx.input.normalized.trim().split(/\s+/)
+
+		markers.push({
+			kind: "route_pair",
+			code: "declared_fork",
+			mechanism: "kind:route_pair",
+			message: `"${tokens.join(" ")}" reads two ways and the pipeline is not choosing between them: two distinct places, or one place with its admin context.`,
+			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.
+				 */
+				interpretations: ["two_toponyms", "locality_with_admin_context"],
+			},
+		})
+	}
+
+	if (fired.has("near_me")) {
+		const subject = nearMeSubject(ctx.input)
+
+		markers.push({
+			kind: "near_me",
+			code: "focus_point_required",
+			mechanism: "kind:near_me",
+			message: `"${subject}" was asked for relative to the asker, and no focus point was supplied.`,
+			evidence: {
+				subject,
+				/**
+				 * The SEAM, 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.
+				 */
+				focusParameter: "photon:lat/lon",
+			},
+		})
+	}
+
+	if (fired.has("poi_category") && ctx.poiLexicon) {
+		const match = matchPOICategory(ctx.input.normalized, ctx.locale ?? ctx.input.appliedLocale, ctx.poiLexicon)
+
+		if (match) {
+			markers.push({
+				kind: "poi_category",
+				code: "poi_category",
+				mechanism: "poi-taxonomy:synonym",
+				message: `"${match.matchedPhrase}" is a POI category with no place to search; resolution against poi.db is out of scope.`,
+				evidence: {
+					categoryID: match.categoryID,
+					matchedPhrase: match.matchedPhrase,
+					...(match.wikidata ? { wikidata: match.wikidata } : {}),
+				},
+			})
+		}
+	}
+
+	return markers
+}

package/intent-rules.ts

@@ -0,0 +1,314 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ *
+ *   ## Why two of these three deliberately lose
+ *
+ *   `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.
+ */
+
+import { MAX_LOCALITY_ONLY_LENGTH, STREET_SUFFIXES } from "./rules.ts"
+import type { NormalizedInputLite, QueryShapeLike } from "./types.ts"
+
+/**
+ * `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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ *
+ * Case-folded on read, because lowercase is the primary user register and "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, 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.
+	"tel",
+	"kuala",
+	"phnom",
+	"cape",
+	"isle",
+	"isla",
+	"ilha",
+])
+
+/**
+ * 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.
+ */
+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 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.
+ *
+ * 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).
+ */
+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.
+ */
+const DEICTIC_ADVERB_TAIL =
+	/\b(?:nearby|near\s?by|close\s+by|around\s+here|in\s+my\s+(?:area|neighborhood|neighbourhood))\s*$/
+
+/**
+ * Split on whitespace + commas, the way the other rules in this package do.
+ */
+function wordsOf(text: string): string[] {
+	return text.split(/[\s,]+/).filter(Boolean)
+}
+
+/**
+ * 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 gates `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 gates (which admits 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.
+ */
+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.
+	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
+
+	// A comma is the admin-context marker ("Paris, FR"). 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 (STREET_SUFFIXES.has(word.toLowerCase())) return null
+	}
+
+	return words
+}
+
+/**
+ * `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.
+ */
+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.
+ *
+ * **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.
+ *
+ * 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.
+ */
+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", "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.
+	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.
+ *
+ * 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.
+ */
+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.
+	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 — 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.
+ */
+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()
+}

package/out/classify.d.ts

@@ -5,12 +5,15 @@
  *
  *   `classifyKind` — entry point for Stage 2.5 (kind classification).
  *
- *   Composes the per-kind rules from `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.
+ *   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.
+ *   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.
  */
 import { type POIPhraseLookup } from "./poi.ts";
 import type { LocaleHint, NormalizedInputLite, QueryKindResult, QueryShapeLike } from "./types.ts";
@@ -30,15 +33,15 @@ export declare function classifyKind(input: NormalizedInputLite, shape: QuerySha
  */
 export interface KindClassifierOpts {
     /**
-     * POI phrase lexicon (spec §3.1). When present, a `poi_query` scorer joins 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, `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}.
      */
     poiLexicon?: POIPhraseLookup;
 }
 /**
  * Build a kind classifier. Without opts this is exactly the default {@link classifyKind}; with a `poiLexicon` it
- * additionally scores `poi_query` and merges it into the ranked result.
+ * additionally scores `poi_query` + `poi_category` (ROAD_TO_V9 §4.4) and merges them into the ranked result.
  */
 export declare function createKindClassifier(opts?: KindClassifierOpts): (input: NormalizedInputLite, shape: QueryShapeLike, locale?: LocaleHint) => Promise<QueryKindResult>;
 //# sourceMappingURL=classify.d.ts.map