@mailwoman/corpus 8.0.0 → 8.2.0

package/src/synthesize-boundary-stress.ts

@@ -51,6 +51,12 @@
 
 import type { CanonicalRow } from "./types.ts"
 
+/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
+   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
+   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
+
 export type BoundaryStressTemplate =
 	| "street-eats-affix"
 	| "comma-less-city-state"
@@ -59,7 +65,9 @@ export type BoundaryStressTemplate =
 	// Added 2026-06-18 after the v1.6.0 probes (the shard's NARROW distribution over-fit "full structured
 	// address" and regressed OOD). These two re-balance the contexts the model actually sees:
 	| "bare-locality" // the ship-blocker fix: locality with NO street (the 84%-dropped "City, STATE" rows)
-	| "house-number-before-street" // the confounding mirror of house-number-after-street (number position)
+	| "house-number-before-street"
+
+// the confounding mirror of house-number-after-street (number position)
 
 export interface BoundaryStressBaseTuple {
 	locality: string
@@ -70,7 +78,9 @@ export interface BoundaryStressBaseTuple {
 
 export interface BoundaryStressSynthesisOpts {
 	random?: () => number
-	/** Force a specific shape (tests + balanced shard composition). */
+	/**
+	 * Force a specific shape (tests + balanced shard composition).
+	 */
 	forceTemplate?: BoundaryStressTemplate
 }
 
@@ -85,10 +95,12 @@ function pick<T>(arr: ReadonlyArray<T>, random: () => number): T {
 	return arr[Math.floor(random() * arr.length)]!
 }
 
-// Multi-word street names — the suffix boundary only bites when "Club" could be read as part of the
-// name. Single-word names alone teach nothing about the suffix edge.
-// Multi-word names are what make the suffix boundary BITE (the model must not read the trailing
-// suffix word as part of the name). Kept diverse so the shard teaches the boundary, not the lexeme.
+/**
+ * Multi-word street names — the suffix boundary only bites when "Club" could be read as part of the name. Single-word
+ * names alone teach nothing about the suffix edge. Multi-word names are what make the suffix boundary BITE (the model
+ * must not read the trailing suffix word as part of the name). Kept diverse so the shard teaches the boundary, not the
+ * lexeme.
+ */
 const MULTIWORD_STREETS = [
 	"Country Club",
 	"Martin Luther King",
@@ -136,6 +148,7 @@ const MULTIWORD_STREETS = [
 	"Queens Gate",
 	"Princeton Junction",
 ] as const
+
 const SINGLE_STREETS = [
 	"Main",
 	"Oak",
@@ -177,6 +190,7 @@ const SINGLE_STREETS = [
 	"12th",
 	"42nd",
 ] as const
+
 const SUFFIXES = [
 	"St",
 	"Street",
@@ -209,10 +223,13 @@ const SUFFIXES = [
 	"Row",
 	"Walk",
 ] as const
+
 const DIRECTIONALS = ["N", "S", "E", "W", "NE", "NW", "SE", "SW"] as const
 
-// FR street-type prefixes + hyphenated honorific street names (the hyphen is incidental; the boundary
-// stress is the prefix↔name split + the number-after-street order).
+/**
+ * FR street-type prefixes + hyphenated honorific street names (the hyphen is incidental; the boundary stress is the
+ * prefix↔name split + the number-after-street order).
+ */
 const FR_PREFIXES = [
 	"Rue",
 	"Avenue",
@@ -229,6 +246,7 @@ const FR_PREFIXES = [
 	"Sentier",
 	"Promenade",
 ] as const
+
 const FR_NAMES = [
 	"Jean-Baptiste Lebas",
 	"Neuve-des-Capucines",
@@ -256,19 +274,18 @@ const FR_NAMES = [
 	"Aristide-Briand",
 ] as const
 
-// Org/venue prefixes for the bare-locality shape — the v1.6.0 locality drop hit org-PREFIXED real rows
-// hardest ("LISBON PUBLIC LIBRARY, …, Lisbon ND"; "Alburg Health Center"). Teaching the locality WITH a
-// leading venue keeps the model emitting it on facility-style addresses (NPPES/HRSA shapes). `venue` is a
-// base ComponentTag.
-//
-// #511-LINTED 2026-06-18 (scripts/lint-venue-vocab — scan of nppes/hrsa/tiger/nad/wof-admin): every token
-// here is venue-DOMINANT in the base, so the shard agrees with it. The first draft was naive — 9 terms
-// were dropped because their tokens are dominantly street/locality and would CONTRADICT the base the way
-// Madison-as-street did (#511): "Fire" 93% street, "Veterans" 94% street, "City" 68% locality, "Hall" 63%
-// street, "Memorial"/"Hospital" 62-63% street, "Recreation" 79% street, "Town" 48% locality, "Library" 51%
-// street, "County" 68% street, "Arts"/"Courthouse"/"Municipal" dependent_locality. Kept tokens: Clinic 98%,
-// Practice 98%, Dental 100%, Health 99%, Medical 88%, Community 92%, Department 90%, Group 87%, Center 65%,
-// School 70%, Public 89%, Elementary/Family 97% (all venue).
+/**
+ * Org/venue prefixes for the bare-locality shape — the v1.6.0 locality drop hit org-PREFIXED real rows hardest ("LISBON
+ * PUBLIC LIBRARY, …, Lisbon ND"; "Alburg Health Center"). Teaching the locality WITH a leading venue keeps the model
+ * emitting it on facility-style addresses (NPPES/HRSA shapes). `venue` is a base ComponentTag. #511-LINTED 2026-06-18
+ * (scripts/lint-venue-vocab — scan of nppes/hrsa/tiger/nad/wof-admin): every token here is venue-DOMINANT in the base,
+ * so the shard agrees with it. The first draft was naive — 9 terms were dropped because their tokens are dominantly
+ * street/locality and would CONTRADICT the base the way Madison-as-street did (#511): "Fire" 93% street, "Veterans" 94%
+ * street, "City" 68% locality, "Hall" 63% street, "Memorial"/"Hospital" 62-63% street, "Recreation" 79% street, "Town"
+ * 48% locality, "Library" 51% street, "County" 68% street, "Arts"/"Courthouse"/"Municipal" dependent_locality. Kept
+ * tokens: Clinic 98%, Practice 98%, Dental 100%, Health 99%, Medical 88%, Community 92%, Department 90%, Group 87%,
+ * Center 65%, School 70%, Public 89%, Elementary/Family 97% (all venue).
+ */
 const VENUES = [
 	"Community Center",
 	"Health Center",
@@ -286,10 +303,12 @@ const VENUES = [
 	"Public School",
 ] as const
 
-// Localities DERIVED from the base corpus (#511): every name here is verified locality-DOMINANT in the
-// training data (B-locality ≫ I-street), so the shard agrees with the base instead of fighting it. The
-// night's targeted scan caught the prior vocab (Madison, Portland, Springfield IL…) at 92–100% STREET
-// in the base ("Madison Ave"), the "5th Avenue Theatre" #511 trap. See 2026-06-17-locality-vocab-fix.
+/**
+ * Localities DERIVED from the base corpus (#511): every name here is verified locality-DOMINANT in the training data
+ * (B-locality ≫ I-street), so the shard agrees with the base instead of fighting it. The night's targeted scan caught
+ * the prior vocab (Madison, Portland, Springfield IL…) at 92–100% STREET in the base ("Madison Ave"), the "5th Avenue
+ * Theatre" #511 trap. See 2026-06-17-locality-vocab-fix.
+ */
 const US_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Albuquerque", region: "NM", postcode: "87102", country: "US" },
 	{ locality: "Indianapolis", region: "IN", postcode: "46203", country: "US" },
@@ -320,11 +339,14 @@ const US_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Chicago", region: "IL", postcode: "60625", country: "US" },
 	{ locality: "Springfield", region: "MA", postcode: "01108", country: "US" },
 ]
-// FR localities DERIVED from the FR (ban) shards specifically — where these famous cities are 95–99%
-// locality-DOMINANT (Paris 515605/24789, Marseille 247014/1752, Lyon 106239/3114). NB: the all-shard
-// scan falsely flagged them street-dominant by undersampling the FR block (parts 180–209) and mixing in
-// US street-contexts; the FR-block scan is the honest distribution. Dept-diverse (28 depts), region
-// empty (French addresses carry no region token; the generator's region-optional path handles it).
+
+/**
+ * FR localities DERIVED from the FR (ban) shards specifically — where these famous cities are 95–99% locality-DOMINANT
+ * (Paris 515605/24789, Marseille 247014/1752, Lyon 106239/3114). NB: the all-shard scan falsely flagged them
+ * street-dominant by undersampling the FR block (parts 180–209) and mixing in US street-contexts; the FR-block scan is
+ * the honest distribution. Dept-diverse (28 depts), region empty (French addresses carry no region token; the
+ * generator's region-optional path handles it).
+ */
 const FR_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Paris", region: "", postcode: "75003", country: "FR" },
 	{ locality: "Marseille", region: "", postcode: "13016", country: "FR" },
@@ -345,6 +367,7 @@ const FR_TUPLES: ReadonlyArray<BoundaryStressBaseTuple> = [
 	{ locality: "Brunoy", region: "", postcode: "91800", country: "FR" },
 	{ locality: "Rambouillet", region: "", postcode: "78120", country: "FR" },
 ]
+
 // NB: no DE_TUPLES — German cities are street-dominated too ("Berliner Straße"), and the base yielded
 // zero locality-dominant DE towns in the scan, so house-number-after-street is FR-only here. DE's
 // native-order number-after-street is covered by the dedicated synth-german shard.
@@ -400,6 +423,7 @@ export function synthesizeBoundaryStressRow(
 				template,
 			}
 		}
+
 		const withZip = random() < 0.5
 		const comma = random() < 0.6 ? "," : "" // include the comma-LESS "City STATE" form too
 		// "United States" (United 98% / States 98% country in the base), NOT "USA" — the #511 lint found
@@ -465,6 +489,7 @@ export function synthesizeBoundaryStressRow(
 				template,
 			}
 		}
+
 		// house-number-after-street: "{name} {hn}, {postcode} {locality}" — number FOLLOWS the street.
 		const raw = `${name} ${hn}, ${b.postcode} ${b.locality}`
 
@@ -484,6 +509,7 @@ export function synthesizeBoundaryStressRow(
 	const name = random() < 0.7 ? pick(MULTIWORD_STREETS, random) : pick(SINGLE_STREETS, random)
 	const suffix = pick(SUFFIXES, random)
 	const streetCore = `${dir ? `${dir} ` : ""}${name} ${suffix}`
+
 	const components: CanonicalRow["components"] = {
 		house_number: hn,
 		...(dir ? { street_prefix: dir } : {}),
@@ -493,6 +519,7 @@ export function synthesizeBoundaryStressRow(
 		region: b.region,
 		postcode: b.postcode,
 	}
+
 	const raw =
 		template === "comma-less-city-state"
 			? // no commas anywhere — the segmentation cue is gone

package/src/synthesize-german.ts

@@ -25,7 +25,15 @@
 import { formatAddress } from "./format.ts"
 import type { CanonicalRow } from "./types.ts"
 
-/** A real address tuple (e.g. one OpenAddresses row): street + locality required, rest optional. */
+/**
+ * A real address tuple (e.g. one OpenAddresses row): street + locality required, rest optional.
+ */
+/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
+   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
+   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
+
 export interface LocaleBaseTuple {
 	house_number?: string
 	street: string
@@ -39,7 +47,10 @@ export interface LocaleBaseTuple {
 	region?: string
 	postcode?: string
 }
-/** @deprecated Alias — use LocaleBaseTuple. */
+
+/**
+ * @deprecated Alias — use LocaleBaseTuple.
+ */
 export type GermanBaseTuple = LocaleBaseTuple
 
 export interface SynthesizedLocaleRow {
@@ -47,7 +58,10 @@ export interface SynthesizedLocaleRow {
 	components: CanonicalRow["components"]
 	locale: string
 }
-/** @deprecated Alias — use SynthesizedLocaleRow. */
+
+/**
+ * @deprecated Alias — use SynthesizedLocaleRow.
+ */
 export type SynthesizedGermanRow = SynthesizedLocaleRow
 
 export interface LocaleSynthesisOpts {
@@ -80,10 +94,15 @@ export interface LocaleSynthesisOpts {
 	 */
 	nativeHouseJoin?: "template" | "space"
 }
-/** @deprecated Alias — use LocaleSynthesisOpts. */
+
+/**
+ * @deprecated Alias — use LocaleSynthesisOpts.
+ */
 export type GermanSynthesisOpts = LocaleSynthesisOpts
 
-/** ISO-3166 alpha-2 → BCP-47 tag for the emitted rows (primary language per country). */
+/**
+ * ISO-3166 alpha-2 → BCP-47 tag for the emitted rows (primary language per country).
+ */
 const LOCALE_TAG: Record<string, string> = {
 	DE: "de-DE",
 	ES: "es-ES",
@@ -111,7 +130,9 @@ function normalizePostcode(postcode: string, country: string): string {
 	return postcode
 }
 
-/** True when `value` appears verbatim AND as a standalone token (so BIO alignment lands cleanly). */
+/**
+ * True when `value` appears verbatim AND as a standalone token (so BIO alignment lands cleanly).
+ */
 function tokenPresent(raw: string, value: string): boolean {
 	if (!raw.includes(value)) return false
 	// Reject substring-of-a-larger-number collisions (e.g. house "2" inside postcode "12623").
@@ -218,7 +239,9 @@ export function synthesizeLocaleRow(
 	return { raw, components, locale: LOCALE_TAG[country] ?? country.toLowerCase() }
 }
 
-/** German wrapper over {@link synthesizeLocaleRow}. Kept for the build-german-shard caller + tests. */
+/**
+ * German wrapper over {@link synthesizeLocaleRow}. Kept for the build-german-shard caller + tests.
+ */
 export function synthesizeGermanRow(
 	base: LocaleBaseTuple,
 	opts: LocaleSynthesisOpts = {}

package/src/synthesize-house-venue.ts

@@ -41,7 +41,9 @@ export interface HouseVenueBaseTuple {
 
 export type HouseVenueTemplate =
 	| "venue-after-street" // "123 Main St, Sunrise Bakery, Springfield, IL 02101"
-	| "venue-before-street" // "Sunrise Bakery, 123 Main St, Springfield, IL 02101"
+	| "venue-before-street"
+
+// "Sunrise Bakery, 123 Main St, Springfield, IL 02101"
 
 export interface HouseVenueSynthesisOpts {
 	random?: () => number
@@ -55,12 +57,12 @@ export interface SynthesizedHouseVenueRow {
 	template: HouseVenueTemplate
 }
 
-// ---------------------------------------------------------------------------------------------
-// Venue pool — PLAIN, no street-typing tokens. The point of this shard is to teach
-// house_number + venue coexistence, NOT to re-introduce decompose-mode pressure.
-// Adversarial venue names live in `synthesize-no-street.ts`.
-// ---------------------------------------------------------------------------------------------
+//#region Venue pool
 
+/**
+ * PLAIN venue names, carrying no street-typing tokens. This shard teaches house_number + venue coexistence, NOT
+ * decompose-mode pressure — adversarial venue names live in `synthesize-no-street.ts`.
+ */
 const PLAIN_VENUES: ReadonlyArray<string> = [
 	"Bob's Pizza",
 	"Acme Corporation",
@@ -84,11 +86,13 @@ const PLAIN_VENUES: ReadonlyArray<string> = [
 	"Westwood Realty",
 ]
 
-// ---------------------------------------------------------------------------------------------
-// Fallback street pool for tuples that didn't carry a `street` field. Plain street names
-// without typing-token ambiguity.
-// ---------------------------------------------------------------------------------------------
+//#endregion
 
+//#region Fallback street pool
+
+/**
+ * Stand-in streets for tuples that carried no `street` field. Plain names, no typing-token ambiguity.
+ */
 const FALLBACK_STREETS: ReadonlyArray<string> = [
 	"Main St",
 	"Oak Ave",
@@ -107,9 +111,9 @@ const FALLBACK_STREETS: ReadonlyArray<string> = [
 	"Forest Blvd",
 ]
 
-// ---------------------------------------------------------------------------------------------
-// House-number generator
-// ---------------------------------------------------------------------------------------------
+//#endregion
+
+//#region House-number generator
 
 function randomHouseNumber(random: () => number): string {
 	// Generate a plain numeric house number 1-9999. No fractions/ranges — those land in
@@ -144,9 +148,9 @@ function countryToLocale(country: string): string {
 	}
 }
 
-// ---------------------------------------------------------------------------------------------
-// Synthesis
-// ---------------------------------------------------------------------------------------------
+//#endregion
+
+//#region Synthesis
 
 export function synthesizeHouseVenueRow(
 	base: HouseVenueBaseTuple,
@@ -190,3 +194,5 @@ export function synthesizeHouseVenueRow(
 export function hasHouseNumberAndVenue(components: CanonicalRow["components"]): boolean {
 	return components.house_number !== undefined && components.venue !== undefined
 }
+
+//#endregion

package/src/synthesize-intersection.ts

@@ -21,7 +21,21 @@
 
 import type { CanonicalRow } from "./types.ts"
 
-/** Street name cores (no suffix) — proper-noun streets that often appear bare. */
+/**
+ * Street name cores (no suffix) — proper-noun streets that often appear bare.
+ */
+
+/**
+ * Attempts to draw a second street distinct from the first before giving up on the pair.
+ */
+const MAX_DISTINCT_STREET_TRIES = 8
+
+/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
+   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
+   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
+
 const STREET_CORES = [
 	"Main",
 	"Oak",
@@ -47,7 +61,9 @@ const STREET_CORES = [
 	"Spring",
 ] as const
 
-/** Bare proper-noun streets that idiomatically take NO suffix. */
+/**
+ * Bare proper-noun streets that idiomatically take NO suffix.
+ */
 const BARE_NAMES = ["Broadway", "Wall", "Bourbon", "Esplanade", "Riverside", "Lakeshore"] as const
 
 const ORDINALS = [
@@ -79,7 +95,9 @@ const CONNECTORS = [" & ", " and ", " at ", " / ", " @ "] as const
 export interface IntersectionBaseTuple {
 	locality: string
 	region: string
-	/** ZIP — optional; ~30% of synthetic intersections omit it (idiomatic). */
+	/**
+	 * ZIP — optional; ~30% of synthetic intersections omit it (idiomatic).
+	 */
 	postcode?: string
 	country: string
 }
@@ -98,7 +116,9 @@ function pick<T>(arr: ReadonlyArray<T>, random: () => number): T {
 	return arr[Math.floor(random() * arr.length)]!
 }
 
-/** Build a single street surface form, e.g. "W 42nd St", "Broadway", "Main St", "N Oak Ave". */
+/**
+ * Build a single street surface form, e.g. "W 42nd St", "Broadway", "Main St", "N Oak Ave".
+ */
 function buildStreetName(random: () => number): string {
 	// ~20% bare proper-noun street (no suffix), else directional? + core/ordinal + suffix.
 	if (random() < 0.2) return pick(BARE_NAMES, random)
@@ -108,6 +128,7 @@ function buildStreetName(random: () => number): string {
 	if (random() < 0.35) {
 		parts.push(pick(DIRECTIONALS, random))
 	}
+
 	parts.push(random() < 0.45 ? pick(ORDINALS, random) : pick(STREET_CORES, random))
 	parts.push(pick(SUFFIXES, random))
 
@@ -131,7 +152,7 @@ export function synthesizeIntersectionRow(
 	// Ensure distinct surface forms (and not a substring of each other — alignment needs unambiguous spans).
 	let tries = 0
 
-	while ((b === a || a.includes(b) || b.includes(a)) && tries++ < 8) {
+	while ((b === a || a.includes(b) || b.includes(a)) && tries++ < MAX_DISTINCT_STREET_TRIES) {
 		b = buildStreetName(random)
 	}
 
@@ -153,9 +174,11 @@ export function synthesizeIntersectionRow(
 		raw = `${cornerPrefix}${a}${connector}${b}`
 	} else {
 		const includePostcode = base.postcode != null && random() < 0.7
+
 		const tail = includePostcode
 			? `, ${base.locality}, ${base.region} ${base.postcode}`
 			: `, ${base.locality}, ${base.region}`
+
 		raw = `${cornerPrefix}${a}${connector}${b}${tail}`
 		components.locality = base.locality
 		components.region = base.region
@@ -168,7 +191,9 @@ export function synthesizeIntersectionRow(
 	return { raw, components, locale: "en-US" }
 }
 
-/** A small built-in US city/region/zip pool for standalone shard generation + tests. */
+/**
+ * A small built-in US city/region/zip pool for standalone shard generation + tests.
+ */
 export const DEFAULT_US_BASES: ReadonlyArray<IntersectionBaseTuple> = [
 	{ locality: "New York", region: "NY", postcode: "10036", country: "US" },
 	{ locality: "Chicago", region: "IL", postcode: "60613", country: "US" },
@@ -182,7 +207,9 @@ export const DEFAULT_US_BASES: ReadonlyArray<IntersectionBaseTuple> = [
 	{ locality: "Atlanta", region: "GA", postcode: "30303", country: "US" },
 ]
 
-/** Generate `count` intersection rows over the provided bases (round-robin). */
+/**
+ * Generate `count` intersection rows over the provided bases (round-robin).
+ */
 export function generateIntersectionRows(
 	count: number,
 	bases: ReadonlyArray<IntersectionBaseTuple> = DEFAULT_US_BASES,

package/src/synthesize-no-street.ts

@@ -39,9 +39,13 @@
 
 import type { CanonicalRow } from "./types.ts"
 
-// -------------------------------------------------------------------------------------------------
-// Types
-// -------------------------------------------------------------------------------------------------
+//#region Types
+
+/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
+   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
+   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
 
 export interface NoStreetBaseTuple {
 	locality: string
@@ -60,7 +64,9 @@ export type NoStreetTemplate =
 
 export interface NoStreetSynthesisOpts {
 	random?: () => number
-	/** Override the template selection entirely (used by tests for deterministic coverage). */
+	/**
+	 * Override the template selection entirely (used by tests for deterministic coverage).
+	 */
 	forceTemplate?: NoStreetTemplate
 }
 
@@ -71,9 +77,9 @@ export interface SynthesizedNoStreetRow {
 	template: NoStreetTemplate
 }
 
-// -------------------------------------------------------------------------------------------------
-// Venue name pools
-// -------------------------------------------------------------------------------------------------
+//#endregion
+
+//#region Venue name pools
 
 /**
  * Plain venue names — businesses without street-typing words in the name. Used as the easy-mode positive class for
@@ -165,9 +171,9 @@ const COUNTRY_NAMES = new Map<string, ReadonlyArray<string>>([
 	["AU", ["Australia"]],
 ])
 
-// -------------------------------------------------------------------------------------------------
-// Synthesis
-// -------------------------------------------------------------------------------------------------
+//#endregion
+
+//#region Synthesis
 
 function pick<T>(arr: ReadonlyArray<T>, random: () => number): T {
 	return arr[Math.floor(random() * arr.length)]!
@@ -339,3 +345,5 @@ export function hasAnyStreetSideTag(components: CanonicalRow["components"]): boo
 
 	return false
 }
+
+//#endregion

package/src/synthesize-po-box.ts

@@ -26,6 +26,22 @@
 
 import type { CanonicalRow } from "./types.ts"
 
+/**
+ * Digits a box number needs before a thousands comma is plausible (`1,234`).
+ */
+const MIN_DIGITS_FOR_COMMA_GROUPING = 4
+
+/**
+ * Digits a box number needs before a hyphen group is plausible (`12-34`).
+ */
+const MIN_DIGITS_FOR_HYPHEN_GROUPING = 3
+
+/* oxlint-disable sister-software/no-unnamed-threshold -- the bare decimals below are weighted-sampler
+   cutoffs, not thresholds: `const r = random()` followed by a cascade of `r < 0.4` branches IS the
+   output distribution, and reading the cascade top-to-bottom is how you see it. Naming each cutoff
+   would hide the distribution behind a wall of identifiers. Genuine thresholds in these files are
+   extracted as named constants above. */
+
 export interface PoBoxBaseTuple {
 	locality: string
 	region: string
@@ -99,14 +115,16 @@ const LEADERS_BY_LOCALE = new Map<string, LocaleTemplate>(PO_BOX_LOCALE_TEMPLATE
  */
 export function maybeNoisifyBoxNumber(num: string, random: () => number): string {
 	if (random() > 0.1) return num
+
 	const variants: Array<(s: string) => string> = [
 		// Thousand-separator comma (real input: "Box 1,234")
-		(s) => (s.length >= 4 ? `${s.slice(0, -3)},${s.slice(-3)}` : s),
+		(s) => (s.length >= MIN_DIGITS_FOR_COMMA_GROUPING ? `${s.slice(0, -3)},${s.slice(-3)}` : s),
 		// Embedded dash (real input: "PMB-200")
-		(s) => (s.length >= 3 ? `${s.slice(0, -2)}-${s.slice(-2)}` : s),
+		(s) => (s.length >= MIN_DIGITS_FOR_HYPHEN_GROUPING ? `${s.slice(0, -2)}-${s.slice(-2)}` : s),
 		// Embedded spaces (real input from OCR: "1 2 3 4")
 		(s) => s.split("").join(" "),
 	]
+
 	const f = variants[Math.floor(random() * variants.length)]!
 
 	return f(num)
@@ -129,11 +147,17 @@ export interface SynthesizedPoBoxRow {
 }
 
 export interface PoBoxSynthesisOpts {
-	/** Random function — pass deterministic seed for tests. Default Math.random. */
+	/**
+	 * Random function — pass deterministic seed for tests. Default Math.random.
+	 */
 	random?: () => number
-	/** Number generator. Default uniform over 1..99999. */
+	/**
+	 * Number generator. Default uniform over 1..99999.
+	 */
 	pickNumber?: (random: () => number) => string
-	/** PMB probability when locale supports it (and a street is provided in the base tuple). */
+	/**
+	 * PMB probability when locale supports it (and a street is provided in the base tuple).
+	 */
 	pmbRatio?: number
 }
 
@@ -150,7 +174,7 @@ function defaultPickNumber(random: () => number): string {
 	if (r < 0.95) return String(1000 + Math.floor(random() * 9000))
 
 	// 1000-9999
-	return String(10000 + Math.floor(random() * 90000)) // 10000-99999
+	return String(10_000 + Math.floor(random() * 90_000)) // 10000-99999
 }
 
 /**
@@ -163,7 +187,7 @@ export function synthesizePoBoxRow(
 ): SynthesizedPoBoxRow | null {
 	const random = opts.random ?? Math.random
 	const pickNumber = opts.pickNumber ?? defaultPickNumber
-	const pmbRatio = opts.pmbRatio ?? 0.0
+	const pmbRatio = opts.pmbRatio ?? 0
 
 	const locale = countryToLocale(base.country)
 	const tpl = LEADERS_BY_LOCALE.get(locale)
@@ -231,15 +255,21 @@ const MIL_UNITS: ReadonlyArray<{ code: string; boxRequired: boolean }> = [
 	{ code: "CMR", boxRequired: true },
 	{ code: "Unit", boxRequired: false },
 ]
+
 const MIL_PO_CODES = ["APO", "FPO", "DPO"] as const
-// region → plausible ZIP prefix (AE Europe 09xxx, AP Pacific 962-966xx, AA Americas 340xx).
+
+/**
+ * Region → plausible ZIP prefix (AE Europe 09xxx, AP Pacific 962-966xx, AA Americas 340xx).
+ */
 const MIL_REGION_ZIP: ReadonlyArray<{ region: string; zip: (r: () => number) => string }> = [
 	{ region: "AE", zip: (r) => `09${String(Math.floor(r() * 1000)).padStart(3, "0")}` },
 	{ region: "AP", zip: (r) => `96${String(200 + Math.floor(r() * 100)).padStart(3, "0")}` },
 	{ region: "AA", zip: (r) => `340${String(Math.floor(r() * 100)).padStart(2, "0")}` },
 ]
 
-/** Generate one US military/diplomatic PO-box row (#517). Self-contained — draws no base tuple. */
+/**
+ * Generate one US military/diplomatic PO-box row (#517). Self-contained — draws no base tuple.
+ */
 export function synthesizeMilitaryPoBoxRow(opts: PoBoxSynthesisOpts = {}): SynthesizedPoBoxRow {
 	const random = opts.random ?? Math.random
 	const unit = MIL_UNITS[Math.floor(random() * MIL_UNITS.length)]!
@@ -293,7 +323,9 @@ export function countryToLocale(country: string): string {
 	return "en-US"
 }
 
-/** All locales we synthesize for. Exposed for tests and for source-weight tuning. */
+/**
+ * All locales we synthesize for. Exposed for tests and for source-weight tuning.
+ */
 export function supportedLocales(): ReadonlyArray<string> {
 	return PO_BOX_LOCALE_TEMPLATES.map((t) => t.locale)
 }