@mailwoman/kind-classifier 7.1.0 → 7.2.1

package/classify.ts

@@ -0,0 +1,120 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `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.
+ *
+ *   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.
+ */
+
+import { createScorePOIQuery, type POIPhraseLookup } from "./poi.ts"
+import {
+	scoreIntersection,
+	scoreLandmark,
+	scoreLocalityOnly,
+	scorePoBox,
+	scorePostcodeOnly,
+	scoreStructuredAddress,
+	scoreVague,
+	scoreVenueLandmark,
+} from "./rules.ts"
+import type { LocaleHint, NormalizedInputLite, QueryKind, QueryKindResult, QueryShapeLike } from "./types.ts"
+
+interface KindScorer {
+	kind: QueryKind
+	score: (input: NormalizedInputLite, shape: QueryShapeLike) => number
+}
+
+const SCORERS: ReadonlyArray<KindScorer> = [
+	{ kind: "po_box", score: scorePoBox },
+	{ kind: "landmark", score: (i, s) => Math.max(scoreLandmark(i, s), scoreVenueLandmark(i, s)) },
+	{ kind: "intersection", score: scoreIntersection },
+	{ kind: "postcode_only", score: scorePostcodeOnly },
+	{ kind: "locality_only", score: scoreLocalityOnly },
+	{ kind: "structured_address", score: scoreStructuredAddress },
+	{ kind: "vague", score: scoreVague },
+]
+
+/**
+ * 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
+	)
+	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,
+	}
+}
+
+/**
+ * Async variant matching the runtime-pipeline's `classifyKind` contract.
+ *
+ * The locale parameter is accepted for future locale-aware rules (Japanese honorifics, etc.) but not currently used.
+ */
+export async function classifyKind(
+	input: NormalizedInputLite,
+	shape: QueryShapeLike,
+	_locale?: LocaleHint
+): Promise<QueryKindResult> {
+	return classifyKindSync(input, shape)
+}
+
+/** Options for {@link createKindClassifier}. */
+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}.
+	 */
+	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.
+ */
+export function createKindClassifier(
+	opts: KindClassifierOpts = {}
+): (input: NormalizedInputLite, shape: QueryShapeLike, locale?: LocaleHint) => Promise<QueryKindResult> {
+	const { poiLexicon } = opts
+
+	if (!poiLexicon) return classifyKind
+
+	return async (input, shape, locale): Promise<QueryKindResult> => {
+		const base = classifyKindSync(input, shape)
+		const poiConfidence = createScorePOIQuery(poiLexicon, locale?.locale)(input, shape)
+
+		if (poiConfidence <= 0) return base
+
+		if (poiConfidence > base.confidence) {
+			return {
+				kind: "poi_query",
+				confidence: poiConfidence,
+				alternatives: [{ 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 }
+
+		return {
+			...base,
+			alternatives: [...base.alternatives, poiAlternative].sort((a, b) => b.confidence - a.confidence),
+		}
+	}
+}

package/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @copyright Sister Software
+ * @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/articles/plan/reference/STAGES.md` § Stage 2.5 for the contract.
+ */
+
+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 {
+	scoreIntersection,
+	scoreLandmark,
+	scoreLocalityOnly,
+	scorePoBox,
+	scorePostcodeOnly,
+	scoreStructuredAddress,
+	scoreVague,
+} from "./rules.ts"
+export type { LocaleHint, NormalizedInputLite, QueryKind, QueryKindResult, QueryShapeLike } from "./types.ts"

package/out/classify.d.ts

@@ -12,6 +12,7 @@
  *   surfaces in `alternatives` — the caller decides whether to act on the top kind only or consider
  *   runner-ups.
  */
+import { type POIPhraseLookup } from "./poi.ts";
 import type { LocaleHint, NormalizedInputLite, QueryKindResult, QueryShapeLike } from "./types.ts";
 /**
  * Classify the query shape into a `QueryKind`. Synchronous + pure — produces the same result for the same `(input,
@@ -24,4 +25,18 @@ export declare function classifyKindSync(input: NormalizedInputLite, shape: Quer
  * The locale parameter is accepted for future locale-aware rules (Japanese honorifics, etc.) but not currently used.
  */
 export declare function classifyKind(input: NormalizedInputLite, shape: QueryShapeLike, _locale?: LocaleHint): Promise<QueryKindResult>;
+/** Options for {@link createKindClassifier}. */
+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}.
+     */
+    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.
+ */
+export declare function createKindClassifier(opts?: KindClassifierOpts): (input: NormalizedInputLite, shape: QueryShapeLike, locale?: LocaleHint) => Promise<QueryKindResult>;
 //# sourceMappingURL=classify.d.ts.map

package/out/classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAa,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAiB7G;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,eAAe,CAcnG;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,eAAe,CAAC,CAE1B"}
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAA;AAWpE,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAa,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAiB7G;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,eAAe,CAcnG;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,eAAe,CAAC,CAE1B;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAA;CAC5B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,IAAI,GAAE,kBAAuB,GAC3B,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,eAAe,CAAC,CA2BtG"}

package/out/classify.js

@@ -12,6 +12,7 @@
  *   surfaces in `alternatives` — the caller decides whether to act on the top kind only or consider
  *   runner-ups.
  */
+import { createScorePOIQuery } from "./poi.js";
 import { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, scoreVenueLandmark, } from "./rules.js";
 const SCORERS = [
     { kind: "po_box", score: scorePoBox },
@@ -45,4 +46,32 @@ export function classifyKindSync(input, shape) {
 export async function classifyKind(input, shape, _locale) {
     return classifyKindSync(input, shape);
 }
+/**
+ * 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.
+ */
+export function createKindClassifier(opts = {}) {
+    const { poiLexicon } = opts;
+    if (!poiLexicon)
+        return classifyKind;
+    return async (input, shape, locale) => {
+        const base = classifyKindSync(input, shape);
+        const poiConfidence = createScorePOIQuery(poiLexicon, locale?.locale)(input, shape);
+        if (poiConfidence <= 0)
+            return base;
+        if (poiConfidence > base.confidence) {
+            return {
+                kind: "poi_query",
+                confidence: poiConfidence,
+                alternatives: [{ 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: "poi_query", confidence: poiConfidence };
+        return {
+            ...base,
+            alternatives: [...base.alternatives, poiAlternative].sort((a, b) => b.confidence - a.confidence),
+        };
+    };
+}
 //# sourceMappingURL=classify.js.map

package/out/classify.js.map

@@ -1 +1 @@
-{"version":3,"file":"classify.js","sourceRoot":"","sources":["../classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,GAClB,MAAM,YAAY,CAAA;AAQnB,MAAM,OAAO,GAA8B;IAC1C,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE;IACrC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;IAC9F,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,iBAAiB,EAAE;IAClD,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,iBAAiB,EAAE;IACnD,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,iBAAiB,EAAE;IACnD,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,sBAAsB,EAAE;IAC7D,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE;CACpC,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA0B,EAAE,KAAqB;IACjF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAC9F,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CACvB,CAAA;IACD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAA;IAElD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,OAAoB,EAAE,UAAU,EAAE,GAAG,EAAE,CAAA;IACxE,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;IAE7F,OAAO;QACN,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,YAAY;KACZ,CAAA;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,KAA0B,EAC1B,KAAqB,EACrB,OAAoB;IAEpB,OAAO,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AACtC,CAAC"}
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../classify.ts"],"names":[],"mappings":"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"}

package/out/index.d.ts

@@ -5,14 +5,17 @@
  *
  *   `@mailwoman/kind-classifier` — Stage 2.5 of the runtime pipeline.
  *
- *   Categorize inputs into one of seven `QueryKind`s by composing rule-based scorers over the
+ *   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/articles/plan/reference/STAGES.md` § Stage 2.5 for the contract.
  */
-export { classifyKind, classifyKindSync } from "./classify.ts";
+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 { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, } from "./rules.ts";
 export type { LocaleHint, NormalizedInputLite, QueryKind, QueryKindResult, QueryShapeLike } from "./types.ts";
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,GACV,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpF,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAChF,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,GACV,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/out/index.js

@@ -5,13 +5,14 @@
  *
  *   `@mailwoman/kind-classifier` — Stage 2.5 of the runtime pipeline.
  *
- *   Categorize inputs into one of seven `QueryKind`s by composing rule-based scorers over the
+ *   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/articles/plan/reference/STAGES.md` § Stage 2.5 for the contract.
  */
-export { classifyKind, classifyKindSync } from "./classify.js";
+export { classifyKind, classifyKindSync, createKindClassifier } from "./classify.js";
+export { matchPOISubject } from "./poi.js";
 export { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, } from "./rules.js";
 //# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,GACV,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAEpF,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE1C,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,GACV,MAAM,YAAY,CAAA"}

package/out/poi.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @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
+ *   default-OFF `poiQueryKind` flag. Spec §3.1.
+ */
+import type { NormalizedInputLite, QueryShapeLike } from "./types.ts";
+/** One lexicon hit for a candidate subject phrase. */
+export interface POIPhraseMatch {
+    categoryID: string;
+    matchedPhrase: string;
+    confidence: number;
+}
+/** Injected phrase→category lookup. Exact-phrase, locale-aware; returns [] on miss. */
+export type POIPhraseLookup = (phrase: string, locale?: string) => ReadonlyArray<POIPhraseMatch>;
+export interface POISubjectMatch {
+    match: POIPhraseMatch;
+    /** The matched subject text as it appeared in the query. */
+    subject: string;
+    /** The anchor remainder after the separator; `""` when the whole input matched. */
+    remainder: string;
+}
+/**
+ * Match a POI subject: the whole input, or the text before the FIRST anchor separator WHOSE PREFIX HITS THE LEXICON (≤
+ * 4 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.
+ */
+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.
+ */
+export declare function createScorePOIQuery(lookup: POIPhraseLookup, locale?: string): (input: NormalizedInputLite, shape: QueryShapeLike) => number;
+//# sourceMappingURL=poi.d.ts.map

package/out/poi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poi.d.ts","sourceRoot":"","sources":["../poi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAErE,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC,cAAc,CAAC,CAAA;AAEhG,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,cAAc,CAAA;IACrB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAA;CACjB;AAWD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,eAAe,GACrB,eAAe,GAAG,IAAI,CA6BxB;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"}

package/out/poi.js

@@ -0,0 +1,69 @@
+/**
+ * @copyright Sister Software
+ * @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
+ *   default-OFF `poiQueryKind` flag. Spec §3.1.
+ */
+/**
+ * Anchor separator between subject and place: comma, or near/in/at/around — scanned left-to-right until a prefix hits
+ * the lexicon.
+ */
+const ANCHOR_SEPARATOR = /\s*,\s*|\s+(?:near|in|at|around)\s+/gi;
+/** Longest subject we accept, in tokens. Lexicon phrases are short; 4 covers the table. */
+const MAX_SUBJECT_TOKENS = 4;
+/**
+ * Match a POI subject: the whole input, or the text before the FIRST anchor separator WHOSE PREFIX HITS THE LEXICON (≤
+ * 4 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.
+ */
+export function matchPOISubject(text, locale, lookup) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    const whole = lookup(trimmed, locale);
+    if (whole.length > 0) {
+        return { match: whole[0], subject: trimmed, remainder: "" };
+    }
+    for (const separator of trimmed.matchAll(ANCHOR_SEPARATOR)) {
+        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.
+        if (subject.split(/\s+/).length > MAX_SUBJECT_TOKENS)
+            break;
+        const hits = lookup(subject, locale);
+        if (hits.length === 0)
+            continue;
+        const remainder = trimmed.slice(separator.index + separator[0].length).trim();
+        return { match: hits[0], subject, remainder };
+    }
+    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.
+ */
+export function createScorePOIQuery(lookup, locale) {
+    return (input, shape) => {
+        const matched = matchPOISubject(input.normalized, locale ?? input.appliedLocale, lookup);
+        if (!matched)
+            return 0;
+        if (matched.remainder === "")
+            return 0.92 * matched.match.confidence;
+        // Venue-led full address: "X, 350 5th Ave, …" stays a structured_address parse.
+        if (/^\d+\s/.test(matched.remainder))
+            return 0;
+        const segCount = shape.segments?.length ?? 1;
+        if (segCount > 3)
+            return 0;
+        return 0.9 * matched.match.confidence;
+    };
+}
+//# sourceMappingURL=poi.js.map

package/out/poi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poi.js","sourceRoot":"","sources":["../poi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;;GAGG;AACH,MAAM,gBAAgB,GAAG,uCAAuC,CAAA;AAEhE,2FAA2F;AAC3F,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAY,EACZ,MAA0B,EAC1B,MAAuB;IAEvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAE3B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IAEzB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAErC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;IAC7D,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC5D,IAAI,SAAS,CAAC,KAAK,KAAK,CAAC;YAAE,SAAQ;QAEnC,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;QAExD,uFAAuF;QACvF,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,kBAAkB;YAAE,MAAK;QAE3D,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAEpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QAE/B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;QAE7E,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;IAC/C,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAClC,MAAuB,EACvB,MAAe;IAEf,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACvB,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;QAExF,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,CAAA;QAEtB,IAAI,OAAO,CAAC,SAAS,KAAK,EAAE;YAAE,OAAO,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAA;QAEpE,gFAAgF;QAChF,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;YAAE,OAAO,CAAC,CAAA;QAE9C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC,CAAA;QAE5C,IAAI,QAAQ,GAAG,CAAC;YAAE,OAAO,CAAC,CAAA;QAE1B,OAAO,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAA;IACtC,CAAC,CAAA;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/kind-classifier",
-  "version": "7.1.0",
+  "version": "7.2.1",
   "description": "Stage 2.5 of the runtime pipeline — categorize inputs by query shape (postcode_only / locality_only / structured_address / intersection / po_box / landmark / vague). Rule-based for v1.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -12,7 +12,15 @@
     "out/**/*.js",
     "out/**/*.js.map",
     "out/**/*.d.ts",
-    "out/**/*.d.ts.map"
+    "out/**/*.d.ts.map",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
@@ -23,16 +31,16 @@
     }
   },
   "publishConfig": {
+    "access": "public",
     "exports": {
       "./package.json": "./package.json",
       ".": {
         "types": "./out/index.d.ts",
         "default": "./out/index.js"
       }
-    },
-    "access": "public"
+    }
   },
   "dependencies": {
-    "@mailwoman/core": "7.1.0"
+    "@mailwoman/core": "7.2.1"
   }
 }

package/poi.ts

@@ -0,0 +1,108 @@
+/**
+ * @copyright Sister Software
+ * @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
+ *   default-OFF `poiQueryKind` flag. Spec §3.1.
+ */
+
+import type { NormalizedInputLite, QueryShapeLike } from "./types.ts"
+
+/** One lexicon hit for a candidate subject phrase. */
+export interface POIPhraseMatch {
+	categoryID: string
+	matchedPhrase: string
+	confidence: number
+}
+
+/** Injected phrase→category lookup. Exact-phrase, locale-aware; returns [] on miss. */
+export type POIPhraseLookup = (phrase: string, locale?: string) => ReadonlyArray<POIPhraseMatch>
+
+export interface POISubjectMatch {
+	match: POIPhraseMatch
+	/** The matched subject text as it appeared in the query. */
+	subject: string
+	/** The anchor remainder after the separator; `""` when the whole input matched. */
+	remainder: string
+}
+
+/**
+ * Anchor separator between subject and place: comma, or near/in/at/around — scanned left-to-right until a prefix hits
+ * the lexicon.
+ */
+const ANCHOR_SEPARATOR = /\s*,\s*|\s+(?:near|in|at|around)\s+/gi
+
+/** Longest subject we accept, in tokens. Lexicon phrases are short; 4 covers the table. */
+const MAX_SUBJECT_TOKENS = 4
+
+/**
+ * Match a POI subject: the whole input, or the text before the FIRST anchor separator WHOSE PREFIX HITS THE LEXICON (≤
+ * 4 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.
+ */
+export function matchPOISubject(
+	text: string,
+	locale: string | undefined,
+	lookup: POIPhraseLookup
+): POISubjectMatch | null {
+	const trimmed = text.trim()
+
+	if (!trimmed) return null
+
+	const whole = lookup(trimmed, locale)
+
+	if (whole.length > 0) {
+		return { match: whole[0]!, subject: trimmed, remainder: "" }
+	}
+
+	for (const separator of trimmed.matchAll(ANCHOR_SEPARATOR)) {
+		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.
+		if (subject.split(/\s+/).length > MAX_SUBJECT_TOKENS) break
+
+		const hits = lookup(subject, locale)
+
+		if (hits.length === 0) continue
+
+		const remainder = trimmed.slice(separator.index + separator[0].length).trim()
+
+		return { match: hits[0]!, subject, remainder }
+	}
+
+	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.
+ */
+export function createScorePOIQuery(
+	lookup: POIPhraseLookup,
+	locale?: string
+): (input: NormalizedInputLite, shape: QueryShapeLike) => number {
+	return (input, shape) => {
+		const matched = matchPOISubject(input.normalized, locale ?? input.appliedLocale, lookup)
+
+		if (!matched) return 0
+
+		if (matched.remainder === "") return 0.92 * matched.match.confidence
+
+		// Venue-led full address: "X, 350 5th Ave, …" stays a structured_address parse.
+		if (/^\d+\s/.test(matched.remainder)) return 0
+
+		const segCount = shape.segments?.length ?? 1
+
+		if (segCount > 3) return 0
+
+		return 0.9 * matched.match.confidence
+	}
+}

package/rules.ts

@@ -0,0 +1,262 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ */
+
+import type { NormalizedInputLite, QueryShapeLike } from "./types.ts"
+
+/** Landmark vocabulary — phrases that suggest a vague-location description rather than an address. */
+const LANDMARK_LEADERS = [
+	"behind",
+	"near",
+	"across from",
+	"opposite",
+	"next to",
+	"by the",
+	"in front of",
+	"close to",
+	"beside",
+]
+
+/** Intersection vocabulary — words that signal "where two streets cross" rather than an address. */
+const INTERSECTION_PATTERNS = [
+	/\bcorner of\b/i,
+	/\bintersection of\b/i,
+	/\bat the corner of\b/i,
+	// "5th and Main", "Broadway & 42nd"
+	/\b\w+(?:st|nd|rd|th|street|ave|avenue|blvd|boulevard|road|rd|lane|ln)?\s+(?:and|&|@)\s+\w+/i,
+]
+
+/**
+ * `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.).
+ */
+export function scorePoBox(_input: NormalizedInputLite, shape: QueryShapeLike): number {
+	const hit = shape.knownFormats.find((f) => f.format === "po_box")
+
+	if (!hit) return 0
+
+	// Boost slightly above the raw hit confidence so po_box wins ties with structured_address when
+	// both rules fire on the same input.
+	return Math.min(1, hit.confidence + 0.1)
+}
+
+/**
+ * `intersection` rule: text matches one of the conventional intersection phrasings.
+ */
+export function scoreIntersection(input: NormalizedInputLite, _shape: QueryShapeLike): number {
+	const text = input.normalized
+
+	for (const pattern of INTERSECTION_PATTERNS) {
+		if (pattern.test(text)) return 0.85
+	}
+
+	return 0
+}
+
+/**
+ * `landmark` rule: text begins with a landmark-leader phrase. These inputs are not addresses proper — they describe a
+ * location relative to another place.
+ */
+export function scoreLandmark(input: NormalizedInputLite, _shape: QueryShapeLike): number {
+	const lc = input.normalized.toLowerCase().trim()
+
+	for (const leader of LANDMARK_LEADERS) {
+		if (lc.startsWith(leader + " ") || lc === leader) return 0.9
+	}
+
+	return 0
+}
+
+/** Street-suffix tokens that indicate an address, not a venue name. */
+const STREET_SUFFIXES = new Set([
+	"st",
+	"street",
+	"ave",
+	"avenue",
+	"blvd",
+	"boulevard",
+	"rd",
+	"road",
+	"dr",
+	"drive",
+	"ln",
+	"lane",
+	"ct",
+	"court",
+	"pl",
+	"place",
+	"way",
+	"pkwy",
+	"parkway",
+	"hwy",
+	"highway",
+	"cir",
+	"circle",
+])
+
+/**
+ * `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".
+ *
+ * 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.
+ */
+export function scoreVenueLandmark(input: NormalizedInputLite, shape: QueryShapeLike): number {
+	const text = input.normalized.trim()
+	const len = text.length
+
+	if (len === 0 || len > 50) return 0
+
+	// Must have at least one capitalized word.
+	if (!/[A-Z]/.test(text)) return 0
+
+	// Reject if any known postcode format hit exists.
+	if (shape.knownFormats.length > 0) return 0
+
+	// Reject if it looks like a multi-segment structured address (City, ST ZIP).
+	const segCount = shape.segments?.length ?? 1
+
+	if (segCount > 2) return 0
+
+	// Reject if any word is a street suffix.
+	const words = text.split(/[\s,]+/)
+
+	for (const w of words) {
+		if (STREET_SUFFIXES.has(w.toLowerCase())) return 0
+	}
+
+	// Reject if the first token is a pure number (house-number-leading pattern).
+	if (/^\d+\s/.test(text)) return 0
+
+	// Boost if the input has a number NOT at the start (venue-style: "Pier 39", "Terminal 5").
+	const hasInternalNumber = /\s\d+/.test(text) && !/^\d/.test(text)
+
+	// Check if every word starts with uppercase (proper-noun pattern).
+	const allProperCase = words.length > 1 && words.every((w) => /^[A-Z]/.test(w))
+
+	// Boost for short single-segment capitalized phrases (2-4 words).
+	const wordCount = words.length
+
+	if (wordCount >= 2 && wordCount <= 4 && segCount === 1) {
+		if (hasInternalNumber) return 0.88
+
+		if (allProperCase) return 0.88
+
+		return 0.65
+	}
+
+	// Longer single-segment capitalized phrases get moderate confidence.
+	if (wordCount <= 6 && segCount === 1 && allProperCase) {
+		return 0.75
+	}
+
+	return 0
+}
+
+/** Known QueryShape format strings that indicate "this token is a postcode". */
+const POSTCODE_FORMATS: ReadonlySet<string> = new Set([
+	"us_zip",
+	"us_zip4",
+	"uk_postcode",
+	"fr_postcode",
+	"de_postcode",
+	"ca_postcode",
+	"jp_postcode",
+	"nl_postcode",
+])
+
+/**
+ * Test whether a format string is a postcode variant. Use the set rather than ad-hoc string-matching to avoid the
+ * `us_zip4.endsWith("_zip")` false-negative trap.
+ */
+export function isPostcodeFormat(format: string): boolean {
+	return POSTCODE_FORMATS.has(format)
+}
+
+/**
+ * `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).
+ */
+export function scorePostcodeOnly(input: NormalizedInputLite, shape: QueryShapeLike): number {
+	const len = input.normalized.length
+
+	if (len === 0 || len > 16) return 0
+	const postcodeHit = shape.knownFormats.find((f) => isPostcodeFormat(f.format))
+
+	if (!postcodeHit) return 0
+	const hitLen = postcodeHit.span.end - postcodeHit.span.start
+
+	// At least 70% of the input must be the postcode for the rule to fire confidently.
+	if (hitLen / len < 0.7) return 0
+
+	// Confidence scales with how much of the input is the postcode and how confident the format hit was.
+	return Math.min(1, postcodeHit.confidence * (hitLen / len) + 0.1)
+}
+
+/**
+ * `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).
+ */
+export function scoreLocalityOnly(input: NormalizedInputLite, shape: QueryShapeLike): number {
+	const len = input.normalized.length
+
+	if (len === 0 || len > 30) return 0
+
+	if (shape.characterClass !== "alpha") return 0
+
+	if (shape.knownFormats.length > 0) return 0
+	// Locality-only inputs typically have 1-3 segments (e.g. "New York" is 1 segment, "Paris, FR" is 2).
+	// We allow up to 2 segments before deciding it's structured.
+	const segCount = shape.segments?.length ?? 1
+
+	if (segCount > 2) return 0
+
+	return 0.85
+}
+
+/**
+ * `structured_address` rule: looks like a real multi-component address. Either has multiple segments or is long and
+ * mixed-class.
+ */
+export function scoreStructuredAddress(input: NormalizedInputLite, shape: QueryShapeLike): number {
+	const len = input.normalized.length
+
+	if (len === 0) return 0
+	const segCount = shape.segments?.length ?? 1
+
+	// Multi-segment input with mixed character class = high confidence structured.
+	if (segCount >= 2 && shape.characterClass === "alphanumeric") return 0.9
+
+	// Single-segment but reasonably long and alphanumeric = moderate confidence.
+	if (len >= 15 && shape.characterClass === "alphanumeric") return 0.75
+
+	// Multi-segment but pure-alpha = moderate (could be a multi-word locality).
+	if (segCount >= 2) return 0.6
+
+	// Single-segment, short, alphanumeric (e.g. "10118-1234" with no other content) — weak.
+	if (len < 15 && shape.characterClass === "alphanumeric") return 0.4
+
+	return 0
+}
+
+/**
+ * `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.
+ */
+export function scoreVague(_input: NormalizedInputLite, _shape: QueryShapeLike): number {
+	return 0.3
+}

package/types.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/** Re-exports of the canonical types from `@mailwoman/core/pipeline`. */
+export type { LocaleHint, QueryKind, QueryKindResult } from "@mailwoman/core/pipeline"
+
+/**
+ * Minimal `NormalizedInput` shape consumed by `classifyKind`. Compatible with `@mailwoman/normalize`'s output.
+ */
+export interface NormalizedInputLite {
+	raw: string
+	normalized: string
+	appliedLocale?: string
+}
+
+/**
+ * Minimal `QueryShape` shape consumed by `classifyKind`. Compatible with `@mailwoman/query-shape`'s output.
+ */
+export interface QueryShapeLike {
+	knownFormats: ReadonlyArray<{
+		format: string
+		span: { start: number; end: number }
+		confidence: number
+	}>
+	segments?: ReadonlyArray<{ body: string; index: number }>
+	characterClass?: string
+	totalLength?: number
+}