@mailwoman/codex 9.3.0 → 10.0.0

package/README.md

@@ -1,38 +1,186 @@
-# @mailwoman/codex
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://mailwoman.ai/img/mailwoman-seal-magenta.svg">
+    <img src="https://mailwoman.ai/img/mailwoman-seal-navy.svg" alt="" width="96" height="96">
+  </picture>
+</p>
+
+<h1 align="center">@mailwoman/codex</h1>
+
+<p align="center"><strong>A postal address formatter, and the per-country reference data behind it.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mailwoman/codex"><img alt="npm version" src="https://img.shields.io/npm/v/@mailwoman/codex?color=ff00b0&label=npm"></a>
+  <img alt="dependencies" src="https://img.shields.io/badge/runtime%20deps-0-339933">
+  <img alt="license" src="https://img.shields.io/npm/l/@mailwoman/codex?color=663399">
+  <img alt="node version" src="https://img.shields.io/node/v/@mailwoman/codex?color=339933">
+</p>
+
+Printing an address is not string concatenation. Germany puts the house number after the
+street and the postcode before the city. Spain separates the street from the number with a
+comma. Japan writes largest unit first, opens with a postal mark, and joins the whole admin
+run without spaces. Get any of it wrong and you have produced a plausible address from
+somewhere else.
 
-**Per-address-system postal reference data and branded types.**
+```ts
+import { formatAddress } from "@mailwoman/codex/address-format"
+
+formatAddress(
+	{ house_number: "1600", street: "Pennsylvania Ave NW", locality: "Washington", region: "DC", postcode: "20500" },
+	"US"
+)
+// → "1600 Pennsylvania Ave NW\nWashington, DC 20500"
+
+formatAddress({ street: "Willy-Brandt-Straße", house_number: "1", locality: "Berlin", postcode: "10557" }, "DE", {
+	singleLine: true,
+})
+// → "Willy-Brandt-Straße 1, 10557 Berlin"
+
+formatAddress({ street: "Calle de Alcalá", house_number: "3", locality: "Madrid", postcode: "28014" }, "ES", {
+	singleLine: true,
+})
+// → "Calle de Alcalá, 3, 28014 Madrid"
+
+formatAddress(
+	{
+		postcode: "100-0005",
+		region: "東京都",
+		subregion: "千代田区",
+		dependent_locality: "丸の内",
+		house_number: "1-9-1",
+	},
+	"JP",
+	{ singleLine: true }
+)
+// → "〒100-0005 東京都千代田区丸の内1-9-1"
+```
+
+**197 countries**, no dependencies, no network, no database. It runs in Node, the browser and
+on an edge worker.
+
+## Installation
+
+```bash
+npm install @mailwoman/codex
+# or
+yarn add @mailwoman/codex
+```
 
-Every country's postal authority (USPS, La Poste, Deutsche Post, …) has its own
-conventions for what a postcode, a street suffix, or a unit designator looks like.
-`@mailwoman/codex` is the shared, dependency-free home for that reference knowledge,
-kept apart from the locale-agnostic tokenizer/solver in `@mailwoman/core` and from
-the training pipeline in `@mailwoman/corpus`.
+> [!IMPORTANT]
+> Requires Node.js ≥ 24.18.0. Pure ESM.
 
-The parser, the resolver, and the synthesis layer all reach for the same tables
-instead of each carrying their own copy.
+## Formatting
+
+### `formatAddress(components, countryCode, options?)`
+
+Takes a partial map of component tags and a country code. Returns the envelope form by
+default; `singleLine: true` joins the lines the way that country joins them — `", "` for
+most, `" "` for Japan and Korea, nothing at all for the Chinese-script systems.
+
+A missing value never leaves a dangling separator behind it, because a connector renders
+only when something rendered on both sides of it:
 
 ```ts
-import { us, fr, gb, de } from "@mailwoman/codex"
+formatAddress({ locality: "New York", postcode: "10118" }, "US", { singleLine: true })
+// → "New York, 10118"   — not "New York, , 10118"
+```
 
-// USPS street suffix lookup
-us.lookupStreetSuffix("PKWY") // → { primary: "Parkway", standard: "Parkway", ... }
-us.lookupStreetSuffix("PKY") // → { primary: "Parkway", standard: "Parkway", ... }
+An unknown country returns `""` rather than guessing an order. 55 of the 252 shipped country
+records carry no usable layout, and saying nothing for one of those reports the absence.
 
-// French postcode pattern
-fr.postcodePattern // → /^\d{5}$/
+### `formatAddressRow(components, countryCode, options?)`
 
-// US ZIP code branded type
-import { us } from "@mailwoman/codex"
-const zip: us.ZipCode = "94043" // branded, not string alone
+The same render, plus **which tags it printed and which it could not**. That second half is
+the reason this function exists: a country's layout legitimately drops components, and
+searching the output string for each value cannot tell a dropped component from one whose
+text happens to sit inside another (`Paris` inside `Rue de Paris`).
+
+```ts
+formatAddressRow({ locality: "Paris", region: "Île-de-France", postcode: "75008" }, "FR", { singleLine: true })
+// → {
+//     raw: "75008 Paris",
+//     components: { postcode: "75008", locality: "Paris" },
+//     unplaced: ["region"],            // France absorbs the region — named, not silently dropped
+//   }
 ```
 
-## Supported address systems
+Returns `null` when nothing rendered at all.
 
-Each system is exposed as a namespace and as a subpath import:
+### `canonicalKey(components, options?)`
+
+A deterministic match key for record linkage — lowercased, diacritic-stripped,
+punctuation-flattened, fields in a fixed order. Two records for the same address that differ
+only in spelling produce the same key.
 
 ```ts
-import { us } from "@mailwoman/codex"
-import { lookupStreetSuffix } from "@mailwoman/codex/us"
+import { canonicalKey } from "@mailwoman/codex/address-key"
+
+canonicalKey({
+	house_number: "123",
+	street: "Main",
+	street_suffix: "St",
+	locality: "Portland",
+	region: "OR",
+	postcode: "97201",
+})
+// → "123|main|st|portland|or|97201"
+```
+
+Venue and attention are excluded on purpose: those carry organization identity, not address
+identity.
+
+### `renderAddress(layout, components)`
+
+The layer under `formatAddress`, for callers that need the pieces rather than a string — a
+syntax highlighter, a template that wraps each component in its own element, an aligner
+turning a render into labeled spans. It returns `AddressPiece[]`, each piece carrying the
+tag that produced it (or `null` for a separator).
+
+## Where the order comes from
+
+Each country's layout is **data**, written as a tagged template that reads in the order it
+prints:
+
+```ts
+// %N%n%O%n%A%n%C, %S %Z
+US: addr`${attention}
+${venue}
+${numberFirstStreet}
+${locality}, ${region} ${postcode}
+${country}`,
+```
+
+Checking a country means looking at the shape of an address from there, not at a nested call.
+The line skeletons are derived from [libaddressinput](https://github.com/google/libaddressinput),
+Google's address metadata (Apache-2.0); 186 countries are generated from it and the 11 locales
+this project publishes models for are hand-authored and checked against real addresses on a
+committed board.
+
+**One rule governs rendering:**
+
+> A node that renders nothing removes itself, and its connector goes with it.
+
+A connector between two slots needs a rendered slot on each side. A connector at a line's edge
+has only one side, so it binds to the single slot it touches — which is how Japan's 〒
+disappears along with an absent postcode while an interior space does not. Where several
+connectors survive in a row, the strongest wins: punctuation outranks whitespace, so
+`Calle Mayor, 12` keeps its comma when the street suffix is absent.
+
+Four things libaddressinput does not model are authored here, each from a measurement rather
+than a guess: the street line's spelling (183 countries space-join the number and the name, 22
+comma-join), the post-office box line, the country line, and the sub-locality line.
+
+## Reference data
+
+The formatter sits on top of the per-address-system tables, which are useful on their own.
+
+```ts
+import { us, fr } from "@mailwoman/codex"
+
+us.lookupStreetSuffix("PKWY") // → { primary: "Parkway", standard: "Parkway", … }
+fr.postcodePattern // → /^\d{5}$/
+
+const zip: us.ZipCode = "94043" // branded, not string alone
 ```
 
 | System   | Scope                                                                                |
@@ -44,34 +192,29 @@ import { lookupStreetSuffix } from "@mailwoman/codex/us"
 | **`ca`** | Canada Post postcode format, province abbreviations, the urban/rural FSA split       |
 | **`au`** | Australia Post postcode format, state abbreviations                                  |
 
-## Cross-system utilities
+### Which country is this postcode from?
 
 ```ts
 import { candidateSystemsForPostcode } from "@mailwoman/codex"
 
-// Which systems could this shape belong to? A five-digit run is not evidence of one country.
 candidateSystemsForPostcode("94043") // → ["us", "de", "fr"]
 candidateSystemsForPostcode("SW1A 1AA") // → ["gb"]
-
-// Address system conventions (forbidden tags, expected shapes, etc.)
-import { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem } from "@mailwoman/codex"
 ```
 
 Note the first answer. This is a **shape** test, not a gazetteer membership test, and
-returning all three is the correct answer rather than a hedge — the caller's country
-scope is what narrows it. Picking one locale here would be a guess wearing a fact's
-clothes.
+returning all three is the correct answer rather than a hedge — the caller's country scope is
+what narrows it. Picking one locale here would be a guess wearing a fact's clothes.
 
-## Postcode granularity: three tiers, each earned by measurement
+### Postcode granularity: three tiers, each earned by measurement
 
-One `postalcode` placetype covers systems that are not comparable. An Irish Eircode
-names a single address; an Australian postcode names a locality. Between them sit
-most of the world, and the distinction that changes an answer is narrower:
-**is this code finer than the locality that contains it?**
+One `postalcode` placetype covers systems that are not comparable. An Irish Eircode names a
+single address; an Australian postcode names a locality. Between them sit most of the world,
+and the distinction that changes an answer is narrower: **is this code finer than the locality
+that contains it?**
 
-That is a fact about a country's _administrative_ geography, not its postal system,
-and code length does not predict it. France and Germany are both five digits and land
-on opposite sides.
+That is a fact about a country's _administrative_ geography, not its postal system, and code
+length does not predict it. France and Germany are both five digits and land on opposite
+sides.
 
 ```ts
 import { isUnitGradePostcodeHit, areaPostcodeLeadsLocality } from "@mailwoman/codex"
@@ -88,54 +231,57 @@ areaPostcodeLeadsLocality("FR") // → false (one code postal often spans severa
 | **area, but still finer than the locality** (`AREA_POSTCODE_FINER_THAN_LOCALITY`) | DE                                | full-panel measurement: 5.84 km → 1.24 km p50, better on every percentile |
 | **area** (the default)                                                            | everything else                   | the locality-first convention                                             |
 
-Membership is earned by a measurement, never by a shape that looks tight. Canada is
-the case that shows why: its urban LDU is unit-grade, its **rural** LDU measures
-2.08 km against the locality's 929 m and is excluded — and Canada Post already marks
-the difference with a `0` in the second character, so the code says which before any
-lookup runs. The pooled Canadian number reads 0.10 km and looks like a uniform win;
-it is two populations, and a tier claim that averages two granularities is exactly
-what these tables exist to prevent.
+Membership is earned by a measurement, never by a shape that looks tight. Canada is the case
+that shows why: its urban LDU is unit-grade, its **rural** LDU measures 2.08 km against the
+locality's 929 m and is excluded — and Canada Post already marks the difference with a `0` in
+the second character, so the code says which before any lookup runs. The pooled Canadian
+number reads 0.10 km and looks like a uniform win; it is two populations, and a tier claim
+that averages two granularities is exactly what these tables exist to prevent.
+
+## What this package does not do
 
-`@mailwoman/resolver`'s `admin-winner` consumes both predicates, and so does the
-browser demo's pin ranking — one definition, because the two once disagreed and
-nothing noticed.
+It does not **parse**. Turning `"1600 Amphitheatre Pkwy, Mountain View CA"` into components is
+a sequence-labeling problem, and that is [`mailwoman`](https://www.npmjs.com/package/mailwoman)
+— a small transformer encoder, installed separately. It does not geocode either. This package
+is the inverse direction and the reference tables, and it stays dependency-free so a consumer
+who only wants to print an address does not pull a model down.
 
 ## Design
 
-- **Zero runtime dependencies.** Pure TypeScript data tables — no database, no I/O,
-  no network. Suitable for bundling into browser and edge environments.
-- **Branded types.** ZIP codes, postcodes, and abbreviations carry nominal types
-  so the type system catches locale mismatches at compile time.
-- **One definition.** The resolver, the decoder's convention masks, the
-  corpus synthesis layer, and the matcher all import from `@mailwoman/codex`.
+- **Zero runtime dependencies.** Pure TypeScript data and a small evaluator — no database, no
+  I/O, no network. Suitable for bundling into browser and edge environments.
+- **Branded types.** ZIP codes, postcodes and abbreviations carry nominal types, so the type
+  system catches locale mismatches at compile time.
+- **An absence is reported, never invented.** A country with no layout returns `""`; a
+  component the layout has no slot for is named in `unplaced`.
+- **One definition.** The parser, the resolver, the corpus synthesis layer and the matcher all
+  import these tables rather than each carrying a copy.
 
 ## The normative tier (codex vs the libpostal dictionaries)
 
-Mailwoman carries two closed-class vocabularies that overlap on purpose and must not
-be merged:
-
-- **Codex is normative.** USPS Pub-28 (and each system's equivalent) verbatim: the
-  canonical word, every _recognized_ variant, and the one _preferred_ abbreviation.
-  Its consumers are precision-shaped — corpus synthesis recipes, the eval harness's
-  invariance transforms, and formatting (rendering `N` vs `North` requires knowing
-  which form the authority prints).
-- **The libpostal dictionaries** (`core/data/libpostal/dictionaries/`, Pelias
-  lineage) **are descriptive**: everything people write, including forms no
-  authority recognizes (`en/directionals.txt` lists `lower`/`upper`/`central`).
-  Their consumers are recall-shaped — evidence-lexicon curation laws, street
-  decomposition for training gold, the street-morphology FST. See the README in
-  that directory for the full consumer map and the four-tier curated-data layering.
-
-Broadening codex with descriptive forms would corrupt formatting; narrowing the
-descriptive lists to normative forms would weaken the evidence guards. Different
-questions, different tables.
+Mailwoman carries two closed-class vocabularies that overlap on purpose and must not be
+merged:
+
+- **Codex is normative.** USPS Pub-28 (and each system's equivalent) verbatim: the canonical
+  word, every _recognized_ variant, and the one _preferred_ abbreviation. Its consumers are
+  precision-shaped — corpus synthesis recipes, the eval harness's invariance transforms, and
+  formatting (rendering `N` vs `North` requires knowing which form the authority prints).
+- **The libpostal dictionaries** (`core/data/libpostal/dictionaries/`, Pelias lineage) **are
+  descriptive**: everything people write, including forms no authority recognizes
+  (`en/directionals.txt` lists `lower`/`upper`/`central`). Their consumers are recall-shaped —
+  evidence-lexicon curation laws, street decomposition for training gold, the street-morphology
+  FST.
+
+Broadening codex with descriptive forms would corrupt formatting; narrowing the descriptive
+lists to normative forms would weaken the evidence guards. Different questions, different
+tables.
 
 ## Related
 
-- [`@mailwoman/core`](../core) — `ComponentTag` schema, pipeline infrastructure
-- [`@mailwoman/address-id`](../address-id) — uses codex for stable address primary keys
+- [`mailwoman`](https://www.npmjs.com/package/mailwoman) — the parser: free text → components
+- [`@mailwoman/record`](../record) — record schema and per-field normalizers for entity matching
+- [`@mailwoman/address-id`](../address-id) — stable address primary keys, built on these tables
 - [`@mailwoman/resolver`](../resolver) — consumes the granularity tiers to order a resolved tree
-- [Address system conventions](https://github.com/sister-software/mailwoman/blob/main/docs/engineering/reference/SCHEMA.mdx)
 
 ## License
 

package/lib/address/format.ts

@@ -0,0 +1,144 @@
+/**
+ * @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, 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
+}
+
+function separatorFor(country: string, opts: FormatAddressOptions): string {
+	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: ComponentDict, country: string, opts: FormatAddressOptions = {}): string {
+	return formatAddressRow(components, country, opts)?.raw ?? ""
+}
+
+/**
+ * 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 function formatAddressRow(
+	components: ComponentDict,
+	country: string,
+	opts: FormatAddressOptions = {}
+): AddressRow | null {
+	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: ComponentDict = {}
+
+	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: ComponentDict, raw: string): ComponentDict {
+	const haystack = raw.toLowerCase().replaceAll(/\s+/g, " ")
+	const out: ComponentDict = {}
+
+	for (const [tag, value] of Object.entries(components)) {
+		if (!value) continue
+
+		if (haystack.includes(value.toLowerCase().replaceAll(/\s+/g, " "))) {
+			out[tag as ComponentTag] = value
+		}
+	}
+
+	return out
+}

package/lib/address/key.ts

@@ -0,0 +1,134 @@
+/**
+ * @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"
+import type { ComponentTag } from "#component"
+
+/**
+ * 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",
+] as const satisfies readonly ComponentTag[]
+
+/**
+ * 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 function foldForKey(input: string, options: FoldForKeyOptions): string {
+	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: string): string {
+	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: ComponentDict, opts: CanonicalKeyOptions = {}): string {
+	const separator = opts.separator ?? "|"
+	const parts: string[] = []
+
+	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)
+}