@mailwoman/match 9.4.0 → 10.1.0

package/README.md

@@ -36,7 +36,7 @@ candidate pairs via cheap, high-recall keys:
 
 The `scorePair` function computes a match probability using:
 
-- **String comparators** — Jaro-Winkler similarity over names and addresses
+- **Text comparators** — Jaro-Winkler similarity over names and addresses
 - **Distance comparison** — great-circle distance bucketed into same-building /
   same-block / same-area / far
 - **Fellegi-Sunter weight model** — agreement-level log-likelihood ratios
@@ -92,4 +92,4 @@ withTermFrequency(model: FSModel, records: SourceRecord[]): FSModel
 
 ## License
 
-[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)
+[AGPL-3.0-only](https://www.gnu.org/licenses/AGPL-3.0.html)

package/lib/blocking.ts

@@ -3,46 +3,46 @@
  * @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
+ *   The blocking stage generates candidate pairs. An all-pairs comparison is O(n²): a million records require a trillion
+ *   comparisons. This stage scores 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
+ *   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.
+ *   cheap rules): block on the spatial cell, canonical key, or postcode. A pair caught by
+ *   any rule 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.
+ *   Recall is the priority. A pair the blocker never proposes can never match, the most dangerous
+ *   silent failure in record linkage. The spatial grid is generous and neighbor-expanded by
+ *   default. The code reports any block too large to scan instead of dropping it silently.
  */
 
-/**
- * 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[]
+import type { GeoCoordinate } from "@mailwoman/spatial"
 
 /**
- * A geographic coordinate (WGS84 decimal degrees).
+ * Maps a record to zero or more block keys.
+ *
+ * Two records sharing any key become a candidate pair.
  */
-export interface LatLon {
-	latitude: number
-	longitude: number
-}
+export type BlockingKey<R> = (record: R) => string[]
 
 /**
- * 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.
+ * 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.
+ * Note: an equal-_degree_ grid (longitude cells shrink toward the poles)
+ * and neighbor expansion inflates block sizes ~9×; an equal-area H3/geohash index
+ * with a single-cell + neighbor-query is the refinement.
+ * Behavior — proximity co-blocking — is the same.
  */
 export function geoCellKey<R>(
-	extract: (record: R) => LatLon | null | undefined,
+	extract: (record: R) => GeoCoordinate | null | undefined,
 	opts: { precisionDegrees?: number; neighbors?: boolean } = {}
 ): BlockingKey<R> {
 	const step = opts.precisionDegrees ?? 0.05
@@ -71,9 +71,10 @@ export function geoCellKey<R>(
 }
 
 /**
- * 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.
+ * 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,
@@ -94,9 +95,12 @@ export function exactKey<R>(
 }
 
 /**
- * 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.
+ * 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) => {
@@ -118,7 +122,7 @@ export function conjunction<R>(...keys: BlockingKey<R>[]): BlockingKey<R> {
  */
 export interface BlockResult<R> {
 	/**
-	 * Deduplicated candidate pairs (no self-pairs; a pair caught by multiple keys appears once).
+	 * Deduplicated candidate pairs (no self-pairs. A pair caught by multiple keys appears once).
 	 */
 	pairs: Array<[R, R]>
 	/**
@@ -128,10 +132,11 @@ export interface BlockResult<R> {
 }
 
 /**
- * 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.
+ * 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 rather than a silent drop.
  */
 export function block<R>(
 	records: readonly R[],

package/lib/clustering.ts

@@ -3,10 +3,10 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Clustering — the third and final matcher stage: resolve scored pairs into canonical entities.
+ *   The clustering stage resolves 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
+ *   The pairwise scorer treats each pair independently. Its scores are not transitive: A~B at a
+ *   high weight and B~C at a high weight do not guarantee that A~C is a match. A separate stage is
  *   required to turn the graph of above-threshold links into coherent groups — skip it and your
  *   "entities" silently fracture or fuse.
  *
@@ -15,7 +15,7 @@
  *   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 version. For a geocode-first matcher the
+ *   score matrix — a documented refinement rather than this first version. 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.
  */
@@ -40,25 +40,32 @@ export interface ClusterOptions {
 	/**
 	 * 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}.
+	 * - `"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.
+	 * 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 boundate it on a
- * size cap.
+ * 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 boundate it on a size cap.
  */
 function averageLinkageRefine<R>(members: R[], edges: Array<[number, number, number]>, threshold: number): R[][] {
 	const clusters = members.map((_, i) => [i])
@@ -105,15 +112,20 @@ function averageLinkageRefine<R>(members: R[], edges: Array<[number, number, num
 }
 
 /**
- * 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.
+ * 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))
 
-	// Local by design: the shared union-find is `@mailwoman/core/utils/union-find`; match takes no core dependency (~11 MB).
+	// Local by design: the shared union-find is `@mailwoman/core/utils/union-find`;
+	// match takes no core dependency (~11 MB).
 	const parent = records.map((_, i) => i)
 	const rank = new Array<number>(records.length).fill(0)
 
@@ -151,9 +163,10 @@ export function cluster<R>(records: readonly R[], links: Iterable<ScoredLink<R>>
 		}
 	}
 
-	// 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.
+	// 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) {
@@ -184,7 +197,7 @@ export function cluster<R>(records: readonly R[], links: Iterable<ScoredLink<R>>
 	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).
+	// 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>()
 
@@ -222,9 +235,13 @@ export function cluster<R>(records: readonly R[], links: Iterable<ScoredLink<R>>
 }
 
 /**
- * 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).
+ * 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

package/lib/comparators.ts

@@ -3,25 +3,14 @@
  * @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.
+ *   Jaro-Winkler is the default record-linkage comparator for names. {@link nameSimilarity} adds
+ *   the literature's token/edit fallback because J-W scores a compound surname's second half near zero.
  */
 
 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.
+ * Jaro similarity in [0, 1], where two empty strings are identical (1) and one empty is 0.
  */
 export function jaro(a: string, b: string): number {
 	if (a === b) return 1
@@ -53,7 +42,6 @@ export function jaro(a: string, b: string): number {
 
 	if (matches === 0) return 0
 
-	// Count transpositions: matched chars of `a` and `b`, in order, that disagree (halved).
 	let transpositions = 0
 	let k = 0
 
@@ -77,9 +65,8 @@ export function jaro(a: string, b: string): number {
 }
 
 /**
- * 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.
+ * Jaro-Winkler similarity in [0, 1]: Jaro plus a shared-prefix bonus, boosting only when Jaro
+ * already clears the 0.7 threshold, with Winkler's standard prefix cap 4 and weight 0.1.
  */
 export function jaroWinkler(
 	a: string,
@@ -105,14 +92,8 @@ export function jaroWinkler(
 }
 
 /**
- * Jaccard similarity between two token sets in [0, 1]: `|a ∩ b| / |a ∪ b|`.
- *
- * The set-of-tokens complement to the string comparators above. Where {@link nameSimilarity} asks how close two names
- * LOOK, this asks how much two token bags OVERLAP — the right question for organization names and address bags, where
- * word order carries no information and a shared rare token is worth more than character-level proximity.
- *
- * Either side empty scores 0 rather than 1: an empty bag agrees with nothing, and treating "no evidence" as "perfect
- * agreement" is how a blocking pass floods with false pairs.
+ * Jaccard similarity `|a ∩ b| / |a ∪ b|` over two token sets, where an empty side scores 0 rather than 1
+ * because treating no evidence as perfect agreement floods a blocking pass with false pairs.
  */
 export function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number {
 	if (!a.size || !b.size) return 0
@@ -140,15 +121,11 @@ export function levenshteinSimilarity(a: string, b: string): number {
 }
 
 /**
- * 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.
+ * Name-aware similarity in [0, 1] that floors the score at 0.9 when one name's
+ * tokens are a strict subset of the other's.
  *
- * Case- and whitespace-insensitive. Empty input scores 0.
+ * In other cases, it returns the better of Jaro-Winkler and normalized edit
+ * similarity without case or whitespace sensitivity.
  */
 export function nameSimilarity(a: string, b: string): number {
 	const x = a.trim().toLowerCase().replaceAll(/\s+/g, " ")

package/lib/distance.ts

@@ -2,46 +2,31 @@
  * @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 { haversineKm as greatCircleKm, type GeoCoordinate } from "@mailwoman/spatial"
 
-import type { LatLon } from "#blocking"
 import type { Comparison, ComparisonLevel } from "#fellegi-sunter"
 
 /**
- * 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.
+ * Computes the great-circle distance in kilometers between two `GeoCoordinate` records.
+ * It delegates to the scalar helper in `@mailwoman/spatial`.
  */
-export const haversineKm = (a: LatLon, b: LatLon): number =>
+export const haversineKm = (a: GeoCoordinate, b: GeoCoordinate): 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.
+ * Creates a comparison that buckets the great-circle distance between two records into
+ * levels ordered nearest first by `maxKm`, with the last level catching everything farther.
+ *
+ * A missing or non-finite coordinate on either side yields no evidence.
  */
 export function distanceComparison<R>(config: {
 	name: string
-	extract: (record: R) => LatLon | null | undefined
+	extract: (record: R) => GeoCoordinate | null | undefined
 	levels: ComparisonLevel[]
 }): Comparison<R> {
-	const valid = (c: LatLon | null | undefined): c is LatLon =>
+	const valid = (c: GeoCoordinate | null | undefined): c is GeoCoordinate =>
 		!!c && Number.isFinite(c.latitude) && Number.isFinite(c.longitude)
 
 	return {
@@ -65,8 +50,8 @@ export function distanceComparison<R>(config: {
 }
 
 /**
- * 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.
+ * Provides default distance levels at building, block and area scales.
+ * Their `m` and `u` values seed EM re-estimation.
  */
 export const DEFAULT_DISTANCE_LEVELS: ComparisonLevel[] = [
 	{ label: "same-building", maxKm: 0.05, m: 0.7, u: 0.001 },
@@ -76,30 +61,19 @@ export const DEFAULT_DISTANCE_LEVELS: ComparisonLevel[] = [
 ]
 
 /**
- * The collapsed spatial-agreement comparison — ONE non-redundant geographic signal.
+ * Creates a single spatial comparison whose level 0 is an exact canonical-key match
+ * and whose remaining levels bucket great-circle distance for pairs with different keys.
  *
- * 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`).
+ * Separate key and distance comparisons count a co-located pair's evidence twice.
+ * They also over-merge distinct entities at a shared address.
  */
 export function spatialComparison<R>(config: {
 	name: string
 	key: (record: R) => string | null | undefined
-	coordinate: (record: R) => LatLon | null | undefined
+	coordinate: (record: R) => GeoCoordinate | null | undefined
 	levels: ComparisonLevel[]
 }): Comparison<R> {
-	const valid = (c: LatLon | null | undefined): c is LatLon =>
+	const valid = (c: GeoCoordinate | null | undefined): c is GeoCoordinate =>
 		!!c && Number.isFinite(c.latitude) && Number.isFinite(c.longitude)
 
 	return {
@@ -109,12 +83,12 @@ export function spatialComparison<R>(config: {
 			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
+			if (ka && kb && ka.trim() && ka === kb) return 0
 
 			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
+			if (!valid(ca) || !valid(cb)) return -1
 
 			const km = haversineKm(ca, cb)
 
@@ -128,8 +102,8 @@ export function spatialComparison<R>(config: {
 }
 
 /**
- * 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).
+ * Provides default levels for {@link spatialComparison}: an exact same-key tier followed
+ * by the building, block, area and far distance buckets, with seed `m` and `u` values.
  */
 export const DEFAULT_SPATIAL_LEVELS: ComparisonLevel[] = [
 	{ label: "same-key", m: 0.85, u: 0.01 },

package/lib/em.ts

@@ -41,15 +41,21 @@ export function agreementPattern<R>(comparisons: Comparison<R>[], a: R, b: R): n
  */
 export interface EmOptions {
 	/**
-	 * Hard iteration cap. Default 100.
+	 * Hard iteration cap.
+	 *
+	 * Default 100.
 	 */
 	maxIterations?: number
 	/**
-	 * Convergence tolerance on the largest parameter change between iterations. Default 1e-6.
+	 * Convergence tolerance on the largest parameter change between iterations.
+	 *
+	 * Default 1e-6.
 	 */
 	tolerance?: number
 	/**
-	 * Starting prior match rate. Defaults to the model's `lambda`.
+	 * Prior match rate used to initialize the model.
+	 *
+	 * Defaults to the model's `lambda`.
 	 */
 	initialLambda?: number
 }
@@ -71,9 +77,11 @@ export interface EmResult<R> {
 }
 
 /**
- * Estimate `m`/`u` and the prior `λ` from unlabeled agreement patterns via EM. The patterns are per-comparison level
- * indices (as produced by {@link agreementPattern}); a `-1` (missing) field contributes no evidence to either class. The
- * model's existing level `m`/`u` seed the iteration.
+ * Estimate `m`/`u` and the prior `λ` from unlabeled agreement patterns via EM.
+ *
+ * The patterns are per-comparison level indices (as produced by {@link agreementPattern});
+ * a `-1` (missing) field contributes no evidence to either class.
+ * The model's existing level `m`/`u` seed the iteration.
  */
 export function estimateParameters<R>(
 	model: FellegiSunterModel<R>,