@mailwoman/corpus 9.4.0 → 10.1.0

package/lib/es/tools/fetch/bizkaia.ts

@@ -0,0 +1,748 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Harvests the INSPIRE Addresses theme the Diputación Foral de Bizkaia publishes into the
+ *   directory `#es/adapters/bizkaia/adapter` reads.
+ *
+ *   ## Two services, because the archives carry addresses alone
+ *
+ *   The ATOM download service at `https://apli.bizkaia.eus/apps/Danok/INSPIRE/addresses.xml` lists
+ *   one entry per municipality, each offering that municipality's addresses as a zipped GML through a
+ *   `rel="enclosure"` link. Those archives hold no `ad:ThoroughfareName`, `ad:PostalDescriptor` or
+ *   `ad:AdminUnitName` feature: every `ad:component` reference an address writes is a stored-query
+ *   URL on the publisher's WFS, which the ATOM service does not republish. An adapter handed the
+ *   archives alone therefore reads every address in the province without its street, its postcode or
+ *   its municipality, which is why this harvest acquires both services into one directory.
+ *
+ *   Each component type is read in one request, which is the only way this service serves it. Its
+ *   capabilities document states `ImplementsResultPaging` as `FALSE` and `CountDefault` as `1000`, so
+ *   a reader that paged a type would receive the first page again. The harvest therefore asks
+ *   `RESULTTYPE=hits` for the type's count and then asks for that many features in one `GetFeature`,
+ *   and {@linkcode fetchBizkaiaComponentDocument} raises where the document returns fewer than the
+ *   count. A truncated component document is the failure that would otherwise reach the adapter as
+ *   an unresolved reference per address.
+ *
+ *   A component document's own bytes are not reproducible. Its `wfs:FeatureCollection` carries a
+ *   `timeStamp` attribute holding the moment of the request, so two identical harvests differ in
+ *   that element and therefore in their digests. The manifest records each document's byte count and
+ *   sha256 as what arrived, never as a value a later run compares against.
+ *
+ *   ## What decides a skip
+ *
+ *   The service document states one `<updated>`, repeated on all of its entries, rather than a
+ *   modification time per municipality: the 112 entries served on 2026-10-03 all read
+ *   `2026-10-01T02:40:20Z`, which is the feed document's own modification time. One request therefore
+ *   states the freshness of every archive the service offers, as ČÚZK's does, and a re-run requests
+ *   only the municipalities whose archive is missing or no longer the recorded length. Whether that
+ *   value moves whenever an archive is replaced is inferred from one observation rather than
+ *   established: on 2026-10-03 the feed read `2026-10-01T02:40:20Z` and `ES.BFA.AD.001.zip` was
+ *   served with `Last-Modified: Thu, 01 Oct 2026 00:01:15 GMT`. Each archive's own `last-modified` is
+ *   recorded beside its entry so a later run can check that inference against the record.
+ *
+ *   The component documents state no version at all. The WFS answers them under `Cache-Control:
+ *   no-cache` with no `Last-Modified`, so a run holds no value to compare and every run that
+ *   harvests them downloads them again. {@linkcode HarvestESBizkaiaOptions.components} is how a run that wants
+ *   the archives alone declines the 14 MB.
+ */
+
+/* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
+   procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
+
+import { APIClient, assertNoOGCServiceException, readWFSFeatureCount } from "@mailwoman/core/api"
+import { ByteFormatter } from "@mailwoman/core/fs/formatters"
+import { tryStat } from "@mailwoman/core/fs/readers"
+import { makeDirectories, writeLocalFile } from "@mailwoman/core/fs/writers"
+import { sha256File, sha256Hex } from "@mailwoman/core/hash"
+import { rootAttribute } from "@mailwoman/core/html/document"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { PathBuilder, type PathBuilderLike } from "path-ts"
+
+import { ES_BIZKAIA_ADAPTER_ID, ES_BIZKAIA_LICENSE } from "#es/adapters/bizkaia/adapter"
+import type { AtomFeed } from "#tools/fetch/atom"
+import { feedChunks, linkWithRel, readAtomFeed } from "#tools/fetch/atom"
+import type { BaseFetchOptions, FetchSummary, SourceCollectionManifest, SourceManifest } from "#tools/fetch/download"
+import { loadCollectionFiles, readManifest, writeManifest } from "#tools/fetch/download"
+import { downloadZipArchive } from "#tools/fetch/zip-archive"
+
+/**
+ * The ATOM download service listing one archive per municipality.
+ */
+export const ES_BIZKAIA_SERVICE_URL = "https://apli.bizkaia.eus/apps/Danok/INSPIRE/addresses.xml"
+
+/**
+ * The WFS the municipality archives reference their components on.
+ *
+ * Read from the `xlink:href` the archives themselves write, which addresses this
+ * endpoint through the `GetFeatureById` stored query.
+ */
+export const ES_BIZKAIA_WFS_URL =
+	"https://geo.bizkaia.eus/arcgisserverinspire/rest/services/Catastro/Annex1/MapServer/exts/InspireFeatureDownload/service"
+
+/**
+ * The attribution the publisher's own `<rights>` element requires, quoted as it writes it.
+ */
+export const ES_BIZKAIA_ATTRIBUTION = "«©Bizkaiko Foru Aldundia»"
+
+/**
+ * The component feature types the harvest saves from the WFS.
+ *
+ * The four the adapter indexes.
+ * `ad:AddressAreaName` is harvested although the province published none when this was written, because
+ * the schema admits one and a type left unasked is indistinguishable from a type that answered empty.
+ */
+export const ES_BIZKAIA_COMPONENT_TYPES = [
+	"ad:ThoroughfareName",
+	"ad:PostalDescriptor",
+	"ad:AdminUnitName",
+	"ad:AddressAreaName",
+] as const
+
+/**
+ * One of {@linkcode ES_BIZKAIA_COMPONENT_TYPES}.
+ */
+export type ESBizkaiaComponentType = (typeof ES_BIZKAIA_COMPONENT_TYPES)[number]
+
+/**
+ * The minimum spacing between two requests, in milliseconds.
+ *
+ * Four requests per second against one government host.
+ * The publisher states no rate limit.
+ */
+export const ES_BIZKAIA_REQUEST_INTERVAL_MS = 250
+
+/**
+ * Per-request timeout for a body, in milliseconds.
+ *
+ * Ten minutes, which covers both a municipality archive and the one component
+ * document that carries every street in the province.
+ */
+const BODY_TIMEOUT_MS = 600_000
+
+/**
+ * How many archives are written between two manifest writes.
+ *
+ * The manifest is what makes an interrupted harvest resumable, and writing it
+ * after every archive would rewrite the whole document once per municipality.
+ * At this interval an interruption re-fetches at most this many archives already on disk.
+ */
+const MANIFEST_INTERVAL = 25
+
+/**
+ * The municipality code an entry's title states, `48001-ABADIÑO Addresses` → `48001`.
+ */
+const TITLE_CODE = /^(\d+)\s*-/u
+
+/**
+ * The archive file name an entry's INSPIRE identifier states, `ES.BFA.AD.001.zip`.
+ *
+ * The identifier is the file name itself on this service rather than a dataset URN.
+ */
+const IDENTIFIER_FILENAME = /^(ES\.BFA\.AD\.(\d+)\.zip)$/u
+
+/**
+ * The file name a component type is written under, `ad:ThoroughfareName` → `ad-ThoroughfareName.xml`.
+ *
+ * The colon is replaced because the adapter globs these documents out of a directory
+ * and a prefixed name is awkward to address from a shell.
+ * The `.xml` extension is what puts the document inside the adapter's own glob.
+ */
+export function bizkaiaComponentFilename(type: string): string {
+	return `${type.replace(":", "-")}.xml`
+}
+
+/**
+ * One municipality's archive, as the service document states it.
+ */
+export interface ESBizkaiaMunicipalityDataset {
+	/**
+	 * The five-digit municipality code the entry's title states, `48001`.
+	 */
+	code: string
+	/**
+	 * The entry's title, `48001-ABADIÑO Addresses`.
+	 */
+	title: string
+	/**
+	 * The `<updated>` the entry states.
+	 * Every entry of this service repeats the feed's own value.
+	 */
+	updated: string
+	/**
+	 * The archive's URL, as the entry's `rel="enclosure"` link writes it.
+	 */
+	downloadURL: string
+	/**
+	 * The file name the archive is written under, which is what the adapter globs.
+	 */
+	filename: string
+}
+
+/**
+ * The municipalities the service document lists.
+ *
+ * The file name comes from the entry's INSPIRE identifier and the municipality code from
+ * its title, and the two are checked against each other, because the file name is what
+ * the archive is stored under: a disagreement between the publisher's two statements of
+ * a municipality would store one municipality's addresses under another's name.
+ *
+ * @throws When the feed lists no entry, when an entry states neither spelling of its municipality,
+ * when the two spellings disagree, when two entries claim one file name — which would make
+ * one archive overwrite the other — or when an entry carries no `rel="enclosure"` link.
+ */
+export function readESBizkaiaServiceFeed(feed: AtomFeed): readonly ESBizkaiaMunicipalityDataset[] {
+	if (!feed.entries.length) {
+		throw new Error(
+			`${ES_BIZKAIA_SERVICE_URL}: the service document holds no <entry>, so the municipalities it offers ` +
+				`could not be read`
+		)
+	}
+
+	const datasets: ESBizkaiaMunicipalityDataset[] = []
+	const seen = new Set<string>()
+
+	for (const entry of feed.entries) {
+		const identified = IDENTIFIER_FILENAME.exec((entry.identifierCode ?? "").trim())
+		const fromTitle = TITLE_CODE.exec(entry.title.trim())?.[1]
+
+		if (!identified) {
+			throw new Error(
+				`${ES_BIZKAIA_SERVICE_URL}: the entry titled "${entry.title}" states the dataset identifier ` +
+					`${stringifyJSON(entry.identifierCode)}, which is not an ES.BFA.AD.<n>.zip archive name`
+			)
+		}
+
+		if (!fromTitle) {
+			throw new Error(
+				`${ES_BIZKAIA_SERVICE_URL}: the entry titled "${entry.title}" opens with no municipality code, ` +
+					`so the archive ${identified[1]!} could not be checked against the title`
+			)
+		}
+
+		// The identifier carries the three-digit tail of the five-digit municipality code:
+		// `48915` is published as `ES.BFA.AD.915.zip`.
+		if (!fromTitle.endsWith(identified[2]!)) {
+			throw new Error(
+				`${ES_BIZKAIA_SERVICE_URL}: the entry titled "${entry.title}" states municipality ${fromTitle} in its ` +
+					`title and ${identified[2]!} in its archive name ${identified[1]!}, so the municipality it holds is ambiguous`
+			)
+		}
+
+		const enclosure = linkWithRel(entry.links, "enclosure")
+
+		if (!enclosure?.href) {
+			throw new Error(
+				`${ES_BIZKAIA_SERVICE_URL}: the entry for municipality ${fromTitle} carries no rel="enclosure" link, ` +
+					`so its archive could not be read`
+			)
+		}
+
+		if (seen.has(identified[1]!)) {
+			throw new Error(
+				`${ES_BIZKAIA_SERVICE_URL}: the archive ${identified[1]!} is listed twice, so one of the two copies ` +
+					`would overwrite the other`
+			)
+		}
+
+		seen.add(identified[1]!)
+
+		datasets.push({
+			code: fromTitle,
+			title: entry.title.trim(),
+			updated: entry.updated,
+			downloadURL: enclosure.href,
+			filename: identified[1]!,
+		})
+	}
+
+	return datasets
+}
+
+/**
+ * One municipality's archive, as the harvest's manifest records it.
+ */
+export interface ESBizkaiaArchiveEntry extends SourceManifest {
+	municipality_code: string
+	/**
+	 * The `<updated>` the service document stated when this archive was fetched.
+	 */
+	feed_updated: string
+	/**
+	 * The `Last-Modified` the host served the archive under, or `null` where it served none.
+	 *
+	 * Recorded rather than compared.
+	 * It is the record against which the service document's single `<updated>` can
+	 * later be checked as a per-municipality signal.
+	 */
+	last_modified: string | null
+}
+
+/**
+ * One saved WFS component document, as the harvest's manifest records it.
+ */
+export interface ESBizkaiaComponentEntry extends SourceManifest {
+	type_name: string
+	/**
+	 * The count the service reported for this type under `RESULTTYPE=hits`.
+	 */
+	feature_count: number
+	/**
+	 * The `numberReturned` the saved document states, which the harvest requires to
+	 * equal {@linkcode ESBizkaiaComponentEntry.feature_count}.
+	 */
+	features_returned: number
+}
+
+/**
+ * The harvest's `MANIFEST.json`.
+ */
+export interface ESBizkaiaHarvestManifest extends SourceCollectionManifest {
+	wfs_url: string
+	/**
+	 * The `<updated>` the service document stated on this run.
+	 */
+	feed_updated: string | null
+	/**
+	 * How many municipalities the service document listed when this manifest was written.
+	 *
+	 * The denominator for `files`, read from the feed on each run rather than fixed here.
+	 */
+	municipalities_listed: number
+	files: ESBizkaiaArchiveEntry[]
+	/**
+	 * The saved WFS documents, kept apart from `files` because they carry no
+	 * municipality and no stated version.
+	 */
+	components: ESBizkaiaComponentEntry[]
+}
+
+export interface HarvestESBizkaiaOptions {
+	/**
+	 * Where the archives, the component documents and the manifest are written,
+	 * which is the adapter's `inputPath`.
+	 */
+	outputDir: PathBuilderLike
+	/**
+	 * Harvest only these five-digit municipality codes, for a probe or for a repair of named ones.
+	 *
+	 * A code the service document does not list is reported as a failure rather than ignored.
+	 */
+	municipalities?: readonly string[]
+	/**
+	 * Stop after this many municipalities, counting the ones already on disk.
+	 */
+	limit?: number
+	/**
+	 * Save the WFS component documents as well as the archives.
+	 * Defaults to true.
+	 *
+	 * An adapter run needs them: an archive references its street, its postcode
+	 * and its municipality and carries none of the three.
+	 */
+	components?: boolean
+	/**
+	 * Download every selected archive again, whatever the manifest records.
+	 */
+	force?: boolean
+	/**
+	 * Re-read the sha256 of every archive already on disk instead of comparing its byte count.
+	 *
+	 * The default compares the recorded byte count against the file's size, which is one `stat`.
+	 */
+	verifyDigests?: boolean
+	signal?: AbortSignal
+	report?: (line: string) => void
+}
+
+/**
+ * Whether the archive recorded for one municipality is still the one the feed now describes.
+ *
+ * Three conditions: the service document states the `<updated>` it stated when the file was
+ * fetched, the file is still there, and it is still the length that was recorded for it.
+ * An entry stating no `<updated>` answers false rather than matching a recorded absence,
+ * so a service that stops stating a version is re-fetched rather than frozen.
+ */
+async function archiveIsCurrent(
+	recorded: ESBizkaiaArchiveEntry | undefined,
+	dataset: ESBizkaiaMunicipalityDataset,
+	path: PathBuilderLike,
+	verifyDigests: boolean
+): Promise<boolean> {
+	if (!dataset.updated) return false
+
+	if (!recorded || recorded.feed_updated !== dataset.updated) return false
+
+	const stat = await tryStat(path)
+
+	if (!stat || stat.size !== recorded.bytes) return false
+
+	// The digest check reads the whole file rather than its metadata, which is why it is opt-in.
+	if (!verifyDigests) return true
+
+	return (await sha256File(path)) === recorded.sha256
+}
+
+/**
+ * Reads one component feature type whole and writes it beside the archives.
+ *
+ * Two requests per type: `RESULTTYPE=hits` for the count, then one `GetFeature` for that many features.
+ * `COUNT` is asked one above the stated count, so a service whose hits response
+ * undercounts its own matches answers with more features than it claimed
+ * rather than with exactly the number the harvest asked for.
+ *
+ * @throws When the document's `numberReturned` is missing, unreadable,
+ * or not the count the service reported.
+ * A document holding fewer features than the service matched would reach the adapter as
+ * an unresolved component reference on every address that referenced a missing feature.
+ */
+export async function fetchBizkaiaComponentDocument(
+	client: Pick<APIClient, "fetch">,
+	typeName: string,
+	options: { dest: PathBuilderLike; signal?: AbortSignal }
+): Promise<ESBizkaiaComponentEntry> {
+	const context = `${ES_BIZKAIA_ADAPTER_ID} WFS ${typeName}`
+
+	const featureCount = await readWFSFeatureCount(client, {
+		wfsURL: ES_BIZKAIA_WFS_URL,
+		typeNames: typeName,
+		context,
+		subject: typeName,
+	})
+
+	const { data } = await client.fetch<string>({
+		method: "GET",
+		url: ES_BIZKAIA_WFS_URL,
+		responseType: "text",
+		timeout: BODY_TIMEOUT_MS,
+		signal: options.signal,
+		params: {
+			service: "WFS",
+			version: "2.0.0",
+			request: "GetFeature",
+			typeNames: typeName,
+			count: String(featureCount + 1),
+		},
+	})
+
+	const document = String(data)
+
+	assertNoOGCServiceException(document, context)
+
+	// `numberMatched` reads `unknown` on this service's feature pages, so the delivered
+	// count is read from `numberReturned` and compared against the hits request's figure.
+	const returned = rootAttribute(document, "numberReturned", { xml: true })
+
+	if (returned === undefined || !/^\d+$/u.test(returned)) {
+		throw new Error(
+			`${context}: the GetFeature response states numberReturned=${stringifyJSON(returned ?? null)} rather than ` +
+				`a count, so what the document holds against the ${featureCount} features the service matched is unknown`
+		)
+	}
+
+	if (Number(returned) !== featureCount) {
+		throw new Error(
+			`${context}: the service matched ${featureCount} features and returned ${returned}. The document is ` +
+				`therefore not the whole type, and this service advertises ImplementsResultPaging=FALSE, so the ` +
+				`remainder cannot be paged.`
+		)
+	}
+
+	const bytes = Buffer.from(document, "utf8")
+
+	await writeLocalFile(bytes, options.dest)
+
+	return {
+		type_name: typeName,
+		filename: PathBuilder.from(options.dest).basename(),
+		source_url: `${ES_BIZKAIA_WFS_URL}?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature&TYPENAMES=${typeName}`,
+		downloaded_at: new Date().toISOString(),
+		sha256: sha256Hex(bytes),
+		bytes: bytes.byteLength,
+		feature_count: featureCount,
+		features_returned: Number(returned),
+	}
+}
+
+/**
+ * Harvest the municipality archives and the WFS component documents into `options.outputDir`.
+ *
+ * The client is injected so the harvest is testable without the network and so a caller decides
+ * the pacing. {@linkcode fetchESBizkaia} is the registry entry point and supplies both.
+ *
+ * @returns What was fetched, what was already current, and which municipality codes
+ * or component types failed.
+ */
+export async function harvestESBizkaia(
+	client: Pick<APIClient, "fetch">,
+	options: HarvestESBizkaiaOptions
+): Promise<FetchSummary> {
+	const { report, signal } = options
+	const destDir = PathBuilder.from(options.outputDir)
+	const manifestPath = destDir("MANIFEST.json")
+
+	// MARK: Read the service document
+	//
+	// One request, and it states the version of every archive the service offers.
+
+	report?.(`=== ${ES_BIZKAIA_ADAPTER_ID}: reading ${ES_BIZKAIA_SERVICE_URL}`)
+
+	const { data: serviceXML } = await client.fetch<string>({
+		method: "GET",
+		url: ES_BIZKAIA_SERVICE_URL,
+		responseType: "text",
+		timeout: 120_000,
+		signal,
+	})
+
+	assertNoOGCServiceException(String(serviceXML), `${ES_BIZKAIA_ADAPTER_ID} service document`)
+
+	const feed = await readAtomFeed(feedChunks(String(serviceXML)))
+	const listed = readESBizkaiaServiceFeed(feed)
+
+	report?.(`  ${listed.length} municipalities listed`)
+
+	const wanted = selectMunicipalities(listed, options)
+
+	report?.(`  ${wanted.selected.length} selected for this run`)
+
+	await makeDirectories(destDir)
+
+	// MARK: Fetch the archives the feed describes anew
+
+	const previous = await loadCollectionFiles(manifestPath)
+	const recordedManifest = await readManifest<ESBizkaiaHarvestManifest>(manifestPath)
+	const files = new Map<string, ESBizkaiaArchiveEntry>()
+
+	// An entry for a municipality this run does not consider is carried through,
+	// so a bounded run never drops what an earlier run recorded.
+	for (const [filename, entry] of previous) {
+		files.set(filename, entry as ESBizkaiaArchiveEntry)
+	}
+
+	const components = new Map<string, ESBizkaiaComponentEntry>()
+
+	for (const entry of recordedManifest?.components ?? []) {
+		components.set(entry.type_name, entry)
+	}
+
+	let fetched = 0
+	let skipped = 0
+	const failedCodes: string[] = [...wanted.unknown]
+
+	for (const unknown of wanted.unknown) {
+		report?.(`  ✗ municipality ${unknown} is not listed in the service document`)
+	}
+
+	const writeHarvestManifest = async (): Promise<void> => {
+		const manifest: ESBizkaiaHarvestManifest = {
+			source: ES_BIZKAIA_ADAPTER_ID,
+			source_url: ES_BIZKAIA_SERVICE_URL,
+			wfs_url: ES_BIZKAIA_WFS_URL,
+			license: ES_BIZKAIA_LICENSE,
+			attribution: ES_BIZKAIA_ATTRIBUTION,
+			downloaded_at: new Date().toISOString(),
+			feed_updated: listed[0]?.updated ?? null,
+			municipalities_listed: listed.length,
+			files: [...files.values()].toSorted((left, right) => left.filename.localeCompare(right.filename)),
+			components: [...components.values()].toSorted((left, right) => left.type_name.localeCompare(right.type_name)),
+		}
+
+		await writeManifest(manifestPath, manifest)
+	}
+
+	for (const dataset of wanted.selected) {
+		if (signal?.aborted) break
+
+		const dest = destDir(dataset.filename)
+
+		if (
+			!options.force &&
+			(await archiveIsCurrent(files.get(dataset.filename), dataset, dest, options.verifyDigests ?? false))
+		) {
+			skipped++
+
+			continue
+		}
+
+		try {
+			const entry = await fetchArchive(client, dataset, { dest, signal })
+
+			files.set(dataset.filename, entry)
+
+			fetched++
+
+			report?.(`  ✓ ${dataset.code} ${ByteFormatter.formatIEC(entry.bytes)} sha256=${entry.sha256}`)
+		} catch (error) {
+			report?.(`  ✗ ${dataset.code}: ${error instanceof Error ? error.message : String(error)}`)
+			failedCodes.push(dataset.code)
+
+			continue
+		}
+
+		if (fetched % MANIFEST_INTERVAL === 0) {
+			await writeHarvestManifest()
+		}
+	}
+
+	// MARK: Save the WFS component documents
+	//
+	// Downloaded on every run that asks for them.
+	// The service states no version to compare.
+
+	if (options.components ?? true) {
+		for (const typeName of ES_BIZKAIA_COMPONENT_TYPES) {
+			if (signal?.aborted) break
+
+			const filename = bizkaiaComponentFilename(typeName)
+
+			try {
+				const entry = await fetchBizkaiaComponentDocument(client, typeName, { dest: destDir(filename), signal })
+
+				components.set(typeName, entry)
+
+				fetched++
+
+				report?.(
+					`  ✓ ${typeName} ${entry.feature_count} features, ` +
+						`${ByteFormatter.formatIEC(entry.bytes)} sha256=${entry.sha256}`
+				)
+			} catch (error) {
+				report?.(`  ✗ ${typeName}: ${error instanceof Error ? error.message : String(error)}`)
+				failedCodes.push(typeName)
+			}
+		}
+	}
+
+	await writeHarvestManifest()
+
+	report?.(`=== ${ES_BIZKAIA_ADAPTER_ID} summary`)
+	report?.(`fetched: ${fetched}`)
+	report?.(`skipped: ${skipped} (the feed states the <updated> already recorded)`)
+	report?.(`failed:  ${failedCodes.length}`)
+
+	return { fetched, skipped, failed: failedCodes.length, failedCodes }
+}
+
+/**
+ * The municipalities this run considers, and the codes a caller named that the feed does not list.
+ *
+ * A code the caller asked for and the service document does not list is returned
+ * rather than dropped, because a municipality that is not published is a different
+ * condition from a selection that holds no municipality.
+ */
+function selectMunicipalities(
+	listed: readonly ESBizkaiaMunicipalityDataset[],
+	options: Pick<HarvestESBizkaiaOptions, "municipalities" | "limit">
+): { selected: readonly ESBizkaiaMunicipalityDataset[]; unknown: readonly string[] } {
+	let selected = listed
+	const unknown: string[] = []
+
+	if (options.municipalities) {
+		const byCode = new Map(listed.map((dataset) => [dataset.code, dataset]))
+		const found: ESBizkaiaMunicipalityDataset[] = []
+
+		for (const code of options.municipalities) {
+			const dataset = byCode.get(code)
+
+			if (dataset) {
+				found.push(dataset)
+			} else {
+				unknown.push(code)
+			}
+		}
+
+		selected = found
+	}
+
+	if (options.limit !== undefined) {
+		selected = selected.slice(0, options.limit)
+	}
+
+	return { selected, unknown }
+}
+
+/**
+ * Download one municipality's archive and answer the manifest entry for it.
+ *
+ * The transfer runs on the harvest's own client through {@linkcode downloadZipArchive},
+ * which refuses a body that does not begin with a zip signature.
+ */
+async function fetchArchive(
+	client: Pick<APIClient, "fetch">,
+	dataset: ESBizkaiaMunicipalityDataset,
+	options: { dest: PathBuilderLike; signal?: AbortSignal }
+): Promise<ESBizkaiaArchiveEntry> {
+	const delivered = await downloadZipArchive(client, {
+		url: dataset.downloadURL,
+		dest: options.dest,
+		timeout: BODY_TIMEOUT_MS,
+		signal: options.signal,
+	})
+
+	return {
+		municipality_code: dataset.code,
+		filename: dataset.filename,
+		source_url: dataset.downloadURL,
+		downloaded_at: new Date().toISOString(),
+		sha256: delivered.sha256,
+		bytes: delivered.bytes,
+		feed_updated: dataset.updated,
+		last_modified: delivered.lastModified,
+	}
+}
+
+/**
+ * The path `#es/adapters/bizkaia/adapter` reads, given the root a fetch wrote under.
+ *
+ * The directory rather than a file: the adapter reads every archive and every saved WFS
+ * document under it, and it is the component documents that carry the streets.
+ */
+export function esBizkaiaInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike {
+	return outRoot(ES_BIZKAIA_ADAPTER_ID)
+}
+
+/**
+ * Per-invocation options for the registry entry.
+ */
+export interface FetchESBizkaiaOptions
+	extends
+		BaseFetchOptions,
+		Pick<HarvestESBizkaiaOptions, "municipalities" | "limit" | "components" | "force" | "verifyDigests" | "signal"> {
+	/**
+	 * The minimum spacing between two requests, in milliseconds.
+	 *
+	 * Defaults to {@linkcode ES_BIZKAIA_REQUEST_INTERVAL_MS}.
+	 */
+	minRequestIntervalMs?: number
+}
+
+/**
+ * Harvest Bizkaia's INSPIRE Addresses into `<outRoot>/es-bizkaia/`.
+ *
+ * A full harvest is the service document, one request per municipality it lists,
+ * and two requests per component type.
+ */
+export async function fetchESBizkaia(
+	options: FetchESBizkaiaOptions,
+	report?: (line: string) => void
+): Promise<FetchSummary> {
+	await using client = new APIClient({
+		displayName: ES_BIZKAIA_ADAPTER_ID,
+		minRequestIntervalMs: options.minRequestIntervalMs ?? ES_BIZKAIA_REQUEST_INTERVAL_MS,
+		retry: true,
+	})
+
+	// Awaited rather than returned: `await using` disposes the client when this scope exits,
+	// and a disposed `APIClient` refuses every later request.
+	return await harvestESBizkaia(client, {
+		outputDir: options.outRoot(ES_BIZKAIA_ADAPTER_ID),
+		municipalities: options.municipalities,
+		limit: options.limit,
+		components: options.components,
+		force: options.force,
+		verifyDigests: options.verifyDigests,
+		signal: options.signal,
+		report,
+	})
+}