@mailwoman/codex 6.0.0 → 6.2.0

package/out/tools/build-country-surface-lexicon.js

@@ -0,0 +1,139 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the COUNTRY-SURFACE LEXICON for the country-lexicon soft-feed channel (#1104). This is the
+ *   third atlas channel, a sibling of the postcode anchor (#239/#240) and the gazetteer anchor
+ *   (#464): a per-token multi-hot clue the neural GRAMMAR conditions on but never obeys. Country is a
+ *   CLOSED, ENUMERABLE class (~250 surfaces) — atlas, not grammar — so a dictionary phrase-lookup
+ *   recovers the WOF-admin / resolver hierarchy case ("United States of America, Wyoming, <locality>")
+ *   the learned tagger reads as a leading STREET. Pelias handled the same class the same way
+ *   (`WhosOnFirstClassifier extends PhraseClassifier`); this is the model-first analogue.
+ *
+ *   WHY A DEDICATED LEXICON (not just the gazetteer's `country` slot): the gazetteer already carries
+ *   these surfaces in slot 0, and the shipped model already consumes them — yet the WOF-admin case
+ *   still fails (model-card #1104: golden country recall 82.0% vs 88.6%). The country bit is one of a
+ *   5-hot vector sharing ONE learned projection with region/po_box/cedex/homograph, and it is ZEROED
+ *   adjacent to a postcode by `suppress_gazetteer_near_postcode` (exactly where a trailing "…12345
+ *   USA" sits). A dedicated channel de-entangles the country signal (its own projection + confidence
+ *   weight) and is immune to that suppression. See
+ *   docs/superpowers/plans/2026-07-14-country-lexicon-channel.md.
+ *
+ *   The matcher REUSES the gazetteer's phrase-scan (longest-first n-gram over whitespace words,
+ *   case-insensitive `entries` + uppercase-exact `code_entries`, char→piece projection) — one tested
+ *   algorithm, two vocabularies. Only the vocabulary + the emitted feature differ. The emitted
+ *   feature is 2-dim per piece: `[country_surface, country_ambiguous]`.
+ *
+ *   - `country_surface` (bit 1): the piece is part of a recognized country surface phrase.
+ *   - `country_ambiguous` (bit 2): the SURFACE is a homograph (also a US region) or a common-word
+ *     name ("Georgia", "America", "England", "IN") — a SOFT version of Pelias's hard blacklist. The
+ *     model learns to trust `surface & !ambiguous` (unambiguous long/code forms) strongly and
+ *     `surface & ambiguous` weakly, using context — model-first, never a hard drop, so recall on
+ *     "Republic of Georgia" is preserved.
+ *
+ *   Source of truth: `@mailwoman/codex` (COUNTRY_SURFACE_FORMS + ISO2_TO_NAME) — the SAME data the
+ *   corpus-python bridge `country-surfaces.json` is generated from (export-country-surfaces.ts), so
+ *   the channel and the corpus shard synthesizer cannot diverge on what a country surface IS.
+ *
+ *   Output: data/gazetteer/country-surface-lexicon-v1.json (small, committed, provenance-tracked).
+ *   Regenerate: `node codex/tools/build-country-surface-lexicon.ts`
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.js";
+import { US_STATE_ABBREVIATIONS, US_STATE_NAMES } from "../us/state.js";
+const BIT = { country_surface: 1, country_ambiguous: 2 };
+const SLOTS = ["country_surface", "country_ambiguous"];
+// Committed output path (a codex-derived artifact, like export-country-surfaces.ts — no argv, so the
+// no-process-globals lint policy holds; codex stays zero-runtime-dep).
+const OUTPUT = resolve(import.meta.dirname, "../../data/gazetteer/country-surface-lexicon-v1.json");
+/**
+ * THE shared word-normalization rule (identical to build-gazetteer-anchor-lexicon.mjs and mirrored in
+ * gazetteer_char_paint on both sides): per whitespace-word, strip LEADING/TRAILING characters that are not Unicode
+ * letters or digits (keep internal ones: "u.s.a", "timor-leste"), rejoin single-spaced. Entry keys and scanned tokens
+ * both pass through it, so "U.S.A." ≡ "u.s.a".
+ */
+const wordNorm = (s) => s
+    .split(/\s+/)
+    .map((w) => w.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
+    .filter(Boolean)
+    .join(" ");
+const norm = (s) => wordNorm(s).toLowerCase();
+/** Short alphabetic code (≤3 letters once punctuation is dropped) → exact-uppercase matching. */
+const isShortCode = (s) => {
+    const letters = s.replace(/[^\p{L}]/gu, "");
+    return letters.length > 0 && letters.length <= 3 && /^[\p{L}.\s]+$/u.test(s);
+};
+// Homograph set: a single-word country surface that is ALSO a US region (name or abbreviation) reads
+// ambiguously (Georgia the country vs the state, IN = India vs Indiana). Computed from codex so it
+// tracks the US region table, never hand-maintained.
+const usStateNames = new Set(US_STATE_NAMES.map((n) => n.toLowerCase()));
+const usStateAbbrevs = new Set(US_STATE_ABBREVIATIONS);
+// Curated common-word country surfaces — single tokens that appear far more often as ordinary
+// street/venue/locality words than as a trailing country. A SOFT flag (the model still decides), the
+// model-first analogue of Pelias's blacklist (north/south/east/west/street/city/king). Tunable.
+const COMMON_WORD_AMBIGUOUS = new Set(["america", "england", "britain", "turkey", "chad", "jordan", "jersey", "guinea"]);
+const isAmbiguousName = (lowerKey) => usStateNames.has(lowerKey) || COMMON_WORD_AMBIGUOUS.has(lowerKey);
+// surface → bits, split across the two match-rule maps (mirrors the gazetteer builder).
+const entries = new Map(); // lowercase key
+const codeEntries = new Map(); // exact-uppercase key
+let maxNgram = 1;
+function add(surface) {
+    const s = surface.trim();
+    if (!s)
+        return;
+    if (isShortCode(s)) {
+        const key = wordNorm(s).toUpperCase();
+        if (!key)
+            return;
+        // A code that collides with a US-state abbreviation (CA/IN/AL/CO/…) is a homograph → ambiguous.
+        const bits = BIT.country_surface | (usStateAbbrevs.has(key) ? BIT.country_ambiguous : 0);
+        codeEntries.set(key, (codeEntries.get(key) ?? 0) | bits);
+        return;
+    }
+    const key = norm(s);
+    if (!key)
+        return;
+    const words = key.split(" ");
+    maxNgram = Math.max(maxNgram, words.length);
+    // Multi-word phrases are unambiguous by construction; single tokens consult the homograph +
+    // common-word rule.
+    const ambiguous = words.length === 1 && isAmbiguousName(key);
+    const bits = BIT.country_surface | (ambiguous ? BIT.country_ambiguous : 0);
+    entries.set(key, (entries.get(key) ?? 0) | bits);
+}
+// Curated rich surface forms first (US/GB/DE/… endonyms + abbreviations), then the canonical English
+// name for every remaining ISO 3166-1 alpha-2 — exactly the merge country-surfaces.json performs.
+for (const forms of Object.values(COUNTRY_SURFACE_FORMS)) {
+    for (const f of forms) {
+        add(f);
+    }
+}
+for (const [, name] of ISO2_TO_NAME) {
+    add(name);
+}
+const ambiguousEntries = [...entries, ...codeEntries].filter(([, b]) => b & BIT.country_ambiguous).map(([k]) => k);
+const lexicon = {
+    version: 1,
+    generated_by: "codex/tools/build-country-surface-lexicon.ts (source: @mailwoman/codex COUNTRY_SURFACE_FORMS + ISO2_TO_NAME)",
+    feature_dim: SLOTS.length,
+    slots: SLOTS,
+    bits: BIT,
+    max_ngram: maxNgram,
+    rules: {
+        word_norm: "per whitespace-word: strip leading/trailing chars that are not Unicode letters/digits " +
+            "(keep internal: 'timor-leste', 'u.s.a'); rejoin single-spaced. Applied to BOTH entry keys and scanned tokens.",
+        entries: "case-insensitive; key = word_norm lowercased. country_surface always set; country_ambiguous set for single-token homographs (US region) or curated common-word names.",
+        code_entries: "case-SENSITIVE exact: word_norm(token) == key (keys uppercase; 'in' the word ≠ 'IN' India). n-gram length 1. country_ambiguous set when the code is also a US-state abbreviation.",
+        scan: "longest-first n-gram over whitespace words, left to right, non-overlapping (shared with the gazetteer matcher)",
+        feature: "emitted per-piece row = [country_surface, country_ambiguous] (the raw bits); confidence = 1.0 where country_surface fires.",
+    },
+    entries: Object.fromEntries([...entries].sort(([a], [b]) => a.localeCompare(b))),
+    code_entries: Object.fromEntries([...codeEntries].sort(([a], [b]) => a.localeCompare(b))),
+};
+mkdirSync(dirname(OUTPUT), { recursive: true });
+writeFileSync(OUTPUT, JSON.stringify(lexicon, null, 1) + "\n");
+process.stderr.write(`wrote ${OUTPUT}: ${entries.size} entries + ${codeEntries.size} code_entries, ` +
+    `max_ngram=${maxNgram}, ${ambiguousEntries.length} ambiguous: ${ambiguousEntries.slice(0, 12).join(", ")}${ambiguousEntries.length > 12 ? ", …" : ""}\n`);
+//# sourceMappingURL=build-country-surface-lexicon.js.map

package/out/tools/build-country-surface-lexicon.js.map

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

package/out/tools/export-country-surfaces.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   codex → corpus-python bridge: emit the authoritative country surface forms as JSON so the Python
+ *   shard generators can synthesize address tails ("…, USA" / "…, United States of America") without
+ *   re-deriving the country name/alias data. `@mailwoman/codex` stays the single source of truth
+ *   (COUNTRY_SURFACE_FORMS + ISO2_TO_NAME, salvaged from isp-nexus spatial/countries); this writes a
+ *   snapshot the language boundary can't import directly.
+ *
+ *   Regenerate: `node codex/tools/export-country-surfaces.ts` (writes the corpus-python data file).
+ */
+export {};
+//# sourceMappingURL=export-country-surfaces.d.ts.map

package/out/tools/export-country-surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-country-surfaces.d.ts","sourceRoot":"","sources":["../../tools/export-country-surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/out/tools/export-country-surfaces.js

@@ -0,0 +1,34 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   codex → corpus-python bridge: emit the authoritative country surface forms as JSON so the Python
+ *   shard generators can synthesize address tails ("…, USA" / "…, United States of America") without
+ *   re-deriving the country name/alias data. `@mailwoman/codex` stays the single source of truth
+ *   (COUNTRY_SURFACE_FORMS + ISO2_TO_NAME, salvaged from isp-nexus spatial/countries); this writes a
+ *   snapshot the language boundary can't import directly.
+ *
+ *   Regenerate: `node codex/tools/export-country-surfaces.ts` (writes the corpus-python data file).
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.js";
+// Merge: rich surface forms where the codex curates them, else the canonical English name for every
+// ISO 3166-1 alpha-2. Canonical-name-first (the codex's own ordering) so the common form leads.
+const surfaces = {};
+for (const [iso2, forms] of Object.entries(COUNTRY_SURFACE_FORMS)) {
+    surfaces[iso2] = [...forms];
+}
+for (const [iso2, name] of ISO2_TO_NAME) {
+    if (!surfaces[iso2]) {
+        surfaces[iso2] = [name];
+    }
+}
+const out = resolve(import.meta.dirname, "../../corpus-python/src/mailwoman_train/data/country-surfaces.json");
+writeFileSync(out, JSON.stringify({
+    _generated: "codex/tools/export-country-surfaces.ts from @mailwoman/codex COUNTRY_SURFACE_FORMS + ISO2_TO_NAME",
+    surfaces,
+}, null, 2) + "\n");
+process.stderr.write(`wrote ${Object.keys(surfaces).length} countries → ${out}\n`);
+//# sourceMappingURL=export-country-surfaces.js.map

package/out/tools/export-country-surfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-country-surfaces.js","sourceRoot":"","sources":["../../tools/export-country-surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAE3E,oGAAoG;AACpG,gGAAgG;AAChG,MAAM,QAAQ,GAA6B,EAAE,CAAA;AAE7C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC;IACnE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;AAC5B,CAAC;AAED,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,YAAY,EAAE,CAAC;IACzC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;AACF,CAAC;AAED,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,oEAAoE,CAAC,CAAA;AAC9G,aAAa,CACZ,GAAG,EACH,IAAI,CAAC,SAAS,CACb;IACC,UAAU,EAAE,mGAAmG;IAC/G,QAAQ;CACR,EACD,IAAI,EACJ,CAAC,CACD,GAAG,IAAI,CACR,CAAA;AACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,CAAA"}

package/out/us/unit-designator.d.ts

@@ -16,6 +16,16 @@
  *   counterpart to the runtime `UnitDesignatorClassifier` (which matches the broader libpostal
  *   `unit_types` lexicon). Designators are LEADING ("Apt 4B"), unlike street suffixes which trail.
  *
+ *   `US_UNIT_DESIGNATOR_REQUIRES_RANGE` (added for #1100, the secondary-address epic; retrieved from
+ *   Appendix C2 2026-07-13) is Pub-28's own "Requires a Secondary Number" column: APT, BLDG, DEPT,
+ *   FL, HNGR, KEY, LOT, PIER, RM, SLIP, SPC, STOP, STE, TRLR, and UNIT must be followed by an
+ *   identifier ("Apt 4B", never bare "Apt"); BSMT, FRNT, LBBY, LOWR, OFC, PH, REAR, SIDE, and UPPR
+ *   may stand alone. This formalizes, as provenance-tracked reference data, the split that
+ *   `corpus/src/shard-recipes/unit.ts` previously hand-rolled (and only partially covered) as
+ *   in-file `ID_DESIGNATORS`/`STANDALONE_DESIGNATORS` arrays for synthesis weighting. A SEPARATE,
+ *   not-yet-built deliverable of #1100 is the per-locale *level-semantics* table (étage/RDC, EG/OG/UG,
+ *   planta/piso/bajo, piano/terra, 階/F/B1, …) — this module stays US/Pub-28 only.
+ *
  *   Data is verbatim USPS Pub-28 C2.
  * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Secondary Unit Designators}
  */
@@ -59,6 +69,13 @@ export type UsUnitDesignator = keyof typeof US_UNIT_DESIGNATOR_VARIANTS;
 export declare const US_UNIT_DESIGNATOR_LOOKUP: ReadonlyMap<string, UsUnitDesignator>;
 /** Approved USPS abbreviation per canonical (`APARTMENT → "APT"`, `SUITE → "STE"`). */
 export declare const US_UNIT_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<UsUnitDesignator, string>>;
+/**
+ * Canonical designators Appendix C2 marks as "Requires a Secondary Number" — the designator must be followed by an
+ * identifier ("Apt 4B", "Rm 12"), never appearing bare. The remaining designators (BASEMENT, FRONT, LOBBY, LOWER,
+ * OFFICE, PENTHOUSE, REAR, SIDE, UPPER) may stand alone with no trailing identifier. Verbatim from USPS Pub-28 C2; see
+ * the module header for provenance (#1100).
+ */
+export declare const US_UNIT_DESIGNATOR_REQUIRES_RANGE: Readonly<Record<UsUnitDesignator, boolean>>;
 /**
  * If the FIRST whitespace-separated word of `unit` is a known USPS designator variant, return the canonical key and the
  * matched word. Returns null if the leading word isn't a known designator (e.g. a bare `"4B"` or `"#210"`).
@@ -68,6 +85,30 @@ export declare function matchLeadingDesignator(unit: string): {
     canonical: UsUnitDesignator;
     matched: string;
 } | null;
+/** Result of {@link matchLeadingDesignatorWithRange}: the leading designator plus its optional secondary range. */
+export interface UnitDesignatorRangeMatch {
+    /** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+    canonical: UsUnitDesignator;
+    /** The designator's own matched surface form, i.e. "Apt". */
+    matched: string;
+    /**
+     * The secondary range/identifier token immediately following the designator, i.e. "4B" in "Apt 4B". Undefined when
+     * the designator appears standalone (e.g. bare "Basement"). This module does not validate the range's own shape —
+     * numeric, letter, or alphanumeric ranges are all USPS-valid.
+     */
+    range: string | undefined;
+    /**
+     * Whether USPS Pub-28 Appendix C2 marks this designator as requiring a secondary range (see
+     * {@link US_UNIT_DESIGNATOR_REQUIRES_RANGE}). Informational only — not enforced by this matcher.
+     */
+    requiresRange: boolean;
+}
+/**
+ * Like {@link matchLeadingDesignator}, but also captures the secondary range/identifier token immediately following the
+ * designator, if present ("Apt 4B" → designator "APARTMENT", range "4B"; "Basement" → range `undefined`). Mirrors
+ * `street-suffix`/`street-directional`'s designator+adjacent-token matchers.
+ */
+export declare function matchLeadingDesignatorWithRange(unit: string): UnitDesignatorRangeMatch | null;
 /** Result of a successful USPS secondary-unit designator lookup. */
 export interface UnitDesignatorMatch<D extends UsUnitDesignator = UsUnitDesignator> {
     /** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
@@ -86,4 +127,9 @@ export declare function lookupUnitDesignator(input: string | null | undefined):
  * `"floor"`.
  */
 export declare function isUnitDesignatorToken(input: unknown): boolean;
+/**
+ * Alias of {@link isUnitDesignatorToken} under Pub-28's own term ("secondary unit designator"). Added for #1100 so
+ * secondary-address call sites can spell the predicate after the publication's vocabulary.
+ */
+export declare function isSecondaryUnitDesignatorToken(input: unknown): boolean;
 //# sourceMappingURL=unit-designator.d.ts.map

package/out/us/unit-designator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unit-designator.d.ts","sourceRoot":"","sources":["../../us/unit-designator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;CAyBc,CAAA;AAEtD,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,2BAA2B,CAAA;AAEvE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAexE,CAAA;AAEJ,uFAAuF;AACvF,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAE1C,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAU5G;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IACjF,mEAAmE;IACnE,UAAU,EAAE,CAAC,CAAA;IACb,yDAAyD;IACzD,YAAY,EAAE,CAAC,OAAO,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;CACxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,EAAE,UAAU,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAA;AACvG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,mBAAmB,GAAG,IAAI,CAAA;AAUlG;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"unit-designator.d.ts","sourceRoot":"","sources":["../../us/unit-designator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;CAyBc,CAAA;AAEtD,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,2BAA2B,CAAA;AAEvE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAexE,CAAA;AAEJ,uFAAuF;AACvF,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAE1C,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAyBpC,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAU5G;AAED,mHAAmH;AACnH,MAAM,WAAW,wBAAwB;IACxC,mEAAmE;IACnE,SAAS,EAAE,gBAAgB,CAAA;IAC3B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAA;CACtB;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,CAgB7F;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IACjF,mEAAmE;IACnE,UAAU,EAAE,CAAC,CAAA;IACb,yDAAyD;IACzD,YAAY,EAAE,CAAC,OAAO,2BAA2B,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;CACxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,EAAE,UAAU,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAA;AACvG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,mBAAmB,GAAG,IAAI,CAAA;AAUlG;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE7D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtE"}

package/out/us/unit-designator.js

@@ -16,6 +16,16 @@
  *   counterpart to the runtime `UnitDesignatorClassifier` (which matches the broader libpostal
  *   `unit_types` lexicon). Designators are LEADING ("Apt 4B"), unlike street suffixes which trail.
  *
+ *   `US_UNIT_DESIGNATOR_REQUIRES_RANGE` (added for #1100, the secondary-address epic; retrieved from
+ *   Appendix C2 2026-07-13) is Pub-28's own "Requires a Secondary Number" column: APT, BLDG, DEPT,
+ *   FL, HNGR, KEY, LOT, PIER, RM, SLIP, SPC, STOP, STE, TRLR, and UNIT must be followed by an
+ *   identifier ("Apt 4B", never bare "Apt"); BSMT, FRNT, LBBY, LOWR, OFC, PH, REAR, SIDE, and UPPR
+ *   may stand alone. This formalizes, as provenance-tracked reference data, the split that
+ *   `corpus/src/shard-recipes/unit.ts` previously hand-rolled (and only partially covered) as
+ *   in-file `ID_DESIGNATORS`/`STANDALONE_DESIGNATORS` arrays for synthesis weighting. A SEPARATE,
+ *   not-yet-built deliverable of #1100 is the per-locale *level-semantics* table (étage/RDC, EG/OG/UG,
+ *   planta/piso/bajo, piano/terra, 階/F/B1, …) — this module stays US/Pub-28 only.
+ *
  *   Data is verbatim USPS Pub-28 C2.
  * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Secondary Unit Designators}
  */
@@ -69,6 +79,38 @@ export const US_UNIT_DESIGNATOR_LOOKUP = (() => {
 })();
 /** Approved USPS abbreviation per canonical (`APARTMENT → "APT"`, `SUITE → "STE"`). */
 export const US_UNIT_DESIGNATOR_PREFERRED_ABBR = Object.fromEntries(Object.keys(US_UNIT_DESIGNATOR_VARIANTS).map((k) => [k, US_UNIT_DESIGNATOR_VARIANTS[k][0]]));
+/**
+ * Canonical designators Appendix C2 marks as "Requires a Secondary Number" — the designator must be followed by an
+ * identifier ("Apt 4B", "Rm 12"), never appearing bare. The remaining designators (BASEMENT, FRONT, LOBBY, LOWER,
+ * OFFICE, PENTHOUSE, REAR, SIDE, UPPER) may stand alone with no trailing identifier. Verbatim from USPS Pub-28 C2; see
+ * the module header for provenance (#1100).
+ */
+export const US_UNIT_DESIGNATOR_REQUIRES_RANGE = {
+    APARTMENT: true,
+    BASEMENT: false,
+    BUILDING: true,
+    DEPARTMENT: true,
+    FLOOR: true,
+    FRONT: false,
+    HANGAR: true,
+    KEY: true,
+    LOBBY: false,
+    LOT: true,
+    LOWER: false,
+    OFFICE: false,
+    PENTHOUSE: false,
+    PIER: true,
+    REAR: false,
+    ROOM: true,
+    SIDE: false,
+    SLIP: true,
+    SPACE: true,
+    STOP: true,
+    SUITE: true,
+    TRAILER: true,
+    UNIT: true,
+    UPPER: false,
+};
 /**
  * If the FIRST whitespace-separated word of `unit` is a known USPS designator variant, return the canonical key and the
  * matched word. Returns null if the leading word isn't a known designator (e.g. a bare `"4B"` or `"#210"`).
@@ -84,6 +126,27 @@ export function matchLeadingDesignator(unit) {
         return null;
     return { canonical, matched: first };
 }
+/**
+ * Like {@link matchLeadingDesignator}, but also captures the secondary range/identifier token immediately following the
+ * designator, if present ("Apt 4B" → designator "APARTMENT", range "4B"; "Basement" → range `undefined`). Mirrors
+ * `street-suffix`/`street-directional`'s designator+adjacent-token matchers.
+ */
+export function matchLeadingDesignatorWithRange(unit) {
+    const trimmed = unit.trim();
+    if (!trimmed)
+        return null;
+    const parts = trimmed.split(/\s+/);
+    const first = parts[0];
+    const canonical = US_UNIT_DESIGNATOR_LOOKUP.get(first.toLowerCase());
+    if (!canonical)
+        return null;
+    return {
+        canonical,
+        matched: first,
+        range: parts[1],
+        requiresRange: US_UNIT_DESIGNATOR_REQUIRES_RANGE[canonical],
+    };
+}
 export function lookupUnitDesignator(input) {
     if (!input || typeof input !== "string")
         return null;
@@ -99,4 +162,11 @@ export function lookupUnitDesignator(input) {
 export function isUnitDesignatorToken(input) {
     return typeof input === "string" && US_UNIT_DESIGNATOR_LOOKUP.has(input.trim().toLowerCase());
 }
+/**
+ * Alias of {@link isUnitDesignatorToken} under Pub-28's own term ("secondary unit designator"). Added for #1100 so
+ * secondary-address call sites can spell the predicate after the publication's vocabulary.
+ */
+export function isSecondaryUnitDesignatorToken(input) {
+    return isUnitDesignatorToken(input);
+}
 //# sourceMappingURL=unit-designator.js.map

package/out/us/unit-designator.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/codex",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Per-address-system postal reference data + branded types (USPS street suffixes, US ZIP codes). Pure, zero-runtime-dep — the shared canonical home for postal-system primitives the parser, resolver, and synthesis layers all reach for.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -116,6 +116,6 @@
     "type-fest": "^5.8.0"
   },
   "devDependencies": {
-    "@mailwoman/annotations": "6.0.0"
+    "@mailwoman/annotations": "6.2.0"
   }
 }