@mailwoman/corpus 10.1.0 → 10.2.0

package/lib/be/adapters/brussels/adapter.ts

@@ -166,15 +166,15 @@ export const BRUSSELS_COUNTRIES: readonly string[] = ["BE"]
  * The license label recorded on every row.
  *
  * The register's source `be-property-building-3` elects `CC-BY-4.0` for Paradigm, read from
- * the `gmd:useConstraints` of ISO 19139 record `260abd6f-c5b4-4a79-aa80-d6c265002d65`,
- * which names `URBIS_ADM_Adresses.zip` among its distributions.
- * That record governs this archive rather than Paradigm's other address product,
- * the BeSt Brussels register, which is CC0-1.0.
+ * the `gmd:useConstraints` of ISO 19139 record `260abd6f-c5b4-4a79-aa80-d6c265002d65`.
+ * That record lists `URBIS_ADM_Adresses.zip` among its distributions and governs this archive
+ * rather than Paradigm's other address product, the BeSt Brussels register, licensed CC0-1.0.
  *
  * The value is the SPDX identifier rather than the license's title, because
  * `licenseVerdict` resolves an identifier and reads a title as unrecognized.
- * This constant previously held `unreviewed-be-brussels-urbis`, which resolved to no expression,
- * so these rows carried unknown obligations into a build that had no way to filter them.
+ * The constant must not hold a placeholder such as `unreviewed-be-brussels-urbis`.
+ *
+ * That value resolves to no expression, so these rows would reach a build as unknown obligations.
  */
 export const BRUSSELS_DEFAULT_LICENSE = "CC-BY-4.0"
 
@@ -246,21 +246,21 @@ const NIS_CODED_NAME = /^(\d+)\s*\((.*)\)$/u
  * a prefix the publisher writes rather than parsing a name: a changed shape must reach a
  * reader as the publisher's own value instead of as a guess at what the name inside might be.
  *
- * A value of that shape whose parentheses hold an empty string answers `undefined`,
+ * A value of that shape whose parentheses hold an empty string answers `null`,
  * so the caller refuses the row rather than writing a NIS code into a locality.
  *
- * @returns The name, or `undefined` for an absent value and for a code with an empty name.
+ * @returns The name, or `null` for an absent value and for a code with an empty name.
  */
-export function placeNameWithoutNISCode(value: string | undefined): string | undefined {
+export function placeNameWithoutNISCode(value: string | null): string | null {
 	const trimmed = value?.trim()
 
-	if (!trimmed) return undefined
+	if (!trimmed) return null
 
 	const coded = NIS_CODED_NAME.exec(trimmed)
 
 	if (!coded) return trimmed
 
-	return coded[2]!.trim() || undefined
+	return coded[2]!.trim() || null
 }
 
 /**
@@ -337,19 +337,19 @@ export async function readBrusselsComponents(
 		if (feature.name === "ad:ThoroughfareName") {
 			const street = thoroughfareName(feature)
 
-			if (street !== undefined) {
+			if (street) {
 				streets.set(id, street)
 			}
 		} else if (feature.name === "ad:PostalDescriptor") {
 			const postcode = postalDescriptorCode(feature)
 
-			if (postcode !== undefined) {
+			if (postcode) {
 				postcodes.set(id, postcode)
 			}
 		} else if (adminUnitLevel(feature) === MUNICIPALITY_LEVEL) {
 			const municipality = placeNameWithoutNISCode(placeName(feature))
 
-			if (municipality !== undefined) {
+			if (municipality) {
 				municipalities.set(id, municipality)
 			}
 		}
@@ -451,10 +451,10 @@ export function createBrusselsAdapter(): CorpusAdapter {
 					if (opts.limit !== undefined && emitted >= opts.limit) break
 
 					// `designatorsByType` leaves out a designator the publisher marked void, so a void number
-					// and an absent one both read as undefined and `voidDesignatorTypes` separates them below.
+					// and an absent one both read as null and `voidDesignatorTypes` separates them below.
 					const house = designator(designatorsByType(address), HOUSE_NUMBER_DESIGNATOR)
 
-					if (house === undefined) {
+					if (!house) {
 						// A void number is a value this run could not read and an absent one is
 						// a number the publisher states the address has none of.
 						// Neither is emitted, and the two are counted apart so a run reports which it met.
@@ -472,14 +472,14 @@ export function createBrusselsAdapter(): CorpusAdapter {
 					// exactly the nine addresses whose postal zone is empty.
 					const slots = componentHrefs(address)
 
-					let street: string | undefined
-					let postcode: string | undefined
-					let locality: string | undefined
+					let street: string | null = null
+					let postcode: string | null = null
+					let locality: string | null = null
 
 					for (const href of slots) {
 						const key = componentJoinKey(href)
 
-						if (key === undefined) continue
+						if (!key) continue
 
 						street = index.streets.get(key) ?? street
 						postcode = index.postcodes.get(key) ?? postcode
@@ -488,7 +488,7 @@ export function createBrusselsAdapter(): CorpusAdapter {
 						locality = index.municipalities.get(key) ?? locality
 					}
 
-					if (postcode === undefined && slots.length < COMPONENTS_PER_ADDRESS) {
+					if (!postcode && slots.length < COMPONENTS_PER_ADDRESS) {
 						// The publisher wrote the postal-zone reference empty.
 						// The row is refused and reported rather than yielded with the postcode missing,
 						// because an unstated value is not an address without a postcode.
@@ -499,7 +499,7 @@ export function createBrusselsAdapter(): CorpusAdapter {
 
 					// A component the index cannot answer is a street, postcode or locality this run could not read.
 					// A row emitted without it would record an absence the publisher never stated.
-					if (street === undefined || postcode === undefined || locality === undefined) {
+					if (!street || !postcode || !locality) {
 						refused.unjoined++
 
 						continue

package/lib/be/adapters/vlaanderen/adapter.ts

@@ -10,24 +10,24 @@
  * through their own services, so this adapter emits `BE` on every row it yields, and a Belgian build needs
  * two more sources beside it.
  *
- * The schema-level reading is `#inspire/address`, which owns every part of an `ad:Address` that the
- * publishers spell alike. This module holds only what is Flanders' own: the `resourceId` rewrite its
- * references need, the homonym discriminator its street names carry, and the lost characters its
- * values carry.
+ * The schema-level reading is `#inspire/address`. That module owns every part of an `ad:Address` the
+ * publishers spell alike. This module holds only Flanders' own additions: the `resourceId` rewrite
+ * its references need, the homonym discriminator appended to its street names, and the lost
+ * characters in its values.
  *
  * The adapter records `Modellicentie voor gratis hergebruik Vlaanderen` on every row, the terms the
  * address-source register elects for `be-property-building-1` in `electedTerms`. Article 3 grants
  * reproduction, adaptation and commercial exploitation for any lawful purpose. Article 4 makes
- * attribution the only condition, in the form the licensor specifies, so the model card must carry
+ * attribution the only condition, in the form the licensor specifies, so the model card must state
  * `Bron: Digitaal Vlaanderen`.
  *
  * The capabilities document's `ows:Fees` and `ows:AccessConstraints` state what calling the service
  * costs and who may call it. They describe the service rather than licensing the data, so the
- * license comes from the register and this adapter reads the capabilities for feature types alone.
+ * license comes from the register and this adapter reads the capabilities only for feature types.
  *
  * ## Why the input is a harvest rather than the service
  *
- * An `ad:Address` carries its house number inline and everything else by reference. Each address
+ * An `ad:Address` states its house number inline and everything else by reference. Each address
  * holds exactly four `ad:component/@xlink:href` values, measured over 1,000 addresses at six
  * `startIndex` offsets with all four prefixes occurring 1,000 times each. The references are
  * absolute URIs that resolve back into the same service under the `resourceId` rewrite that
@@ -40,7 +40,7 @@
  * | `https://data.vlaanderen.be/id/gemeentenaam/44083` | `gemeentenaam_44083` | `ad:AdminUnitName`    |
  * | `http://vocab.belgif.be/auth/refnis1995/1000#id`   | `refnis1995_1000`    | `ad:AdminUnitName`    |
  *
- * Resolving per address would cost four requests per row against 4,563,062 addresses. The component
+ * A per-address resolution would cost four requests per row against 4,563,062 addresses. The component
  * types are small — 167,218 thoroughfare names, 1,190 postal descriptors, 609 administrative-unit
  * names — so the harvest takes each component type whole and the adapter joins locally.
  *
@@ -98,9 +98,10 @@ export const VLAANDEREN_ADAPTER_ID = "vlaanderen"
 /**
  * The terms the address-source register elects for `be-property-building-1`.
  *
- * The value is the register's `electedTerms` for license
- * `unchecked-access-free-be-agentschap-digitaal-vlaanderen`, which carries no `spdx`,
- * so `electedLicenseLabel` answers this string and the share-alike prefix filter matches it.
+ * The register's `electedTerms` for license
+ * `unchecked-access-free-be-agentschap-digitaal-vlaanderen` states this value.
+ * That license has no `spdx`, so `electedLicenseLabel` answers this string
+ * and the share-alike prefix filter matches it.
  */
 export const VLAANDEREN_DEFAULT_LICENSE = "Modellicentie voor gratis hergebruik Vlaanderen"
 
@@ -108,8 +109,9 @@ export const VLAANDEREN_DEFAULT_LICENSE = "Modellicentie voor gratis hergebruik
  * The one jurisdiction this adapter emits.
  *
  * The service publishes the Flemish Region.
- * ISO 3166-1 assigns that region no code of its own, so its own, so the set holds one code
- * and a caller naming any other gets {@linkcode UnsupportedCountryError} rather than zero rows.
+ * ISO 3166-1 assigns that region no code of its own, so the set holds one code.
+ *
+ * A caller that requests any other gets {@linkcode UnsupportedCountryError} rather than zero rows.
  */
 export const VLAANDEREN_COUNTRIES: readonly string[] = ["BE"]
 
@@ -120,19 +122,19 @@ export const VLAANDEREN_COUNTRIES: readonly string[] = ["BE"]
  * rather than by position.
  * Flanders uses one type across 1,000 addresses sampled.
  *
- * Czechia and Brussels write `buildingIdentifier` and the Netherlands `addressNumber` for
- * the same part, which is why `#inspire/address` leaves the vocabulary to the caller.
+ * Czechia and Brussels write `buildingIdentifier` and the Netherlands `addressNumber` for the same part.
+ * `#inspire/address` therefore leaves the vocabulary to the caller.
  */
 const HOUSE_NUMBER_DESIGNATOR = "addressIdentifierGeneral"
 
 /**
- * The `ad:level` of the administrative unit that carries the municipality name.
+ * The `ad:level` of the administrative unit that states the municipality name.
  *
  * An address references two `ad:AdminUnitName` features.
  * `gemeentenaam_44083` is `5thOrder` and resolves to the municipality `Deinze`.
  *
  * `refnis1995_1000` is `1stOrder` and resolves to the country (`België`).
- * Taking whichever arrives first would write `België` into the `locality` of some rows.
+ * A reader that takes whichever arrives first would write `België` into the `locality` of some rows.
  */
 const MUNICIPALITY_LEVEL = "5thOrder"
 
@@ -146,8 +148,8 @@ const MUNICIPALITY_LEVEL = "5thOrder"
  * for `straatnaam_138007`, with zero bytes above 0x7F in either body.
  *
  * Measured over 20,000 `ad:ThoroughfareName` values at twenty offsets,
- * 1,657 carry a `?` and 0 carry any non-ASCII character.
- * `ad:AdminUnitName` carries 34 of 609 and `ad:PostalDescriptor` 161 of 1,189 — and `ad:AdminUnitName`
+ * 1,657 have a `?` and 0 have any non-ASCII character.
+ * `ad:AdminUnitName` has 34 of 609 and `ad:PostalDescriptor` 161 of 1,189 — and `ad:AdminUnitName`
  * also serves `België` intact, so the loss is per-value rather than a service-wide transcode.
  *
  * No address component is written with a question mark, so a value holding one
@@ -279,24 +281,19 @@ export function componentResourceID(href: string): string | null {
 /**
  * A Flemish street name read apart from the homonym discriminator that follows it.
  *
- * `gn:text` on an `ad:ThoroughfareName` is not the street name alone: it is the name,
+ * `gn:text` on an `ad:ThoroughfareName` states more than the street name: the name,
  * an underscore, and a discriminator that is usually empty.
- * Over 20,000 values at twenty offsets, 19,979 end with `_` and the remaining 21 carry a
- * discriminator after it — `Rue de Cronwez_01`, `Rue de Cronwez_02`, `Heide_01`, `Heide_02`,
- * `Kattenberg_BO`, `Kattenberg_EK`, `Ringlaan_ME`, `Ringlaan_BEWI`, `Berkenlaan_WI`,
- * `Weerstandlaan_BO`, `Weerstandlaan_HO`, `Cit? du Repos_01` through `_04`, `Rue du Roeulx_01`,
- * `Rue du Roeulx_02`, `Rue Verte_01`, `Rue Verte_02` and `Rue des Par?onniers_01`/`_02`.
- *
- * Exactly 21 values carry an `_` anywhere but at the end, and they are the same 21: no value holds
- * both a discriminator and a trailing separator, so the field is one separator at one position.
- *
- * The same streets read through `ad:AddressRepresentation/ad:thoroughfare` carry
- * no separator at all, 0 of 10,000, which is the publisher's own evidence that
- * everything from the `_` onward is bookkeeping rather than name.
- *
- * So the split takes the last `_` and keeps the head.
- * Stripping only a trailing `_` would leave `Rue de Cronwez_01` in a corpus,
- * and keeping the whole value would leave `Acacialaan_`.
+ * Over 20,000 values at twenty offsets, 19,979 end with `_` and the remaining
+ * 21 have a discriminator after it.
+ *
+ * Exactly 21 values have an `_` somewhere other than the end.
+ * Those same 21 values hold the only discriminators, so the field has one separator at one position.
+ *
+ * The same streets read through `ad:AddressRepresentation/ad:thoroughfare` have no separator, 0 of 10,000.
+ * The publisher's own data therefore marks everything from the `_` onward as bookkeeping.
+ *
+ * The split takes the last `_` and keeps the head.
+ * That drops a trailing separator and any discriminator in one step.
  */
 export interface SplitStreetName {
 	/**
@@ -312,10 +309,10 @@ export interface SplitStreetName {
 /**
  * Splits an `ad:ThoroughfareName` `gn:text` value into its {@link SplitStreetName}.
  *
- * @throws {@linkcode VlaanderenHarvestError} when the value carries no `_`,
- * which no value of the 20,000 measured did.
- * That is a change in the publisher's field rather than an odd street, and guessing at
- * it would write a bookkeeping suffix into every row sharing the new shape.
+ * @throws {@linkcode VlaanderenHarvestError} when the value has no `_`.
+ * Every one of the 20,000 measured values had one.
+ * That would be a change in the publisher's field.
+ * A guess at it would write a bookkeeping suffix into every row sharing the new shape.
  */
 export function splitStreetName(value: string): SplitStreetName {
 	const separator = value.lastIndexOf("_")
@@ -332,17 +329,17 @@ export function splitStreetName(value: string): SplitStreetName {
 }
 
 /**
- * The house number an address states inline, or `undefined` when it states none this adapter can use.
+ * The house number an address states inline, or `null` when it states none this adapter can use.
  *
  * `designatorsByType` skips a designator the publisher marked void, so a void number
- * and an absent one both answer `undefined` here.
+ * and an absent one both answer `null` here.
  * Both are refusals rather than addresses with no number, and the caller counts
  * them together for that reason.
  *
  * `ad:designator` was present and populated on 1,000 of 1,000 addresses sampled,
  * so neither condition has been seen on this service.
  */
-export function houseNumberOf(address: MarkupElement): string | undefined {
+export function houseNumberOf(address: MarkupElement): string | null {
 	return designator(designatorsByType(address), HOUSE_NUMBER_DESIGNATOR)
 }
 
@@ -353,7 +350,7 @@ async function readComponentFiles<T>(
 	root: PathBuilder,
 	files: readonly string[],
 	typeName: string,
-	read: (feature: MarkupElement) => T | undefined,
+	read: (feature: MarkupElement) => T | null,
 	signal?: AbortSignal
 ): Promise<Map<string, T>> {
 	const index = new Map<string, T>()
@@ -374,7 +371,7 @@ async function readComponentFiles<T>(
 
 			const value = read(feature)
 
-			if (value !== undefined) {
+			if (value !== null) {
 				index.set(id, value)
 			}
 		}
@@ -415,7 +412,7 @@ async function readComponentIndex(
 		root,
 		harvest.components.AdminUnitName,
 		"ad:AdminUnitName",
-		(feature) => (adminUnitLevel(feature) === MUNICIPALITY_LEVEL ? placeName(feature) : undefined),
+		(feature) => (adminUnitLevel(feature) === MUNICIPALITY_LEVEL ? placeName(feature) : null),
 		signal
 	)
 
@@ -539,21 +536,21 @@ export function createVlaanderenAdapter(): CorpusAdapter {
 
 						const house = houseNumberOf(address)
 
-						if (house === undefined) {
+						if (!house) {
 							refused.noHouseNumber++
 
 							continue
 						}
 
-						let street: string | undefined
-						let postcode: string | undefined
-						let locality: string | undefined
+						let street: string | null = null
+						let postcode: string | null = null
+						let locality: string | null = null
 						let unreadable = false
 
 						for (const href of componentHrefs(address)) {
 							const id = componentResourceID(href)
 
-							if (id === null) {
+							if (!id) {
 								unreadable = true
 
 								break
@@ -561,7 +558,7 @@ export function createVlaanderenAdapter(): CorpusAdapter {
 
 							const streetValue = index.streets.get(id)
 
-							if (streetValue !== undefined) {
+							if (streetValue) {
 								street = streetValue
 
 								continue
@@ -569,7 +566,7 @@ export function createVlaanderenAdapter(): CorpusAdapter {
 
 							const postcodeValue = index.postcodes.get(id)
 
-							if (postcodeValue !== undefined) {
+							if (postcodeValue) {
 								postcode = postcodeValue
 
 								continue
@@ -582,8 +579,8 @@ export function createVlaanderenAdapter(): CorpusAdapter {
 
 						// A reference the harvest cannot answer is a street, postcode
 						// or locality this run could not read.
-						// Emitting the row without it would record an absence the publisher never stated.
-						if (unreadable || street === undefined || postcode === undefined || locality === undefined) {
+						// A row emitted without it would record an absence the publisher never stated.
+						if (unreadable || !street || !postcode || !locality) {
 							refused.unjoined++
 
 							continue
@@ -637,8 +634,8 @@ export function createVlaanderenAdapter(): CorpusAdapter {
 					}
 
 					// A short page is a page this run could not read whole.
-					// Reading it as a smaller page would drop its tail silently,
-					// and a harvest of 457 pages hides one missing tail.
+					// A smaller-page read would drop its tail silently, and a harvest of
+					// 457 pages hides one missing tail.
 					const bounded = opts.limit !== undefined || Boolean(opts.signal?.aborted)
 
 					if (!bounded && seen !== page.numberReturned) {

package/lib/be/adapters/wallonie/adapter.ts

@@ -78,8 +78,8 @@
  * and states what identifies it: the SPW's ICAR presentation to the Club des utilisateurs du PICC
  * (27 February 2015) lists the communes' validation of sub-addresses identified by their
  * `numéro de boîte`, the box number, and its ICAR address form records each sub-address's `Numéro` apart from the `Index`
- * field. A box number identifies one delivery point inside the numbered premise, which is the
- * concept the `unit` tag carries. It is not a floor, a building, an entrance or a staircase, even
+ * field. A box number identifies one delivery point inside the numbered premise. That is the
+ * concept the `unit` tag records. It is not a floor, a building, an entrance or a staircase, even
  * where a code such as `0RCH` (rez-de-chaussée) names the box after the floor it sits on.
  *
  * The value is rendered as the publisher writes it, with no designator word: `Rue de la Station 29
@@ -308,25 +308,25 @@ export async function readWallonieComponents(
 		if (feature.name === "ad:ThoroughfareName") {
 			const street = thoroughfareName(feature)
 
-			if (street !== undefined) {
+			if (street) {
 				streets.set(id, street)
 			}
 		} else if (feature.name === "ad:PostalDescriptor") {
 			const postcode = postalDescriptorCode(feature)
 
-			if (postcode !== undefined) {
+			if (postcode) {
 				postcodes.set(id, postcode)
 			}
 		} else if (feature.name === "ad:AddressAreaName") {
 			const area = placeName(feature)
 
-			if (area !== undefined) {
+			if (area) {
 				areas.set(id, area)
 			}
 		} else if (adminUnitLevel(feature) === MUNICIPALITY_LEVEL) {
 			const municipality = placeName(feature)
 
-			if (municipality !== undefined) {
+			if (municipality) {
 				municipalities.set(id, municipality)
 			}
 		}
@@ -413,11 +413,11 @@ export function createWallonieAdapter(): CorpusAdapter {
 					if (opts.limit !== undefined && emitted >= opts.limit) break
 
 					// `designatorsByType` leaves out a designator the publisher marked void, so a void number
-					// and an absent one both read as undefined and `voidDesignatorTypes` separates them below.
+					// and an absent one both read as null and `voidDesignatorTypes` separates them below.
 					const byType = designatorsByType(address)
 					const house = designator(byType, HOUSE_NUMBER_DESIGNATOR)
 
-					if (house === undefined) {
+					if (!house) {
 						// A void number is a value this run could not read and an absent one is
 						// a number the publisher states the address has none of.
 						// Neither is emitted, and the two are counted apart so a run reports which it met.
@@ -432,19 +432,19 @@ export function createWallonieAdapter(): CorpusAdapter {
 
 					const box = designator(byType, NUMBER_EXTENSION_DESIGNATOR)
 
-					if (box !== undefined) {
+					if (box) {
 						extensions++
 					}
 
-					let street: string | undefined
-					let postcode: string | undefined
-					let locality: string | undefined
-					let area: string | undefined
+					let street: string | null = null
+					let postcode: string | null = null
+					let locality: string | null = null
+					let area: string | null = null
 
 					for (const href of componentHrefs(address)) {
 						const key = componentJoinKey(href)
 
-						if (key === undefined) continue
+						if (!key) continue
 
 						street = index.streets.get(key) ?? street
 						postcode = index.postcodes.get(key) ?? postcode
@@ -456,7 +456,7 @@ export function createWallonieAdapter(): CorpusAdapter {
 
 					// A component the index cannot answer is a street, postcode or locality this run could not read.
 					// A row emitted without it would record an absence the publisher never stated.
-					if (street === undefined || postcode === undefined || locality === undefined) {
+					if (!street || !postcode || !locality) {
 						countDropped(tally, Refusal.Unjoined)
 
 						continue
@@ -469,14 +469,14 @@ export function createWallonieAdapter(): CorpusAdapter {
 						locality,
 					}
 
-					if (box !== undefined) {
+					if (box) {
 						components.unit = box
 					}
 
 					// The `partie de commune` is a dependent locality only where it names
 					// something other than the municipality.
 					// `Braine-l'Alleud` has an area of the same name, and `Beauvechain` has `Hamme-Mille`.
-					if (area !== undefined && area !== locality) {
+					if (area && area !== locality) {
 						components.dependent_locality = area
 					}
 

package/lib/be/tools/fetch/brussels.ts

@@ -29,7 +29,7 @@
 
 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 { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -39,12 +39,13 @@ import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetc
 import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 /**
- * The archive's URL, which is the whole acquisition path for this theme.
+ * The archive's URL, the whole acquisition path for this theme.
  */
 export const BE_BRUSSELS_ARCHIVE_URL = "https://urbisdownload.datastore.brussels/INSPIRE/URBIS_ADM_Adresses.zip"
 
 /**
- * The name the archive is written under, which is what the adapter's `inputPath` states.
+ * The name the archive is written under.
+ * The adapter's `inputPath` states this name.
  */
 export const BE_BRUSSELS_ARCHIVE_FILENAME = "URBIS_ADM_Adresses.zip"
 
@@ -86,8 +87,9 @@ export interface DownloadBrusselsOptions {
  * What the publisher's HEAD response states about the archive it holds.
  *
  * 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 happens to match the one on disk.
  */
 export interface BrusselsPublication {
 	lastModified: string | null
@@ -97,7 +99,7 @@ export interface BrusselsPublication {
 /**
  * Reads the publisher's HEAD response.
  *
- * Separate from {@linkcode downloadBrussels} because this one request carries the whole freshness
+ * Separate from {@linkcode downloadBrussels} because this one request holds the whole freshness
  * decision, and the download itself runs on global `fetch`, which a unit test cannot intercept.
  */
 export async function readBrusselsPublication(
@@ -123,16 +125,17 @@ export async function readBrusselsPublication(
  * Whether the archive on disk is the one the publisher currently serves.
  *
  * A skip requires the publisher 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.
- * Downloading 11 MiB again is the cheaper error.
+ * Where it states none, both sides read `null` and an equality test would hold.
+ *
+ * A skip there would keep an archive of unknown age for as long as the service stayed silent.
+ * A second 11 MiB download is the cheaper error.
  */
 export function brusselsPublicationIsRecorded(
 	recorded: BrusselsManifest,
 	bytesOnDisk: number,
 	publication: BrusselsPublication
 ): boolean {
-	if (publication.lastModified === null) return false
+	if (!publication.lastModified) return false
 
 	return recorded.last_modified === publication.lastModified && recorded.bytes === bytesOnDisk
 }

package/lib/be/tools/fetch/wallonie.ts

@@ -27,7 +27,7 @@
 
 import { APIClient, assertNoOGCServiceException } 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 { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -38,12 +38,12 @@ import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetc
 import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 /**
- * The ATOM service document, which lists the region's one dataset feed.
+ * The ATOM service document for the region's one dataset feed.
  */
 export const BE_WALLONIE_SERVICE_URL = "https://geoservices.wallonie.be/inspire/atom/AD_Service.xml"
 
 /**
- * The name the archive is written under, which is what the adapter's `inputPath` states.
+ * The archive filename, the same one the adapter's `inputPath` states.
  */
 export const BE_WALLONIE_ARCHIVE_FILENAME = "AD.Addresses.gml.zip"
 
@@ -58,8 +58,9 @@ const SLUG = WALLONIE_ADAPTER_ID
  * What one run recorded.
  *
  * `feed_updated` is the dataset feed's own `<updated>`.
- * A later run downloads again when that value changes, which is what the INSPIRE
- * pattern offers in place of an HTTP validator.
+ * A later run downloads again when that value changes.
+ *
+ * The INSPIRE pattern offers that field in place of an HTTP validator.
  */
 export interface WallonieManifest extends SourceManifest {
 	service_url: string
@@ -93,7 +94,7 @@ export interface WallonieArchiveReference {
 	 * The archive entry's own `<updated>`, or `null` where the feed states none.
 	 *
 	 * `updated` sits on an Atom entry rather than on the feed, so this reads the
-	 * entry that carried the archive link.
+	 * entry that holds the archive link.
 	 * Wallonia's feed reported `2025-12-11` when this reader was written.
 	 */
 	feedUpdated: string | null
@@ -196,7 +197,7 @@ export async function downloadWallonie(
 	const recorded = await readManifest<WallonieManifest>(manifestPath)
 	const stat = await tryStat(archivePath)
 
-	if (!options.force && recorded && stat && feedUpdated !== null && recorded.feed_updated === feedUpdated) {
+	if (!options.force && recorded && stat && feedUpdated && recorded.feed_updated === feedUpdated) {
 		report?.(`  present, and the dataset feed reports the recorded updated ${feedUpdated}`)
 
 		return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] }

package/lib/build/adapters.ts

@@ -6,7 +6,8 @@
  *   previous build finished.
  */
 
-import { pathExists, readLocalJSONFile, statPath } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { pathExists, statPath } from "@mailwoman/core/fs/readers/stat"
 import type { PathBuilder } from "path-ts"
 
 import type { BuildStage } from "#build/types"

package/lib/build/align.ts

@@ -78,8 +78,9 @@ export interface AlignPhaseResult {
 	/**
 	 * Rows the license policy refused, counted per `source`.
 	 *
-	 * A source here contributed zero rows to the corpus whatever its adapter reported writing, which is
-	 * the distinction between a source present in corpus provenance and one present in model provenance.
+	 * A source here contributed zero rows to the corpus whatever its adapter reported writing.
+	 * That is the distinction between a source present in corpus provenance
+	 * and one present in model provenance.
 	 */
 	refusedBySource: Map<string, number>
 	excludedByLicense: number
@@ -256,8 +257,8 @@ export async function runAlignPhase(opts: AlignPhaseOptions): Promise<AlignPhase
 
 				// Counted per source as well as per refusal kind, because an adapter's own
 				// `written` count records what it emitted rather than what entered the corpus.
-				// A source refused here contributed no row, and model provenance generated from
-				// `adapters[].written` alone would credit it with rows it did not supply.
+				// A source refused here contributed no row, and model provenance generated from model provenance
+				// generated from `adapters[].written` only would credit it with rows it did not supply.
 				result.refusedBySource.set(row.source, (result.refusedBySource.get(row.source) ?? 0) + 1)
 
 				continue