@mailwoman/corpus 10.1.0 → 10.2.0

package/lib/dk/adapters/inspire/adapter.ts

@@ -14,27 +14,26 @@
  * `@mailwoman/sqlite`'s Kysely client. The file is a published artifact and is opened read-only.
  *
  * The INSPIRE address model is normalized, so one address is a join rather than a row. The `address`
- * table carries the locator designators and a reference per component. The street name and the
- * postcode live in `thoroughfarename` and `postaldescriptor` and are reached through
- * `component_thoroughfarename` and `component_postaldescriptor`. Both resolve for every row of the
- * measured file, and a reference that does not resolve raises
+ * table holds the locator designators and a reference per component. The street name and the postcode
+ * live in `thoroughfarename` and `postaldescriptor`, reached through `component_thoroughfarename` and
+ * `component_postaldescriptor`. An unresolved reference raises
  * {@linkcode UnresolvedAddressComponentError} rather than yielding an address missing its street.
  *
- * The adapter reads `locator_designator_1_designator` as `house_number`, which already carries any
- * letter (`2A`, `68A`); `thoroughfarename.name_name` as `street`; `postaldescriptor.postcode` and
- * `postname` as `postcode` and `locality`. Denmark writes a floor and a door after the house number,
- * and the publisher splits them across `locator_designator_2_designator` and
- * `locator_designator_3_designator`; the adapter joins the two into one `unit`, because the Danish
- * address layout places `unit` and leaves `level` unplaced.
+ * The adapter reads `locator_designator_1_designator` as `house_number`. That column already holds
+ * any letter (`2A`, `68A`). It reads `thoroughfarename.name_name` as `street`, and
+ * `postaldescriptor.postcode` and `postname` as `postcode` and `locality`. Denmark writes a floor
+ * and a door after the house number, and the publisher splits them across
+ * `locator_designator_2_designator` and `locator_designator_3_designator`. The adapter joins the two
+ * into one `unit`, because the Danish address layout places `unit` and leaves `level` unplaced.
  *
- * The file carries no region column that belongs in an address. `component_adminunitname_2` and
+ * The file holds no region column that belongs in an address. `component_adminunitname_2` and
  * `_3` name a region and a municipality, neither of which a Danish address line states, so region
  * is left to the wof-postalcode and wof-admin cross-reference at corpus build time, as BAN's is.
  *
- * The address-source register records this source as `dk-property-building-1` and its license as
- * `unchecked-access-free-dk-klimadatastyrelsen`, whose `spdx` field reads `CC-BY-4.0` in an
- * `elected` state with `train` permitted. The adapter records that license on every row, and the
- * model card must attribute Klimadatastyrelsen.
+ * The address-source register lists this source as `dk-property-building-1`. Its
+ * `unchecked-access-free-dk-klimadatastyrelsen` license holds `CC-BY-4.0` in `spdx`, an `elected`
+ * state with `train` permitted. The adapter records that license on every row, and the model card
+ * must attribute Klimadatastyrelsen.
  *
  * The adapter streams through Kysely's `.stream()`, so the `address` table never sits in memory, and
  * orders by `objectid` so two runs over one file emit the same rows in the same order. It honors
@@ -42,9 +41,9 @@
  * Denmark proper, and Greenland and the Faroe Islands are their own jurisdictions and are absent
  * from it.
  *
- * The measured file holds 599,999 `address` rows, which is one short of a round 600,000 against a
- * national register several times that size. Treat it as a possible export cap rather than as
- * Denmark's address count. The register's `coverage` field records the same reading.
+ * The measured file holds 599,999 `address` rows. That is one short of a round 600,000, while the
+ * national register is several times larger, so treat the file as a possible export cap rather than
+ * as Denmark's address count.
  */
 
 import { formatAddressRow } from "@mailwoman/codex/address/format"
@@ -66,9 +65,10 @@ export const DK_INSPIRE_ADAPTER_ID = "dk-inspire"
 /**
  * The license the address-source register elects for this source.
  *
- * Read from the `spdx` field of the register's `unchecked-access-free-dk-klimadatastyrelsen`
- * license, which the register's `dk-property-building-1` source names.
- * The feed's own `<rights>` says the same, but the register is what governs.
+ * Read from the `spdx` field of the register's `unchecked-access-free-dk-klimadatastyrelsen` license.
+ * The register's `dk-property-building-1` source points to it.
+ *
+ * The feed's own `<rights>` states the same, but the register is what governs.
  */
 export const DK_INSPIRE_DEFAULT_LICENSE = "CC-BY-4.0"
 
@@ -82,12 +82,13 @@ export const DK_INSPIRE_DEFAULT_LICENSE = "CC-BY-4.0"
 export const DK_INSPIRE_COUNTRIES: readonly string[] = ["DK"]
 
 /**
- * The tables the adapter reads, which it requires `gpkg_contents` to declare.
+ * The tables the adapter reads.
+ * It requires `gpkg_contents` to declare them.
  *
  * The GeoPackage declares five.
- * `addressareaname` is a supplementary locality that resolves for 206,416 of the 599,999 rows
- * and that a Danish address line does not state, and `adminunitname` holds the region
- * and municipality the adapter leaves to cross-reference, so neither is read.
+ * `addressareaname` holds a supplementary locality that a Danish address line does
+ * not state, and `adminunitname` holds the region and municipality the adapter
+ * leaves to cross-reference, so neither is read.
  */
 export const DK_INSPIRE_REQUIRED_TABLES: readonly string[] = ["address", "postaldescriptor", "thoroughfarename"]
 
@@ -116,15 +117,14 @@ export class AddressGeoPackageSchemaError extends Error {
 /**
  * Raised when an address row's component reference resolves to no row of the referenced table.
  *
- * Every reference resolves in the measured file.
- * One that does not means the database is incomplete, which is reported
- * rather than converted into an address missing its street.
+ * An unresolved reference means the database is incomplete.
+ * The adapter reports it rather than converting it into an address missing its street.
  */
 export class UnresolvedAddressComponentError extends Error {
 	constructor(inspireID: string, column: string, reference: string | null) {
 		super(
 			`${DK_INSPIRE_ADAPTER_ID} adapter: address ${inspireID} carries ${column}=` +
-				`${reference === null ? "NULL" : `"${reference}"`}, which resolves to no row.`
+				`${reference ? `"${reference}"` : "NULL"}, which resolves to no row.`
 		)
 
 		this.name = "UnresolvedAddressComponentError"
@@ -172,11 +172,10 @@ export interface AddressGeoPackageDatabase {
  * `locator_designator_3_designator` (`tv` for `til venstre`, or a number).
  * Danish writes the floor first, so the two join in that order.
  *
- * {@linkcode composeHouseNumber} answers the empty string when its first argument is absent,
- * which is right for the house-number columns it was written for and wrong here:
- * 967 of the measured file's rows carry a door and no floor, and passing the pair
- * straight through would drop every one of those doors.
- * The door alone is therefore the value when the floor is absent.
+ * {@linkcode composeHouseNumber} answers the empty string when its first argument is absent.
+ * That suits the house-number columns it was written for, and it would drop every
+ * door here: 967 measured rows have a door and no floor.
+ * The door is therefore the value when the floor is absent.
  *
  * @returns The joined designator, or the empty string when the publisher states neither.
  */
@@ -223,8 +222,9 @@ export function createDKInspireAdapter(): CorpusAdapter {
 				throw new AddressGeoPackageSchemaError(inputPath, declared, missing)
 			}
 
-			// Left joins, deliberately: an inner join would drop an address whose component reference
-			// does not resolve, which is the absence this adapter has to report rather than apply.
+			// Left joins, deliberately: an inner join would drop an address whose
+			// component reference does not resolve.
+			// That absence has to be reported rather than applied.
 			const stream = db
 				.selectFrom("address as a")
 				.leftJoin("thoroughfarename as t", "t.inspireid", "a.component_thoroughfarename")
@@ -256,7 +256,7 @@ export function createDKInspireAdapter(): CorpusAdapter {
 					// The street is the one component every address needs and every row
 					// of the measured file resolves.
 					// An unresolved reference is reported, never read as a missing street.
-					if (record.street === null) {
+					if (!record.street) {
 						throw new UnresolvedAddressComponentError(
 							record.inspireid,
 							"component_thoroughfarename",
@@ -264,7 +264,7 @@ export function createDKInspireAdapter(): CorpusAdapter {
 						)
 					}
 
-					if (record.postcode === null && record.postname === null) {
+					if (!record.postcode && !record.postname) {
 						throw new UnresolvedAddressComponentError(
 							record.inspireid,
 							"component_postaldescriptor",

package/lib/dk/tools/fetch/inspire.ts

@@ -20,11 +20,11 @@
  *
  * Five properties of this host were measured, and each one breaks a reader that assumes otherwise:
  *
- * 1. `content-length` on the feed is the gzip-compressed length. The header says 1,455 while 3,130
+ * 1. `content-length` on the feed is the gzip-compressed length. The header reports 1,455 while 3,130
  *    bytes are delivered, so a reader that trusts it truncates the feed. Every byte count here is
  *    counted off the delivered body.
  * 2. The entry's `rel="alternate"` href is a Wing FTP weblink landing page, HTTP 200 `text/html`,
- *    3,811 bytes. The file needs `&realfilename=DK_INSPIRE_Addresses.zip` appended, which answers
+ *    3,811 bytes. The file needs `&realfilename=DK_INSPIRE_Addresses.zip` appended. That query answers
  *    HTTP 200 `application/zip`.
  * 3. The host ignores `Range`. `bytes=0-4095` answers HTTP 200 with no `content-range` and the whole
  *    101 MB body, so the one-byte range GET that sizes an OpenAddresses source cannot be used here.
@@ -43,7 +43,7 @@
    procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { pathExists, statPath } from "@mailwoman/core/fs/readers"
+import { pathExists, statPath } 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"
@@ -70,7 +70,7 @@ export const DK_ADDRESSES_GEOPACKAGE_MEMBER = "ad_inspire.gpkg"
 /**
  * The query parameter that turns the entry's weblink landing page into the file itself.
  *
- * Wing FTP serves a listing page for a weblink and the file only when the member is named.
+ * Wing FTP serves the file only when the request asks for the member.
  */
 const REAL_FILENAME_PARAMETER = "realfilename"
 
@@ -91,7 +91,7 @@ export interface AddressesFeedEntry {
 	 */
 	title: string
 	/**
-	 * The download URL, with the member named so the host serves the file rather than its landing page.
+	 * The download URL, with the member in the query so the host serves the file.
 	 */
 	downloadURL: string
 	/**
@@ -106,7 +106,7 @@ export interface AddressesFeedEntry {
  * Parsed with `@mailwoman/core/html/elements` rather than matched with a pattern.
  *
  * The feed needs both of the things a pattern handles badly.
- * Its entry tag carries an `xml:lang` attribute, so a reader has to keep attributes.
+ * Its entry tag has an `xml:lang` attribute, so a reader has to keep attributes.
  *
  * Its hrefs escape the ampersand between query parameters, so a reader has to decode entities.
  *
@@ -115,7 +115,8 @@ export interface AddressesFeedEntry {
  *
  * @param xml The whole feed, 3,130 bytes, taken as one string rather than as a stream.
  * @throws When the feed holds no entry, or its entry no usable link.
- * A feed holding neither reads as a change at the publisher, which a caller has to see.
+ * A feed holding neither reads as a change at the publisher.
+ * A caller has to see that.
  */
 export async function readAddressesFeed(xml: string, feedURL: string): Promise<AddressesFeedEntry> {
 	async function* oneChunk(): AsyncIterable<string> {
@@ -123,7 +124,7 @@ export async function readAddressesFeed(xml: string, feedURL: string): Promise<A
 	}
 
 	// The feed holds one entry covering the whole country, so the first is the dataset.
-	let entry: MarkupElement | undefined
+	let entry: MarkupElement | null = null
 
 	for await (const found of streamMarkupElements(oneChunk(), "entry", { xml: true })) {
 		entry ??= found
@@ -136,8 +137,8 @@ export async function readAddressesFeed(xml: string, feedURL: string): Promise<A
 	const title = childElement(entry, "title")?.text ?? ""
 
 	// The alternate link is the dataset.
-	// The same entry carries a `describedby` link to the ISO 19139 record,
-	// and either would download as a dataset without this check.
+	// The same entry also has a `describedby` link to the ISO 19139 record.
+	// Either would download as a dataset without this check.
 	const alternate = childElements(entry, "link").find(
 		(link: MarkupElement) => (link.attributes.rel ?? "").toLowerCase() === "alternate"
 	)
@@ -243,8 +244,9 @@ export async function fetchDKAddresses(
 
 	// MARK: Download the dataset
 	//
-	// Streamed rather than buffered, and the byte count comes from the body rather than
-	// from the entry's `length` attribute, which understates the file by 23 times.
+	// Streamed rather than buffered, and the byte count comes from the body
+	// rather than from the entry's `length` attribute.
+	// That attribute understates the file by 23 times.
 
 	const datasetResponse = await fetch(entry.downloadURL, { redirect: "follow" })
 
@@ -256,8 +258,8 @@ export async function fetchDKAddresses(
 
 	const contentType = datasetResponse.headers.get("content-type") ?? ""
 
-	// The bare weblink href answers HTTP 200 `text/html` with a landing page,
-	// which would otherwise be written to disk and fail later as a corrupt zip.
+	// The bare weblink href answers HTTP 200 `text/html` with a landing page.
+	// A write to disk would fail later as a corrupt zip.
 	if (contentType.includes("text/html")) {
 		report?.(`  ✗ The dataset URL answered ${contentType}, which is the weblink's landing page rather than the file`)
 

package/lib/ee/adapters/ads/adapter.ts

@@ -14,39 +14,32 @@
  * GeoServer flattens the INSPIRE application schema here, so every component value arrives inline on
  * the feature's `properties` and the adapter resolves no reference. The county, the municipality, the
  * settlement unit, the address area, the thoroughfare and the postal descriptor each occupy one of six
- * fixed `component<n>_xlink_title` slots, and an unused slot carries the string `unpopulated` rather
- * than a void object. The slot a value lands in is fixed: read through `JSONSpliterator` over 1,003
- * features across ten windows spread through the 729,973, slot 1 is `AU.AdministrativeUnit_maakond`
- * on all 1,003, slot 2 is `AU.AdministrativeUnit_ov` on all 1,003 and slot 6 is
- * `AD.Address_PostalDescriptor` on all 1,003, whose title is five digits on all 1,003. Slots 3, 4 and
- * 5 hold the settlement unit (926), the address area (4) and the thoroughfare (314) or `unpopulated`.
- *
- * The field named after the INSPIRE designator holds an internal ADS code, and the house number
- * sits in the locator's name-spelling element. Estonia writes that ADS code in
- * `locator_addresslocator_designator_locatordesignator_designator` — `7_1DOW`, `7_3P4Y`, `6_0MU3` —
- * and 0 of 1,003 sampled values take a house-number shape. The human-readable number is in
- * `locator_addresslocator_name_locatorname_name_spelling_text`. The designator's own type says
- * `addressNumber` on the street rows, which is what makes that field tempting to read. Reading it
- * would stamp `7_1DOW` as the house number on all 729,973 rows.
- *
- * Which of the two the locator name is follows the feature's structure rather than the value's shape.
- * A feature carrying a thoroughfare or an address area writes its number there, and one carrying
- * neither writes the farm or building name that designates the addressable unit. Over the same 1,003
- * features the split is exact: 314 of 314 features with a thoroughfare carry a number-shaped locator
- * name, 4 of 4 with an address area do, and 685 of 685 with neither carry a name instead. The two
- * never co-occur. The adapter therefore reads `house_number` where a thoroughfare element exists and
- * `venue` where none does, so a farm name never arrives labeled as a number.
- *
- * Slots 4 and 5 carry a malformed `href`: it addresses the `AU_haldusyksused` workspace with an
+ * fixed `component<n>_xlink_title` slots. An unused slot holds the string `unpopulated` rather than a
+ * void object. The slot a value lands in is fixed: slot 1 holds the county, slot 2 the municipality,
+ * slot 3 the settlement unit, slot 4 the address area, slot 5 the thoroughfare and slot 6 the postal
+ * descriptor.
+ *
+ * The field whose name matches the INSPIRE designator holds an internal ADS code, and the house
+ * number sits in the locator's name-spelling element. Estonia writes that ADS code in
+ * `locator_addresslocator_designator_locatordesignator_designator` (`7_1DOW`, `7_3P4Y`, `6_0MU3`).
+ * The human-readable number is in `locator_addresslocator_name_locatorname_name_spelling_text`. The
+ * designator's own type states `addressNumber` on the street rows, so that field is tempting to
+ * read. A reader that takes it would stamp `7_1DOW` as the house number on every row.
+ *
+ * The locator name takes one of two roles, and the feature's structure decides which. A feature that
+ * holds a thoroughfare or an address area writes its number there, and one that holds neither writes
+ * the farm or building name that designates the addressable unit. The two never co-occur. The adapter
+ * therefore reads `house_number` where a thoroughfare element exists and `venue` where none does, so a
+ * farm name never arrives labeled as a number.
+ *
+ * Slots 4 and 5 hold a malformed `href`: it addresses the `AU_haldusyksused` workspace with an
  * `AD_Address` type and answers HTTP 400 `Unknown namespace [AD_Address]`. The adapter reads the slot's
  * `title` and never follows an `href`.
  *
- * A row with no thoroughfare element is the ordinary rural case rather than a defect: 685 of those
- * 1,003 features, against the whole-service share of 288,009 thoroughfare-bearing rows in 729,973,
- * which is 39.5%.
+ * A row with no thoroughfare element is the ordinary rural case rather than a defect.
  *
- * Maa- ja Ruumiamet's dataset record states Creative Commons CC0 1.0 in `otherConstraints`, which the
- * address-source register elected and records under `spdx` as `CC0-1.0`. CC0 reserves no act, so the
+ * Maa- ja Ruumiamet's dataset record states Creative Commons CC0 1.0 in `otherConstraints`. The
+ * address-source register elected that license and records it under `spdx` as `CC0-1.0`. CC0 reserves no act, so the
  * adapter stamps that label on every row and the model card needs no attribution clause, although
  * crediting the publisher stays good practice.
  *
@@ -126,7 +119,7 @@ interface ADSFeature {
  * The sentinel is compared case-insensitively because it renders an INSPIRE codelist term
  * rather than a value the publisher authored.
  */
-function slotValue(value: string | undefined): string {
+function slotValue(value: string | null | undefined): string {
 	const trimmed = (value ?? "").trim()
 
 	return trimmed.toLowerCase() === UNPOPULATED ? "" : trimmed
@@ -192,8 +185,9 @@ export function createADSAdapter(): CorpusAdapter {
 
 					components.street = street
 				} else if (locatorName) {
-					// With no thoroughfare the locator name is the site or building name that
-					// designates the addressable unit, which is how a rural Estonian address works.
+					// With no thoroughfare the locator name is the site or building name
+					// that designates the addressable unit.
+					// That is how a rural Estonian address works.
 					components.venue = locatorName
 				}
 

package/lib/ee/tools/fetch/ads.ts

@@ -14,7 +14,7 @@
  *
  * `#tools/fetch/inspire-addresses` owns the capabilities read and the GeoJSON page read, and
  * `#tools/fetch/wfs-harvest` owns the appending, the manifest and the resumption. This module states
- * what is particular to Estonia, which is four measurements taken on 2026-10-02:
+ * what is particular to Estonia: four measurements taken on 2026-10-02:
  *
  * 1. The payload needs no component resolution. GeoServer flattens the application schema here, so
  *    each `component<n>_xlink_href` has a sibling `component<n>_xlink_title` carrying the referenced
@@ -25,14 +25,14 @@
  *    `readCheckedWFSFeatureCount`, which proves the number against a page before a caller uses it,
  *    and no count is written into this file.
  * 3. The service honors a sort. `ImplementsSorting` is `TRUE`, `sortBy=gml_id` answers HTTP 200 and
- *    `sortBy=gml_id D` returns the type's last features first, which is what proves the parameter is
+ *    `sortBy=gml_id D` returns the type's last features first. That proves the parameter is
  *    applied rather than accepted and dropped. `sortBy=gml:identifier` and `sortBy=inspireId` answer
  *    HTTP 400 `Illegal property name`, so the sort property is one of the flattened names.
  * 4. A `count=10000` page of `application/json` is 31,198,909 bytes and takes about 6 seconds. At
  *    729,973 features that is 73 pages and about 2.3 GB, plus three requests for the capabilities and
  *    the checked count.
  *
- * The harvest writes one feature per line, which is what lets the adapter stream the whole extract
+ * The harvest writes one feature per line. The adapter can then stream the whole extract
  * without holding a page. The `FeatureCollection` envelope is dropped: its counts describe one page
  * and the manifest records them per page instead.
  */
@@ -105,8 +105,10 @@ const LICENSE = "CC0-1.0"
  * The spacing between requests.
  *
  * The service answers a 10,000-feature page in about 6 seconds, so this is not what limits the harvest.
- * It bounds the harvest to one request per second against a government host whose published terms
- * state no rate, which the shorter requests — the capabilities and the count — would otherwise exceed.
+ * It bounds the harvest to one request per second against a government host
+ * whose published terms state no rate.
+ *
+ * The shorter requests (the capabilities and the count) would otherwise exceed that rate.
  */
 const MIN_REQUEST_INTERVAL_MS = 1000
 
@@ -186,7 +188,7 @@ export async function harvestADSEE(
 
 	options.report?.(`  Feature count: ${featureCount.count ?? "not stated"} — ${featureCount.because}`)
 
-	return await harvestPagedWFS({
+	return harvestPagedWFS({
 		context: CONTEXT,
 		source: SLUG,
 		outputDir: options.outputDir,
@@ -246,7 +248,7 @@ export type FetchADSEEOptions = BaseFetchOptions &
 export async function fetchADSEE(options: FetchADSEEOptions, report?: (line: string) => void): Promise<FetchSummary> {
 	const pageSize = options.pageSize ?? EE_ADS_PAGE_SIZE
 
-	return await runWFSHarvest(
+	return runWFSHarvest(
 		{
 			slug: SLUG,
 			outRoot: options.outRoot,
@@ -257,7 +259,7 @@ export async function fetchADSEE(options: FetchADSEEOptions, report?: (line: str
 			client: options.client,
 			maxPages: options.maxPages,
 			harvest: async (client) =>
-				await harvestADSEE(client, {
+				harvestADSEE(client, {
 					outputDir: options.outRoot(SLUG),
 					pageSize,
 					maxPages: options.maxPages,

package/lib/es/adapters/bizkaia/adapter.ts

@@ -8,17 +8,17 @@
  *
  * The ATOM service at `https://apli.bizkaia.eus/apps/Danok/INSPIRE/addresses.xml` lists 112
  * municipality entries, one zipped GML each. Catastro's national feed links this service rather than
- * serving its data, which is why the publisher is a register of its own.
+ * serving its data. The publisher is therefore a register of its own.
  *
- * The archives carry addresses alone, and that is what shapes this reader. Abadiño's
+ * The archives hold only addresses. That shapes this reader. Abadiño's
  * `ES.BFA.AD.001.zip` holds one member, `ES.BFA.AD.gml`, whose 1,360 `ad:Address` features write
  * 4,080 `ad:component` references and not one `ad:ThoroughfareName`, `ad:PostalDescriptor` or
  * `ad:AdminUnitName` feature. Every reference is a stored-query URL on
  * `https://geo.bizkaia.eus/arcgisserverinspire/…` addressing an `adComponent.<n>` the ATOM feed never
- * publishes. A reader of the archive alone therefore writes every address in the province without
+ * publishes. A reader given only those archives therefore writes every address in the province without
  * its street, its postcode or its municipality.
  *
- * Those features are on the publisher's WFS, which serves the whole province in three requests. The
+ * Those features are on the publisher's WFS. It serves the whole province in one request per type. The
  * service answers `ad:ThoroughfareName` with `numberMatched="6921"`, `ad:PostalDescriptor` with
  * `96` and `ad:AdminUnitName` with `113`, and a `GetFeature` with `COUNT=10000` returns each type
  * whole: 6,921 thoroughfare names arrive in one 13,916,056-byte document. One request per type is
@@ -32,14 +32,14 @@
  * addresses. An unresolved reference is a value the reader asked for and could not read, and it
  * raises.
  *
- * Two of the publisher's own spellings decide what a row carries.
+ * Two of the publisher's own spellings decide what a row records.
  *
  * A thoroughfare name is a cadastral field rather than a street name:
  * `BO\TRAÑA-MATIENA(1)` is the street-type abbreviation `BO`, a backslash, the name, and the
  * street's own sequence code in parentheses. All 6,921 take that form. The row keeps the
  * abbreviation, as the Dirección General del Catastro's own rendered line does with `CL SANTIAGO
- * APOSTOL`, writes a space where the cadastre writes its separator, and drops the sequence code,
- * which is an identifier rather than part of the name.
+ * APOSTOL`, writes a space where the cadastre writes its separator, and drops the sequence code
+ * because it is an identifier rather than part of the name.
  *
  * The house number is the last of the four dot-separated fields of the designator, and the
  * designator is a cadastral code: `48.001.00026.003` is municipality 48001, street 00026 and number
@@ -57,10 +57,9 @@
  * The first three are an ordinary Spanish number, a number with a letter, and a number with a
  * *bis*, *izquierda* or *derecha* qualifier. The fourth is two fields concatenated and what its
  * second field designates is not established: it is three digits wide like the number itself, and
- * no document the publisher publishes says what it counts. Those 181 of 1,360 rows therefore carry the
- * publisher's own concatenation with its padding removed, which transcribes the designator without
- * interpreting it. Splitting the field on a guessed separator would state a number the cadastre does
- * not hold.
+ * no document the publisher publishes states what it counts. The row therefore writes the
+ * publisher's own concatenation with its padding removed. A split on a guessed separator would
+ * state a number the cadastre does not hold.
  *
  * The municipality is `ad:AdminUnitName` at `3rdOrder`, which is the only level the service
  * publishes: 113 of 113 of its administrative-unit features state it, and their names are padded
@@ -71,14 +70,14 @@
  * `48 001 CL\TRAÑAETXOSTE(00066) 002` for the address whose designator is `48.001.00066.002`. It
  * restates the municipality code, the street type and name, the street code zero-padded to five, and
  * the number field, and it is written inside the archive while the street itself comes from a
- * separate WFS document. Putting the resolved street and the composed number beside it therefore
- * checks that the right feature was joined, which is what the adapter's test does. The register's
+ * separate WFS document. The adapter's test compares the resolved street and the composed number
+ * against it to check that the right feature was joined. The register's
  * personal-data review reads these values as internal cadastral references rather than names, and
  * the adapter writes none of them into a row.
  *
  * No service either publisher runs was found to render a postal address for this province: the
- * ArcGIS layer behind the WFS exposes INSPIRE fields alone. So the number's unexplained second field
- * stays an open question rather than one this adapter resolved.
+ * ArcGIS layer behind the WFS exposes only INSPIRE fields. The number's unexplained second field
+ * therefore stays open.
  */
 
 import { openReadStream } from "@mailwoman/core/fs/streams"
@@ -120,26 +119,26 @@ export const ES_BIZKAIA_COUNTRIES: readonly string[] = ["ES"]
 /**
  * The license the address-source register elected for this publisher.
  *
- * Bizkaia names no license instrument, so no SPDX identifier is written and this records the
- * publisher's own words. Its INSPIRE metadata carries the controlled values `No limitations to
+ * Bizkaia states no license instrument, so no SPDX identifier is written and this records the
+ * publisher's own words. Its INSPIRE metadata states the controlled values `No limitations to
  * public access` and `No conditions to access and use`, and its feed-level `rights` adds the
  * condition that authorship and ownership of the BFA be stated as «©Bizkaiko Foru Aldundia». The
  * register records two contradictions it did not resolve: all 112 municipality entries also read
  * `Copyright (c) 2017", ES.BFA; all rights reserved`, and Catastro's national feed labels this
- * publisher `CC BY 3.0 ES`, which no document Bizkaia publishes names.
+ * publisher `CC BY 3.0 ES`. No document Bizkaia publishes states that label.
  */
 export const ES_BIZKAIA_LICENSE = "No conditions to access and use, with attribution to «©Bizkaiko Foru Aldundia»"
 
 /**
  * The member of a municipality's archive that holds the GML.
  *
- * Each archive ships one member, named `ES.BFA.AD.gml` whichever municipality it holds,
- * so the extension selects it and the archive's own name carries the municipality.
+ * Each archive ships one member, `ES.BFA.AD.gml` whichever municipality it holds,
+ * so the extension selects it and the archive's own name identifies the municipality.
  */
 const GML_MEMBER = /\.gml$/iu
 
 /**
- * The feature types the saved WFS documents carry, indexed before any address is read.
+ * The feature types in the saved WFS documents, indexed before any address is read.
  */
 const COMPONENT_ELEMENTS = [
 	"ad:ThoroughfareName",
@@ -165,7 +164,7 @@ const MUNICIPALITY_LEVEL = "3rdOrder"
 const HOUSE_NUMBER_TYPE = "buildingIdentifier"
 
 /**
- * How many dot-separated fields a designator carries.
+ * How many dot-separated fields a designator has.
  *
  * Municipality, street, number: `48.001.00026.003` splits the municipality code across two.
  */
@@ -176,15 +175,16 @@ const DESIGNATOR_FIELDS = 4
  *
  * `BO\TRAÑA-MATIENA(1)` answers `BO TRAÑA-MATIENA`.
  * The backslash is the cadastre's separator between the street-type abbreviation
- * and the name, and the trailing parenthesis holds the street's sequence code,
- * which the address's own designator repeats as its third field.
+ * and the name, and the trailing parenthesis holds the street's sequence code.
  *
- * @returns The street, or undefined where the feature states no name.
+ * The address's own designator repeats that code as its third field.
+ *
+ * @returns The street, or null where the feature states no name.
  */
-export function bizkaiaStreet(feature: MarkupElement): string | undefined {
+export function bizkaiaStreet(feature: MarkupElement): string | null {
 	const text = thoroughfareName(feature)
 
-	if (!text) return undefined
+	if (!text) return null
 
 	const street = text
 		.replace(/\((\d+)\)\s*$/u, "")
@@ -192,19 +192,19 @@ export function bizkaiaStreet(feature: MarkupElement): string | undefined {
 		.replaceAll(/\s+/gu, " ")
 		.trim()
 
-	return street || undefined
+	return street || null
 }
 
 /**
  * The street's sequence code a thoroughfare feature states, as the feature writes it.
  *
- * The code the address's designator joins on, which is what makes the publisher's own
- * `ad:LocatorName` a check of the join rather than a copy of it.
+ * The code the address's designator joins on.
+ * The publisher's own `ad:LocatorName` therefore checks the join rather than copying it.
  *
- * @returns The digits inside the trailing parentheses, or undefined where there are none.
+ * @returns The digits inside the trailing parentheses, or null where there are none.
  */
-export function bizkaiaStreetCode(feature: MarkupElement): string | undefined {
-	return /\((\d+)\)\s*$/u.exec(thoroughfareName(feature) ?? "")?.[1]
+export function bizkaiaStreetCode(feature: MarkupElement): string | null {
+	return /\((\d+)\)\s*$/u.exec(thoroughfareName(feature) ?? "")?.[1] ?? null
 }
 
 /**
@@ -215,20 +215,20 @@ export function bizkaiaStreetCode(feature: MarkupElement): string | undefined {
  *
  * This module's header tabulates the four shapes it takes, with their counts.
  *
- * @returns The number, or undefined where the designator is absent or does not carry four fields.
+ * @returns The number, or null where the designator is absent or does not have four fields.
  */
-export function bizkaiaHouseNumber(byType: ReadonlyMap<string, readonly string[]>): string | undefined {
+export function bizkaiaHouseNumber(byType: ReadonlyMap<string, readonly string[]>): string | null {
 	const code = designator(byType, HOUSE_NUMBER_TYPE)
 
-	if (!code) return undefined
+	if (!code) return null
 
 	const fields = code.split(".")
 
-	if (fields.length !== DESIGNATOR_FIELDS) return undefined
+	if (fields.length !== DESIGNATOR_FIELDS) return null
 
 	const number = fields[DESIGNATOR_FIELDS - 1]!.replace(/^0+(?=.)/u, "")
 
-	return number || undefined
+	return number || null
 }
 
 export function createESBizkaiaAdapter(): CorpusAdapter {
@@ -296,19 +296,19 @@ export function createESBizkaiaAdapter(): CorpusAdapter {
 }
 
 /**
- * One address's row, or undefined when it carries too little to render.
+ * One address's row, or null when it has too little to render.
  */
-function composeRow(address: MarkupElement, referenced: ReadonlyMap<string, MarkupElement>): CanonicalRow | undefined {
-	const addressID = address.attributes["gml:id"]?.trim()
+function composeRow(address: MarkupElement, referenced: ReadonlyMap<string, MarkupElement>): CanonicalRow | null {
+	const addressID = address.attributes["gml:id"]?.trim() ?? null
 
 	if (voidDesignatorTypes(address).has(HOUSE_NUMBER_TYPE)) {
 		throw new VoidDesignatorError(ES_BIZKAIA_ADAPTER_ID, addressID, HOUSE_NUMBER_TYPE)
 	}
 
-	let street: string | undefined
-	let postcode: string | undefined
-	let locality: string | undefined
-	let settlement: string | undefined
+	let street: string | null = null
+	let postcode: string | null = null
+	let locality: string | null = null
+	let settlement: string | null = null
 
 	for (const href of componentHrefs(address)) {
 		const key = componentJoinKey(href)
@@ -361,8 +361,8 @@ function memberChunks(path: PathBuilderLike): AsyncIterable<string | Uint8Array>
  * The two passes read the same list, so an input holding addresses and an input holding
  * component features need not be told apart: a municipality archive contributes addresses
  * to the second pass and no feature to the first, and a saved WFS page the reverse.
- * Deciding by extension would be wrong on a hand-assembled input that holds both,
- * and the publisher's own naming distinguishes neither.
+ * Extension cannot decide: a hand-assembled input can hold both, and the
+ * publisher's own naming distinguishes neither.
  *
  * A path holding no input raises rather than yielding zero rows, so a wrong path
  * reports itself instead of reading as an empty publisher.