@mailwoman/corpus 10.1.0 → 10.2.1

package/lib/types.ts

@@ -195,7 +195,7 @@ export interface SourceProvenance {
 	/**
 	 * The license label or SPDX id for this row.
 	 *
-	 * It defaults to the adapter's `defaultLicense`, and sources with per-record terms override it.
+	 * @defaultValue the adapter's `defaultLicense`, and sources with per-record terms override it.
 	 */
 	license: string
 }
@@ -382,8 +382,9 @@ export interface AdapterOptions {
 	 *
 	 * The runner writes the map into `MANIFEST.json` as `dropped`, so the gap between a
 	 * source's record count and the rows written has a counted reason.
-	 * An adapter that does not count leaves the map empty, which the manifest records
-	 * as an empty object rather than as zero drops of any named kind.
+	 * An adapter that does not count leaves the map empty.
+	 *
+	 * The manifest records that as an empty object rather than as zero drops of a specific kind.
 	 */
 	dropped?: Map<string, number>
 }

package/lib/us/adapters/state/hi-schools/workbook.ts

@@ -35,6 +35,6 @@ export interface HiSchoolRow {
 /**
  * Convert a typed workbook cell or legacy CSV field to the trimmed text used by the corpus row.
  */
-export function schoolCellText(value: XLSXCellValue | undefined): string {
+export function schoolCellText(value: XLSXCellValue | null | undefined): string {
 	return value === null || value === undefined ? "" : String(value).trim()
 }

package/lib/us/adapters/usgov/nad/adapter.ts

@@ -76,14 +76,14 @@ interface NADRecord {
  */
 const US_STATES_SET: ReadonlySet<string> = new Set(US_STATE_ABBREVIATIONS)
 
-function nonEmpty(...values: Array<string | null | undefined>): string | undefined {
+function nonEmpty(...values: Array<string | null | undefined>): string | null {
 	for (const v of values) {
 		const trimmed = (v ?? "").toString().trim()
 
 		if (trimmed) return trimmed
 	}
 
-	return undefined
+	return null
 }
 
 /**
@@ -94,17 +94,17 @@ function nonEmpty(...values: Array<string | null | undefined>): string | undefin
  * The shared `composeHouseNumber` in `#adapters/street-line` joins exactly two columns with
  * one separator, so it fits a publisher that splits the number in two rather than in four.
  */
-function nadHouseNumber(r: NADRecord): string | undefined {
+function nadHouseNumber(r: NADRecord): string | null {
 	const full = (r.AddNo_Full ?? "").toString().trim()
 
 	if (full) return full
 	const num = r.Add_Number == null ? "" : String(r.Add_Number).trim()
 
-	if (!num) return undefined
+	if (!num) return null
 	const pre = (r.AddNum_Pre ?? "").toString().trim()
 	const suf = (r.AddNum_Suf ?? "").toString().trim()
 
-	return [pre, num, suf].filter(isPresent).join(" ").trim() || undefined
+	return [pre, num, suf].filter(isPresent).join(" ").trim() || null
 }
 
 interface DecomposedNADStreet {
@@ -116,7 +116,7 @@ interface DecomposedNADStreet {
 
 // Structured street fields take precedence.
 // If they are empty, `StNam_Full` supplies the whole street.
-function decomposeNADStreet(r: NADRecord): DecomposedNADStreet | undefined {
+function decomposeNADStreet(r: NADRecord): DecomposedNADStreet | null {
 	const name = (r.St_Name ?? "").toString().trim()
 
 	if (name) {
@@ -136,18 +136,18 @@ function decomposeNADStreet(r: NADRecord): DecomposedNADStreet | undefined {
 
 	if (full) return { full, street: full }
 
-	return undefined
+	return null
 }
 
 // The postal city comes first because it is the name that people write on mail.
-function composeLocality(r: NADRecord): string | undefined {
+function composeLocality(r: NADRecord): string | null {
 	return nonEmpty(r.Post_City, r.Inc_Muni, r.Census_Plc, r.Uninc_Comm)
 }
 
-function composePostcode(r: NADRecord): string | undefined {
+function composePostcode(r: NADRecord): string | null {
 	const zip = (r.Zip_Code ?? "").toString().trim()
 
-	if (!zip) return undefined
+	if (!zip) return null
 	const plus4 = (r.Plus_4 ?? "").toString().trim()
 
 	return plus4 ? `${zip}-${plus4}` : zip
@@ -196,7 +196,7 @@ export function createUsgovNADAdapter(): CorpusAdapter {
 
 					const record = tryParsingJSON<NADRecord>(line)
 
-					if (record === null) continue
+					if (!record) continue
 
 					const state = (record.State ?? "").toString().trim().toUpperCase()
 

package/lib/us/adapters/usgov/samhsa-treatment-locator/adapter.ts

@@ -78,7 +78,7 @@ interface SamhsaSiteRow {
  * The combined value is the `street` component surface form.
  * Phase 1 does not break this out into the `unit` component — see the file-level comment.
  */
-function joinTwoLineStreet(street1: string, street2: string | undefined): string {
+function joinTwoLineStreet(street1: string, street2: string | null): string {
 	const s1 = street1.trim()
 	const s2 = (street2 ?? "").trim()
 
@@ -101,7 +101,7 @@ function joinTwoLineStreet(street1: string, street2: string | undefined): string
  * Both render together as `"<name1> - <name2>"` when both are present — geocoder users
  * typically type either form, so the model benefits from the joined surface.
  */
-function composeVenue(name1: string, name2: string | undefined): string {
+function composeVenue(name1: string, name2: string | null): string {
 	const n1 = name1.trim()
 	const n2 = (name2 ?? "").trim()
 
@@ -140,8 +140,8 @@ export function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter {
 
 				if (opts.limit !== undefined && emitted >= opts.limit) break
 
-				const venue = composeVenue(record.name1 ?? "", record.name2)
-				const street = joinTwoLineStreet(record.street1 ?? "", record.street2)
+				const venue = composeVenue(record.name1 ?? "", record.name2 ?? null)
+				const street = joinTwoLineStreet(record.street1 ?? "", record.street2 ?? null)
 				const split = splitStreetLine(street)
 				const city = record.city ?? ""
 				const stateAbbr = record.state ?? ""

package/lib/us/fips-state.ts

@@ -92,7 +92,7 @@ export const US_FIPS_STATE: Readonly<Record<string, USStateInfo>> = Object.freez
  *
  * @returns Null when the FIPS code isn't recognized.
  */
-export function lookupFipsState(statefp: string | null | undefined): USStateInfo | null {
+export function lookupFipsState(statefp: string | null): USStateInfo | null {
 	if (!statefp) return null
 
 	return US_FIPS_STATE[statefp] ?? null
@@ -115,7 +115,7 @@ export const US_STATE_BY_ABBREVIATION: Readonly<Record<string, USStateInfo>> = O
  * Case-folded.
  * Null for any value outside the 50 states + DC + the five primary territories.
  */
-export function lookupStateAbbreviation(abbreviation: string | null | undefined): USStateInfo | null {
+export function lookupStateAbbreviation(abbreviation: string | null): USStateInfo | null {
 	if (!abbreviation) return null
 
 	return US_STATE_BY_ABBREVIATION[abbreviation.toUpperCase()] ?? null

package/lib/{synthesizers → us/synthesizers}/intersection.ts

@@ -19,13 +19,10 @@
  *   US-idiomatic only (the harness intersection cases are US: "X & Y, City, ST ZIP").
  */
 
-/* oxlint-disable mailwoman/prefer-home -- the admin tails below are written as US templates because this synthesizer
-   refuses a non-US tuple outright (`if (base.country !== "US") return null`). A layout call would answer the same
-   string for the only country that reaches it. The function would read as though the file served more. */
-
 import type { DirectionalAbbreviation } from "@mailwoman/codex/us"
 import { sample } from "@mailwoman/core/random"
 
+import { layoutAdminTail } from "#synthesizers/tail"
 import type { CanonicalRow } from "#types"
 
 /**
@@ -156,6 +153,9 @@ export function synthesizeIntersectionRow(
 ): SynthesizedIntersectionRow | null {
 	const random = opts.random ?? Math.random
 
+	// The junction connectors and the street vocabulary are US English,
+	// which is why this synthesizer sits under `us/`.
+	// The admin tail renders through the country's layout.
 	if (base.country !== "US") return null
 
 	const a = buildStreetName(random)
@@ -187,17 +187,16 @@ export function synthesizeIntersectionRow(
 	} else {
 		const includePostcode = base.postcode != null && random() < 0.7
 
-		const tail = includePostcode
-			? `, ${base.locality}, ${base.region} ${base.postcode}`
-			: `, ${base.locality}, ${base.region}`
+		const tail = layoutAdminTail(base.country, {
+			locality: base.locality,
+			region: base.region,
+			postcode: includePostcode ? base.postcode : undefined,
+		})
 
-		raw = `${cornerPrefix}${a}${connector}${b}${tail}`
-		components.locality = base.locality
-		components.region = base.region
+		if (!tail) return null
 
-		if (includePostcode) {
-			components.postcode = base.postcode
-		}
+		raw = `${cornerPrefix}${a}${connector}${b}, ${tail.raw}`
+		Object.assign(components, tail.components)
 	}
 
 	return { raw, components, locale: "en-US" }

package/lib/{synthesizers → us/synthesizers}/street.ts

@@ -19,13 +19,10 @@
  *   adapter.
  */
 
-/* oxlint-disable mailwoman/prefer-home -- the admin tails below are written as US templates because this synthesizer
-   refuses a non-US tuple outright (`if (base.country !== "US") return null`). A layout call would answer the same
-   string for the only country that reaches it. The function would read as though the file served more. */
-
 import { isPresent } from "@mailwoman/core/objects"
 import { sample } from "@mailwoman/core/random"
 
+import { layoutAdminTail } from "#synthesizers/tail"
 import { tieredNumber } from "#synthesizers/utils"
 import type { CanonicalRow } from "#types"
 import { decomposeStreet } from "#us/adapters/tiger/street-decompose"
@@ -182,17 +179,18 @@ export interface StreetSynthesisOpts {
 	/**
 	 * Probability of emitting house_number alongside the street.
 	 *
-	 * Default 0.85.
+	 * @defaultValue `0.85`
 	 */
 	includeHouseNumberProb?: number
 	/**
 	 * Probability of emitting the street bare — no `, City, ST ZIP` tail and no region/locality/
 	 * postcode components (just `street_prefix`/`street`/`street_suffix` + optional `house_number`).
 	 *
-	 * Default 0 (leaves the original full-address output exactly as it was, including the RNG sequence).
 	 * Set >0 to teach the model that a bare `10th Ave` / `Main St` is a street rather than a
 	 * locality — the functional-test failure cluster (bare streets mislabeled `locality`),
 	 * the bare-format analogue of the v0.7.x intersection-bare fix.
+	 *
+	 * @defaultValue `0` (leaves the original full-address output exactly as it was, including the RNG sequence)
 	 */
 	bareProb?: number
 }
@@ -223,6 +221,9 @@ export function synthesizeStreetRow(
 	const random = opts.random ?? Math.random
 	const includeHN = opts.includeHouseNumberProb ?? 0.85
 
+	// The street vocabulary (`STREET_NAMES`, `STREET_SUFFIXES`, the directionals) is
+	// US English, which is why this synthesizer sits under `us/`.
+	// The admin tail renders through the country's layout.
 	if (base.country !== "US") return null
 
 	const prefix = sample(DIRECTIONAL_PREFIXES, random)
@@ -247,13 +248,13 @@ export function synthesizeStreetRow(
 	const bareProb = opts.bareProb ?? 0
 	const bare = bareProb > 0 && random() < bareProb
 
-	const components: CanonicalRow["components"] = bare
-		? {}
-		: {
-				region: base.region,
-				locality: base.locality,
-				postcode: base.postcode,
-			}
+	const tail = bare
+		? null
+		: layoutAdminTail(base.country, { locality: base.locality, region: base.region, postcode: base.postcode })
+
+	if (!bare && !tail) return null
+
+	const components: CanonicalRow["components"] = tail ? { ...tail.components } : {}
 
 	if (decomposed.prefix) {
 		components.street_prefix = decomposed.prefix
@@ -272,9 +273,9 @@ export function synthesizeStreetRow(
 	if (random() < includeHN) {
 		const hn = randomHouseNumber(random)
 		components.house_number = hn
-		raw = bare ? `${hn} ${fullStreet}` : `${hn} ${fullStreet}, ${base.locality}, ${base.region} ${base.postcode}`
+		raw = tail ? `${hn} ${fullStreet}, ${tail.raw}` : `${hn} ${fullStreet}`
 	} else {
-		raw = bare ? fullStreet : `${fullStreet}, ${base.locality}, ${base.region} ${base.postcode}`
+		raw = tail ? `${fullStreet}, ${tail.raw}` : fullStreet
 	}
 
 	return { raw, components, locale: "en-US" }

package/lib/us/tools/fetch/imls-pls.ts

@@ -13,7 +13,7 @@
    procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"

package/lib/us/tools/fetch/nad.ts

@@ -37,7 +37,7 @@
  */
 
 import { APIClient, pluckResponseData } from "@mailwoman/core/api"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, writeLocalTextFile } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { stringifyJSON } from "@mailwoman/core/json"
@@ -55,7 +55,7 @@ export interface FetchNADOptions extends BaseFetchOptions {
 	/**
 	 * Fetch strategy.
 	 *
-	 * Default `featureserver`.
+	 * @defaultValue `featureserver`
 	 */
 	mode?: "featureserver" | "bulk"
 	/**
@@ -65,31 +65,31 @@ export interface FetchNADOptions extends BaseFetchOptions {
 	/**
 	 * Records per output file.
 	 *
-	 * Default `100000`.
+	 * @defaultValue `100000`
 	 */
 	chunkSize?: number
 	/**
 	 * Records per http request.
 	 *
-	 * Default `5000`.
+	 * @defaultValue `5000`
 	 */
 	pageSize?: number
 	/**
 	 * Parallel page fetches within a chunk.
 	 *
-	 * Default `4`.
+	 * @defaultValue `4`
 	 */
 	concurrency?: number
 	/**
 	 * Start objectid.
 	 *
-	 * Default `1`.
+	 * @defaultValue `1`
 	 */
 	startOID?: number
 	/**
 	 * Stop before this OID.
 	 *
-	 * Default = total count.
+	 * @defaultValue = total count.
 	 */
 	endOID?: number
 }

package/lib/us/tools/fetch/nppes.ts

@@ -15,7 +15,7 @@
    procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 
 import { APIClient, pluckResponseData } from "@mailwoman/core/api"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"
@@ -35,7 +35,7 @@ export type FetchNPPESOptions = BaseFetchOptions
  * files match `NPPES_Data_Dissemination_<Month>_<Year>*.zip`, while weekly files
  * include a `MMDDYY_MMDDYY` date range and are excluded.
  */
-async function discoverLatestZip(): Promise<string | undefined> {
+async function discoverLatestZip(): Promise<string | null> {
 	const html = await new APIClient({
 		displayName: "nppes-index",
 		retry: true,
@@ -50,17 +50,17 @@ async function discoverLatestZip(): Promise<string | undefined> {
 		if (name && !/\d{6}_\d{6}/.test(name)) return name
 	}
 
-	return undefined
+	return null
 }
 
 /**
  * The main registry CSV (`npidata_pfile_*.csv`); the archive also includes a
  * header file and a per-month change file.
  */
-async function findNpidataCSV(zipPath: PathBuilderLike): Promise<string | undefined> {
+async function findNpidataCSV(zipPath: PathBuilderLike): Promise<string | null> {
 	const entries = await listZipEntries(zipPath)
 
-	return entries.find((entry) => /npidata_pfile\S+\.csv/i.test(entry.name))?.name
+	return entries.find((entry) => /npidata_pfile\S+\.csv/i.test(entry.name))?.name ?? null
 }
 
 export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: string) => void): Promise<FetchSummary> {

package/lib/us/tools/fetch/state/hi-schools.ts

@@ -17,7 +17,7 @@
  */
 
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import type { PathBuilderLike } from "path-ts"
@@ -35,8 +35,9 @@ export interface FetchStateHISchoolsOptions extends BaseFetchOptions {
 	/**
 	 * Workbook URL.
 	 *
-	 * Defaults to the Hawaii DOE source.
 	 * Overridable for an isolated fetch test.
+	 *
+	 * @defaultValue the Hawaii DOE source.
 	 */
 	sourceURL?: string
 }

package/lib/us/tools/fetch/tiger-full.ts

@@ -15,7 +15,7 @@ import { APIClient, pluckResponseData } from "@mailwoman/core/api"
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
    procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { isoSeconds } from "@mailwoman/core/utils"

package/lib/utils/align.ts

@@ -33,10 +33,11 @@
  */
 
 import type { BIOLabel, ComponentTag } from "@mailwoman/codex/component"
+import type { TextSpan } from "@mailwoman/query-shape"
 import { distance as levenshteinDistance } from "fastest-levenshtein"
 
 import type { CanonicalRow, LabeledRow, QuarantinedRow } from "#types"
-import { whitespaceTokenizer, type TokenSpan, type Tokenizer } from "#utils/tokenize"
+import { whitespaceTokenizer, type Tokenizer } from "#utils/tokenize"
 
 /**
  * Options for `alignRow`.
@@ -45,7 +46,7 @@ export interface AlignOptions {
 	/**
 	 * Tokenizer to use.
 	 *
-	 * Defaults to `whitespaceTokenizer()`.
+	 * @defaultValue `whitespaceTokenizer()`
 	 */
 	tokenizer?: Tokenizer
 
@@ -53,19 +54,21 @@ export interface AlignOptions {
 	 * Max Levenshtein edit distance to accept when a verbatim substring match fails.
 	 *
 	 * Set `0` to require verbatim matches only.
-	 * Default `2`.
 	 *
 	 * Distance is computed against same-length windows in `raw`, so the threshold
 	 * scales naturally with the component value length.
+	 *
+	 * @defaultValue `2`
 	 */
 	maxEditDistance?: number
 
 	/**
 	 * Case-insensitive comparison for substring search.
 	 *
-	 * Default `true`.
 	 * The retained span in `raw` is the original case.
 	 * Only matching is case-insensitive.
+	 *
+	 * @defaultValue `true`
 	 */
 	caseInsensitive?: boolean
 }
@@ -221,17 +224,17 @@ function locateSpan(args: {
 	raw: string
 	claimed: Array<[number, number]>
 	maxEditDistance: number
-}): { start: number; end: number } | undefined {
+}): { start: number; end: number } | null {
 	const { haystack, needle, claimed, maxEditDistance } = args
 
-	if (!needle.length) return undefined
+	if (!needle) return null
 
 	// Pass 1: verbatim substring.
 	// Word-boundary-aligned matches are preferred over intra-word ones, so a short
 	// value cannot claim the inside of an earlier word.
 	// Intra-word matches stay allowed as the fallback because they are essential for affix
 	// supervision (street_suffix "straße" inside "Hauptstraße" has no boundary-aligned occurrence).
-	let intraWord: { start: number; end: number } | undefined
+	let intraWord: { start: number; end: number } | null = null
 	let from = 0
 
 	while (true) {
@@ -250,7 +253,7 @@ function locateSpan(args: {
 
 	if (intraWord) return intraWord
 
-	if (maxEditDistance <= 0) return undefined
+	if (maxEditDistance <= 0) return null
 
 	// Pass 2: fuzzy sliding-window.
 	const len = needle.length
@@ -265,7 +268,7 @@ function locateSpan(args: {
 		if (d <= maxEditDistance) return { start: i, end: i + len }
 	}
 
-	return undefined
+	return null
 }
 
 const WORD_CHAR = /[\p{L}\p{N}]/u
@@ -291,7 +294,7 @@ function overlapsClaimed(start: number, end: number, claimed: Array<[number, num
 /**
  * Assign BIO labels to tokens from component spans sorted by start offset.
  */
-function labelTokens(tokens: readonly TokenSpan[], spans: readonly ComponentSpan[]): readonly BIOLabel[] {
+function labelTokens(tokens: readonly TextSpan[], spans: readonly ComponentSpan[]): readonly BIOLabel[] {
 	const out: BIOLabel[] = []
 	const seenSpan = new Set<number>()
 

package/lib/utils/golden.ts

@@ -70,7 +70,7 @@ export interface GoldenReport {
 export function parseGoldenLine(line: string): GoldenEntry {
 	const obj = parseJSONStrict<Partial<GoldenEntry> & Record<string, unknown>>(line)
 
-	if (typeof obj.raw !== "string" || !obj.raw.length) {
+	if (typeof obj.raw !== "string" || !obj.raw) {
 		throw new Error("missing/empty raw")
 	}
 
@@ -87,7 +87,7 @@ export function parseGoldenLine(line: string): GoldenEntry {
 	for (const [k, v] of Object.entries(components)) {
 		if (!TAG_SET.has(k)) throw new Error(`unknown ComponentTag: ${k}`)
 
-		if (typeof v !== "string" || !v.length) {
+		if (typeof v !== "string" || !v) {
 			throw new Error(`components.${k} must be a non-empty string`)
 		}
 	}

package/lib/utils/license.ts

@@ -129,7 +129,7 @@ export function compileLicenseExcludes(spec: string): RegExp[] {
 /**
  * True when `license` matches any of the operator's exclude `patterns`; empty patterns never exclude.
  */
-export function licenseExcluded(license: string | undefined, patterns: readonly RegExp[]): boolean {
+export function licenseExcluded(license: string | null, patterns: readonly RegExp[]): boolean {
 	const l = license ?? ""
 
 	return patterns.some((p) => p.test(l))
@@ -143,7 +143,7 @@ export function licenseExcluded(license: string | undefined, patterns: readonly
  * so a row loop calls {@linkcode createLicenseVerdictCache} instead.
  */
 export function licenseVerdict(
-	license: string | undefined,
+	license: string | null,
 	policy: LicensePolicy,
 	excluded: readonly RegExp[] = []
 ): LicenseVerdict {
@@ -217,7 +217,7 @@ export interface LicenseVerdictCache {
 	/**
 	 * The verdict for this value under the policy this cache was built with.
 	 */
-	read(license: string | undefined): LicenseVerdict
+	read(license: string | null): LicenseVerdict
 	/**
 	 * Every distinct value refused so far, with the class it was refused under,
 	 * so a build that dropped rows reports which values caused each drop.

package/lib/utils/split.ts

@@ -109,10 +109,10 @@ export function defaultHoldouts(): Record<string, CountryHoldout> {
 			// Cornwall matches the admin rows for the same place `TR` covers.
 			regions: ["Cornwall"],
 		},
-		// The eight countries below enter training through OpenStreetMap rows, most of which carry no
-		// region and many no postcode, so each holdout matches its place three ways: the region an admin
-		// row carries, the postcode prefix, and the city as the OSM rows spell it. The spellings are the
-		// ones the 2026-10-02 extracts write.
+		// The eight countries below enter training through OpenStreetMap rows. Most hold no
+		// region and many no postcode, so each holdout matches its place three ways: the region an
+		// admin row holds, the postcode prefix, and the city as the OSM rows spell it. The spellings
+		// are the ones the 2026-10-02 extracts write.
 		CN: {
 			// Gansu by its province and capital, and Qinghai `81` and Tibet `85` by postcode.
 			regions: ["甘肃省", "甘肃", "Gansu"],
@@ -120,20 +120,22 @@ export function defaultHoldouts(): Record<string, CountryHoldout> {
 			localities: ["兰州市", "兰州", "Lanzhou"],
 		},
 		IN: {
-			// Kerala, whose PIN codes run 67 to 69.
+			// Kerala.
+			// Its PIN codes run 67 to 69.
 			regions: ["Kerala"],
 			postcodePrefixes: ["67", "68", "69"],
 			localities: ["Kochi", "Kollam", "Thiruvananthapuram", "Kozhikode"],
 		},
 		ID: {
-			// Bali, whose postcodes begin `80`.
+			// Bali.
+			// Its postcodes begin `80`.
 			regions: ["Bali"],
 			postcodePrefixes: ["80"],
 			localities: ["Denpasar", "Bali"],
 		},
 		NG: {
 			// Enugu State.
-			// OSM Nigeria rows carry almost no postcode or region, so the cities carry it.
+			// OSM Nigeria rows hold almost no postcode or region, so the city names supply the holdout.
 			regions: ["Enugu"],
 			localities: ["Enugu", "Nsukka"],
 		},
@@ -144,7 +146,8 @@ export function defaultHoldouts(): Record<string, CountryHoldout> {
 			localities: ["Islamabad", "islamabad", "اسلام آباد"],
 		},
 		BD: {
-			// Chattogram, Khulna and Sylhet, whose postcodes begin 4, 9 and 3 respectively.
+			// Chattogram, Khulna and Sylhet.
+			// Their postcodes begin 4, 9 and 3 respectively.
 			postcodePrefixes: ["40", "41", "42", "43", "90", "91", "92", "31"],
 			localities: ["Chittagong", "Chattogram", "Khulna", "Sylhet"],
 		},
@@ -153,7 +156,8 @@ export function defaultHoldouts(): Record<string, CountryHoldout> {
 			localities: ["Cần Thơ", "Thành phố Cần Thơ", "Huế", "Thành phố Huế"],
 		},
 		RU: {
-			// Primorsky Krai, whose postcodes run 690 to 692.
+			// Primorsky Krai.
+			// Its postcodes run 690 to 692.
 			regions: ["Приморский край"],
 			postcodePrefixes: ["690", "691", "692"],
 			localities: ["Владивосток", "Уссурийск", "Находка"],
@@ -169,13 +173,13 @@ export function defaultHoldouts(): Record<string, CountryHoldout> {
 		PM: { localities: ["Miquelon-Langlade"] },
 		YT: { localities: ["Dzaoudzi", "Pamandzi"] },
 		// Tumaraa holds 1,522 of PF's 6,755 rows with a street, more than a tenth,
-		// because Pirae's 958 rows carry no street name and Papeete holds the remaining 5,233.
+		// because Pirae's 958 rows have no street name and Papeete has the remaining 5,233.
 		PF: { localities: ["Tumaraa"] },
 		NC: { localities: ["Koné", "Pouembout", "Kaala-Gomen"] },
 		LV: {
-			// Latgale's south-east: the Krāslava, Ludza, Balvi, Preiļi and Līvāni
-			// municipalities, whose postcodes begin LV-56, LV-57, LV-45 and LV-53,
-			// and the state city Rēzekne, which lies in no municipality.
+			// Latgale's south-east: the Krāslava, Ludza, Balvi, Preiļi and Līvāni municipalities.
+			// Their postcodes begin LV-56, LV-57, LV-45 and LV-53.
+			// The state city Rēzekne lies in no municipality.
 			// The address register writes `nov.`; other sources spell the municipality out.
 			regions: [
 				"Krāslavas nov.",
@@ -203,7 +207,7 @@ export function defaultHoldouts(): Record<string, CountryHoldout> {
 /**
  * Returns the matchers for one country, reading a bare array as a region list.
  */
-export function holdoutPolicyFor(holdout: CountryHoldout | undefined): HoldoutPolicy {
+export function holdoutPolicyFor(holdout: CountryHoldout | null): HoldoutPolicy {
 	if (!holdout) return {}
 
 	return Array.isArray(holdout) ? { regions: holdout } : (holdout as HoldoutPolicy)
@@ -221,7 +225,7 @@ export function splitForRow(
 	row: Pick<SplitInputRow, "source_id" | "country" | "components">,
 	holdouts: Record<string, CountryHoldout> = defaultHoldouts()
 ): SplitName {
-	const policy = holdoutPolicyFor(holdouts[row.country])
+	const policy = holdoutPolicyFor(holdouts[row.country] ?? null)
 	const { region, postcode, locality } = row.components
 
 	const isHeldOut =