@mailwoman/kind-classifier 4.0.0

package/out/classify.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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 type { LocaleHint, NormalizedInputLite, QueryKindResult, QueryShapeLike } from "./types.js";
+/**
+ * Classify the query shape into a `QueryKind`. Synchronous + pure — produces the same result for
+ * the same `(input, shape)` pair.
+ */
+export declare function classifyKindSync(input: NormalizedInputLite, shape: QueryShapeLike): QueryKindResult;
+/**
+ * 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 declare function classifyKind(input: NormalizedInputLite, shape: QueryShapeLike, _locale?: LocaleHint): Promise<QueryKindResult>;
+//# sourceMappingURL=classify.d.ts.map

package/out/classify.d.ts.map

@@ -0,0 +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;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,UAAU,GAClB,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/out/classify.js

@@ -0,0 +1,49 @@
+/**
+ * @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 { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, scoreVenueLandmark, } from "./rules.js";
+const SCORERS = [
+    { 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, shape) {
+    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", 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, shape, _locale) {
+    return classifyKindSync(input, shape);
+}
+//# sourceMappingURL=classify.js.map

package/out/classify.js.map

@@ -0,0 +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;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,KAA0B,EAC1B,KAAqB,EACrB,OAAoB;IAEpB,OAAO,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AACtC,CAAC"}

package/out/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 seven `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 { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, } from "./rules.js";
+export type { LocaleHint, NormalizedInputLite, QueryKind, QueryKindResult, QueryShapeLike } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +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"}

package/out/index.js

@@ -0,0 +1,17 @@
+/**
+ * @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 seven `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 { scoreIntersection, scoreLandmark, scoreLocalityOnly, scorePoBox, scorePostcodeOnly, scoreStructuredAddress, scoreVague, } from "./rules.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +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"}

package/out/rules.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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.js";
+/**
+ * `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 declare function scorePoBox(_input: NormalizedInputLite, shape: QueryShapeLike): number;
+/**
+ * `intersection` rule: text matches one of the conventional intersection phrasings.
+ */
+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.
+ */
+export declare function scoreLandmark(input: NormalizedInputLite, _shape: QueryShapeLike): number;
+/**
+ * `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 declare function scoreVenueLandmark(input: NormalizedInputLite, shape: QueryShapeLike): number;
+/**
+ * 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 declare function isPostcodeFormat(format: string): boolean;
+/**
+ * `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 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).
+ */
+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.
+ */
+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.
+ */
+export declare function scoreVague(_input: NormalizedInputLite, _shape: QueryShapeLike): number;
+//# sourceMappingURL=rules.d.ts.map

package/out/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAwBrE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAMrF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAM5F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAMxF;AA6BD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CA4C5F;AAaD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAU3F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAU3F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAahG;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAEtF"}

package/out/rules.js

@@ -0,0 +1,234 @@
+/**
+ * @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.
+ */
+/** 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, shape) {
+    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, _shape) {
+    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, _shape) {
+    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, shape) {
+    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 = new Set([
+    "us_zip",
+    "us_zip4",
+    "uk_postcode",
+    "fr_postcode",
+    "de_postcode",
+    "ca_postcode",
+    "jp_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) {
+    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, shape) {
+    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, shape) {
+    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, shape) {
+    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, _shape) {
+    return 0.3;
+}
+//# sourceMappingURL=rules.js.map

package/out/rules.js.map

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

package/out/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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;
+}
+//# sourceMappingURL=types.d.ts.map

package/out/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yEAAyE;AACzE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAEtF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,YAAY,EAAE,aAAa,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;QACpC,UAAU,EAAE,MAAM,CAAA;KAClB,CAAC,CAAA;IACF,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB"}

package/out/types.js

@@ -0,0 +1,7 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/out/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mailwoman/kind-classifier",
+  "version": "4.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "kind-classifier"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js"
+  },
+  "dependencies": {
+    "@mailwoman/core": "4.0.0"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}