@mailwoman/kind-classifier 10.0.0 → 10.1.0

package/out/poi.d.ts

@@ -3,10 +3,10 @@
  * @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";
 /**
@@ -14,9 +14,9 @@ import type { NormalizedInputLite, QueryShapeSegmentsView as QueryShapeLike } fr
  */
 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;
@@ -24,42 +24,45 @@ 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, 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.
+     * 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.
      *
-     * 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.
+     * 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.
+     *
+     * 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>;
 export type POISpatialRelation = "comma" | "near" | "in" | "at" | "around" | "to";
@@ -72,25 +75,24 @@ export interface POIQuerySpan {
     end: number;
 }
 /**
- * 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;
     /**
@@ -105,35 +107,41 @@ export interface POISubjectMatch {
     anchorSpan?: POIQuerySpan;
 }
 /**
- * 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 declare function matchPOISubject(text: string, locale: string | undefined, lookup: POIPhraseLookup): POISubjectMatch | null;
 /**
- * `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 declare function createScorePOIQuery(lookup: POIPhraseLookup, locale?: string): (input: NormalizedInputLite, shape: QueryShapeLike) => number;
 /**
- * `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 declare function createScorePOICategory(lookup: POIPhraseLookup, locale?: string): (input: NormalizedInputLite, shape: QueryShapeLike) => number;
 /**
- * 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 declare function matchPOICategory(text: string, locale: string | undefined, lookup: POIPhraseLookup): POIPhraseMatch | null;
 //# sourceMappingURL=poi.d.ts.map

package/out/poi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"poi.d.ts","sourceRoot":"","sources":["../lib/poi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAO3G;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,GAAG,mBAAmB,GAAG,MAAM,CAAA;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,MAAM,CAAA;IACpC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC,cAAc,CAAC,CAAA;AAEhG,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAA;AAEjF,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,KAAK,EAAE,cAAc,CAAA;IACrB;;;;;;OAMG;IACH,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,YAAY,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,YAAY,CAAA;CACzB;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,eAAe,GACrB,eAAe,GAAG,IAAI,CAoExB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,MAAM,GACb,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,KAAK,MAAM,CAiB/D;AAUD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,MAAM,GACb,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,KAAK,MAAM,CAU/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,eAAe,GACrB,cAAc,GAAG,IAAI,CAQvB"}
+{"version":3,"file":"poi.d.ts","sourceRoot":"","sources":["../lib/poi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAS3G;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,GAAG,mBAAmB,GAAG,MAAM,CAAA;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,MAAM,CAAA;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC,cAAc,CAAC,CAAA;AAEhG,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAA;AAEjF,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,KAAK,EAAE,cAAc,CAAA;IACrB;;;;;OAKG;IACH,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,YAAY,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,YAAY,CAAA;CACzB;AAuCD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,eAAe,GACrB,eAAe,GAAG,IAAI,CAoExB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,MAAM,GACb,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,KAAK,MAAM,CAiB/D;AAYD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,MAAM,GACb,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,KAAK,MAAM,CAU/D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,eAAe,GACrB,cAAc,GAAG,IAAI,CAQvB"}

package/out/poi.js

@@ -3,58 +3,62 @@
  * @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.
  */
 /**
- * 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;
 /**
- * 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) {
     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, locale, lookup) {
     const trimmed = text.trim();
@@ -76,8 +80,8 @@ export function matchPOISubject(text, locale, lookup) {
         if (separator.index === 0)
             continue;
         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);
@@ -117,10 +121,12 @@ export function matchPOISubject(text, locale, lookup) {
     return null;
 }
 /**
- * `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, locale) {
     return (input, shape) => {
@@ -139,20 +145,23 @@ export function createScorePOIQuery(lookup, locale) {
     };
 }
 /**
- * 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, locale) {
     return (input, _shape) => {
@@ -165,8 +174,9 @@ export function createScorePOICategory(lookup, locale) {
     };
 }
 /**
- * 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, locale, lookup) {
     const matched = matchPOISubject(text, locale, lookup);

package/out/poi.js.map

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

package/out/rules.d.ts

@@ -3,80 +3,63 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Rule-based classifiers for each `QueryKind`. Each rule inspects the normalized input + QueryShape
- *   and returns a confidence score in [0, 1], or 0 if the rule doesn't fire.
- *
- *   Bitter-lesson-safe: only universal structural patterns — no place-name dictionaries. ~1 small
- *   regex set per new locale, not 50K dictionary entries.
+ *   Rule-based `QueryKind` scorers. Each scorer reads structural patterns in the normalized input and
+ *   its QueryShape and returns a confidence from 0 to 1.
  */
 import type { NormalizedInputLite, QueryShapeSegmentsView as QueryShapeLike } from "@mailwoman/query-shape";
 /**
- * Longest input still plausible as a bare locality name, including a trailing region code.
- *
- * Exported so `intent-rules.ts`'s `bare_toponym` can share the exact same ceiling. Sharing it is what makes
- * "bare_toponym is a strict refinement of locality_only" a structural property rather than two numbers that happen to
- * agree today.
+ * Maximum length for a bare locality.
+ * The `bare_toponym` intent rule uses the same limit.
  */
 export declare const MAX_LOCALITY_ONLY_LENGTH = 30;
 /**
- * `po_box` rule: high-confidence iff QueryShape detected a po_box format hit. Confidence comes directly from the hit;
- * covers all locale variants (US "PO Box 123", FR "BP 42", etc.).
+ * Scores input in which QueryShape detected a PO Box format.
  */
 export declare function scorePoBox(_input: NormalizedInputLite, shape: QueryShapeLike): number;
 /**
- * `intersection` rule: text matches one of the conventional intersection phrasings.
+ * Scores street-intersection phrasing.
  */
 export declare function scoreIntersection(input: NormalizedInputLite, _shape: QueryShapeLike): number;
 /**
- * `landmark` rule: text begins with a landmark-leader phrase. These inputs are not addresses proper — they describe a
- * location relative to another place.
+ * Scores input that begins with a relative-landmark phrase.
  */
 export declare function scoreLandmark(input: NormalizedInputLite, _shape: QueryShapeLike): number;
 /**
- * Split on whitespace + commas and drop empty words — the word grammar shared with `intent-rules.ts`. Dropping empties
- * matters: a trailing comma or doubled separator otherwise yields an empty string that inflates the word count and
- * falsifies every-word predicates like the proper-case check below.
+ * Splits text on whitespace and commas and drops empty tokens.
  */
 export declare function wordsOf(text: string): string[];
 /**
- * True when a word is USPS street-suffix vocabulary that unambiguously signals an address — the full Pub-28 table via
- * `@mailwoman/codex`, minus its curated name-prone canonicals (PARK, FIELD, HILL, LAKE, …). Those double as ordinary
- * proper-name heads ("Wrigley Field", "Menlo Park"), and disqualifying on them would reject the very venue and place
- * names the rules below exist to capture. Shared with `intent-rules.ts` so both rule sets read one definition.
+ * Reports whether a word is a USPS street suffix that rarely appears in place names.
  */
 export declare function isDisqualifyingStreetSuffix(word: string): boolean;
 /**
- * `landmark` rule (venue/named-place variant): short capitalized input with no street suffixes, no postcode hits, and
- * no region abbreviations. Captures "Pier 39", "Empire State Building", "Wrigley Field", "Grand Central Terminal".
+ * Removes postcode spans in the final segment and collapses the remaining separators.
+ */
+export declare function withoutPostcodeSpans(text: string, shape: QueryShapeLike): string;
+/**
+ * Reports whether text contains a Unicode letter.
  *
- * Fires at moderate confidence (0.65) — below structured_address (0.9) so addresses always win, but above vague (0.3)
- * so the pipeline can route landmark queries to the venue resolver.
+ * By itself, the `alpha` character class can match punctuation-only input.
+ */
+export declare function carriesLetter(text: string): boolean;
+/**
+ * Scores short capitalized venue names that have no street suffix or recognized format.
  */
 export declare function scoreVenueLandmark(input: NormalizedInputLite, shape: QueryShapeLike): number;
 /**
- * `postcode_only` rule: input is short AND has a postcode format hit covering most of it.
- *
- * The "covering most of it" check is what distinguishes `"10118"` (postcode-only) from `"350 5th Ave 10118"`
- * (structured-address with a postcode in it).
+ * Scores short input in which a postcode covers most of the text.
  */
 export declare function scorePostcodeOnly(input: NormalizedInputLite, shape: QueryShapeLike): number;
 /**
- * `locality_only` rule: short input, alpha-class, single segment, no format hits.
- *
- * Examples: `"Paris"`, `"NYC NY"`, `"Tokyo"`. Distinguishes from `structured_address` (multiple segments) and `vague`
- * (long or mixed-class).
+ * Scores a place name with at most an administrative tail and an optional postcode.
  */
 export declare function scoreLocalityOnly(input: NormalizedInputLite, shape: QueryShapeLike): number;
 /**
- * `structured_address` rule: looks like a real multi-component address. Either has multiple segments or is long and
- * mixed-class.
+ * Scores multi-component address shapes.
  */
 export declare function scoreStructuredAddress(input: NormalizedInputLite, shape: QueryShapeLike): number;
 /**
- * `vague` rule: nothing else fired with high confidence — input is ambiguous.
- *
- * Returns a moderate baseline so `vague` always shows up as an alternative, even when other rules dominate. The
- * coordinator decides whether to trust vague as the primary kind.
+ * Returns a low constant fallback score for ambiguous input.
  */
 export declare function scoreVague(_input: NormalizedInputLite, _shape: QueryShapeLike): number;
 //# sourceMappingURL=rules.d.ts.map

package/out/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../lib/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAmB3G;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAkD1C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAQrF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAQ5F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAQxF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAkD5F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAc3F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAe3F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAmBhG;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAEtF"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../lib/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAkB3G;;;GAGG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAgD1C;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAOrF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAQ5F;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAQxF;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9C;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAmBhF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AA0CD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CA2C5F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAY3F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAwC3F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAuBhG;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAEtF"}