mailwoman 10.1.0 → 10.2.0

package/README.md

@@ -15,8 +15,8 @@ npx mailwoman parse "1600 Amphitheatre Parkway, Mountain View, CA 94043"
 ```ts
 // Library — parse programmatically
 import { decodeAsJSON } from "@mailwoman/core/decoder"
-import { createRuntimePipeline } from "mailwoman"
 import { NeuralAddressClassifier } from "@mailwoman/neural"
+import { createRuntimePipeline } from "mailwoman"
 
 const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" })
 const parse = createRuntimePipeline({ classifier })
@@ -91,8 +91,8 @@ classification with production-ready defaults.
 
 ```ts
 import { decodeAsJSON, decodeAsTuples } from "@mailwoman/core/decoder"
-import { createRuntimePipeline } from "mailwoman"
 import { NeuralAddressClassifier } from "@mailwoman/neural"
+import { createRuntimePipeline } from "mailwoman"
 
 const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" })
 const parse = createRuntimePipeline({ classifier })
@@ -143,12 +143,12 @@ ones you'll reach for most:
 const parse = createRuntimePipeline({
 	classifier,
 	resolver, // optional — see "Geocoding" below
-	normalizeCase: true, // title-case detected all-caps input before the model (default: off)
+	caseNormalization: "title-case", // title-case detected all-caps input before the model (the default)
 })
 
 await parse("350 5TH AVE, NEW YORK, NY 10118", {
 	locale: "en-US", // assert a locale instead of detecting it
-	hardPlaceCountry: true, // confine resolution to a confidently-detected country (default: on)
+	placerCountryUse: "filter", // confine resolution to a confidently-detected country (the default)
 })
 ```
 

package/cli/commands/clients/generate.tsx

@@ -42,7 +42,7 @@ const ClientsGenerate: CommandComponent<typeof spec> = ({ options }) => {
 		async () => {
 			const { generateClients } = await import("#tools/generate-clients")
 
-			return await generateClients({
+			return generateClients({
 				outDir: options.outDir,
 				skipVerify: options.skipVerify,
 				onPhase: phaseReporter(),
@@ -51,7 +51,8 @@ const ClientsGenerate: CommandComponent<typeof spec> = ({ options }) => {
 		(result) => (result.ok ? 0 : 1)
 	)
 
-	// Progress streams to stderr until the summary lands, which `CommandTaskResult` renders.
+	// Progress streams to stderr until the summary lands.
+	// `CommandTaskResult` renders that summary.
 	if (state.status !== "done") return <CommandTaskResult state={state} />
 
 	const { ok, checks, receipt } = state.result

package/cli/commands/corpus/align-slice.tsx

@@ -30,7 +30,7 @@ export const spec = {
 
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { alignCanonicalRows } = await import("@mailwoman/corpus/tools")
+		const { alignCanonicalRows } = await import("@mailwoman/corpus/tools/align-canonical")
 
 		await alignCanonicalRows({
 			input: options.input,

package/cli/commands/corpus/audit.tsx

@@ -34,7 +34,7 @@ export const spec = {
 
 const CorpusAudit: CommandComponent<typeof spec, [string]> = ({ options, args }) => {
 	const state = useCommandTask(async () => {
-		const { audit } = await import("@mailwoman/corpus/tools")
+		const { audit } = await import("@mailwoman/corpus/tools/audit")
 
 		audit({ corpusDir: args[0], configPath: options.config, sampleFileCount: options.sample })
 	})

package/cli/commands/corpus/build.tsx

@@ -118,7 +118,7 @@ export const spec = {
 type AdapterInput = string | AdapterOptions
 
 function isAdapterInputMap(input: unknown): input is Record<string, AdapterInput> {
-	if (typeof input !== "object" || input === null || Array.isArray(input)) return false
+	if (typeof input !== "object" || !input || Array.isArray(input)) return false
 
 	return Object.values(input).every((value) => {
 		if (typeof value === "string") return true

package/cli/commands/corpus/fetch.tsx

@@ -10,7 +10,8 @@
 
 import { dataRootPath } from "@mailwoman/core/data-root"
 import { extractDelimited } from "@mailwoman/core/scripting/arguments"
-import type { FetchSourceID, FetchSummary } from "@mailwoman/corpus/tools"
+import type { FetchSourceID } from "@mailwoman/corpus/tools/fetch"
+import type { FetchSummary } from "@mailwoman/corpus/tools/fetch/download/network"
 import { Text } from "ink"
 import { PathBuilder } from "path-ts"
 
@@ -123,49 +124,47 @@ export const spec = {
 type Options = OptionsOf<typeof spec>
 
 async function runSource(source: FetchSourceID, options: Options): Promise<FetchSummary> {
-	const {
-		fetchACRASG,
-		fetchADSEE,
-		fetchBan,
-		fetchBDAdresses,
-		fetchBrussels,
-		fetchCORDIS,
-		fetchAnnuaireEducationOverseas,
-		fetchFinessOverseas,
-		fetchGLEIF,
-		fetchVaris,
-		fetchVlaanderenAD,
-		fetchWallonie,
-		fetchCzCuzk,
-		fetchDKAddresses,
-		fetchEMUiAPL,
-		fetchESBizkaia,
-		fetchESCatastro,
-		fetchESGipuzkoa,
-		fetchESNavarra,
-		fetchGCISTW,
-		fetchGeonamesDumps,
-		fetchGeonamesPostal,
-		fetchHoujinJP,
-		fetchHRSA,
-		fetchIMLSPLS,
-		fetchITANAC,
-		fetchJusoKR,
-		fetchLocaldataKR,
-		fetchMatrikkelen,
-		fetchNAD,
-		fetchNLKadaster,
-		fetchNPPES,
-		fetchOpenAddresses,
-		fetchOurAirports,
-		fetchReteaScolara,
-		fetchRyhti,
-		fetchSKInspire,
-		fetchStateHISchools,
-		fetchStateSources,
-		fetchTigerFull,
-		fetchWikidataSubVenue,
-	} = await import("@mailwoman/corpus/tools")
+	const { fetchACRASG } = await import("@mailwoman/corpus/sg/tools/fetch/acra")
+	const { fetchADSEE } = await import("@mailwoman/corpus/ee/tools/fetch/ads")
+	const { fetchBan } = await import("@mailwoman/corpus/fr/tools/fetch/ban")
+	const { fetchBDAdresses } = await import("@mailwoman/corpus/lu/tools/fetch/bd-adresses")
+	const { fetchBrussels } = await import("@mailwoman/corpus/be/tools/fetch/brussels")
+	const { fetchCORDIS } = await import("@mailwoman/corpus/tools/fetch/cordis")
+	const { fetchAnnuaireEducationOverseas } = await import("@mailwoman/corpus/fr/tools/fetch/annuaire-education")
+	const { fetchFinessOverseas } = await import("@mailwoman/corpus/fr/tools/fetch/finess")
+	const { fetchGLEIF } = await import("@mailwoman/corpus/tools/fetch/gleif")
+	const { fetchVaris } = await import("@mailwoman/corpus/lv/tools/fetch/varis")
+	const { fetchVlaanderenAD } = await import("@mailwoman/corpus/tools/fetch/vlaanderen-ad")
+	const { fetchWallonie } = await import("@mailwoman/corpus/be/tools/fetch/wallonie")
+	const { fetchCzCuzk } = await import("@mailwoman/corpus/cz/tools/fetch/cuzk")
+	const { fetchDKAddresses } = await import("@mailwoman/corpus/dk/tools/fetch/inspire")
+	const { fetchEMUiAPL } = await import("@mailwoman/corpus/pl/tools/fetch/emuia")
+	const { fetchESBizkaia } = await import("@mailwoman/corpus/es/tools/fetch/bizkaia")
+	const { fetchESCatastro } = await import("@mailwoman/corpus/es/tools/fetch/catastro")
+	const { fetchESGipuzkoa } = await import("@mailwoman/corpus/es/tools/fetch/gipuzkoa")
+	const { fetchESNavarra } = await import("@mailwoman/corpus/es/tools/fetch/navarra")
+	const { fetchGCISTW } = await import("@mailwoman/corpus/tw/tools/fetch/gcis")
+	const { fetchGeonamesDumps } = await import("@mailwoman/corpus/tools/fetch/geonames/dump")
+	const { fetchGeonamesPostal } = await import("@mailwoman/corpus/tools/fetch/geonames/postal")
+	const { fetchHoujinJP } = await import("@mailwoman/corpus/jp/tools/fetch/houjin")
+	const { fetchHRSA } = await import("@mailwoman/corpus/us/tools/fetch/hrsa")
+	const { fetchIMLSPLS } = await import("@mailwoman/corpus/us/tools/fetch/imls-pls")
+	const { fetchITANAC } = await import("@mailwoman/corpus/it/tools/fetch/anac")
+	const { fetchJusoKR } = await import("@mailwoman/corpus/kr/tools/fetch/juso")
+	const { fetchLocaldataKR } = await import("@mailwoman/corpus/kr/tools/fetch/localdata")
+	const { fetchMatrikkelen } = await import("@mailwoman/corpus/no/tools/fetch/matrikkelen")
+	const { fetchNAD } = await import("@mailwoman/corpus/us/tools/fetch/nad")
+	const { fetchNLKadaster } = await import("@mailwoman/corpus/nl/tools/fetch/kadaster")
+	const { fetchNPPES } = await import("@mailwoman/corpus/us/tools/fetch/nppes")
+	const { fetchOpenAddresses } = await import("@mailwoman/corpus/tools/fetch/openaddresses")
+	const { fetchOurAirports } = await import("@mailwoman/corpus/tools/fetch/ourairports")
+	const { fetchReteaScolara } = await import("@mailwoman/corpus/ro/tools/fetch/retea-scolara")
+	const { fetchRyhti } = await import("@mailwoman/corpus/fi/tools/fetch/ryhti")
+	const { fetchSKInspire } = await import("@mailwoman/corpus/sk/tools/fetch/inspire")
+	const { fetchStateHISchools } = await import("@mailwoman/corpus/us/tools/fetch/state/hi-schools")
+	const { fetchStateSources } = await import("@mailwoman/corpus/us/tools/fetch/state/sources")
+	const { fetchTigerFull } = await import("@mailwoman/corpus/us/tools/fetch/tiger-full")
+	const { fetchWikidataSubVenue } = await import("@mailwoman/corpus/tools/fetch/wikidata-subvenue")
 
 	const base = { outRoot: PathBuilder.from(options.outRoot) }
 
@@ -206,8 +205,8 @@ async function runSource(source: FetchSourceID, options: Options): Promise<Fetch
 			return fetchESCatastro(
 				{
 					...base,
-					provinces: options.provinces === undefined ? undefined : extractDelimited(options.provinces),
-					municipalities: options.municipalities === undefined ? undefined : extractDelimited(options.municipalities),
+					provinces: options.provinces ? extractDelimited(options.provinces) : undefined,
+					municipalities: options.municipalities ? extractDelimited(options.municipalities) : undefined,
 					limit: options.limit,
 				},
 				reportToStderr
@@ -218,7 +217,7 @@ async function runSource(source: FetchSourceID, options: Options): Promise<Fetch
 			return fetchESNavarra(
 				{
 					...base,
-					partitions: options.partitions === undefined ? undefined : extractDelimited(options.partitions),
+					partitions: options.partitions ? extractDelimited(options.partitions) : undefined,
 					limit: options.limit,
 				},
 				reportToStderr
@@ -227,9 +226,9 @@ async function runSource(source: FetchSourceID, options: Options): Promise<Fetch
 			return fetchMatrikkelen(
 				{
 					...base,
-					// Undefined takes both areas the address-source register carries rows for,
+					// Undefined takes both areas the address-source register holds rows for,
 					// `0000` for the mainland and `2100` for Svalbard.
-					areas: options.areas === undefined ? undefined : extractDelimited(options.areas),
+					areas: options.areas ? extractDelimited(options.areas) : undefined,
 				},
 				reportToStderr
 			)
@@ -245,14 +244,14 @@ async function runSource(source: FetchSourceID, options: Options): Promise<Fetch
 			return fetchHoujinJP(base, reportToStderr)
 		case "it-anac":
 			return fetchITANAC(
-				{ ...base, editions: options.editions === undefined ? undefined : extractDelimited(options.editions) },
+				{ ...base, editions: options.editions ? extractDelimited(options.editions) : undefined },
 				reportToStderr
 			)
 		case "juso-kr":
 			return fetchJusoKR({ ...base, month: options.month }, reportToStderr)
 		case "localdata-kr":
 			return fetchLocaldataKR(
-				{ ...base, categories: options.categories === undefined ? undefined : extractDelimited(options.categories) },
+				{ ...base, categories: options.categories ? extractDelimited(options.categories) : undefined },
 				reportToStderr
 			)
 		case "ban":
@@ -277,7 +276,7 @@ async function runSource(source: FetchSourceID, options: Options): Promise<Fetch
 					...base,
 					// Undefined means every country the source's own countryInfo.txt catalogs.
 					// Present dumps are skipped.
-					countries: options.countries === undefined ? undefined : extractDelimited(options.countries),
+					countries: options.countries ? extractDelimited(options.countries) : undefined,
 				},
 				reportToStderr
 			)
@@ -288,7 +287,7 @@ async function runSource(source: FetchSourceID, options: Options): Promise<Fetch
 					// Undefined rather than an empty list when the flag is absent:
 					// the module's own default set is the answer for "fetch what the corpus wants",
 					// and an empty array would fetch no countries while looking deliberate.
-					countries: options.countries === undefined ? undefined : extractDelimited(options.countries),
+					countries: options.countries ? extractDelimited(options.countries) : undefined,
 				},
 				reportToStderr
 			)

package/cli/commands/corpus/golden/expand.tsx

@@ -41,7 +41,7 @@ export const spec = {
 
 const CorpusGoldenExpand: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { expandGolden } = await import("@mailwoman/corpus/tools")
+		const { expandGolden } = await import("@mailwoman/corpus/tools/golden/expand")
 
 		return expandGolden(
 			{

package/cli/commands/corpus/golden/promote.tsx

@@ -35,7 +35,7 @@ export const spec = {
 
 const CorpusGoldenPromote: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { promoteGolden } = await import("@mailwoman/corpus/tools")
+		const { promoteGolden } = await import("@mailwoman/corpus/tools/golden/promote")
 
 		return promoteGolden(
 			{

package/cli/commands/corpus/golden/relabel.tsx

@@ -43,7 +43,7 @@ export const spec = {
 
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { relabelGoldenDirectory } = await import("@mailwoman/corpus/tools")
+		const { relabelGoldenDirectory } = await import("@mailwoman/corpus/tools/golden/relabel-street/directory")
 
 		const report = await relabelGoldenDirectory({
 			input: options.input,

package/cli/commands/corpus/ingest-csv.tsx

@@ -43,7 +43,7 @@ export const spec = {
 
 const CorpusIngestCSV: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { ingestCSV } = await import("@mailwoman/corpus/tools")
+		const { ingestCSV } = await import("@mailwoman/corpus/tools/ingest-csv")
 		// `out` is the CLI's spelling.
 		// `ingestCSV` expects the option `output`.
 		// The command would pass an unread key and silently omit the destination if it spread `rest`.

package/cli/commands/corpus/merge-source.tsx

@@ -33,7 +33,7 @@ export const spec = {
 
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { mergeSourceFiles } = await import("@mailwoman/corpus/tools")
+		const { mergeSourceFiles } = await import("@mailwoman/corpus/tools/overlay/merge-source")
 		const inputs = extractDelimited(options.inputs)
 
 		if (inputs.length < 2) {

package/cli/commands/corpus/migrate/overlays.tsx

@@ -35,7 +35,7 @@ export const spec = {
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
 		const { readLocalJSONFile } = await import("@mailwoman/core/fs/readers")
-		const { baseManifestFiles, localManifestFilePath } = await import("@mailwoman/corpus/tools")
+		const { baseManifestFiles, localManifestFilePath } = await import("@mailwoman/corpus/tools/overlay/manifest")
 		const { migrateOverlayParquet } = await import("@mailwoman/corpus/tools/migrate/overlay-parquet")
 
 		type Manifest = Parameters<typeof baseManifestFiles>[0]

package/cli/commands/corpus/overlay-manifest.tsx

@@ -51,7 +51,7 @@ export const spec = {
 
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { assembleOverlayManifest } = await import("@mailwoman/corpus/tools")
+		const { assembleOverlayManifest } = await import("@mailwoman/corpus/tools/overlay/manifest")
 
 		const parquets = extractDelimited(options.parquet)
 		const sources = extractDelimited(options.source)

package/cli/commands/corpus/slice/index.tsx

@@ -61,13 +61,14 @@ export const spec = {
 		"multilocale-count": stringOption("multilocale row count"),
 		lexicon: stringOption("sub-venue lexicon"),
 		"extracts-dir": stringOption("OSM extract directory"),
-		"poi-db": stringOption("POI database"),
 		"sub-venue-tuples": stringOption("address-context tuples"),
 		"negative-fraction": stringOption("confound-negative fraction"),
+		"venue-names": stringOption("venue, sub-venue: Overture place-names parquet"),
+		"venue-region-fraction": stringOption("venue: share of locality rows that also carry the region"),
 	},
 } as const satisfies CommandSpec
 
-const num = (s: string | undefined): number | undefined => (s == null ? undefined : Number(s))
+const num = (s: string | null | undefined): number | undefined => (s ? Number(s) : undefined)
 
 const CorpusRecipeRun: CommandComponent<typeof spec> = ({ options, args }) => {
 	const state = useCommandTask(async () => {
@@ -96,7 +97,7 @@ const CorpusRecipeRun: CommandComponent<typeof spec> = ({ options, args }) => {
 
 		if (recipe.mode === "generate" && !options.count) throw new CommandError(`recipe "${name}" needs --count <N>`)
 
-		const seed = options.seed != null ? Number(options.seed) : Date.now()
+		const seed = options.seed ? Number(options.seed) : Date.now()
 
 		const opts: RecipeOptions = {
 			output: options.out,
@@ -127,9 +128,10 @@ const CorpusRecipeRun: CommandComponent<typeof spec> = ({ options, args }) => {
 			multilocaleCount: num(options.multilocaleCount),
 			lexicon: options.lexicon,
 			extractsDir: options.extractsDir,
-			poiDB: options.poiDB,
 			subVenueTuples: options.subVenueTuples,
 			negativeFraction: num(options.negativeFraction),
+			venueNames: options.venueNames,
+			venueRegionFraction: num(options.venueRegionFraction),
 		}
 
 		console.error(`▸ recipe "${name}" [${recipe.mode}] seed=${seed} → ${options.out}`)

package/cli/commands/corpus/slice/kryptonite.tsx

@@ -48,7 +48,7 @@ export const spec = {
 
 const CorpusKryptoniteParquet: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { buildKryptoniteOverlay } = await import("@mailwoman/corpus/tools")
+		const { buildKryptoniteOverlay } = await import("@mailwoman/corpus/tools/overlay/kryptonite")
 
 		await buildKryptoniteOverlay(
 			{

package/cli/commands/corpus/slice/translit.tsx

@@ -53,7 +53,7 @@ export const spec = {
 
 const CorpusTranslitParquet: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { buildTranslitOverlay } = await import("@mailwoman/corpus/tools")
+		const { buildTranslitOverlay } = await import("@mailwoman/corpus/tools/overlay/translit")
 
 		await buildTranslitOverlay(
 			{

package/cli/commands/corpus/source-register.tsx

@@ -41,7 +41,7 @@ export const spec = {
 
 const CorpusSourceRegister: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { buildSourceRegister } = await import("@mailwoman/corpus/tools")
+		const { buildSourceRegister } = await import("@mailwoman/corpus/tools/source-register/build")
 
 		if (!options.inventory) throw new Error("--inventory is required")
 
@@ -49,7 +49,7 @@ const CorpusSourceRegister: CommandComponent<typeof spec> = ({ options }) => {
 
 		if (!options.authoredAt) throw new Error("--authored-at is required")
 
-		return await buildSourceRegister({
+		return buildSourceRegister({
 			inventoryPath: options.inventory,
 			sourcesPath: options.sources,
 			outPath: options.out,

package/cli/commands/corpus/split-slice.tsx

@@ -29,7 +29,7 @@ export const spec = {
 
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { splitOverlaySlice } = await import("@mailwoman/corpus/tools")
+		const { splitOverlaySlice } = await import("@mailwoman/corpus/tools/overlay/split-slice")
 
 		return splitOverlaySlice({ input: options.input, outputDir: options.outDir })
 	})

package/cli/commands/corpus/stats.tsx

@@ -32,7 +32,7 @@ export const spec = {
 
 const Cmd: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { buildCorpusStats } = await import("@mailwoman/corpus/tools")
+		const { buildCorpusStats } = await import("@mailwoman/corpus/tools/corpus-stats")
 
 		await buildCorpusStats({
 			parquetPath: options.parquet,

package/cli/commands/corpus/sub/venue/lexicon.tsx

@@ -46,7 +46,7 @@ export const spec = {
  *
  * A bare path keeps region `""`.
  */
-function parseExtracts(extractSpec: string | undefined): Array<{ path: string; region: string }> {
+function parseExtracts(extractSpec: string | null | undefined): Array<{ path: string; region: string }> {
 	if (!extractSpec) return []
 
 	return extractDelimited(extractSpec).map((entry) => {
@@ -60,14 +60,16 @@ function parseExtracts(extractSpec: string | undefined): Array<{ path: string; r
 
 const CorpusSubVenueLexicon: CommandComponent<typeof spec> = ({ options }) => {
 	const state = useCommandTask(async () => {
-		const { generateSubVenueLexicon, readOvertureLayerVintage, readOvertureSubVenues } =
-			await import("@mailwoman/corpus/tools")
+		const { generateSubVenueLexicon } = await import("@mailwoman/corpus/tools/sub/venue/lexicon")
+
+		const { readOvertureLayerVintage, readOvertureSubVenues } =
+			await import("@mailwoman/corpus/tools/overture-subvenue")
 
 		const overtureRows = options.overtureDB
 			? await readOvertureSubVenues({ databasePath: options.overtureDB })
 			: undefined
 
-		return await generateSubVenueLexicon({
+		return generateSubVenueLexicon({
 			wikidataDir: options.wikidataDir,
 			extracts: parseExtracts(options.extracts),
 			overtureRows,

package/cli/commands/corpus/upload.tsx

@@ -8,7 +8,7 @@
  */
 
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { extractDelimited } from "@mailwoman/core/scripting/arguments"
 import { childEnv } from "@mailwoman/core/scripting/utils"
 import type { BuildCorpusManifest } from "@mailwoman/corpus/build"
@@ -91,19 +91,19 @@ interface AssembledCorpusManifest {
 }
 
 /**
- * The assembled corpus manifest's `total_rows`, or `undefined` when no manifest sits at `path`.
+ * The assembled corpus manifest's `total_rows`, or `null` when no manifest sits at `path`.
  *
  * A build without a corpus manifest and a flat-layout entry without one both read
  * `undefined`. {@linkcode refuseShareAlike} then skips the overlay comparison
  * rather than reading a missing file as a corpus with no overlay rows.
  */
-async function assembledRowCount(path: PathBuilderLike): Promise<number | undefined> {
+async function assembledRowCount(path: PathBuilderLike): Promise<number | null> {
 	const { readLocalJSONFile } = await import("@mailwoman/core/fs/readers")
 
 	try {
-		return (await readLocalJSONFile<AssembledCorpusManifest>(path)).total_rows
+		return (await readLocalJSONFile<AssembledCorpusManifest>(path)).total_rows ?? null
 	} catch {
-		return undefined
+		return null
 	}
 }
 
@@ -119,7 +119,7 @@ async function assembledRowCount(path: PathBuilderLike): Promise<number | undefi
  * An unreadable or absent `MANIFEST.json` throws as well.
  * A corpus whose license set cannot be read is an unanswered question rather than a clean one.
  *
- * `corpusRows` is the assembled corpus manifest's own `total_rows`, or `undefined`
+ * `corpusRows` is the assembled corpus manifest's own `total_rows`, or `null`
  * when the upload found no nested corpus directory to read one from.
  * It decides whether the license set answers for every row.
  */
@@ -127,7 +127,7 @@ async function refuseShareAlike(
 	version: string,
 	manifestPath: PathBuilderLike,
 	allow: boolean,
-	corpusRows: number | undefined
+	corpusRows: number | null
 ): Promise<void> {
 	const { readLocalJSONFile } = await import("@mailwoman/core/fs/readers")
 	const { stringifyJSON } = await import("@mailwoman/core/json")

package/cli/commands/coverage/jurisdictions.tsx

@@ -0,0 +1,108 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Implements `mailwoman coverage jurisdictions`, which builds the jurisdiction coverage PMTiles:
+ *   Natural Earth map units carrying a training run's realized draws, the register's sources,
+ *   the address system and the board rows of each jurisdiction.
+ *
+ *   The command requires `tippecanoe` on the path. `mailwoman tiles publish` uploads the result.
+ */
+
+import { ByteFormatter } from "@mailwoman/core/fs/formatters"
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { repoRootPath } from "@mailwoman/core/paths"
+import { readScopeConfig } from "@mailwoman/core/scope-config"
+import { Box, Text } from "ink"
+import { resolvePath } from "path-ts"
+
+import { type CommandSpec, CommandTaskResult, type CommandComponent, useCommandTask } from "#cli-kit"
+
+/**
+ * The maximum zoom level that Tippecanoe supports.
+ */
+const MAX_TILE_ZOOM = 22
+
+/**
+ * The command specification for `mailwoman coverage jurisdictions`.
+ *
+ * The CLI reference page `docs/articles/developers/reference/cli.mdx` is generated
+ * from these option names and descriptions.
+ * The docs check fails when the page is stale.
+ */
+export const spec = {
+	name: "jurisdictions",
+	description: "Build jurisdiction coverage PMTiles.",
+	options: {
+		exposure: {
+			type: "string",
+			default: resolvePath(dataRootPath("exposure", "exposure-realized-v720.json")),
+			description: "Realized-draws report",
+		},
+		config: { type: "string", description: "Training config" },
+		"max-zoom": {
+			type: "number",
+			default: 7,
+			validate: (value) => Number.isInteger(value) && value >= 0 && value <= MAX_TILE_ZOOM,
+			description: "Max zoom",
+		},
+		out: {
+			type: "string",
+			default: resolvePath(dataRootPath("coverage", "jurisdictions-v1.pmtiles")),
+			description: "Output PMTiles",
+		},
+	},
+} as const satisfies CommandSpec
+
+/**
+ * Builds the jurisdiction tiles and renders a summary.
+ */
+const CoverageJurisdictions: CommandComponent<typeof spec> = ({ options }) => {
+	const state = useCommandTask(async () => {
+		const { buildJurisdictionTiles } = await import("#tools/coverage/jurisdictions")
+		const { fetchNaturalEarthFile, readNaturalEarthMapUnits } = await import("#tools/coverage/natural-earth")
+		const { readAddressSystemRegistry } = await import("#tools/dev-tools/codex/address/systems")
+
+		const systems = await readAddressSystemRegistry()
+
+		if (!systems) throw new Error("the address-system registry is missing; run `mailwoman dev generate address-systems`")
+
+		const { resolveTrainingConfig } = await import("#tools/coverage/census")
+		const configPath = resolveTrainingConfig(await readScopeConfig(), { requested: options.config }).path
+
+		return buildJurisdictionTiles({
+			units: await readNaturalEarthMapUnits(await fetchNaturalEarthFile()),
+			exposurePath: options.exposure,
+			configPath,
+			casesRoot: repoRootPath("packages", "mailwoman", "tools", "eval-harness", "gauntlet", "cases"),
+			systems,
+			out: options.out,
+			maxZoom: options.maxZoom,
+		})
+	})
+
+	if (state.status === "error") return <CommandTaskResult state={state} />
+
+	if (state.status === "done") {
+		const done = state.result
+
+		return (
+			<Box flexDirection="column">
+				<Text>
+					<Text color="green">✓</Text> {done.features.toLocaleString()} map units ·{" "}
+					{done.jurisdictions.toLocaleString()} jurisdictions · {ByteFormatter.formatIEC(done.pmtilesBytes)}
+				</Text>
+				<Text dimColor>
+					{done.unownedUnits.length} units without a jurisdiction · jurisdictions without a unit:{" "}
+					{done.unmappedJurisdictions.join(" ") || "none"}
+				</Text>
+				<Text dimColor>{done.out}</Text>
+			</Box>
+		)
+	}
+
+	return <Text>building jurisdiction tiles…</Text>
+}
+
+export default CoverageJurisdictions

package/cli/commands/data/bom.tsx

@@ -11,7 +11,7 @@
  */
 
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalTextFile } from "@mailwoman/core/fs/writers"
 import { repoRootPathBuilder } from "@mailwoman/core/paths"
 

package/cli/commands/data/coverage.tsx

@@ -67,7 +67,7 @@ const CoverageCommand: CommandComponent<typeof spec> = ({ options }) => {
 			return { ok: true }
 		}
 
-		const wanted = options.countries === undefined ? undefined : splitCountryCodes(options.countries)
+		const wanted = options.countries ? splitCountryCodes(options.countries) : undefined
 
 		writeRawStdout(render(report, wanted))