@mailwoman/corpus 10.1.0 → 10.2.1

package/lib/no/tools/fetch/matrikkelen.ts

@@ -10,7 +10,7 @@
  *   `#no/adapters/matrikkelen/adapter` reads `kommunenummer` to decide a row's country, and
  *   municipality 2100 is Svalbard rather than the mainland. Geonorge publishes the dataset per area
  *   from one 375-entry area list, and the two entries this repository reads are `0000` `Hele landet`
- *   and `2100` `Svalbard`. The mainland extract carries no Svalbard row, so taking only `0000` would
+ *   and `2100` `Svalbard`. The mainland extract has no Svalbard row, so taking only `0000` would
  *   leave `SJ` with no rows while the adapter still claimed to cover it.
  *
  *   Each area is a separate archive at the dataset's conventional download path, so no download
@@ -20,11 +20,11 @@
  *
  *   ## Why the member is extracted
  *
- *   The adapter opens `opts.inputPath` with `CSVSpliterator.fromAsync`, which reads a delimited file
- *   rather than an archive, so the member is written out beside the archive it came from. The member
- *   is named `matrikkelenAdresse.csv` in every area's archive, inside a directory named after the
- *   archive, so each area is written under its own area-code directory and the publisher's own file
- *   name is kept.
+ *   The adapter opens `opts.inputPath` with `CSVSpliterator.fromAsync`. That reader takes a
+ *   delimited file rather than an archive, so the member is written out beside the archive it came
+ *   from. The member is `matrikkelenAdresse.csv` in every area's archive, inside a directory whose
+ *   name follows the archive. Each area is written under its own area-code directory, and the
+ *   publisher's own file name is kept.
  *
  *   The archive is kept rather than removed, because its sha256 is the value the address-source
  *   register records for the publication and the member's is not.
@@ -40,14 +40,14 @@
  *
  *   A renamed column reaches the adapter as an empty string on every row rather than as an error, so
  *   the extract's header is read through the same `CSVSpliterator` the adapter uses and checked
- *   against the nine columns the adapter indexes by name. The file's first column name carries a
- *   byte-order mark, and none of the nine is that column, so the check does not depend on the mark
- *   being stripped.
+ *   against the nine columns the adapter indexes by name. The file's first column name has a
+ *   byte-order mark, and none of the nine is that column, so the check does not depend on stripping
+ *   the mark.
  */
 
 import { APIClient } from "@mailwoman/core/api"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { tryStat } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { extractZipEntry } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"
@@ -63,22 +63,27 @@ import { assertHeaderColumns, readDelimitedHeader } from "#tools/fetch/header"
  */
 export interface MatrikkelenArea {
 	/**
-	 * The area code, which is also the directory each area is written under.
+	 * The area code.
+	 * Each area is written under this directory.
 	 */
 	code: string
 	/**
-	 * The area name as the download path spells it, which is not always the list's `name`:
-	 * area `0000` is named `Hele landet` in the list and `Norge` in the path.
+	 * The area name as the download path spells it.
+	 *
+	 * That name differs from the list's `name`: the list calls area `0000` `Hele landet`,
+	 * and the path calls it `Norge`.
 	 */
 	pathName: string
 }
 
 /**
- * The areas a fetch takes when a caller names none.
+ * The areas a fetch takes when a caller gives no codes.
  *
- * `0000` is the mainland and `2100` is Svalbard, which are the two areas the
- * address-source register carries rows for.
- * Svalbard is also published as `fylke` 21, which holds the same rows as kommune 2100.
+ * `0000` is the mainland and `2100` is Svalbard.
+ * These are the two areas the address-source register holds rows for.
+ *
+ * Svalbard is also published as `fylke` 21.
+ * That area holds the same rows as kommune 2100.
  */
 export const MATRIKKELEN_AREAS: readonly MatrikkelenArea[] = [
 	{ code: "0000", pathName: "Norge" },
@@ -86,7 +91,8 @@ export const MATRIKKELEN_AREAS: readonly MatrikkelenArea[] = [
 ]
 
 /**
- * The area code of the whole-country extract, which carries every mainland municipality.
+ * The area code of the whole-country extract.
+ * That extract holds every mainland municipality.
  */
 export const MATRIKKELEN_MAINLAND_AREA = "0000"
 
@@ -104,7 +110,8 @@ export const MATRIKKELEN_PROJECTION = "4258"
 export const MATRIKKELEN_DOWNLOAD_ROOT = "https://nedlasting.geonorge.no/geonorge/Basisdata/MatrikkelenAdresse/CSV"
 
 /**
- * The dataset's metadata record, which is where the elected license is stated.
+ * The dataset's metadata record.
+ * That record states the elected license.
  */
 export const MATRIKKELEN_METADATA_URL =
 	"https://kartkatalog.geonorge.no/api/getdata/f7df7a18-b30f-4745-bd64-d0863812350c"
@@ -153,7 +160,8 @@ export const MATRIKKELEN_LICENSE = "CC-BY-4.0"
 const SLUG = MATRIKKELEN_ADAPTER_ID
 
 /**
- * The archive's name for one area, which is also the name it is written under.
+ * The archive's name for one area.
+ * The fetch writes the archive under this name.
  */
 export function matrikkelenArchiveFilename(area: MatrikkelenArea): string {
 	return `Basisdata_${area.code}_${area.pathName}_${MATRIKKELEN_PROJECTION}_MatrikkelenAdresse_CSV.zip`
@@ -171,8 +179,9 @@ export function matrikkelenArchiveURL(area: MatrikkelenArea): string {
  *
  * `last_modified` is the service's own header and the one freshness signal it offers,
  * so a changed value is the one reason to download that area again.
- * `bytes` and `sha256` describe the archive, which is the artifact the
- * address-source register records a digest for.
+ * `bytes` and `sha256` describe the archive.
+ *
+ * The address-source register records a digest for that artifact.
  */
 export interface MatrikkelenFileManifest extends SourceManifest {
 	area_code: string
@@ -183,18 +192,19 @@ export interface MatrikkelenFileManifest extends SourceManifest {
 }
 
 /**
- * The recorded entry for one area, or `undefined` where the manifest holds none that can decide a skip.
+ * The recorded entry for one area, or `null` where the manifest holds none that can decide a skip.
+ *
+ * `loadCollectionFiles` reads the shared collection shape.
+ * That shape states the fields common to every source's manifest and omits this source's area fields.
  *
- * `loadCollectionFiles` reads the shared collection shape, which states what every
- * source's manifest states and not this source's area fields.
  * An entry written before those fields existed, or written with no stated `last_modified`,
  * cannot answer whether the archive on disk is current, and this reports that as
  * no recorded entry rather than as an entry that disagrees.
  */
-export function recordedMatrikkelenArea(entry: SourceManifest | undefined): MatrikkelenFileManifest | undefined {
-	const candidate = entry as (Partial<MatrikkelenFileManifest> & SourceManifest) | undefined
+export function recordedMatrikkelenArea(entry: SourceManifest | null): MatrikkelenFileManifest | null {
+	const candidate = entry as (Partial<MatrikkelenFileManifest> & SourceManifest) | null
 
-	if (!candidate) return undefined
+	if (!candidate) return null
 
 	const complete =
 		typeof candidate.area_code === "string" &&
@@ -203,15 +213,15 @@ export function recordedMatrikkelenArea(entry: SourceManifest | undefined): Matr
 		typeof candidate.member_bytes === "number" &&
 		typeof candidate.member_sha256 === "string"
 
-	return complete ? (candidate as MatrikkelenFileManifest) : undefined
+	return complete ? (candidate as MatrikkelenFileManifest) : null
 }
 
 /**
  * What the service's HEAD response states about one area's archive.
  *
  * Both fields read `null` where the header is absent, rather than an empty string or zero.
- * An absent `last-modified` is the service declining to state a version, which is a
- * different fact from a version that happens to match the one on disk.
+ * An absent `last-modified` is the service declining to state a version.
+ * That differs from a version that matches the one on disk.
  */
 export interface MatrikkelenPublication {
 	lastModified: string | null
@@ -221,8 +231,8 @@ export interface MatrikkelenPublication {
 /**
  * Reads the service's HEAD response for one area.
  *
- * Separate from {@linkcode downloadMatrikkelen} because this one request carries the whole freshness
- * decision, and the download itself runs on global `fetch`, which a unit test cannot intercept.
+ * Separate from {@linkcode downloadMatrikkelen}: this request supplies the whole freshness decision.
+ * The download itself runs on global `fetch`, so a unit test cannot intercept it.
  */
 export async function readMatrikkelenPublication(
 	client: Pick<APIClient, "fetch">,
@@ -248,8 +258,9 @@ export async function readMatrikkelenPublication(
  * Whether one area's archive and extract on disk are the ones the service currently serves.
  *
  * A skip requires the service to state a `last-modified` value.
- * Where it states none, both sides read `null` and an equality test would hold,
- * which would keep an archive of unknown age for as long as the service stayed silent.
+ * Where it states none, both sides read `null` and an equality test would hold.
+ *
+ * That would keep an archive of unknown age for as long as the service stayed silent.
  */
 export function matrikkelenPublicationIsRecorded(
 	recorded: MatrikkelenFileManifest,
@@ -257,7 +268,7 @@ export function matrikkelenPublicationIsRecorded(
 	memberBytesOnDisk: number,
 	publication: MatrikkelenPublication
 ): boolean {
-	if (publication.lastModified === null) return false
+	if (!publication.lastModified) return false
 
 	return (
 		recorded.last_modified === publication.lastModified &&
@@ -267,12 +278,12 @@ export function matrikkelenPublicationIsRecorded(
 }
 
 /**
- * The areas named by their codes, or every area in {@linkcode MATRIKKELEN_AREAS}.
+ * The areas for the given codes, or every area in {@linkcode MATRIKKELEN_AREAS}.
  *
- * @throws Naming the codes that the area list does not carry, so a typed code
- * reports itself rather than reading as a fetch of no areas.
+ * @throws When the area list holds no matching area, the error states the unmatched codes.
+ * A typed code then reports itself rather than reading as a fetch of no areas.
  */
-export function matrikkelenAreasFor(codes: readonly string[] | undefined): readonly MatrikkelenArea[] {
+export function matrikkelenAreasFor(codes: readonly string[] | null): readonly MatrikkelenArea[] {
 	if (!codes?.length) return MATRIKKELEN_AREAS
 
 	const wanted = codes.map((code) => code.trim()).filter((code) => code.length > 0)
@@ -309,14 +320,15 @@ export interface DownloadMatrikkelenOptions {
 /**
  * Downloads one area's archive, extracts the member the adapter reads and checks its header.
  *
- * @returns The manifest entry for the area, which the collection manifest carries.
+ * @returns The manifest entry for the area.
+ * The collection manifest holds it.
  */
 export async function downloadMatrikkelenArea(
 	client: Pick<APIClient, "fetch">,
 	area: MatrikkelenArea,
 	options: {
 		outputDir: PathBuilderLike
-		recorded?: MatrikkelenFileManifest
+		recorded?: MatrikkelenFileManifest | null
 		force?: boolean
 		retries?: number
 		retryDelayMs?: number
@@ -368,8 +380,8 @@ export async function downloadMatrikkelenArea(
 
 	report?.(`  ✓ ${ByteFormatter.formatIEC(bytes)}  sha256=${sha256}`)
 
-	// The member sits inside a directory named after the archive, so the selector matches
-	// the name's tail rather than the whole archive-internal path.
+	// The member sits inside a directory whose name follows the archive, so the selector
+	// matches the name's tail rather than the whole archive-internal path.
 	const memberBytes = await extractZipEntry(archivePath, /(?:^|\/)matrikkelenAdresse\.csv$/u, memberPath)
 
 	const header = await readDelimitedHeader(memberPath, MATRIKKELEN_DELIMITER)
@@ -428,7 +440,7 @@ export async function downloadMatrikkelen(
 		try {
 			const { entry, downloaded } = await downloadMatrikkelenArea(client, area, {
 				outputDir: destDir,
-				recorded: recordedMatrikkelenArea(entries.get(matrikkelenArchiveFilename(area))),
+				recorded: recordedMatrikkelenArea(entries.get(matrikkelenArchiveFilename(area)) ?? null),
 				force: options.force,
 				retries: options.retries,
 				retryDelayMs: options.retryDelayMs,
@@ -471,7 +483,7 @@ export async function downloadMatrikkelen(
  * The path `#no/adapters/matrikkelen/adapter` reads for one area, given the root a fetch wrote under.
  *
  * The area is a parameter because the adapter covers two jurisdictions and reads one
- * file at a time: `0000` carries Norway's rows and `2100` carries Svalbard's.
+ * file at a time: `0000` holds Norway's rows and `2100` holds Svalbard's.
  */
 export function matrikkelenInputPath(
 	outRoot: BaseFetchOptions["outRoot"],
@@ -501,7 +513,7 @@ export async function fetchMatrikkelen(
 	options: FetchMatrikkelenOptions,
 	report?: (line: string) => void
 ): Promise<FetchSummary> {
-	const areas = matrikkelenAreasFor(options.areas)
+	const areas = matrikkelenAreasFor(options.areas ?? null)
 
 	await using client = new APIClient({ displayName: SLUG, retry: true })
 

package/lib/parquet/duckdb.ts

@@ -31,7 +31,6 @@ export type DisposableDuckDB = import("@duckdb/node-api").DuckDBConnection & Dis
  * A `COUNT(DISTINCT …)` over `v0.6.0-register-surface`'s 697,675,170 train rows did
  * that twice on 2026-09-28, with a second corpus tool running beside it.
  *
- * The default is a quarter because it has to bound the host rather than one query.
  * Two instances at half the host exceed it together.
  *
  * That case took the machine down.
@@ -43,6 +42,8 @@ export type DisposableDuckDB = import("@duckdb/node-api").DuckDBConnection & Dis
  * That is the failure to prefer.
  *
  * A caller that knows it holds the host by itself passes a larger `memoryLimitBytes`.
+ *
+ * @defaultValue a quarter because it has to bound the host rather than one query.
  */
 export const DUCKDB_MEMORY_SHARE = 0.25
 
@@ -52,26 +53,28 @@ export const DUCKDB_MEMORY_SHARE = 0.25
 export interface DuckDBLimits {
 	/**
 	 * Bytes one instance may hold before it spills.
-	 * Defaults to {@linkcode DUCKDB_MEMORY_SHARE} of host memory.
+	 * @defaultValue {@linkcode DUCKDB_MEMORY_SHARE} of host memory.
 	 */
 	memoryLimitBytes?: number
 
 	/**
 	 * Worker threads.
-	 * Defaults to DuckDB's own choice.
 	 *
 	 * A build phase that runs DuckDB beside other work sets this, because each thread
 	 * holds its own share of the memory limit and the default takes every core.
+	 *
+	 * @defaultValue DuckDB's own choice.
 	 */
 	threads?: number
 
 	/**
 	 * Where a spill is written.
-	 * Defaults to the data root's `tmp/duckdb`.
 	 *
 	 * The default sits under the data root rather than in the system temporary directory,
 	 * because a spill from a corpus-sized query is tens of gigabytes and `/tmp` is commonly a
 	 * memory-backed filesystem, where spilling to it consumes the memory the spill exists to release.
+	 *
+	 * @defaultValue the data root's `tmp/duckdb`.
 	 */
 	temporaryDirectory?: string
 }

package/lib/parquet/readers.ts

@@ -8,7 +8,7 @@
  *   Both throw for an unreadable file, so a caller cannot mistake a read failure for an empty file.
  */
 
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import type { PathBuilderLike } from "path-ts"
 
 import { escapeSQLString, openDuckDB } from "#parquet/duckdb"
@@ -26,7 +26,7 @@ export async function readParquetRows<T>(path: PathBuilderLike, options: Parquet
 		throw new Error(`No parquet file at ${path}`)
 	}
 
-	return await Array.fromAsync(openParquetRowStream<T>(path, options))
+	return Array.fromAsync(openParquetRowStream<T>(path, options))
 }
 
 /**
@@ -40,7 +40,7 @@ export async function tryReadParquetRows<T>(
 ): Promise<T[] | null> {
 	if (!(await pathExists(path))) return null
 
-	return await Array.fromAsync(openParquetRowStream<T>(path, options))
+	return Array.fromAsync(openParquetRowStream<T>(path, options))
 }
 
 /**

package/lib/parquet/schema.ts

@@ -163,7 +163,7 @@ export const LABELED_ROW_SCHEMA: ParquetSchemaDefinition<ParquetRow> = {
 export function rowToParquet(row: LabeledRow): ParquetRow {
 	const { span_starts, span_ends, span_tags } = row
 
-	if (span_starts === undefined || span_ends === undefined || span_tags === undefined) {
+	if (!span_starts || !span_ends || !span_tags) {
 		throw new Error(
 			`rowToParquet: row is missing the char-offset span triple (#519) — ` +
 				`span_starts=${span_starts !== undefined} span_ends=${span_ends !== undefined} span_tags=${span_tags !== undefined} ` +

package/lib/parquet/writers.ts

@@ -31,7 +31,8 @@
  *   the head of the next. A reader must therefore take a file's sources from all of its rows.
  */
 
-import { pathExists, readLocalJSONFile, tryStat } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { pathExists, tryStat } from "@mailwoman/core/fs/readers/stat"
 import { openWriteStream, type WriteStream } from "@mailwoman/core/fs/streams"
 import { temporaryDirectory } from "@mailwoman/core/fs/temporary"
 import { makeDirectories, writeLocalBuffer, writeLocalJSONFile } from "@mailwoman/core/fs/writers"
@@ -200,7 +201,7 @@ export interface WriteParquetSplitsOptions {
 	/**
 	 * Max rows per `.parquet` file.
 	 *
-	 * Default 1,000,000.
+	 * @defaultValue `1,000,000`
 	 */
 	rowsPerFile?: number
 

package/lib/pl/adapters/emuia/adapter.ts

@@ -15,25 +15,25 @@
  * The payload is the Polish register's own schema rather than the harmonized INSPIRE model: a member's
  * element names are the register's columns and every address value is inline, so there is no
  * `ad:ThoroughfareName` to join to and no `xlink:href` to resolve. Read with that same function over
- * 500 members across ten windows spread through the service, a member carries 21 children and never a
- * twenty-second: `gml:boundedBy`, `ms:msGeometry` and nineteen columns, which are `ms:id`,
+ * 500 members across ten windows spread through the service, a member holds 21 children and never a
+ * twenty-second. The children are `gml:boundedBy`, `ms:msGeometry` and these nineteen columns: `ms:id`,
  * `ms:gml_id`, `ms:lokalnyid`, `ms:jednostkaadmnistracyjna`, `ms:miejscowosc`,
  * `ms:miejscowosc_lower`, `ms:czescmiejscowosci`, `ms:ulica`, `ms:ulica_pol`, `ms:ulica_skr`,
  * `ms:numer`, `ms:kod`, `ms:teryt`, `ms:simc`, `ms:ulic`, `ms:status`, `ms:data_od`, `ms:wazny_od`
  * and `ms:adres`. The adapter reads `ulica` as the street, `numer` as the house number, `kod` as the
  * postcode and `miejscowosc` as the locality, with `czescmiejscowosci` as the part of the locality
- * where the publisher populates it. Every column is written on every member, and three carry a value
+ * where the publisher populates it. Every column is written on every member, and three hold a value
  * on every one of the 500: `numer`, `kod` and `miejscowosc`. Two are written and populated on none:
  * `status` and `czescmiejscowosci`.
  *
  * A row with no street is the ordinary rural case rather than a defect. Over those 500 members 299
- * carry a street and 201 leave `ms:ulica` written and empty, and the publisher's own `ms:adres` writes
+ * hold a street and 201 leave `ms:ulica` written and empty, and the publisher's own `ms:adres` writes
  * the streetless form as locality and number: `Księżyki 5`, `Jawor 19`. The adapter emits those rows
- * with a locality and a number and no street, which is the address Poland delivers to.
+ * with a locality and a number and no street. Poland delivers to that form.
  *
- * `ms:jednostkaadmnistracyjna` carries the administrative path as a PostgreSQL array literal,
+ * `ms:jednostkaadmnistracyjna` holds the administrative path as a PostgreSQL array literal,
  * `{Polska,łódzkie,"Piotrków Trybunalski","Piotrków Trybunalski"}`, whose second element is the
- * voivodeship. It is left unread: a Polish postal address does not carry the voivodeship, the codex
+ * voivodeship. It is left unread: a Polish postal address does not include the voivodeship, the codex
  * layout for `PL` leaves a `region` component unplaced, and parsing a quoted array literal to reach a
  * value the layout leaves unplaced would cost a parse and reach no rendered component.
  *
@@ -46,7 +46,7 @@
  * GUGiK's dataset record states one condition of use, in `otherConstraints`: `Brak warunków dostępu i
  * użytkowania`, no conditions for access and use. The address-source register elected that and names
  * no license instrument, so no SPDX identifier exists and the publisher's own words are the label the
- * adapter stamps on every row. Crediting GUGiK stays good practice and the statement requires it
+ * adapter stamps on every row. GUGiK credit remains good practice and the statement requires it
  * nowhere.
  *
  * The adapter honors `opts.limit` and `opts.signal`. `opts.country` is optional and accepts only `PL`.
@@ -99,8 +99,8 @@ const ADDRESS_ELEMENT = "ms:AD.Address"
  *
  * `textAtPath` answers an empty string for an element the publisher wrote
  * and left blank and `undefined` for one it omitted.
- * Both are an absent value for this adapter's purposes, and all 500 members measured carried
- * every one of the nineteen columns, so the distinction carries no information on this service.
+ * Both are an absent value for this adapter's purposes, and all 500 members measured held
+ * every one of the nineteen columns, so the distinction has no effect on this service.
  */
 function column(feature: MarkupElement, name: string): string {
 	return (textAtPath(feature, `ms:${name}`) ?? "").trim()
@@ -170,8 +170,8 @@ export function createEMUiAAdapter(): CorpusAdapter {
 
 					const { raw, components: aligned } = rendered
 
-					// `ms:gml_id` names the upstream municipal register and its record, which is
-					// the identifier worth keeping; `ms:id` is this service's own row number.
+					// Keep `ms:gml_id`: it gives the upstream municipal register and its record.
+					// `ms:id` is this service's own row number.
 					const seed = column(feature, "gml_id") || column(feature, "id")
 
 					const sourceID = seed ? `${EMUIA_ADAPTER_ID}-${seed}` : stableSourceID(EMUIA_ADAPTER_ID, aligned)

package/lib/pl/tools/fetch/emuia.ts

@@ -9,7 +9,7 @@
  * Główny Urząd Geodezji i Kartografii publishes the Państwowy Rejestr Granic through MapServer at
  * {@linkcode PL_EMUIA_WFS}. Its dataset record states one condition of use in `otherConstraints`,
  * `Brak warunków dostępu i użytkowania` — no conditions for access and use — which the
- * address-source register elected. No license instrument is named, so the publisher's own words are
+ * address-source register elected. No license instrument is recorded, so the publisher's own words are
  * the label, and that statement grants the reproduction a paged harvest performs.
  *
  * `#tools/fetch/wfs-harvest` owns the page read, the appending, the manifest and the resumption.
@@ -35,7 +35,7 @@
  *    harvest ends on the first page that returns no features. The size is read from the service when
  *    a caller asks for it, by `countWFSFeaturesByPaging`, and no count is written into this file.
  * 5. The service honors a sort. `ImplementsSorting` is `TRUE`, `sortBy=ms:id` answers HTTP 200 and
- *    `sortBy=ms:id D` returns the register's last rows first, which proves the parameter is applied.
+ *    `sortBy=ms:id D` returns the register's last rows first. That proves the parameter is applied.
  *    `PagingIsTransactionSafe` is `FALSE`, which is the service stating that a paged sequence may
  *    shift under edits made while it is being read. The sort bounds that shift to the rows whose
  *    `ms:id` changed rather than leaving the whole sequence unordered.
@@ -45,7 +45,7 @@
  * fails reports the first gap rather than the extent. The figure is therefore reported with the date
  * it was taken, never stored as a constant: the register recorded 8,625,921 on 2026-10-01, and on
  * 2026-10-02 `startIndex=8626950` returned one feature while `startIndex=8626951` returned none, so
- * the service then held 8,626,951. That is 1,030 more than the day before, which is ordinary
+ * the service then held 8,626,951. Such growth is ordinary
  * business for a municipal address register.
  *
  * At 1,000 features per page and 1,607,180 bytes per page, a full harvest at that size is 8,627
@@ -88,7 +88,8 @@ export const PL_EMUIA_WFS = "https://mapy.geoportal.gov.pl/wss/service/INSPIRE/A
 export const PL_EMUIA_TYPE_NAME = "ms:AD.Address"
 
 /**
- * The output format the harvest asks for, which is the first the service advertises.
+ * The output format the harvest asks for.
+ * The service advertises it first.
  */
 export const PL_EMUIA_OUTPUT_FORMAT = "application/gml+xml; version=3.2"
 
@@ -268,7 +269,7 @@ export async function harvestEMUiAPL(
 
 	options.report?.(`  Feature count: ${featureCount.count ?? "not stated"} — ${featureCount.because}`)
 
-	return await harvestPagedWFS({
+	return harvestPagedWFS({
 		context: CONTEXT,
 		source: SLUG,
 		outputDir: options.outputDir,
@@ -280,8 +281,8 @@ export async function harvestEMUiAPL(
 			sortBy: PL_EMUIA_SORT_BY,
 		},
 		license: LICENSE,
-		// The elected statement names no attribution clause.
-		// Crediting GUGiK stays good practice.
+		// The elected statement states no attribution clause.
+		// GUGiK credit stays good practice.
 		attribution: "",
 		featureCount,
 		pageSize: Math.min(options.pageSize ?? PL_EMUIA_PAGE_SIZE, PL_EMUIA_PAGE_SIZE),
@@ -335,7 +336,7 @@ export async function fetchEMUiAPL(
 	// and the manifest records what was asked for rather than what arrived.
 	const pageSize = Math.min(options.pageSize ?? PL_EMUIA_PAGE_SIZE, PL_EMUIA_PAGE_SIZE)
 
-	return await runWFSHarvest(
+	return runWFSHarvest(
 		{
 			slug: SLUG,
 			outRoot: options.outRoot,
@@ -346,7 +347,7 @@ export async function fetchEMUiAPL(
 			client: options.client,
 			maxPages: options.maxPages,
 			harvest: async (client) =>
-				await harvestEMUiAPL(client, {
+				harvestEMUiAPL(client, {
 					outputDir: options.outRoot(SLUG),
 					pageSize,
 					maxPages: options.maxPages,

package/lib/recipes/bare/postcode.ts

@@ -10,7 +10,7 @@
 
 import { isNLPostcodeKey } from "@mailwoman/codex/nl"
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { SeededRandom } from "@mailwoman/core/utils"
 import { computeQueryShape } from "@mailwoman/query-shape"
 import { isPostcodeFormat } from "@mailwoman/query-shape/known-formats"

package/lib/recipes/boundary-stress.ts

@@ -73,7 +73,7 @@ export const boundaryStressRecipe: CorpusRecipe = {
 		let skipped = 0
 
 		for (let i = 0; i < count; i++) {
-			const row = synthesizeBoundaryStressRow(undefined, { random, forceTemplate: pickTemplate(random) })
+			const row = synthesizeBoundaryStressRow(null, { random, forceTemplate: pickTemplate(random) })
 			const country = row.locale.split("-")[1] ?? "US"
 			// One resolution for both, because `source_id` includes the source as its prefix
 			// and a pair that disagreed would name a source no row of this output declares.

package/lib/recipes/house-venue.ts

@@ -10,6 +10,7 @@
  *   it replaced.
  */
 
+import { layoutForCountry, layoutPrintsTag } from "@mailwoman/codex/address/layouts"
 import { makeLcg } from "@mailwoman/core/utils"
 
 import {
@@ -58,9 +59,12 @@ export const houseVenueRecipe: CorpusRecipe = {
 		for await (const tuple of readTuples(opts.input)) {
 			read++
 
-			// FR renders without a region (postcode-before-locality tail — the run-2 contingency),
-			// so an empty region is valid there and stays required everywhere else.
-			if (!tuple.locality || !tuple.postcode || !tuple.country || (!tuple.region && tuple.country !== "FR")) {
+			// A region is required where the country's layout prints one.
+			// The FR layout prints none, so an FR tuple without a region is whole.
+			const layout = tuple.country ? layoutForCountry(tuple.country) : null
+			const regionRequired = layout ? layoutPrintsTag(layout, "region") : true
+
+			if (!tuple.locality || !tuple.postcode || !tuple.country || (!tuple.region && regionRequired)) {
 				skipped++
 
 				continue

package/lib/recipes/intersection.ts

@@ -35,7 +35,7 @@
 import type { DuckDBConnection } from "@duckdb/node-api"
 import type { ComponentTag } from "@mailwoman/codex/component"
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalJSONFile } from "@mailwoman/core/fs/writers"
 import { stringifyJSON } from "@mailwoman/core/json"
 import { repoRootPath } from "@mailwoman/core/paths"
@@ -396,7 +396,7 @@ function auditRow(row: LabeledRow, components: Partial<Record<ComponentTag, stri
 	}
 
 	for (const [tag, value] of Object.entries(components)) {
-		if (value == null) continue
+		if (!value) continue
 		const indices = span_tags.map((t, i) => (t === tag ? i : -1)).filter((i) => i >= 0)
 
 		if (indices.length !== 1) {

package/lib/recipes/po/box/cedex/recipe.ts

@@ -23,7 +23,7 @@ import {
 	US_EVAL_SOURCE,
 	US_TRAIN_SOURCES,
 } from "#recipes/po/box/cedex/sources"
-import type { AUTuple, NZTuple, Rendered, USTuple } from "#recipes/po/box/cedex/types"
+import type { Rendered, USTuple } from "#recipes/po/box/cedex/types"
 import { renderPmbUs, renderPoBoxUs } from "#recipes/po/box/cedex/us"
 import { CLASS_MIX } from "#recipes/po/box/cedex/vocabulary"
 import { recipeSourceID, type CanonicalRecipeRow, type CorpusRecipe } from "#recipes/scaffold"
@@ -86,8 +86,8 @@ export const poBoxCedexRecipe: CorpusRecipe = {
 
 		console.error(`  GeoNames CA: QC ${qcAll.length}→${qcPool.length}, ON ${onAll.length}→${onPool.length}`)
 
-		const auAll = (await readPostalTuples(GEONAMES_POSTAL_AU, { withState: true })) as AUTuple[],
-			nzAll = (await readPostalTuples(GEONAMES_POSTAL_NZ, { withState: false })) as NZTuple[]
+		const auAll = await readPostalTuples(GEONAMES_POSTAL_AU, { withState: true })
+		const nzAll = await readPostalTuples(GEONAMES_POSTAL_NZ, { withState: false })
 
 		const auPool = auAll.filter((tuple) => isHoldoutLocality(tuple.locality) === opts.golden),
 			nzPool = nzAll.filter((tuple) => isHoldoutLocality(tuple.locality) === opts.golden)

package/lib/recipes/po/box/cedex/sources.ts

@@ -5,7 +5,7 @@
 import { isAuPostcode, isAuStateAbbreviation } from "@mailwoman/codex/au"
 import { isNZPostcode } from "@mailwoman/codex/nz"
 import { dataRootPath } from "@mailwoman/core/data-root"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { readZipEntry } from "@mailwoman/core/fs/zip"
 import type { PathBuilderLike } from "path-ts"
 import { TextSpliterator, TSVSpliterator } from "spliterator"
@@ -156,6 +156,16 @@ export async function readCaLocalities(admin1: string): Promise<string[]> {
 	return [...localities]
 }
 
+export function readPostalTuples(
+	source: { zip: PathBuilderLike; txt: string },
+	opts: { withState: true }
+): Promise<AUTuple[]>
+
+export function readPostalTuples(
+	source: { zip: PathBuilderLike; txt: string },
+	opts: { withState: false }
+): Promise<NZTuple[]>
+
 export async function readPostalTuples(
 	source: { zip: PathBuilderLike; txt: string },
 	opts: { withState: boolean }
@@ -181,7 +191,9 @@ export async function readPostalTuples(
 		const key = `${locality}|${postcode}`.toLowerCase()
 
 		if (seen.has(key)) continue
+
 		seen.add(key)
+
 		tuples.push(opts.withState ? { locality, region, postcode } : { locality, postcode })
 	}