@mailwoman/kind-classifier 9.4.0 → 10.1.0

package/out/index.d.ts

@@ -3,20 +3,13 @@
  * @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";
 export { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, scoreVenueLandmark, } from "#rules";

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChF,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAE9G,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChF,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAE9G,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}

package/out/index.js

@@ -3,18 +3,11 @@
  * @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 { deriveIntentMarkers } from "#intent-markers";
-export { nearMeSubject, scoreBareToponym, scoreNearMe, scoreRoutePair } from "#intent-rules";
+export { deriveIntentMarkers } from "#intent/markers";
+export { nearMeSubject, scoreBareToponym, scoreNearMe, scoreRoutePair } from "#intent/rules";
 export { matchPOICategory, matchPOISubject } from "#poi";
 export { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, scoreVenueLandmark, } from "#rules";
 //# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAEhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAGxD,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAEhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAErD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAGxD,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GAClB,MAAM,QAAQ,CAAA"}

package/out/intent/markers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * 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 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 { type POIPhraseLookup } from "#poi";
+/**
+ * Context the marker builder needs beyond the scored kinds.
+ */
+export interface IntentMarkerContext {
+    input: NormalizedInputLite;
+    /**
+     * 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, taking the full verdict — top plus alternatives —
+ * because two of the four intent kinds live in `alternatives` by design (see `intent-rules.ts`).
+ *
+ * @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 declare function deriveIntentMarkers(kinds: ReadonlyArray<{
+    kind: QueryKind;
+    confidence: number;
+}>, ctx: IntentMarkerContext): QueryIntentMarker[];
+//# sourceMappingURL=markers.d.ts.map

package/out/intent/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../../lib/intent/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAGjE,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,MAAM,CAAA;AAE7D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,mBAAmB,CAAA;IAC1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,EAC7D,GAAG,EAAE,mBAAmB,GACtB,iBAAiB,EAAE,CAoErB"}

package/out/intent/markers.js

@@ -0,0 +1,88 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * 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 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 { nearMeSubject } from "#intent/rules";
+import { matchPOICategory } from "#poi";
+/**
+ * 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`).
+ *
+ * @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, ctx) {
+    const fired = new Set(kinds.map((k) => k.kind));
+    const markers = [];
+    if (fired.has("route_pair")) {
+        // 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({
+            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, 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"],
+            },
+        });
+    }
+    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 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",
+            },
+        });
+    }
+    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;
+}
+//# sourceMappingURL=markers.js.map

package/out/intent/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../lib/intent/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAwB,MAAM,MAAM,CAAA;AAiB7D;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAClC,KAA6D,EAC7D,GAAwB;IAExB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAY,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IAC1D,MAAM,OAAO,GAAwB,EAAE,CAAA;IAEvC,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,+EAA+E;QAC/E,qFAAqF;QACrF,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAEvD,OAAO,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,iBAAiB;YAC5B,OAAO,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,2HAA2H;YACxJ,QAAQ,EAAE;gBACT,MAAM;gBACN;;;;;;mBAMG;gBACH,eAAe,EAAE,CAAC,cAAc,EAAE,6BAA6B,CAAC;aAChE;SACD,CAAC,CAAA;IACH,CAAC;IAED,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAExC,OAAO,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,sBAAsB;YAC5B,SAAS,EAAE,cAAc;YACzB,OAAO,EAAE,IAAI,OAAO,yEAAyE;YAC7F,QAAQ,EAAE;gBACT,OAAO;gBACP;;;;;mBAKG;gBACH,cAAc,EAAE,gBAAgB;aAChC;SACD,CAAC,CAAA;IACH,CAAC;IAED,IAAI,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,CAAA;QAE3G,IAAI,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,cAAc;gBACpB,IAAI,EAAE,cAAc;gBACpB,SAAS,EAAE,sBAAsB;gBACjC,OAAO,EAAE,IAAI,KAAK,CAAC,aAAa,yFAAyF;gBACzH,QAAQ,EAAE;oBACT,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,aAAa,EAAE,KAAK,CAAC,aAAa;oBAClC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACvD;aACD,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IAED,OAAO,OAAO,CAAA;AACf,CAAC"}

package/out/intent/rules.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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";
+/**
+ * `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 declare function scoreBareToponym(input: NormalizedInputLite, shape: QueryShapeLike): number;
+/**
+ * `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 declare function scoreRoutePair(input: NormalizedInputLite, shape: QueryShapeLike): number;
+/**
+ * `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 declare function scoreNearMe(input: NormalizedInputLite, _shape: QueryShapeLike): number;
+/**
+ * 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 declare function nearMeSubject(input: NormalizedInputLite): string;
+//# sourceMappingURL=rules.d.ts.map

package/out/intent/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../lib/intent/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAkN3G;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAE1F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAgBxF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAatF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAQhE"}

package/out/intent/rules.js

@@ -0,0 +1,281 @@
+/**
+ * @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 { 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 = 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 = 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) {
+    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, shape) {
+    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, shape) {
+    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, shape) {
+    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, _shape) {
+    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) {
+    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();
+}
+//# sourceMappingURL=rules.js.map

package/out/intent/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../lib/intent/rules.ts"],"names":[],"mappings":"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"}