@mailwoman/match 7.2.0 → 7.3.0

package/blocking.ts

@@ -0,0 +1,180 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Blocking — candidate generation. Comparing every pair is O(n²) (a million records is a trillion
+ *   comparisons), so we only score pairs that share a cheap key. This is where the geocode-first
+ *   bet pays off: two records resolving to the same place land in the same spatial cell regardless
+ *   of how their address strings are spelled, so geography is the primary block.
+ *
+ *   A {@link BlockingKey} maps a record to zero or more string keys; records sharing any key become
+ *   candidates. Keys compose as a _union_ (the standard multi-pass approach — high recall from
+ *   cheap rules): block on the spatial cell OR the canonical key OR the postcode, and a pair that
+ *   any rule catches is scored. {@link conjunction} builds the AND-style key Geo-ER uses (`name-cell
+ *   AND geo-cell`) when a single rule is too loose.
+ *
+ *   Recall is the priority — a pair the blocker never proposes can never match, the most dangerous
+ *   silent failure in record linkage. So the spatial grid is generous and neighbour-expanded by
+ *   default, and any block too large to scan is _reported_, never silently dropped.
+ */
+
+/** Maps a record to zero or more block keys. Two records sharing any key become a candidate pair. */
+export type BlockingKey<R> = (record: R) => string[]
+
+/** A geographic coordinate (WGS84 decimal degrees). */
+export interface LatLon {
+	latitude: number
+	longitude: number
+}
+
+/**
+ * A spatial-cell block key: a configurable lat/lon grid. `precisionDegrees` sets the cell size (default 0.05° ≈ 5.5 km
+ * of latitude — deliberately generous, per the literature, so same-place records reliably co-block). With `neighbors`
+ * (default `true`) a record also keys its 8 adjacent cells, so a pair straddling a cell boundary still meets.
+ *
+ * Note: an equal-_degree_ grid (longitude cells shrink toward the poles) and neighbour expansion inflates block sizes
+ * ~9×; an equal-area H3/geohash index with a single-cell + neighbour-query is the refinement. Behaviour — proximity
+ * co-blocking — is the same.
+ */
+export function geoCellKey<R>(
+	extract: (record: R) => LatLon | null | undefined,
+	opts: { precisionDegrees?: number; neighbors?: boolean } = {}
+): BlockingKey<R> {
+	const step = opts.precisionDegrees ?? 0.05
+	const expand = opts.neighbors ?? true
+
+	return (record) => {
+		const coordinate = extract(record)
+
+		if (!coordinate || !Number.isFinite(coordinate.latitude) || !Number.isFinite(coordinate.longitude)) return []
+
+		const latCell = Math.floor(coordinate.latitude / step)
+		const lonCell = Math.floor(coordinate.longitude / step)
+
+		if (!expand) return [`${latCell}:${lonCell}`]
+
+		const keys: string[] = []
+
+		for (let dLat = -1; dLat <= 1; dLat++) {
+			for (let dLon = -1; dLon <= 1; dLon++) {
+				keys.push(`${latCell + dLat}:${lonCell + dLon}`)
+			}
+		}
+
+		return keys
+	}
+}
+
+/**
+ * An exact-value block key (the canonical address key, a postcode, an email domain…), normalized and optionally
+ * truncated to a leading `prefix` of characters (a cheaper, higher-recall rule). A missing or empty value produces no
+ * key.
+ */
+export function exactKey<R>(
+	extract: (record: R) => string | null | undefined,
+	opts: { prefix?: number; normalize?: (value: string) => string } = {}
+): BlockingKey<R> {
+	const normalize = opts.normalize ?? ((v: string) => v.trim().toLowerCase().replace(/\s+/g, " "))
+
+	return (record) => {
+		const value = extract(record)
+
+		if (!value) return []
+		const normalized = normalize(value)
+
+		if (!normalized) return []
+
+		return [opts.prefix ? normalized.slice(0, opts.prefix) : normalized]
+	}
+}
+
+/**
+ * A conjunctive block key — the cross-product of its sub-keys, joined (Geo-ER's "name AND distance"). A record is keyed
+ * by every combination of one sub-key from each input, so two records co-block only when they agree on _all_ inputs.
+ * Tighter blocks, lower recall — use when a single rule is too loose.
+ */
+export function conjunction<R>(...keys: BlockingKey<R>[]): BlockingKey<R> {
+	return (record) => {
+		let combos = [""]
+
+		for (const key of keys) {
+			const parts = key(record)
+
+			if (parts.length === 0) return []
+			combos = combos.flatMap((prefix) => parts.map((part) => (prefix ? `${prefix}&${part}` : part)))
+		}
+
+		return combos
+	}
+}
+
+/** The outcome of a blocking pass. */
+export interface BlockResult<R> {
+	/** Deduplicated candidate pairs (no self-pairs; a pair caught by multiple keys appears once). */
+	pairs: Array<[R, R]>
+	/** Blocks that exceeded `maxBlockSize` and were skipped — surfaced so coverage limits are visible. */
+	droppedBlocks: Array<{ key: string; size: number }>
+}
+
+/**
+ * Generate candidate pairs from `records` via one or more blocking keys (their union). Builds an inverted index (key →
+ * records) and emits the unique within-block pairs. A block larger than `maxBlockSize` is skipped and reported in
+ * `droppedBlocks` rather than blowing up into a quadratic scan — an explicit, visible coverage limit, not a silent
+ * drop.
+ */
+export function block<R>(
+	records: readonly R[],
+	blockingKeys: BlockingKey<R> | BlockingKey<R>[],
+	opts: { maxBlockSize?: number } = {}
+): BlockResult<R> {
+	const keys = Array.isArray(blockingKeys) ? blockingKeys : [blockingKeys]
+	const maxBlockSize = opts.maxBlockSize ?? Infinity
+	const index = new Map<string, number[]>()
+
+	records.forEach((record, i) => {
+		const seen = new Set<string>()
+
+		for (const keyFn of keys) {
+			for (const key of keyFn(record)) {
+				if (!key || seen.has(key)) continue
+				seen.add(key)
+				const bucket = index.get(key)
+
+				if (bucket) {
+					bucket.push(i)
+				} else {
+					index.set(key, [i])
+				}
+			}
+		}
+	})
+
+	const n = records.length
+	const emitted = new Set<number>()
+	const pairs: Array<[R, R]> = []
+	const droppedBlocks: BlockResult<R>["droppedBlocks"] = []
+
+	for (const [key, bucket] of index) {
+		if (bucket.length < 2) continue
+
+		if (bucket.length > maxBlockSize) {
+			droppedBlocks.push({ key, size: bucket.length })
+			continue
+		}
+
+		for (let a = 0; a < bucket.length; a++) {
+			for (let b = a + 1; b < bucket.length; b++) {
+				const lo = Math.min(bucket[a]!, bucket[b]!)
+				const hi = Math.max(bucket[a]!, bucket[b]!)
+				const id = lo * n + hi
+
+				if (emitted.has(id)) continue
+				emitted.add(id)
+				pairs.push([records[lo]!, records[hi]!])
+			}
+		}
+	}
+
+	return { pairs, droppedBlocks }
+}

package/clustering.ts

@@ -0,0 +1,238 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Clustering — the third and final matcher stage: resolve scored pairs into canonical entities.
+ *
+ *   The pairwise scorer treats each pair independently, and its scores are NOT transitive: A~B at a
+ *   high weight and B~C at a high weight does not guarantee A~C is a match. So a distinct stage is
+ *   required to turn the graph of above-threshold links into coherent groups — skip it and your
+ *   "entities" silently fracture or fuse.
+ *
+ *   This ships the standard baseline: connected components of the link graph (union-find), with the
+ *   link threshold as the precision/recall knob — raise it for tighter, purer clusters, lower it
+ *   for more recall. Its known weakness is over-merging via transitive chains (a string of weak
+ *   links can pull unrelated records into one component); the principled fix is
+ *   centroid-/average-linkage hierarchical clustering (Dedupe), which uses the full within-cluster
+ *   score matrix — a documented refinement, not this first cut. For a geocode-first matcher the
+ *   over-merge risk is already damped: blocking keeps candidate sets local, so chains can't run
+ *   across the whole dataset.
+ */
+
+/** A scored candidate pair: two records and the match weight (bits) the scorer assigned them. */
+export interface ScoredLink<R> {
+	a: R
+	b: R
+	weight: number
+}
+
+/** Options for {@link cluster}. */
+export interface ClusterOptions {
+	/**
+	 * Link two records only when their match weight is at or above this (bits) — the precision/recall knob.
+	 */
+	threshold: number
+	/**
+	 * How the above-threshold link graph resolves into clusters:
+	 *
+	 * - `"single"` (default) — connected components (union-find). Fast; ANY above-threshold link fuses two groups, so a
+	 *   single weak link can over-merge unrelated records through a transitive chain.
+	 * - `"average"` — agglomerative average-linkage refinement WITHIN each connected component: two sub-clusters merge only
+	 *   when the AVERAGE weight of the links between them clears the threshold, so a lone weak bridge no longer fuses two
+	 *   otherwise-dense groups. The documented over-merge fix (Dedupe). Falls back to single-linkage for any component
+	 *   larger than {@link maxAverageLinkageComponent}.
+	 */
+	linkage?: "single" | "average"
+	/**
+	 * Components larger than this skip the O(k³) average-linkage refine and keep single-linkage. Default 64.
+	 */
+	maxAverageLinkageComponent?: number
+}
+
+/**
+ * Refine one connected component by agglomerative average-linkage. Starts with every member a singleton and repeatedly
+ * merges the cluster pair with the highest _average_ inter-cluster link weight while that average is at or above
+ * `threshold`; clusters with no link between them never merge. O(k³) in the component size, so callers gate it on a
+ * size cap.
+ */
+function averageLinkageRefine<R>(members: R[], edges: Array<[number, number, number]>, threshold: number): R[][] {
+	const clusters = members.map((_, i) => [i])
+	const crossAverage = (a: number[], b: number[]): number | null => {
+		const inA = new Set(a)
+		const inB = new Set(b)
+		let sum = 0
+		let count = 0
+
+		for (const [i, j, w] of edges) {
+			if ((inA.has(i) && inB.has(j)) || (inA.has(j) && inB.has(i))) {
+				sum += w
+				count++
+			}
+		}
+
+		return count > 0 ? sum / count : null
+	}
+
+	for (;;) {
+		let bestAvg = -Infinity
+		let bestPair: [number, number] | null = null
+
+		for (let p = 0; p < clusters.length; p++) {
+			for (let q = p + 1; q < clusters.length; q++) {
+				const avg = crossAverage(clusters[p]!, clusters[q]!)
+
+				if (avg !== null && avg > bestAvg) {
+					bestAvg = avg
+					bestPair = [p, q]
+				}
+			}
+		}
+
+		if (!bestPair || bestAvg < threshold) break
+		const [p, q] = bestPair
+		clusters[p] = clusters[p]!.concat(clusters[q]!)
+		clusters.splice(q, 1)
+	}
+
+	return clusters.map((local) => local.map((i) => members[i]!))
+}
+
+/**
+ * Cluster records into canonical entities by connected components of the above-threshold link graph. Every input record
+ * lands in exactly one cluster — a record with no qualifying link is a singleton. Links referencing a record not in
+ * `records` are ignored. Reference identity is used, so pass the same record objects to both arguments.
+ */
+export function cluster<R>(records: readonly R[], links: Iterable<ScoredLink<R>>, opts: ClusterOptions): R[][] {
+	const index = new Map<R, number>()
+	records.forEach((record, i) => index.set(record, i))
+
+	const parent = records.map((_, i) => i)
+	const rank = new Array<number>(records.length).fill(0)
+
+	const find = (x: number): number => {
+		let root = x
+
+		while (parent[root] !== root) {
+			root = parent[root]!
+		}
+
+		// Path compression.
+		while (parent[x] !== root) {
+			const next = parent[x]!
+			parent[x] = root
+			x = next
+		}
+
+		return root
+	}
+
+	const union = (x: number, y: number): void => {
+		const rx = find(x)
+		const ry = find(y)
+
+		if (rx === ry) return
+
+		if (rank[rx]! < rank[ry]!) {
+			parent[rx] = ry
+		} else if (rank[rx]! > rank[ry]!) {
+			parent[ry] = rx
+		} else {
+			parent[ry] = rx
+			rank[rx]!++
+		}
+	}
+
+	// Collect ALL valid links (not just above-threshold): connected components form from the
+	// above-threshold ones, but the average-linkage refinement needs the full sub-graph — a weak or
+	// disagreeing below-threshold edge between two sub-clusters is exactly what should pull them apart.
+	const allLinks: ScoredLink<R>[] = []
+
+	for (const link of links) {
+		const ia = index.get(link.a)
+		const ib = index.get(link.b)
+
+		if (ia === undefined || ib === undefined) continue
+		allLinks.push(link)
+
+		if (link.weight >= opts.threshold) {
+			union(ia, ib)
+		}
+	}
+
+	const groups = new Map<number, R[]>()
+	records.forEach((record, i) => {
+		const root = find(i)
+		const group = groups.get(root)
+
+		if (group) {
+			group.push(record)
+		} else {
+			groups.set(root, [record])
+		}
+	})
+
+	if (opts.linkage !== "average") return [...groups.values()]
+
+	// Average-linkage refinement: split each component where its sub-clusters are joined only by a weak
+	// bridge (the average inter-cluster link weight, over ALL edges between them, falls below the threshold).
+	const maxComponent = opts.maxAverageLinkageComponent ?? 64
+	const localOf = new Map<R, number>()
+
+	// member → its index within its own group
+	for (const members of groups.values()) {
+		members.forEach((m, i) => localOf.set(m, i))
+	}
+	const groupEdges = new Map<number, Array<[number, number, number]>>()
+
+	for (const link of allLinks) {
+		const root = find(index.get(link.a)!)
+
+		if (root !== find(index.get(link.b)!)) continue // cross-component edge — not part of any refinement
+		const list = groupEdges.get(root) ?? []
+		list.push([localOf.get(link.a)!, localOf.get(link.b)!, link.weight])
+		groupEdges.set(root, list)
+	}
+
+	const result: R[][] = []
+
+	for (const [root, members] of groups) {
+		if (members.length <= 1 || members.length > maxComponent) {
+			result.push(members)
+			continue
+		}
+
+		for (const sub of averageLinkageRefine(members, groupEdges.get(root) ?? [], opts.threshold)) {
+			result.push(sub)
+		}
+	}
+
+	return result
+}
+
+/**
+ * Pick a cluster's most complete record as its canonical representative — the one with the fewest empty fields (`null`
+ * / `undefined` / `""`). Ties keep the earliest. A basic, generic canonicalizer; field-level merging across the cluster
+ * is the application's job (it knows which source to trust).
+ */
+export function representative<R extends object>(group: readonly R[]): R | undefined {
+	let best: R | undefined
+	let bestFilled = -1
+
+	for (const record of group) {
+		let filled = 0
+
+		for (const value of Object.values(record)) {
+			if (value !== null && value !== undefined && value !== "") {
+				filled++
+			}
+		}
+
+		if (filled > bestFilled) {
+			bestFilled = filled
+			best = record
+		}
+	}
+
+	return best
+}

package/comparators.ts

@@ -0,0 +1,142 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   String comparators for the matcher's scoring stage.
+ *
+ *   The record-linkage literature (Winkler/Census; Belin 1993) settles on the prefix-weighted Jaro
+ *   comparator (Jaro-Winkler) as the default for names: it tolerates the typographical error real
+ *   data is full of better than raw character-edit distance. But J-W has a documented blind spot on
+ *   compound / double surnames (e.g. Hispanic `Garcia Lopez`): the second half of the compound
+ *   falls outside J-W's match window, so `Lopez` vs `Garcia Lopez` scores ~0. The fix the
+ *   literature prescribes is an edit-distance / token fallback for single-vs-compound pairs —
+ *   implemented in {@link nameSimilarity}.
+ *
+ *   These are pure similarity primitives in [0, 1]. The mapping of a similarity onto discrete
+ *   Fellegi-Sunter agreement levels (and the m/u weights) is the scorer's job, not theirs.
+ */
+
+import { distance as levenshteinDistance } from "fastest-levenshtein"
+
+/**
+ * Jaro similarity in [0, 1]. Two empty strings are identical (1); one empty is 0. Counts matching characters within a
+ * sliding window of `floor(max(len)/2) - 1`, discounting half-transpositions.
+ */
+export function jaro(a: string, b: string): number {
+	if (a === b) return 1
+	const la = a.length
+	const lb = b.length
+
+	if (la === 0 || lb === 0) return 0
+
+	const window = Math.max(0, Math.floor(Math.max(la, lb) / 2) - 1)
+	const aMatched = new Array<boolean>(la).fill(false)
+	const bMatched = new Array<boolean>(lb).fill(false)
+
+	let matches = 0
+
+	for (let i = 0; i < la; i++) {
+		const start = Math.max(0, i - window)
+		const end = Math.min(i + window + 1, lb)
+
+		for (let j = start; j < end; j++) {
+			if (bMatched[j] || a[i] !== b[j]) continue
+			aMatched[i] = true
+			bMatched[j] = true
+			matches++
+			break
+		}
+	}
+
+	if (matches === 0) return 0
+
+	// Count transpositions: matched chars of `a` and `b`, in order, that disagree (halved).
+	let transpositions = 0
+	let k = 0
+
+	for (let i = 0; i < la; i++) {
+		if (!aMatched[i]) continue
+
+		while (!bMatched[k]) {
+			k++
+		}
+
+		if (a[i] !== b[k]) {
+			transpositions++
+		}
+		k++
+	}
+	transpositions /= 2
+
+	return (matches / la + matches / lb + (matches - transpositions) / matches) / 3
+}
+
+/**
+ * Jaro-Winkler similarity in [0, 1]: Jaro with a bonus for a shared prefix — `jw = jaro + prefix * weight * (1 -
+ * jaro)`, prefix capped at `maxPrefix` (Winkler's standard 4), `weight` the scaling factor (standard 0.1). Only boosts
+ * when `jaro` already clears `boostThreshold` (0.7), per Winkler.
+ */
+export function jaroWinkler(
+	a: string,
+	b: string,
+	opts: { weight?: number; maxPrefix?: number; boostThreshold?: number } = {}
+): number {
+	const weight = opts.weight ?? 0.1
+	const maxPrefix = opts.maxPrefix ?? 4
+	const boostThreshold = opts.boostThreshold ?? 0.7
+
+	const base = jaro(a, b)
+
+	if (base < boostThreshold) return base
+
+	let prefix = 0
+	const limit = Math.min(maxPrefix, a.length, b.length)
+
+	while (prefix < limit && a[prefix] === b[prefix]) {
+		prefix++
+	}
+
+	return base + prefix * weight * (1 - base)
+}
+
+/** Normalized Levenshtein similarity in [0, 1]: `1 - editDistance / max(len)`. */
+export function levenshteinSimilarity(a: string, b: string): number {
+	if (a === b) return 1
+	const longest = Math.max(a.length, b.length)
+
+	if (longest === 0) return 1
+
+	return 1 - levenshteinDistance(a, b) / longest
+}
+
+/**
+ * Name-aware similarity in [0, 1]. Jaro-Winkler by default, with the compound-surname fallback the literature
+ * prescribes:
+ *
+ * - If one name's tokens are a strict subset of the other's (`Lopez` ⊂ `Garcia Lopez`), that is strong partial agreement
+ *   J-W misses — floor the score at 0.9.
+ * - Otherwise return the better of Jaro-Winkler and normalized edit similarity, so a single token that is a substring of
+ *   a longer compound (`Garcia` vs `Garcialopez`) still scores sensibly.
+ *
+ * Case- and whitespace-insensitive. Empty input scores 0.
+ */
+export function nameSimilarity(a: string, b: string): number {
+	const x = a.trim().toLowerCase().replace(/\s+/g, " ")
+	const y = b.trim().toLowerCase().replace(/\s+/g, " ")
+
+	if (!x || !y) return 0
+
+	if (x === y) return 1
+
+	const jw = jaroWinkler(x, y)
+
+	const xTokens = new Set(x.split(" "))
+	const yTokens = new Set(y.split(" "))
+	const [small, big] = xTokens.size <= yTokens.size ? [xTokens, yTokens] : [yTokens, xTokens]
+	const subset = small.size < big.size && [...small].every((t) => big.has(t))
+
+	if (subset) return Math.max(jw, 0.9)
+
+	return Math.max(jw, levenshteinSimilarity(x, y))
+}

package/distance.ts

@@ -0,0 +1,140 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Geographic distance as a scoring feature — the other half of geocode-first matching.
+ *
+ *   Blocking uses geography to _propose_ candidates; this scores them on it. The research is explicit
+ *   that an address must be matched as a SPATIAL attribute, not by string similarity (a
+ *   one-character edit can be 650 m apart), and that distance measurably helps as a comparison
+ *   feature. So we bucket the great-circle distance between two records' coordinates into ordered
+ *   Fellegi-Sunter agreement levels (Splink's `DistanceInKMAtThresholds`): "same building" / "same
+ *   block" / "same area" / far, each with its own m/u and weight.
+ *
+ *   Calibrate the bucket boundaries to the geocoder's OWN error, which is heavy-tailed and density-
+ *   dependent (≈38 m urban, ≈200 m rural). A weakening of this evidence by geocode quality (a
+ *   shared interpolated centroid is softer than a shared rooftop point) is the documented
+ *   refinement.
+ */
+
+import { haversineKm as greatCircleKm } from "@mailwoman/spatial"
+
+import type { LatLon } from "./blocking.ts"
+import type { Comparison, ComparisonLevel } from "./fellegi-sunter.ts"
+
+/**
+ * Great-circle (haversine) distance in km between two coordinates. The formula's one true home is `@mailwoman/spatial`;
+ * this is a thin domain-typed adapter from `match`'s `LatLon` ({ latitude, longitude }) onto the canonical scalar
+ * helper — not a second implementation.
+ */
+export const haversineKm = (a: LatLon, b: LatLon): number =>
+	greatCircleKm(a.latitude, a.longitude, b.latitude, b.longitude)
+
+/**
+ * A geo-distance comparison: bucket the great-circle distance between two records' coordinates into ordered agreement
+ * levels. Levels must be ordered NEAREST first by `maxKm`, the last acting as the `far` catch-all (`maxKm` omitted →
+ * unbounded). A missing/invalid coordinate on either side yields no evidence.
+ */
+export function distanceComparison<R>(config: {
+	name: string
+	extract: (record: R) => LatLon | null | undefined
+	levels: ComparisonLevel[]
+}): Comparison<R> {
+	const valid = (c: LatLon | null | undefined): c is LatLon =>
+		!!c && Number.isFinite(c.latitude) && Number.isFinite(c.longitude)
+
+	return {
+		name: config.name,
+		levels: config.levels,
+		assess(a, b) {
+			const ca = config.extract(a)
+			const cb = config.extract(b)
+
+			if (!valid(ca) || !valid(cb)) return -1
+
+			const km = haversineKm(ca, cb)
+
+			for (let i = 0; i < config.levels.length; i++) {
+				if (km <= (config.levels[i]!.maxKm ?? Infinity)) return i
+			}
+
+			return config.levels.length - 1
+		},
+	}
+}
+
+/**
+ * Default distance levels, nearest → far, with boundaries at rooftop / block / locality scale. The m/u are illustrative
+ * seeds (EM re-estimates them); the boundaries reflect typical geocoder error.
+ */
+export const DEFAULT_DISTANCE_LEVELS: ComparisonLevel[] = [
+	{ label: "same-building", maxKm: 0.05, m: 0.7, u: 0.001 },
+	{ label: "same-block", maxKm: 0.5, m: 0.2, u: 0.02 },
+	{ label: "same-area", maxKm: 5, m: 0.08, u: 0.2 },
+	{ label: "far", m: 0.02, u: 0.779 },
+]
+
+/**
+ * The collapsed spatial-agreement comparison — ONE non-redundant geographic signal.
+ *
+ * The first matcher carried TWO spatial comparisons: canonical-address-key similarity AND great-circle distance. They
+ * double-count — an exact key match implies distance ≈ 0, so a co-located pair banked the same evidence twice, and the
+ * redundant vote is exactly what over-merges distinct providers at a shared clinic address. This folds them into one
+ * comparison:
+ *
+ * - **level 0 `same-key`** — an EXACT canonical-key match: the strongest tier, and the one the inverse-address-frequency
+ *   adjustment rides ({@link withTermFrequency} on level 0), so agreement on a crowded shared key is down-weighted
+ *   toward worthless while a rare one keeps full weight.
+ * - **levels 1…n** — great-circle distance buckets for pairs whose keys DIFFER, so "123 Main St" vs "123 Main Street Apt
+ *   2" that geocode to the same rooftop still earns near-agreement (the geo-first point of the whole design).
+ * - Keys differ and no usable coordinate → no evidence.
+ *
+ * Exactly one spatial vote, no redundancy. Pass {@link DEFAULT_SPATIAL_LEVELS} or your own; index 0 must be the
+ * exact-key tier, indices 1…n the distance buckets nearest → far by `maxKm` (last = `far`).
+ */
+export function spatialComparison<R>(config: {
+	name: string
+	key: (record: R) => string | null | undefined
+	coordinate: (record: R) => LatLon | null | undefined
+	levels: ComparisonLevel[]
+}): Comparison<R> {
+	const valid = (c: LatLon | null | undefined): c is LatLon =>
+		!!c && Number.isFinite(c.latitude) && Number.isFinite(c.longitude)
+
+	return {
+		name: config.name,
+		levels: config.levels,
+		assess(a, b) {
+			const ka = config.key(a)
+			const kb = config.key(b)
+
+			if (ka && kb && ka.trim() && ka === kb) return 0 // exact canonical-key match — one strong vote
+
+			const ca = config.coordinate(a)
+			const cb = config.coordinate(b)
+
+			if (!valid(ca) || !valid(cb)) return -1 // keys differ and no coordinate → no spatial evidence
+
+			const km = haversineKm(ca, cb)
+
+			for (let i = 1; i < config.levels.length; i++) {
+				if (km <= (config.levels[i]!.maxKm ?? Infinity)) return i
+			}
+
+			return config.levels.length - 1
+		},
+	}
+}
+
+/**
+ * Default levels for {@link spatialComparison}: an exact same-key tier on top of the distance buckets. `m`/`u` are
+ * EM-estimable seeds (m decreasing, u increasing down the tiers; each column ≈ sums to 1).
+ */
+export const DEFAULT_SPATIAL_LEVELS: ComparisonLevel[] = [
+	{ label: "same-key", m: 0.85, u: 0.01 },
+	{ label: "same-building", maxKm: 0.05, m: 0.1, u: 0.02 },
+	{ label: "same-block", maxKm: 0.5, m: 0.03, u: 0.05 },
+	{ label: "same-area", maxKm: 5, m: 0.015, u: 0.2 },
+	{ label: "far", m: 0.005, u: 0.72 },
+]