@mailwoman/corpus 10.1.0 → 10.2.0

package/lib/inspire/address.ts

@@ -27,8 +27,8 @@
  *    without regard to case, and accept either form of a coded value.
  *
  * So this module exposes the primitives and leaves composition to each adapter. A configuration
- * object describing those four axes would have to be right about publishers whose files nobody has
- * read yet. A handful of small functions carries no such claim.
+ * object describing those axes would state claims about files no one has read. These small
+ * functions state none.
  *
  * The reference form is the exception, because its shapes are enumerable and measured:
  * {@linkcode componentJoinKey} reads all four.
@@ -44,39 +44,40 @@ import type { MarkupElement } from "@mailwoman/core/html/elements"
  *
  * The Dirección General del Catastro and the Gobierno de Navarra bind the same
  * two namespaces to `AD:` and `GN:`.
- * A reader comparing the name exactly finds neither a locator nor a street
- * nor a postcode in either Spanish file.
+ * An exact comparison finds neither a locator, a street nor a postcode in either Spanish file.
  *
- * That reads as an address carrying none rather than as a prefix this repository had not met.
+ * That reads as an address with none of those rather than as an unfamiliar prefix.
  *
- * The prefix is still compared, because it carries the namespace and the namespace carries the meaning.
+ * The prefix is still compared, because it identifies the namespace and the namespace holds the meaning.
  * The Service public de Wallonie writes three `gml:name` elements inside each
  * `ad:ThoroughfareName`, ahead of the `ad:name` that holds the street.
  *
- * A reader that dropped the prefix and matched on `name` alone read the first of those three
- * and found no street on any of Wallonia's 58,591 thoroughfare features.
+ * A reader that dropped the prefix and matched only on `name` read the first of those three,
+ * so it found no street on any of Wallonia's 58,591 thoroughfare features.
  */
 export function inspireNameIs(name: string, wanted: string): boolean {
 	return name.toLowerCase() === wanted.toLowerCase()
 }
 
 /**
- * The first child of `element` named `name`, ignoring case.
+ * The first child of `element` whose name matches `name`, ignoring case.
  *
- * `name` is written with the prefix the INSPIRE guideline uses, which is the
- * prefix eight of the nine publishers write.
- * The case-insensitive sibling of `childElement` from `@mailwoman/core/html/elements`,
- * which compares the name exactly as a general markup reader must.
+ * Write `name` with the prefix the INSPIRE guideline uses.
+ * Eight of the nine publishers use it.
+ *
+ * The case-insensitive sibling of `childElement` from `@mailwoman/core/html/elements`.
+ * That
+ * function compares the name exactly, as a general markup reader must.
  */
-export function inspireChild(element: MarkupElement, name: string): MarkupElement | undefined {
-	return element.children.find((child) => inspireNameIs(child.name, name))
+export function inspireChild(element: MarkupElement, name: string): MarkupElement | null {
+	return element.children.find((child) => inspireNameIs(child.name, name)) ?? null
 }
 
 /**
- * Every child of `element` named `name`, in document order, ignoring case.
+ * Every child of `element` whose name matches `name`, in document order, ignoring case.
  *
  * The case-insensitive sibling of `childElements` from `@mailwoman/core/html/elements`,
- * for the same reason {@linkcode inspireChild} is.
+ * for the same reason {@linkcode inspireChild} exists.
  */
 export function inspireChildren(element: MarkupElement, name: string): readonly MarkupElement[] {
 	return element.children.filter((child) => inspireNameIs(child.name, name))
@@ -89,11 +90,11 @@ export function inspireChildren(element: MarkupElement, name: string): readonly
  * An INSPIRE value sits five or six elements down, so the path form reads better than
  * a chain of {@linkcode inspireChild} calls and reports the same absence.
  */
-export function inspireElementAt(element: MarkupElement, ...path: readonly string[]): MarkupElement | undefined {
-	let current: MarkupElement | undefined = element
+export function inspireElementAt(element: MarkupElement, ...path: readonly string[]): MarkupElement | null {
+	let current: MarkupElement | null = element
 
 	for (const step of path) {
-		if (!current) return undefined
+		if (!current) return null
 
 		current = inspireChild(current, step)
 	}
@@ -102,20 +103,21 @@ export function inspireElementAt(element: MarkupElement, ...path: readonly strin
 }
 
 /**
- * The final segment of an INSPIRE codelist URI, which is the value's name.
+ * The final segment of an INSPIRE codelist URI.
+ * That segment is the value's name.
  *
  * `http://inspire.ec.europa.eu/codelist/LocatorDesignatorTypeValue/buildingIdentifier`
  * reads `buildingIdentifier`.
  * A `#` fragment is dropped first, because Flanders appends one to a `vocab.belgif.be`
  * reference and Czechia folds it into `base:localId`.
  */
-export function codelistValue(uri: string | undefined): string | undefined {
-	if (!uri) return undefined
+export function codelistValue(uri: string | null | undefined): string | null {
+	if (!uri) return null
 
 	const withoutFragment = uri.split("#")[0]!
 	const segment = withoutFragment.split("/").pop()
 
-	return segment || undefined
+	return segment || null
 }
 
 /**
@@ -123,25 +125,27 @@ export function codelistValue(uri: string | undefined): string | undefined {
  *
  * INSPIRE writes `xsi:nil="true"` and usually a `nilReason`.
  * Brussels writes the nil marker and no reason on all 232,003 of its void `ad:validFrom`
- * elements, and Czechia writes four `gn:pronunciation` elements nil with no reason,
- * so a reader keyed on `nilReason` alone mistakes a void value for a populated one.
+ * elements, and Czechia writes four `gn:pronunciation` elements nil with no reason.
+ *
+ * A reader that keys only on `nilReason` mistakes a void value for a populated one.
  *
  * An absent element answers false, so a caller distinguishes a void value from a missing one.
  */
-export function isVoid(element: MarkupElement | undefined): boolean {
+export function isVoid(element: MarkupElement | null): boolean {
 	return element?.attributes["xsi:nil"] === "true"
 }
 
 /**
  * The reason a publisher gave for a void element, as a codelist value such as `Unpopulated`.
  *
- * Returns undefined when the element is void and states no reason, which the
- * schema permits and which Brussels does throughout.
- * A caller that needs to separate a void carrying a reason from a void carrying
- * none reads this together with {@linkcode isVoid}.
+ * Returns null when the element is void and states no reason.
+ * The schema permits that form, and Brussels uses it throughout.
+ *
+ * A caller that needs to separate a void with a reason from a void with none
+ * reads this together with {@linkcode isVoid}.
  */
-export function voidReason(element: MarkupElement | undefined): string | undefined {
-	if (!isVoid(element)) return undefined
+export function voidReason(element: MarkupElement | null): string | null {
+	if (!isVoid(element)) return null
 
 	return codelistValue(element?.attributes.nilReason)
 }
@@ -149,17 +153,19 @@ export function voidReason(element: MarkupElement | undefined): string | undefin
 /**
  * Every locator designator on an address, keyed by its INSPIRE type name.
  *
- * One `ad:AddressLocator` carries a designator per part of the number, each in its
- * own `ad:LocatorDesignator` beside an `ad:type` naming what it is.
+ * One `ad:AddressLocator` holds a designator per part of the number, each in its own
+ * `ad:LocatorDesignator` beside an `ad:type` that states what it is.
  * Czechia writes two, `č.ev.` typed `buildingIdentifierPrefix` and `502` typed `buildingIdentifier`.
  *
  * The Netherlands writes four, including an empty `LocatorDesignatorTypeValue/addressNumberExtension`
  * and the postcode as `LocatorDesignatorTypeValue/postalDeliveryIdentifier`.
  *
  * A type may repeat, so each key holds a list in document order.
- * A designator the publisher wrote empty contributes an empty string, which is a value the publisher
- * stated rather than one it omitted: the Netherlands writes `<ad:designator/>` 198,118 times
- * over 108,708 features to mean "no extension", and that is a different condition from void.
+ * A designator the publisher wrote empty contributes an empty string.
+ *
+ * That string is a value the publisher stated rather than one it omitted.
+ * The Netherlands writes `<ad:designator/>` 198,118 times over 108,708 features to
+ * mean "no extension", and that condition differs from void.
  *
  * A designator whose `ad:type` is absent or void is skipped, because its value cannot be placed.
  */
@@ -216,7 +222,7 @@ export function designatorsByType(address: MarkupElement): ReadonlyMap<string, r
  * value has to be reported rather than turned into an absence.
  *
  * A caller reads this when the difference changes what it does.
- * An adapter that refuses a row carrying no house number should report a void `buildingIdentifier` as
+ * An adapter that refuses a row with no house number should report a void `buildingIdentifier` as
  * a value it could not read, and an absent one as an address the publisher states has no number.
  */
 export function voidDesignatorTypes(address: MarkupElement): ReadonlySet<string> {
@@ -235,20 +241,18 @@ export function voidDesignatorTypes(address: MarkupElement): ReadonlySet<string>
 		if (!value || !isVoid(value)) continue
 
 		const type = inspireChild(locatorDesignator, "ad:type")
-		const name = type && !isVoid(type) ? (codelistValue(type.attributes["xlink:href"]) ?? type.text) : undefined
+		const name = type && !isVoid(type) ? (codelistValue(type.attributes["xlink:href"]) ?? type.text) : null
 
-		// A void value whose own type is void or absent cannot be placed, so it is reported under
-		// the empty name rather than dropped, which keeps the address's unreadable parts countable.
+		// A void value whose own type is void or absent cannot be placed,
+		// so it is reported under the empty name.
+		// That keeps the address's unreadable parts countable.
 		voided.add(name || "")
 	}
 
 	return voided
 }
 
-export function designator(
-	byType: ReadonlyMap<string, readonly string[]>,
-	...types: readonly string[]
-): string | undefined {
+export function designator(byType: ReadonlyMap<string, readonly string[]>, ...types: readonly string[]): string | null {
 	for (const type of types) {
 		for (const value of byType.get(type) ?? []) {
 			const trimmed = value.trim()
@@ -257,7 +261,7 @@ export function designator(
 		}
 	}
 
-	return undefined
+	return null
 }
 
 /**
@@ -266,8 +270,10 @@ export function designator(
  * The href is returned verbatim, and {@linkcode componentJoinKey} turns it into a join key.
  * A component whose href is absent or empty is skipped.
  *
- * Brussels writes `<ad:component xlink:href=""/>` on 9 addresses, and those 9 therefore
- * carry no postal zone, which a caller must report rather than read as a resolved component.
+ * Brussels writes `<ad:component xlink:href=""/>` on 9 addresses.
+ * Those 9 hold no postal zone.
+ *
+ * A caller must report that rather than read a resolved component.
  */
 export function componentHrefs(address: MarkupElement): readonly string[] {
 	return componentLinks(address).map((link) => link.href)
@@ -283,9 +289,9 @@ export interface ComponentLink {
 	readonly href: string
 
 	/**
-	 * The `xlink:title`, or undefined where the reference carries none.
+	 * The `xlink:title`, or null where the reference has no title.
 	 */
-	readonly title?: string
+	readonly title: string | null
 }
 
 /**
@@ -299,7 +305,7 @@ export interface ComponentLink {
  * and an administrative-unit reference addresses a CartoCiudad stored query.
  *
  * The title is the only statement of the street name, the postcode and the place names
- * that its own file carries, so its adapter reads titles and resolves no reference.
+ * in its own file, so its adapter reads titles and resolves no reference.
  *
  * A component whose href is absent or empty is skipped, as in {@linkcode componentHrefs}.
  */
@@ -313,17 +319,17 @@ export function componentLinks(address: MarkupElement): readonly ComponentLink[]
 
 		const title = component.attributes["xlink:title"]?.trim()
 
-		links.push(title ? { href, title } : { href })
+		links.push({ href, title: title || null })
 	}
 
 	return links
 }
 
 /**
- * The query parameters a WFS stored-query reference carries its feature id in.
+ * The query parameters that hold a WFS stored-query reference's feature id.
  *
- * Each publisher picked a spelling, and the match below ignores case, so Czechia's `Id`
- * and Slovakia's `id` both resolve without naming each casing separately.
+ * Each publisher picked a spelling, and the match below ignores case,
+ * so Czechia's `Id` and Slovakia's `id` both resolve.
  * A reader that knew only `id` returned Czechia's whole URL as the key, and no `gml:id`
  * equals a URL, so all 5,460 of one municipality's references read as unjoinable.
  */
@@ -342,30 +348,32 @@ const REFERENCE_ID_PARAMETERS = new Set(["id", "featureid", "resourceid"])
  * | Slovakia | `…ad/ows?…&id=AdminUnitName.15345` | `AdminUnitName.15345` |
  * | Flanders | `https://data.vlaanderen.be/id/straatnaam/6301` | the URI itself |
  *
- * A URI with no id parameter is its own key, which is what Flanders publishes on both sides of the join.
- * Its fragment is dropped, because a reference may carry one where the identifier does not:
+ * A URI with no id parameter is its own key.
+ * Flanders publishes that form on both sides of the join.
+ *
+ * Its fragment is dropped, because a reference may hold one where the identifier does not:
  * `http://vocab.belgif.be/auth/refnis1995/1000#id` addresses the same term as that URI without it.
  *
  * Whether a key joins is not a property of its spelling, so this reads a key
  * and the caller decides joinability against the features the publisher actually served.
- * Deciding it here from the URL's shape once reported 15 of Flanders' 20 references as
- * belonging to another register when every one of them addressed a feature of the same service.
+ * A check based on the URL's shape once reported 15 of Flanders' 20 references as belonging
+ * to another register, when every one of them addressed a feature of the same service.
  *
- * @returns The key, or undefined when the href is neither a fragment nor a URL.
+ * @returns The key, or null when the href is neither a fragment nor a URL.
  */
-export function componentJoinKey(href: string): string | undefined {
+export function componentJoinKey(href: string): string | null {
 	const trimmed = href.trim()
 
-	if (!trimmed) return undefined
+	if (!trimmed) return null
 
-	if (trimmed.startsWith("#")) return trimmed.slice(1) || undefined
+	if (trimmed.startsWith("#")) return trimmed.slice(1) || null
 
 	let url: URL
 
 	try {
 		url = new URL(trimmed)
 	} catch {
-		return undefined
+		return null
 	}
 
 	for (const [parameter, value] of url.searchParams) {
@@ -382,7 +390,7 @@ export function componentJoinKey(href: string): string | undefined {
 }
 
 /**
- * The spelling a `gn:GeographicalName` carries, reached from a feature that holds one.
+ * The spelling a `gn:GeographicalName` holds, reached from a feature that has one.
  *
  * Every name-bearing INSPIRE feature nests the text at
  * `…/gn:GeographicalName/gn:spelling/gn:SpellingOfName/gn:text`, under a per-feature
@@ -390,9 +398,9 @@ export function componentJoinKey(href: string): string | undefined {
  * while an `ad:AdminUnitName` and an `ad:AddressAreaName` add only `ad:name`.
  * The caller gives the prefix.
  *
- * @returns The text, or undefined when any step is absent or the name is void.
+ * @returns The text, or null when any step is absent or the name is void.
  */
-export function geographicalNameText(feature: MarkupElement, ...prefix: readonly string[]): string | undefined {
+export function geographicalNameText(feature: MarkupElement, ...prefix: readonly string[]): string | null {
 	const name = inspireElementAt(
 		feature,
 		...prefix,
@@ -402,24 +410,24 @@ export function geographicalNameText(feature: MarkupElement, ...prefix: readonly
 		"gn:text"
 	)
 
-	if (!name || isVoid(name)) return undefined
+	if (!name || isVoid(name)) return null
 
 	const text = name.text.trim()
 
-	return text || undefined
+	return text || null
 }
 
 /**
  * The street name an `ad:ThoroughfareName` feature states.
  */
-export function thoroughfareName(feature: MarkupElement): string | undefined {
+export function thoroughfareName(feature: MarkupElement): string | null {
 	return geographicalNameText(feature, "ad:name", "ad:ThoroughfareNameValue", "ad:name")
 }
 
 /**
  * The place name an `ad:AdminUnitName` or `ad:AddressAreaName` feature states.
  */
-export function placeName(feature: MarkupElement): string | undefined {
+export function placeName(feature: MarkupElement): string | null {
 	return geographicalNameText(feature, "ad:name")
 }
 
@@ -430,14 +438,14 @@ export function placeName(feature: MarkupElement): string | undefined {
  * Left-padding belongs to the caller that knows the jurisdiction's width,
  * because this reader returns what the publisher wrote.
  */
-export function postalDescriptorCode(feature: MarkupElement): string | undefined {
+export function postalDescriptorCode(feature: MarkupElement): string | null {
 	const code = inspireChild(feature, "ad:postCode")
 
-	if (!code || isVoid(code)) return undefined
+	if (!code || isVoid(code)) return null
 
 	const text = code.text.trim()
 
-	return text || undefined
+	return text || null
 }
 
 /**
@@ -448,10 +456,10 @@ export function postalDescriptorCode(feature: MarkupElement): string | undefined
  * publishes exactly one `ad:AdminUnitName` feature, the country.
  * A caller picks the finest level it wants by this value rather than by the order the references appear.
  */
-export function adminUnitLevel(feature: MarkupElement): string | undefined {
+export function adminUnitLevel(feature: MarkupElement): string | null {
 	const level = inspireChild(feature, "ad:level")
 
-	if (!level || isVoid(level)) return undefined
+	if (!level || isVoid(level)) return null
 
-	return codelistValue(level.attributes["xlink:href"]) ?? (level.text.trim() || undefined)
+	return codelistValue(level.attributes["xlink:href"]) ?? (level.text.trim() || null)
 }

package/lib/inspire/errors.ts

@@ -8,8 +8,8 @@
  * An `ad:Address` states its street, its postcode and its place names by reference, and states the
  * parts of its number as typed designators. Both forms can hold a value the reader asked for and
  * could not read: a reference whose target the service never served, and a designator the publisher
- * marked `xsi:nil`. Turning either into an empty component would publish an address the publisher
- * did not state, so each raises and names what it could not read.
+ * marked `xsi:nil`. An empty component for either would publish an address the publisher did not
+ * state, so each raises and names what it could not read.
  *
  * The errors live beside {@linkcode "#inspire/address"} because every publisher of this theme writes
  * both forms, so an adapter for the next one reports the same two conditions in the same words.
@@ -27,7 +27,7 @@
  * unresolved reference and an absent one are the same observation.
  */
 export class UnresolvedComponentReferenceError extends Error {
-	constructor(adapterID: string, addressID: string | undefined, href: string) {
+	constructor(adapterID: string, addressID: string | null, href: string) {
 		super(
 			`${adapterID} adapter: address ${addressID ?? "(no gml:id)"} carries ad:component xlink:href="${href}", which resolves to no feature`
 		)
@@ -44,7 +44,7 @@ export class UnresolvedComponentReferenceError extends Error {
  * `voidDesignatorTypes` separates them, and this error reports the first case.
  */
 export class VoidDesignatorError extends Error {
-	constructor(adapterID: string, addressID: string | undefined, type: string) {
+	constructor(adapterID: string, addressID: string | null, type: string) {
 		super(`${adapterID} adapter: address ${addressID ?? "(no gml:id)"} marks its ${type} designator void`)
 
 		this.name = "VoidDesignatorError"
@@ -55,11 +55,12 @@ export class VoidDesignatorError extends Error {
  * Raised when a publication's archive cannot answer what the adapter asked it for.
  *
  * An archive holding no component feature is not a smaller publication.
- * Every address references a fixed set of components, so an empty index turns
- * each row into a row with no street rather than into fewer rows, which is the
- * absence the repository's partial-read rule refuses.
+ * Every address references a fixed set of components, so an empty index turns each
+ * row into a row with no street rather than into fewer rows.
  *
- * The adapter id carries which publisher failed, so one class serves every
+ * That is the absence the repository's partial-read rule refuses.
+ *
+ * The adapter id records which publisher failed, so one class serves every
  * publisher that ships its theme as one archive.
  */
 export class InspireArchiveError extends Error {

package/lib/inspire/stream.ts

@@ -8,10 +8,10 @@
  *
  * A publisher shipping the Addresses theme as one document writes an `ad:Address` beside the
  * `ad:ThoroughfareName`, `ad:PostalDescriptor` and place-name features it references, and the order
- * is the publisher's own. Czechia interleaves them per municipality, and the Netherlands writes
- * 300,318 reference features before its first address.
+ * is the publisher's own. Czechia interleaves them per municipality, and the Netherlands writes its
+ * reference features before its first address.
  *
- * Either way a reader has to index as it goes, because a document of 32 GB cannot be read twice from
+ * Either way a reader has to index as it goes, because a 32 GB document cannot be read twice from
  * one stream and the references are local. An address naming a feature the pass has not reached yet
  * is held rather than refused, since until the document ends an unresolved reference and an absent
  * one are the same observation. That distinction is what the repository's partial-read rule turns on.
@@ -22,10 +22,8 @@
  *
  * A publisher that writes every reference *after* its addresses needs the opposite of holding, and
  * {@linkcode streamIndexedInspireRows} serves it. The Dirección General del Catastro and the
- * Diputación Foral de Gipuzkoa both do: Catastro's Ceuta member writes its 511 reference features in
- * the last 530,000 of 11,861,975 bytes, and Gipuzkoa writes its 4,516 in the last 6,722,000 of
- * 313,162,472. Holding would mean holding every address. That is 68,744 subtrees for Gipuzkoa and
- * the whole of Madrid for Catastro, so those two read the member twice and index first.
+ * Diputación Foral de Gipuzkoa both do, so holding would leave every address pending. Those two
+ * read the member twice and index first.
  */
 
 import type { MarkupElement } from "@mailwoman/core/html/elements"
@@ -37,12 +35,13 @@ import type { CanonicalRow } from "#types"
  * What a {@linkcode ComposeInspireRow} callback answers for one address.
  *
  * A row is emitted.
- * `undefined` refuses the address, which the caller counts.
+ * `null` refuses the address.
+ * The caller counts each refusal.
  *
- * `deferred` states that the address carries a reference the pass has not indexed yet,
+ * `deferred` states that the address holds a reference the pass has not indexed yet,
  * so the driver holds it and asks again once the document has ended.
  */
-export type InspireRowResult = CanonicalRow | undefined | "deferred"
+export type InspireRowResult = CanonicalRow | null | "deferred"
 
 /**
  * Builds one row from an address and the references indexed so far.
@@ -70,30 +69,33 @@ export interface StreamInspireRowsOptions<Indexed> {
 	chunks: AsyncIterable<string | Uint8Array>
 
 	/**
-	 * The element each address is written as, which every INSPIRE publisher spells `ad:Address`.
+	 * The element each address is written as.
+	 * Every INSPIRE publisher spells it `ad:Address`.
 	 */
 	addressElement?: string
 
 	/**
-	 * The elements an address references, which are indexed as they arrive.
+	 * The elements an address references.
+	 * The reader indexes them as they arrive.
 	 */
 	componentElements: readonly string[]
 
 	/**
 	 * What to index a referenced feature under.
 	 *
-	 * The default is its `gml:id`, which is what a local `#` fragment
-	 * and a stored-query `Id` parameter both name.
 	 * A feature carrying no key is skipped, because an address cannot reference it.
+	 *
+	 * @defaultValue its `gml:id`, which is what a local `#` fragment
+	 * and a stored-query `Id` parameter both name.
 	 */
-	key?: (feature: MarkupElement) => string | undefined
+	key?: (feature: MarkupElement) => string | null
 
 	/**
 	 * What to keep per referenced feature.
 	 *
 	 * Czechia keeps the subtree, because it reads several values off one feature.
-	 * The Netherlands keeps the one string it needs, which holds 300,318 strings
-	 * rather than 300,318 subtrees.
+	 * The Netherlands keeps the one string it needs.
+	 * That holds 300,318 strings rather than 300,318 subtrees.
 	 */
 	index: (feature: MarkupElement) => Indexed
 
@@ -116,15 +118,15 @@ export interface StreamInspireRowsOptions<Indexed> {
 /**
  * The default key a referenced feature is indexed under.
  */
-function gmlID(feature: MarkupElement): string | undefined {
-	return feature.attributes["gml:id"]
+function gmlID(feature: MarkupElement): string | null {
+	return feature.attributes["gml:id"] ?? null
 }
 
 /**
  * The rows one document holds, in the order the publisher wrote its addresses.
  *
  * A held address is answered after the document ends, so those rows arrive last.
- * That reorders a publisher's output and changes no row, because each row carries its own `source_id`.
+ * That reorders a publisher's output and changes no row, because each row holds its own `source_id`.
  */
 export async function* streamInspireRows<Indexed>(
 	options: StreamInspireRowsOptions<Indexed>
@@ -181,8 +183,8 @@ export async function* streamInspireRows<Indexed>(
 
 		const row = options.compose(element, referenced, true)
 
-		// `deferred` after the document ended is a caller that ignored `final`,
-		// and the row is refused rather than held again, which would never terminate.
+		// `deferred` after the document ended is a caller that ignored `final`.
+		// The row is refused, because holding it again would never terminate.
 		if (!row || row === "deferred") continue
 
 		yield row
@@ -204,8 +206,9 @@ export interface StreamIndexedInspireRowsOptions<Indexed> extends Omit<
 	 * Called once per pass, so it must deliver the same bytes each time.
 	 *
 	 * A factory rather than an iterable, because a byte stream is consumed by the first pass.
-	 * `inspireGMLChunks` inflates the archive member again, which is what makes the
-	 * second pass cheap relative to holding every address.
+	 * `inspireGMLChunks` inflates the archive member again.
+	 *
+	 * That is what makes the second pass cheap relative to holding every address.
 	 */
 	chunks: () => AsyncIterable<string | Uint8Array>
 
@@ -216,7 +219,7 @@ export interface StreamIndexedInspireRowsOptions<Indexed> extends Omit<
 	 * so a reference resolving to no feature is a value the reader asked for and could not read.
 	 * The caller raises on one rather than writing the address without it.
 	 */
-	compose: (address: MarkupElement, referenced: ReadonlyMap<string, Indexed>) => CanonicalRow | undefined
+	compose: (address: MarkupElement, referenced: ReadonlyMap<string, Indexed>) => CanonicalRow | null
 }
 
 /**
@@ -224,7 +227,7 @@ export interface StreamIndexedInspireRowsOptions<Indexed> extends Omit<
  *
  * The first pass reads only the component elements and the second only the addresses,
  * so the resident set is the index rather than the addresses.
- * The rows arrive in the publisher's own order, which {@linkcode streamInspireRows}
+ * The rows arrive in the publisher's own order. {@linkcode streamInspireRows}
  * cannot promise because it answers a held address last.
  */
 export async function* streamIndexedInspireRows<Indexed>(

package/lib/international/recipes/locale.ts

@@ -230,7 +230,7 @@ export async function readTuples(part: LocalePart, rng: () => number): Promise<L
 		for await (const cells of CSVSpliterator.fromAsync<string[]>(input, {
 			header: false,
 		})) {
-			if (header === null) {
+			if (!header) {
 				header = cells.map((h) => h.toLowerCase())
 				// oxlint-disable-next-line no-loop-func -- the binding is per-iteration (for-of/for-await) and the batch is awaited before the next
 				const ix = (name: string): number => header!.indexOf(name)
@@ -259,7 +259,7 @@ export async function readTuples(part: LocalePart, rng: () => number): Promise<L
 				continue
 			}
 
-			if (cols === null) continue
+			if (!cols) continue
 
 			// Raw CNIG splits the road type from the street name, so the two are joined here.
 			const street =
@@ -272,7 +272,7 @@ export async function readTuples(part: LocalePart, rng: () => number): Promise<L
 			if (!street) continue
 
 			let locality: string | null
-			let dependent_locality: string | undefined
+			let dependent_locality: string | null = null
 
 			if (part.districtAsLocality) {
 				const rawDistrict = get(cells, cols.district)
@@ -289,7 +289,7 @@ export async function readTuples(part: LocalePart, rng: () => number): Promise<L
 					dependent_locality =
 						cleanedCity && cleanedCity.localeCompare(locality, undefined, { sensitivity: "base" }) !== 0
 							? cleanedCity
-							: undefined
+							: null
 				} else {
 					locality = cleanCityNoise(rawCity)
 				}
@@ -368,15 +368,15 @@ export function applyCountryAppend(
  * Applies the per-run `districtAsLocality` override to a part.
  * An unset override returns the part unchanged.
  */
-export function applyDistrictAsLocalityOverride(part: LocalePart, override: boolean | undefined): LocalePart {
-	return override === undefined ? part : { ...part, districtAsLocality: override }
+export function applyDistrictAsLocalityOverride(part: LocalePart, override: boolean | null): LocalePart {
+	return override === null ? part : { ...part, districtAsLocality: override }
 }
 
 /**
  * Returns the country's `pedaniaParts` when the override is true and that property exists.
  * Returns the default parts in all other cases.
  */
-export function resolveLocaleParts(countrySource: LocaleCountrySource, override: boolean | undefined): LocalePart[] {
+export function resolveLocaleParts(countrySource: LocaleCountrySource, override: boolean | null): LocalePart[] {
 	return override === true && countrySource.pedaniaParts ? countrySource.pedaniaParts : countrySource.parts
 }
 
@@ -432,7 +432,7 @@ export const localeRecipe: CorpusRecipe = {
 		const count = opts.count ?? 4000
 		// When unset, each part keeps its own setting.
 		// True also selects the ES pedanía parts.
-		const districtAsLocalityOverride = opts.districtAsLocality
+		const districtAsLocalityOverride = opts.districtAsLocality ?? null
 		const parts = resolveLocaleParts(countrySource, districtAsLocalityOverride)
 
 		const pool: LocaleBaseTuple[] = []
@@ -462,10 +462,14 @@ export const localeRecipe: CorpusRecipe = {
 			const base = pool[Math.floor(random() * N)]!
 			const order = random() < intlFraction ? "international" : "native"
 
-			// These draws happen only for ES and NL, so other countries' seeded output is unaffected.
+			// These draws happen only for ES and NL, so other countries' seeded output
+			// is unaffected. country-branch: the ES house-number join and the NL glued
+			// postcode are measured surface shares for those two sources.
+			// A per-country surface table in the codex address layouts would replace both branches.
 			const nativeHouseJoin =
 				country === "ES" ? (random() < ES_SPACE_JOIN_FRACTION ? ("space" as const) : ("template" as const)) : undefined
 
+			// country-branch: see the ES branch above.
 			const postcodeShape =
 				country === "NL"
 					? random() < NL_GLUED_POSTCODE_FRACTION