@mailwoman/kind-classifier 9.4.0 → 10.1.0

package/lib/poi.ts

@@ -3,16 +3,18 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   POI subject detection for the `poi_query` kind. The lexicon is INJECTED (`POIPhraseLookup`) —
- *   this package keeps its bitter-lesson invariant (no dictionaries in-tree); the phrase table
- *   lives in `@mailwoman/poi-taxonomy` and is wired in by `createRuntimePipeline` behind the
- *   `poiQueryKind` flag (default-ON since 2026-07-20). Spec §3.1.
+ * POI subject detection for the `poi_query` kind. The lexicon is injected (`POIPhraseLookup`) so this
+ * package keeps its bitter-lesson invariant (no dictionaries in-tree); the phrase table lives in
+ * `@mailwoman/poi-taxonomy` and is wired in by `createRuntimePipeline` behind the `poiQueryKind` flag.
+ * Spec §3.1.
  */
 
 import type { NormalizedInputLite, QueryShapeSegmentsView as QueryShapeLike } from "@mailwoman/query-shape"
 /**
- * Comma-segment ceiling for a POI-led query. Past it the input is a venue plus a full address (`X, 350 5th Ave, New
- * York, NY`), which the structured-address scorer should claim instead.
+ * Comma-segment ceiling for a POI-led query.
+ *
+ * Past it the input is a venue plus a full address (`X, 350 5th Ave, New York, NY`),
+ * which the structured-address scorer should claim instead.
  */
 const MAX_POI_SEGMENTS = 3
 
@@ -21,9 +23,9 @@ const MAX_POI_SEGMENTS = 3
  */
 export interface POIPhraseMatch {
 	/**
-	 * The matched subject's identifier string. For `kind: "category"`, a `@mailwoman/poi-taxonomy` category id; for
-	 * `kind: "brand"` or `kind: "name"`, the canonical display name. `matchPOISubject` treats it opaquely; the caller
-	 * (`mailwoman`'s `poi-intent.ts`) interprets it per `kind`.
+	 * The matched subject's identifier: a `@mailwoman/poi-taxonomy` category id for
+	 * `kind: "category"`, otherwise the canonical display name; `matchPOISubject`
+	 * treats it opaquely and the caller interprets it per `kind`.
 	 */
 	categoryID: string
 	matchedPhrase: string
@@ -31,43 +33,46 @@ export interface POIPhraseMatch {
 	mechanism?: "exact" | "locale_normalized" | "typo"
 	inputPhrase?: string
 	/**
-	 * Absent = "category" (the pre-brand shape) — optional so pre-7.3 POIPhraseLookup implementors stay
-	 * source-compatible.
+	 * Absent means `"category"`; optional so existing `POIPhraseLookup` implementors stay source-compatible.
 	 */
 	kind?: "category" | "brand" | "name"
 	/**
-	 * Wikidata QID, when known. `kind: "brand"` only — absent when a brand resolved by name alone (no QID match).
+	 * Wikidata QID when known, `kind: "brand"` only.
+	 * Absent when a brand resolved using its name only.
 	 */
 	wikidata?: string
 	/**
-	 * Whether this hit is one member of a set the caller must search TOGETHER, rather than one candidate in a preference
-	 * list.
+	 * Whether this hit is one member of a set the caller must search together
+	 * rather than one candidate in a preference list.
+	 *
+	 * A lookup returning several hits means two different things: a phrase index
+	 * returns the categories one typed phrase could name, the curated reading first
+	 * (`credit union` → the `bank` rollup its synonym redirects to), while an affordance
+	 * rung returns every entity kind that affords one activity in a stable enumeration.
+	 * The enumeration does not express a preference.
 	 *
-	 * A lookup returning several hits means two different things, and the difference decides whether narrowing to the
-	 * first is an answer or an invented ordering. A phrase index returns the categories one typed phrase could name, the
-	 * curated reading first (`credit union` → the `bank` rollup its synonym redirects to, then the standalone
-	 * `credit_union` category), and the first entry IS the subject. An affordance rung returns every entity kind that
-	 * affords ONE activity, in a stable enumeration that is not a preference, and taking the first picks a winner nobody
-	 * authored.
+	 * The first result would impose an ordering that the source does not provide.
+	 * Set on every member of such a set, so {@link matchPOISubject} returns them all
+	 * and the POI branch searches their union.
 	 *
-	 * Set on every member of such a set. {@link matchPOISubject} then carries them all, the POI branch searches their
-	 * union, and the candidate ordering the resolver already owns decides the answer. Absent — the committed lexicon's
-	 * shape — keeps the first-hit reading unchanged.
+	 * Absent, the committed lexicon's shape, keeps the first-hit reading.
 	 */
 	searchAsSet?: boolean
 	/**
-	 * ISO 3166-1 alpha-2 countries the authority behind this hit scopes its claim to. Absent = the claim holds
-	 * everywhere.
+	 * ISO 3166-1 alpha-2 countries the authority behind this hit scopes its claim to.
+	 * Absent means the condition is true everywhere.
 	 *
-	 * A scope is a statement about ESTABLISHMENTS, so it is judged against the country of the place being searched, not
-	 * the caller's locale: the locale is the lens the phrase is read through, and it says nothing about where the claim
-	 * holds. `matchPOISubject` carries the value untouched; the POI intent stage binds it once the anchor has resolved.
+	 * A scope is a statement about establishments, so it is judged against the country of
+	 * the place being searched rather than the caller's locale: the locale is the lens the
+	 * phrase is read through and makes no statement about where the condition is true.
+	 * `matchPOISubject` returns the value unchanged.
+	 * The POI intent stage binds it once the anchor has resolved.
 	 */
 	countryScope?: readonly string[]
 }
 
 /**
- * Injected phrase→category lookup. Exact-phrase, locale-aware; returns [] on miss.
+ * Injected phrase→category lookup, exact-phrase and locale-aware, returning `[]` on miss.
  */
 export type POIPhraseLookup = (phrase: string, locale?: string) => ReadonlyArray<POIPhraseMatch>
 
@@ -83,25 +88,24 @@ export interface POIQuerySpan {
 }
 
 /**
- * Which lexicon this hit came from. Existing category lookups set `"category"` (backward-compatible default).
+ * Which lexicon this hit came from.
+ *
+ * Category lookups set `"category"` as the backward-compatible default.
  */
 export interface POISubjectMatch {
 	/**
-	 * The hit the subject SCORES under — its kind and its confidence. Always `matches[0]`; the two are built together in
-	 * one place so they cannot disagree.
+	 * The hit the subject scores under.
+	 *
+	 * Always `matches[0]`, built together in one place so they cannot disagree.
 	 */
 	match: POIPhraseMatch
 	/**
-	 * Every category the subject reaches, `match` first.
-	 *
-	 * One entry unless the lookup returned a {@link POIPhraseMatch.searchAsSet} set, in which case it holds the whole set
-	 * and the POI branch searches their union. The order is the order the lookup returned and states no preference:
-	 * nothing downstream may read position as rank.
+	 * Every category the subject reaches, `match` first: one entry unless the lookup
+	 * returned a {@link POIPhraseMatch.searchAsSet} set, in which case it holds the
+	 * whole set and the POI branch searches their union.
+	 * The order is the lookup's and states no preference.
 	 */
 	matches: POIPhraseMatch[]
-	/**
-	 * The matched subject text as it appeared in the query.
-	 */
 	subject: string
 	subjectSpan: POIQuerySpan
 	/**
@@ -117,50 +121,52 @@ export interface POISubjectMatch {
 }
 
 /**
- * Anchor separator between subject and place: comma, or near/in/at/around/to — scanned left-to-right until a prefix
- * hits the lexicon.
+ * Anchor separator between subject and place: comma, or near/in/at/around/to —
+ * scanned left-to-right until a prefix hits the lexicon.
+ *
+ * Linear by construction (no polynomial ReDoS): neither alternative places an unbounded
+ * whitespace quantifier before its required literal, the classic `js/polynomial-redos` shape.
+ * The comma alternative starts at the literal `,`.
  *
- * Linear by construction (no polynomial ReDoS): neither alternative places an unbounded whitespace quantifier _before_
- * its required literal — the classic `\s*`/`\s+`-then-literal backtracking shape that CodeQL's `js/polynomial-redos`
- * flags. The comma alternative starts at the literal `,`; the anchor alternative starts at a single `\s` immediately
- * before a fixed anchor word. Every remaining quantifier (`,\s*`, `…\s+`) is _trailing_ — it runs only after the
- * required literal has already matched and nothing follows it, so it never backtracks. Each start offset does O(1)
- * work, making `matchAll` O(n).
+ * The anchor alternative starts at one `\s` before a fixed anchor word.
+ * Every remaining quantifier is trailing and runs only after the required literal matches.
+ * Each start offset does O(1) work, so `matchAll` is O(n).
  *
- * Behaviour is byte-identical to the previous `\s*,\s*|\s+(?:…)\s+` because `matchPOISubject` `.trim()`s both the
- * subject (text before `.index`) and the remainder (text after the match), so surrounding whitespace on either side of
- * the separator is redundant. The leading `\s*`/`\s+` only shifted the match _start_ within a whitespace run — trim
- * absorbs that — while the retained _trailing_ greedy quantifier keeps the match _end_ (and thus `matchAll`'s
- * lastIndex) identical, preserving the exact subsequent-match sequence. Verified: 0 divergences across 22.7k inputs
- * (systematic + fuzzed adversarial whitespace + shared-whitespace anchor/comma chains).
+ * Behavior is byte-identical to the previous `\s*,\s*|\s+(?:…)\s+`, because `matchPOISubject`
+ * trims both the subject and the remainder, so surrounding whitespace is redundant.
+ * The leading quantifier only shifted the match start within a whitespace run, while the retained
+ * trailing greedy quantifier keeps the match end and thus `matchAll`'s lastIndex identical.
  */
 const ANCHOR_SEPARATOR = /,\s*|\s(near|in|at|around|to)\s+/gi
 
 /**
- * Longest subject we accept, in tokens. Eight covers compound taxonomy phrases while bounding lexicon probes.
+ * Longest subject accepted, in tokens: eight covers compound taxonomy phrases
+ * while bounding lexicon probes.
  */
 const MAX_SUBJECT_TOKENS = 8
 
 /**
- * The categories one candidate subject reaches, from the hits the lookup returned for it.
+ * The categories one candidate subject reaches: the whole array when the first hit
+ * declares {@link POIPhraseMatch.searchAsSet}, preserved as the lookup returned it
+ * and never filtered, so a rung that flagged only some members keeps every member.
  *
- * The whole array when the first hit declares {@link POIPhraseMatch.searchAsSet} — carried as the lookup returned it,
- * never filtered, so a rung that flagged only some of its members loses nothing here and the inconsistency stays
- * visible to whoever reads the set. Otherwise the first hit alone, which is the preference-list reading the committed
- * phrase index has always had.
+ * The inconsistency stays visible.
+ * Otherwise, use only the first hit.
  */
 function reachedMatches(hits: ReadonlyArray<POIPhraseMatch>): POIPhraseMatch[] {
 	return hits[0]!.searchAsSet ? [...hits] : [hits[0]!]
 }
 
 /**
- * Match a POI subject: the whole input, or the text before the FIRST anchor separator WHOSE PREFIX HITS THE LEXICON (≤
- * 8 tokens). Scans separator occurrences left-to-right — a lexicon phrase may itself contain a bare separator word
- * (e.g. "walk in clinic"), so the first separator isn't necessarily the right split point. Returns null when the
- * lexicon never fires — including comma-ridden full addresses whose leading segment isn't a lexicon phrase.
+ * Match a POI subject: the whole input, or the text before the first anchor
+ * separator whose prefix hits the lexicon (≤ 8 tokens).
+ *
+ * Scans separators left-to-right, because a lexicon phrase may itself contain a bare separator
+ * word ("walk in clinic") and the first separator is not necessarily the right split point.
+ * Returns null when the lexicon never fires, including comma-ridden full addresses
+ * whose leading segment is not a phrase.
  *
- * The winning candidate's hits are carried per {@link reachedMatches}: the first hit, or the whole set when the lookup
- * declared one.
+ * The winning candidate's hits are listed per {@link reachedMatches}.
  */
 export function matchPOISubject(
 	text: string,
@@ -191,8 +197,8 @@ export function matchPOISubject(
 
 		const subject = trimmed.slice(0, separator.index).trim()
 
-		// Subjects only grow as the scan moves right — once over budget, later splits are too. Whitespace-only
-		// split, not `wordsOf`: a comma inside a subject is real content here, not a separator to erase.
+		// Subjects only grow as the scan moves right, so once over budget later splits are too.
+		// Whitespace-only split rather than `wordsOf`, because a comma inside a subject is real content.
 		if (subject.split(/\s+/).length > MAX_SUBJECT_TOKENS) break
 
 		const hits = lookup(subject, locale)
@@ -237,10 +243,12 @@ export function matchPOISubject(
 }
 
 /**
- * `poi_query` scorer over an injected lexicon. Confidence bands: whole-input lexicon hit 0.92 (above venue-landmark's
- * 0.88 ceiling — an exact lexicon phrase beats a shape heuristic); subject + anchor 0.9. Guards below keep venue-led
- * FULL addresses (class 2) on the structured-address path: a remainder that leads with a house number, or a 4+-segment
- * input, scores 0 here.
+ * `poi_query` scorer over an injected lexicon, with confidence bands: a whole-input lexicon hit
+ * scores 0.92 (above venue-landmark's 0.88 ceiling, because an exact phrase beats a shape heuristic)
+ * and a subject plus anchor 0.9.
+ *
+ * The guards keep venue-led full addresses (class 2) on the structured-address path:
+ * a remainder leading with a house number, or a 4+-segment input, scores 0.
  */
 export function createScorePOIQuery(
 	lookup: POIPhraseLookup,
@@ -265,21 +273,24 @@ export function createScorePOIQuery(
 }
 
 /**
- * Confidence band for a bare category. One notch above `poi_query`'s whole-input band (0.92) so the anchorless subset
- * takes the top slot from it, and only from it — every anchored POI query keeps scoring `poi_query` exactly as before.
- * The coordinator's POI branch accepts both kinds, so the routing is identical either way; the split exists so the
- * marker can say "you named a category and no place", which is a different thing to tell a caller.
+ * Confidence band for a bare category, one notch above `poi_query`'s whole-input
+ * band (0.92) so only the anchorless subset takes the top slot and every anchored
+ * POI query keeps scoring `poi_query` as before.
+ *
+ * The coordinator's POI branch accepts both kinds, so the routing is identical either way.
+ * The split exists so the marker can say "you supplied a category and no place".
  */
 const POI_CATEGORY_CONFIDENCE = 0.93
 
 /**
- * `poi_category` scorer (ROAD_TO_V9 §4.4) — a bare taxonomy category with nowhere to search: "tacos", "grocery store",
- * "drinking fountain".
+ * `poi_category` scorer (ROAD_TO_V9 §4.4) — a bare taxonomy category with nowhere
+ * to search: "tacos", "grocery store", "drinking fountain".
+ *
+ * Fires only on a whole-input lexicon hit (`remainder === ""`) whose subject is a category.
+ * A brand (`kind: "brand"`) is excluded because `POIPhraseMatch.categoryID`
+ * then holds the brand's display name.
  *
- * Fires ONLY on a whole-input lexicon hit (`remainder === ""`) whose subject is a CATEGORY. A brand (`kind: "brand"`)
- * is excluded: a bare "Starbucks" is a name lookup, not a category, and the taxonomy id a category marker promises to
- * carry does not exist for it — `POIPhraseMatch.categoryID` holds the brand's display name in that case, which would
- * make the marker's `categoryID` evidence a lie.
+ * That value would misrepresent the marker's `categoryID` evidence.
  */
 export function createScorePOICategory(
 	lookup: POIPhraseLookup,
@@ -297,8 +308,9 @@ export function createScorePOICategory(
 }
 
 /**
- * The whole-input category hit behind a `poi_category` verdict, for the marker's evidence. `null` when the input is not
- * a bare category — same conditions as {@link createScorePOICategory}, so the two cannot disagree.
+ * The whole-input category hit behind a `poi_category` verdict, for the marker's evidence;
+ * `null` when the input is not a bare category, under the same conditions as
+ * {@link createScorePOICategory} so the two cannot disagree.
  */
 export function matchPOICategory(
 	text: string,