@mailwoman/codex 9.3.0 → 10.0.0

package/lib/postcode/shapes.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Postcode SHAPE patterns — which substrings of a line LOOK like a postcode, ordered most-specific
+ *   to least. Priority IS the index: a lower index wins an overlap.
+ *
+ *   The DATA lives in `./shapes.json` so non-TS consumers read the identical record, the
+ *   same arrangement `us/street-suffix.json` has. Two runtimes need this table and both used to
+ *   carry their own typed copy: `@mailwoman/neural`'s postcode repair, and the Python trainer's
+ *   `features/postcode_shapes.py`, which paints the train-side anchor on the spans inference paints.
+ *   Hand-mirrored, they drifted twice — the IE Eircode row was TS-only for a month, the BR CEP row
+ *   for five weeks — and each time the trainer painted one fewer shape than inference, silently.
+ *
+ *   This is a SHAPE test, not a gazetteer-membership test. A bare `68161` matches the US, German,
+ *   French, Spanish and Italian 5-digit shapes; `./systems.ts` answers the membership
+ *   question, and neither module reads the other.
+ *
+ *   REGEX DIALECT. The bodies are written in the subset both JavaScript `RegExp` and Python `re`
+ *   accept, which is what lets one file serve both. A row needing different source text in the two
+ *   dialects needs a second field and a stated reason, not a loosened comparison on either side.
+ */
+
+import postcodeShapeData from "./shapes.json" with { type: "json" }
+
+/**
+ * What a match is eligible to do. `designated` may overwrite any existing label, `alnum` may add a postcode where the
+ * model emitted none, and `numeric` may only snap an existing one — so a numeric shape can never invent a postcode over
+ * a hyphenated house number.
+ */
+export type PostcodeShapeKind = "alnum" | "numeric" | "designated"
+
+/**
+ * One shape: the label it reports, what it is eligible to do, and the compiled pattern.
+ */
+export interface PostcodeShape {
+	readonly label: string
+	readonly kind: PostcodeShapeKind
+	readonly re: RegExp
+}
+
+/**
+ * Every postcode shape, in priority order. Compiled once at module load; each `RegExp` carries the `g` flag because
+ * callers scan a whole line, and `u` as well where the row declares it.
+ */
+export const POSTCODE_SHAPES: readonly PostcodeShape[] = postcodeShapeData.shapes.map((shape) => ({
+	label: shape.label,
+	kind: shape.kind as PostcodeShapeKind,
+	re: new RegExp(shape.pattern, "unicode" in shape && shape.unicode ? "gu" : "g"),
+}))
+
+/**
+ * The record's own version string, so a consumer that vendors a copy can say which revision it holds.
+ */
+export const POSTCODE_SHAPES_VERSION: string = postcodeShapeData.version

package/lib/{postcode-systems.ts → postcode/systems.ts}

@@ -186,8 +186,15 @@ export function isUnitGradePostcodeHit(parsed: string, resolverName: string | un
  * **The JP row is the JP board through the served path** (`jp-served-resolve.run.ts`, 2,000 rows, seed 42): the 586
  * rows carrying a postcode the candidate table keys, graded on the row's own entrance point — the locality-first answer
  * is the municipality centroid, the postcode answer the code's 町域 centroid from the WOF extract.
+ *
+ * **SG** is the limiting case of the tier: a six-digit Singapore postcode names ONE building, so the code's point IS
+ * the address, and the only locality above it is the city-state itself. Measured on a 300-row seeded draw of the
+ * Overture-SG register (`postalcode-sg-overture.db` folded, each row geocoded as `<number> <street> Singapore
+ * <postcode>` and graded on its own point): the postcode point answers 300 of 300 within 1 km (p99 0.16 km);
+ * locality-first answers 185, and the other 115 take the "Singapore" locality centroid (p75 6.30 km, p90 11.43 km, p99
+ * 24.18 km). The postcode point is closer on those 115 and equal on the rest; it is never farther.
  */
-export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE", "JP"])
+export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE", "JP", "SG"])
 
 /**
  * True when this country's area-grade postal code outranks its locality. Absent or unknown country → false, so the

package/lib/register-completion.ts

@@ -0,0 +1,24 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The one read every name register offers a decode-time repair: given the surface a model closed a span on and the
+ *   text that follows, the characters that would extend the surface to a register name. A surface that already IS a
+ *   name and is not the prefix of a longer one answers null.
+ */
+
+/**
+ * The remainder of the first register name that begins with `surface` and continues into `following`, or null.
+ */
+export function completeFromRegister(names: readonly string[], surface: string, following: string): string | null {
+	for (const name of names) {
+		if (name.length > surface.length && name.startsWith(surface)) {
+			const remainder = name.slice(surface.length)
+
+			if (following.startsWith(remainder)) return remainder
+		}
+	}
+
+	return null
+}

package/lib/us/index.ts

@@ -13,7 +13,7 @@ export * from "#us/floor-designator"
 export * from "#us/military-address"
 export * from "#us/po-box"
 export * from "#us/state"
-export * from "#us/street-directional"
-export * from "#us/street-suffix"
+export * from "#us/street/directional"
+export * from "#us/street/suffix"
 export * from "#us/unit-designator"
 export * from "#us/zipcode"

package/lib/us/po-box.ts

@@ -31,11 +31,37 @@ export const US_PO_BOX_DESIGNATORS = [
 export type USPoBoxDesignator = (typeof US_PO_BOX_DESIGNATORS)[number]
 
 /**
- * Matches a leading PO-box designator + its identifier. Allows "P.O. Box", "PO BOX", "Post Office Box", "Box 12-A",
- * etc. The id is alphanumeric with optional dashes (USPS caller/firm ids exist).
+ * Recognition patterns for {@link US_PO_BOX_DESIGNATORS}. Keeping the surface grammar next to the canonical designator
+ * prevents the exported lexicon and matcher from drifting apart.
  */
-const PO_BOX_RE =
-	/^\s*(?:(p\.?\s*o\.?\s*box)|(post\s+office\s+box)|(firm\s+caller)|(caller)|(drawer)|(lockbox)|(box))\s*#?\s*([\dA-Za-z][\dA-Za-z-]*)\s*$/i
+const PO_BOX_DESIGNATOR_PATTERNS: ReadonlyArray<readonly [USPoBoxDesignator, string]> = [
+	["POST OFFICE BOX", String.raw`post\s+office\s+box`],
+	["PO BOX", String.raw`p\.?\s*o\.?\s*box`],
+	["P O BOX", String.raw`p\.?\s*o\.?\s*box`],
+	["FIRM CALLER", String.raw`firm\s+caller`],
+	["CALLER", "caller"],
+	["DRAWER", "drawer"],
+	["LOCKBOX", "lockbox"],
+	["BOX", "box"],
+]
+
+/**
+ * One standalone matcher per USPS designator. The id is alphanumeric with optional dashes (USPS caller/firm ids exist).
+ */
+const PO_BOX_MATCHERS = PO_BOX_DESIGNATOR_PATTERNS.map(([designator, pattern]) => ({
+	designator,
+	designatorRe: new RegExp(String.raw`^\s*${pattern}\s*$`, "i"),
+	phraseRe: new RegExp(String.raw`^\s*(${pattern})\s*#?\s*([\dA-Za-z][\dA-Za-z-]*)\s*$`, "i"),
+}))
+
+/**
+ * True when `input` is a USPS PO-box designator without its box identifier. This is useful to consumers that compose a
+ * phrase and need to distinguish USPS vocabulary from their own locale-specific aliases (for example, the corpus's
+ * `POB` training variant).
+ */
+export function isUSPoBoxDesignator(input: unknown): input is string {
+	return typeof input === "string" && PO_BOX_MATCHERS.some(({ designatorRe }) => designatorRe.test(input))
+}
 
 /**
  * Type-predicate: does the input look like a standalone PO Box address? Case-insensitive and tolerant of "P.O. Box",
@@ -43,7 +69,7 @@ const PO_BOX_RE =
  * all-caps "PO BOX 123".)
  */
 export function isPOBox(input: unknown): boolean {
-	return typeof input === "string" && PO_BOX_RE.test(input)
+	return matchPOBox(input) !== null
 }
 
 /**
@@ -67,13 +93,14 @@ export interface PoBoxMatch {
  */
 export function matchPOBox(input: unknown): PoBoxMatch | null {
 	if (typeof input !== "string") return null
-	const m = PO_BOX_RE.exec(input)
 
-	if (!m) return null
-	const matched = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? m[6] ?? m[7] ?? "").trim()
-	const id = m[8]!
+	for (const { phraseRe } of PO_BOX_MATCHERS) {
+		const match = phraseRe.exec(input)
+
+		if (match) return { matched: match[1]!.trim(), id: match[2]! }
+	}
 
-	return { matched, id }
+	return null
 }
 
 /**

package/lib/us/{street-directional.ts → street/directional.ts}

@@ -10,7 +10,7 @@
  * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Pub 28 Appendix C1}
  */
 
-import { matchCase } from "#us/street-suffix"
+import { matchCase } from "#us/street/suffix"
 
 /**
  * The 8 directional abbreviations accepted by the USPS. The USPS prefers the abbreviation over the fully-spelled-out

package/lib/us/{street-suffix.ts → street/suffix.ts}

@@ -24,7 +24,7 @@
  * @see {@link https://pe.usps.com/text/pub28/28apc_002.htm USPS Street Suffix Abbreviations}
  */
 
-import streetSuffixData from "./street-suffix.json" with { type: "json" }
+import streetSuffixData from "../street-suffix.json" with { type: "json" }
 
 /**
  * Canonical USPS street suffix → list of recognized variants. The first variant in each list is the preferred USPS

package/out/address/format.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string — the inverse of the parser.
+ *
+ *   The order lives in `@mailwoman/codex/address-layouts`, as data. This module is the public surface over
+ *   {@linkcode renderAddress}: {@linkcode formatAddress} is the join, and {@linkcode formatAddressRow} is the join plus
+ *   the tags the layout printed, which is what every corpus adapter actually wants.
+ *
+ *   IT USED TO WRAP A THIRD-PARTY ENGINE, and 229 of this file's 438 lines existed to work around templates written
+ *   against OpenStreetMap's tag vocabulary rather than this project's: a pass that parsed 295 mustache templates at
+ *   module load to discover which of them could render a sub-locality, a second that spliced a missing line back in
+ *   afterwards, a third that removed a connector the template wrote between two slots when one was empty, and a
+ *   translation layer between the two vocabularies. Owning the layouts deletes all four — a layout that declares a
+ *   `dependent_locality` slot needs no interrogation about whether it has one, and a line assembled from present values
+ *   never writes a connector around an absent one.
+ */
+import { type ComponentDict } from "#address/render";
+import type { ComponentTag } from "#component";
+export type { ComponentDict } from "#address/render";
+/**
+ * Options accepted by {@linkcode formatAddress} and {@linkcode formatAddressRow}.
+ */
+export interface FormatAddressOptions {
+    /**
+     * Replace the layout's line breaks with this separator. Default `"\n"`: the envelope form.
+     */
+    separator?: string;
+    /**
+     * Join the lines the way the COUNTRY does, for the single-line form a query or a corpus row takes — `", "` for most,
+     * `" "` for Japan and Korea, and nothing at all for the Chinese-script systems, whose admin run is unseparated.
+     *
+     * It is an option rather than each caller's literal because the literal is wrong outside the anglophone systems:
+     * joining Japan's lines with a comma gives `1-9-1, 丸の内, 千代田区, 東京都 100-0005`, which is the romanized convention
+     * printed backwards. `separator` wins when both are given.
+     */
+    singleLine?: boolean;
+}
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string when the dict is empty, and when no layout names `country` — 55 of the 252 shipped country
+ * records carry no usable skeleton, and answering nothing for one of those reports absence rather than inventing an
+ * order. Throws nothing; a partial dict degrades to the parts the layout can print.
+ */
+export declare function formatAddress(components: ComponentDict, country: string, opts?: FormatAddressOptions): string;
+/**
+ * A rendered address and the components that survived the render.
+ */
+export interface AddressRow {
+    /**
+     * The rendered string.
+     */
+    readonly raw: string;
+    /**
+     * The subset of the input dict the layout PRINTED, with the caller's original values. This is the half a corpus row
+     * needs: a label whose text is not in `raw` cannot be aligned against it.
+     */
+    readonly components: ComponentDict;
+    /**
+     * Tags the dict carried a value for that the layout has no slot for, NAMED rather than silently dropped. France
+     * absorbing a region into its postcode line is the common case.
+     */
+    readonly unplaced: readonly ComponentTag[];
+}
+/**
+ * Render `components` for `country` and report what the layout printed, in one pass.
+ *
+ * Returns null when nothing rendered — an empty dict, a country with no layout, or a dict whose every value falls in a
+ * slot this country omits. Every corpus adapter asked both questions and paid for two renders to get them, then
+ * recovered the alignment by searching the output string for each value; that search cannot tell a component the layout
+ * dropped from one whose value happens to sit inside another — `Paris` inside `Rue de Paris`. The render knows, so the
+ * answer is read rather than inferred.
+ */
+export declare function formatAddressRow(components: ComponentDict, country: string, opts?: FormatAddressOptions): AddressRow | null;
+/**
+ * Which of `components` occur verbatim in `raw`, case- and whitespace-insensitively.
+ *
+ * This is a question about a string somebody else built — a committed golden fixture, a source's own address line — and
+ * it is the WEAKER of the two reconciliations: a substring test cannot tell a component the renderer dropped from one
+ * whose value happens to sit inside another. Anything rendered through a layout should read
+ * {@linkcode formatAddressRow}'s `components` instead, which the render knows rather than infers.
+ */
+export declare function componentsPresentIn(components: ComponentDict, raw: string): ComponentDict;
+//# sourceMappingURL=format.d.ts.map

package/out/address/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../lib/address/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB;AAQD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAEjH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAClC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC/B,UAAU,EAAE,aAAa,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,oBAAyB,GAC7B,UAAU,GAAG,IAAI,CAwBnB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAazF"}

package/out/address/format.js

@@ -0,0 +1,85 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string — the inverse of the parser.
+ *
+ *   The order lives in `@mailwoman/codex/address-layouts`, as data. This module is the public surface over
+ *   {@linkcode renderAddress}: {@linkcode formatAddress} is the join, and {@linkcode formatAddressRow} is the join plus
+ *   the tags the layout printed, which is what every corpus adapter actually wants.
+ *
+ *   IT USED TO WRAP A THIRD-PARTY ENGINE, and 229 of this file's 438 lines existed to work around templates written
+ *   against OpenStreetMap's tag vocabulary rather than this project's: a pass that parsed 295 mustache templates at
+ *   module load to discover which of them could render a sub-locality, a second that spliced a missing line back in
+ *   afterwards, a third that removed a connector the template wrote between two slots when one was empty, and a
+ *   translation layer between the two vocabularies. Owning the layouts deletes all four — a layout that declares a
+ *   `dependent_locality` slot needs no interrogation about whether it has one, and a line assembled from present values
+ *   never writes a connector around an absent one.
+ */
+import { layoutForCountry, lineJoinForCountry } from "#address/layouts/index";
+import { joinRendering, renderAddress } from "#address/render";
+function separatorFor(country, opts) {
+    if (opts.separator !== undefined)
+        return opts.separator;
+    return opts.singleLine ? lineJoinForCountry(country) : "\n";
+}
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string when the dict is empty, and when no layout names `country` — 55 of the 252 shipped country
+ * records carry no usable skeleton, and answering nothing for one of those reports absence rather than inventing an
+ * order. Throws nothing; a partial dict degrades to the parts the layout can print.
+ */
+export function formatAddress(components, country, opts = {}) {
+    return formatAddressRow(components, country, opts)?.raw ?? "";
+}
+/**
+ * Render `components` for `country` and report what the layout printed, in one pass.
+ *
+ * Returns null when nothing rendered — an empty dict, a country with no layout, or a dict whose every value falls in a
+ * slot this country omits. Every corpus adapter asked both questions and paid for two renders to get them, then
+ * recovered the alignment by searching the output string for each value; that search cannot tell a component the layout
+ * dropped from one whose value happens to sit inside another — `Paris` inside `Rue de Paris`. The render knows, so the
+ * answer is read rather than inferred.
+ */
+export function formatAddressRow(components, country, opts = {}) {
+    const layout = layoutForCountry(country);
+    if (!layout)
+        return null;
+    const rendering = renderAddress(layout, components);
+    if (!rendering.placed.length)
+        return null;
+    const raw = joinRendering(rendering, separatorFor(country, opts));
+    if (!raw)
+        return null;
+    const placed = {};
+    for (const tag of rendering.placed) {
+        const value = components[tag];
+        if (value) {
+            placed[tag] = value;
+        }
+    }
+    return { raw, components: placed, unplaced: rendering.unplaced };
+}
+/**
+ * Which of `components` occur verbatim in `raw`, case- and whitespace-insensitively.
+ *
+ * This is a question about a string somebody else built — a committed golden fixture, a source's own address line — and
+ * it is the WEAKER of the two reconciliations: a substring test cannot tell a component the renderer dropped from one
+ * whose value happens to sit inside another. Anything rendered through a layout should read
+ * {@linkcode formatAddressRow}'s `components` instead, which the render knows rather than infers.
+ */
+export function componentsPresentIn(components, raw) {
+    const haystack = raw.toLowerCase().replaceAll(/\s+/g, " ");
+    const out = {};
+    for (const [tag, value] of Object.entries(components)) {
+        if (!value)
+            continue;
+        if (haystack.includes(value.toLowerCase().replaceAll(/\s+/g, " "))) {
+            out[tag] = value;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=format.js.map

package/out/address/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../lib/address/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAsB,MAAM,iBAAiB,CAAA;AAyBlF,SAAS,YAAY,CAAC,OAAe,EAAE,IAA0B;IAChE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAA;IAEvD,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC5D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB,EAAE,OAAe,EAAE,IAAI,GAAyB,EAAE;IACxG,OAAO,gBAAgB,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAAA;AAC9D,CAAC;AAsBD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC/B,UAAyB,EACzB,OAAe,EACf,IAAI,GAAyB,EAAE;IAE/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAExC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAExB,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAEnD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAEzC,MAAM,GAAG,GAAG,aAAa,CAAC,SAAS,EAAE,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;IAEjE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IAErB,MAAM,MAAM,GAAkB,EAAE,CAAA;IAEhC,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAE7B,IAAI,KAAK,EAAE,CAAC;YACX,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QACpB,CAAC;IACF,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAA;AACjE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAyB,EAAE,GAAW;IACzE,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC1D,MAAM,GAAG,GAAkB,EAAE,CAAA;IAE7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,KAAK;YAAE,SAAQ;QAEpB,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,GAAmB,CAAC,GAAG,KAAK,CAAA;QACjC,CAAC;IACF,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC"}

package/out/address/key.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical match key — a normalized, deterministic string derived from address components,
+ *   distinct from the human-readable formatted string.
+ *
+ *   Where `format.ts` produces something for a person to read, this produces something for a
+ *   _machine_ to collide on: lowercased, diacritic-stripped, punctuation-flattened, whitespace-
+ *   collapsed, fields in a fixed canonical order. Two records for the same address that differ only
+ *   in spelling, case, or punctuation produce the same key — which is exactly what the matcher's
+ *   blocking stage wants as one cheap, high-precision candidate signal (alongside geographic
+ *   proximity, which carries the real weight — see the geocode-first record-matching concept doc).
+ *
+ *   Deliberately NOT done yet (follow-ups, all conditioned on `@mailwoman/codex`): expanding street
+ *   suffixes (`Ave` → `avenue`) and directionals (`N` → `north`) to a canonical form, and
+ *   USPS-style standardization. This first version is pure normalization with no dictionary expansion,
+ *   so the key is stable and explainable; expansion is an additive refinement, not a rewrite.
+ */
+import type { ComponentDict } from "#address/format";
+/**
+ * Options accepted by {@linkcode canonicalKey}.
+ */
+export interface CanonicalKeyOptions {
+    /**
+     * Field separator in the emitted key. Default `"|"` — preserves field boundaries for blocking.
+     */
+    separator?: string;
+}
+/**
+ * Options for {@linkcode foldForKey} — the two points where the formatter's address-token fold and the record package's
+ * fragment fold legitimately differ.
+ */
+export interface FoldForKeyOptions {
+    /**
+     * How connective punctuation folds. `"space"` turns `&`, `+`, and `/` into word boundaries (`"A&B"` → `"a b"`);
+     * `"and"` spells `&` and `+` out as the word `and` (`"AT&T"` → `"at and t"`), leaving `/` to the punctuation
+     * catch-all (still a word boundary).
+     */
+    ampersand: "space" | "and";
+    /**
+     * Intra-token deletion set. When true, periods join the apostrophes as intra-token noise and are deleted (`"S.A."` →
+     * `"sa"`), while a backtick falls to the punctuation catch-all. When false or omitted, backticks are deleted
+     * alongside the apostrophes and periods become word boundaries (`"S.A."` → `"s a"`).
+     */
+    dropPeriods?: boolean;
+}
+/**
+ * The shared fold behind every match key: NFKD-decompose and strip combining marks (so `é` → `e`), lowercase, delete
+ * intra-token punctuation, expand or flatten connective punctuation per {@linkcode FoldForKeyOptions}, space every
+ * remaining non-alphanumeric, and collapse whitespace. Deterministic — the same input and options always yield the same
+ * output.
+ */
+export declare function foldForKey(input: string, options: FoldForKeyOptions): string;
+/**
+ * Normalize a single token for matching: {@linkcode foldForKey} with connective punctuation flattened to spaces (so
+ * `"A&B"` → `"a b"`, not `"ab"`). Deterministic and reversible-free — the same input always yields the same output.
+ */
+export declare function normalizeAddressToken(input: string): string;
+/**
+ * Derive the canonical match key from an address component dict: each present, address-identifying field normalized via
+ * {@linkcode normalizeAddressToken}, in fixed order, joined by the separator. Empty / whitespace-only fields are
+ * skipped. Returns an empty string if nothing identifying remains.
+ */
+export declare function canonicalKey(components: ComponentDict, opts?: CanonicalKeyOptions): string;
+//# sourceMappingURL=key.d.ts.map

package/out/address/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../lib/address/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAyBpD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,KAAK,CAAA;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAqB5E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAgB9F"}

package/out/address/key.js

@@ -0,0 +1,91 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical match key — a normalized, deterministic string derived from address components,
+ *   distinct from the human-readable formatted string.
+ *
+ *   Where `format.ts` produces something for a person to read, this produces something for a
+ *   _machine_ to collide on: lowercased, diacritic-stripped, punctuation-flattened, whitespace-
+ *   collapsed, fields in a fixed canonical order. Two records for the same address that differ only
+ *   in spelling, case, or punctuation produce the same key — which is exactly what the matcher's
+ *   blocking stage wants as one cheap, high-precision candidate signal (alongside geographic
+ *   proximity, which carries the real weight — see the geocode-first record-matching concept doc).
+ *
+ *   Deliberately NOT done yet (follow-ups, all conditioned on `@mailwoman/codex`): expanding street
+ *   suffixes (`Ave` → `avenue`) and directionals (`N` → `north`) to a canonical form, and
+ *   USPS-style standardization. This first version is pure normalization with no dictionary expansion,
+ *   so the key is stable and explainable; expansion is an additive refinement, not a rewrite.
+ */
+/**
+ * The address-identifying components, in canonical key order. Venue / attention are intentionally excluded — those
+ * carry organization identity, which the record layer keys separately.
+ */
+const KEY_FIELD_ORDER = [
+    "po_box",
+    "house_number",
+    "street_prefix",
+    "street_prefix_particle",
+    "street",
+    "street_suffix",
+    "intersection_a",
+    "intersection_b",
+    "unit",
+    "dependent_locality",
+    "locality",
+    "subregion",
+    "region",
+    "postcode",
+    "country",
+];
+/**
+ * The shared fold behind every match key: NFKD-decompose and strip combining marks (so `é` → `e`), lowercase, delete
+ * intra-token punctuation, expand or flatten connective punctuation per {@linkcode FoldForKeyOptions}, space every
+ * remaining non-alphanumeric, and collapse whitespace. Deterministic — the same input and options always yield the same
+ * output.
+ */
+export function foldForKey(input, options) {
+    const folded = input
+        .normalize("NFKD")
+        // strip combining marks (U+0300–U+036F) left by NFKD decomposition, so "é" → "e"
+        .replaceAll(/[\u0300-\u036F]/g, "")
+        .toLowerCase()
+        // apostrophes are intra-word (possessives, "O'Brien") — delete so the token stays whole
+        .replaceAll(options.dropPeriods ? /[.'’]/g : /['’`]/g, "");
+    const connected = options.ampersand === "and"
+        ? folded.replaceAll("&", " and ").replaceAll("+", " and ")
+        : folded.replaceAll(/[&+/]/g, " ");
+    return (connected
+        // everything else non-alphanumeric (keep spaces) is noise
+        .replaceAll(/[^a-z0-9\s]/g, " ")
+        .replaceAll(/\s+/g, " ")
+        .trim());
+}
+/**
+ * Normalize a single token for matching: {@linkcode foldForKey} with connective punctuation flattened to spaces (so
+ * `"A&B"` → `"a b"`, not `"ab"`). Deterministic and reversible-free — the same input always yields the same output.
+ */
+export function normalizeAddressToken(input) {
+    return foldForKey(input, { ampersand: "space" });
+}
+/**
+ * Derive the canonical match key from an address component dict: each present, address-identifying field normalized via
+ * {@linkcode normalizeAddressToken}, in fixed order, joined by the separator. Empty / whitespace-only fields are
+ * skipped. Returns an empty string if nothing identifying remains.
+ */
+export function canonicalKey(components, opts = {}) {
+    const separator = opts.separator ?? "|";
+    const parts = [];
+    for (const tag of KEY_FIELD_ORDER) {
+        const value = components[tag];
+        if (!value)
+            continue;
+        const normalized = normalizeAddressToken(value);
+        if (normalized) {
+            parts.push(normalized);
+        }
+    }
+    return parts.join(separator);
+}
+//# sourceMappingURL=key.js.map

package/out/address/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../lib/address/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH;;;GAGG;AACH,MAAM,eAAe,GAAG;IACvB,QAAQ;IACR,cAAc;IACd,eAAe;IACf,wBAAwB;IACxB,QAAQ;IACR,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,MAAM;IACN,oBAAoB;IACpB,UAAU;IACV,WAAW;IACX,QAAQ;IACR,UAAU;IACV,SAAS;CACkC,CAAA;AA+B5C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,OAA0B;IACnE,MAAM,MAAM,GAAG,KAAK;SAClB,SAAS,CAAC,MAAM,CAAC;QAClB,iFAAiF;SAChF,UAAU,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAClC,WAAW,EAAE;QACd,wFAAwF;SACvF,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IAE3D,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,KAAK,KAAK;QAC1B,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;QAC1D,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IAEpC,OAAO,CACN,SAAS;QACR,0DAA0D;SACzD,UAAU,CAAC,cAAc,EAAE,GAAG,CAAC;SAC/B,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;SACvB,IAAI,EAAE,CACR,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAA;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAyB,EAAE,IAAI,GAAwB,EAAE;IACrF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAA;IACvC,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAE7B,IAAI,CAAC,KAAK;YAAE,SAAQ;QACpB,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;QAE/C,IAAI,UAAU,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACvB,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;AAC7B,CAAC"}