@mailwoman/corpus 9.4.0 → 10.1.0

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

@@ -0,0 +1,345 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `dk-inspire`: Klimadatastyrelsen's INSPIRE Addresses GeoPackage adapter, street-level over Denmark.
+ *
+ * Input is a local `ad_inspire.gpkg`, the one member of the `DK_INSPIRE_Addresses.zip` that
+ * Denmark's ATOM download service serves. The download belongs to
+ * `#dk/tools/fetch/inspire`; this module reads a file that is already on disk, as the CSV adapters do.
+ *
+ * Denmark serves the Addresses (AD) theme as a GeoPackage rather than as GML, so there is no XML to
+ * parse. A GeoPackage is a SQLite database, and this adapter reads it through
+ * `@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
+ * {@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 file carries 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 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
+ * `opts.limit` and `opts.signal`. `opts.country` is optional and accepts only `DK`: the file covers
+ * 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.
+ */
+
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import { UnsupportedCountryError } from "#adapters/errors"
+import { stableSourceID } from "#adapters/source-id"
+import { composeHouseNumber } from "#adapters/street-line"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
+
+/**
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
+ */
+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.
+ */
+export const DK_INSPIRE_DEFAULT_LICENSE = "CC-BY-4.0"
+
+/**
+ * Every jurisdiction this adapter emits, checked against a caller's `--country`.
+ *
+ * Klimadatastyrelsen's INSPIRE obligation covers Denmark proper.
+ * Greenland and the Faroe Islands are separate ISO 3166-1 jurisdictions outside the EU,
+ * and the file's administrative units name `Danmark` and its five regions only.
+ */
+export const DK_INSPIRE_COUNTRIES: readonly string[] = ["DK"]
+
+/**
+ * The tables the adapter reads, which it requires `gpkg_contents` to declare.
+ *
+ * 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.
+ */
+export const DK_INSPIRE_REQUIRED_TABLES: readonly string[] = ["address", "postaldescriptor", "thoroughfarename"]
+
+/**
+ * How many rows Kysely buffers per chunk while streaming the join.
+ */
+const STREAM_CHUNK_ROWS = 2000
+
+/**
+ * Raised when the input is not a GeoPackage this adapter can read.
+ *
+ * The message lists the tables that were declared, so a caller reads which file it opened
+ * rather than receiving zero rows from a database with a different schema.
+ */
+export class AddressGeoPackageSchemaError extends Error {
+	constructor(inputPath: string, declared: readonly string[], missing: readonly string[]) {
+		super(
+			`${DK_INSPIRE_ADAPTER_ID} adapter: ${inputPath} declares no ${missing.join(", ")} in gpkg_contents. ` +
+				`It declares ${declared.length ? declared.join(", ") : "no tables"}.`
+		)
+
+		this.name = "AddressGeoPackageSchemaError"
+	}
+}
+
+/**
+ * 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.
+ */
+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.`
+		)
+
+		this.name = "UnresolvedAddressComponentError"
+	}
+}
+
+/**
+ * The GeoPackage tables and columns the adapter reads.
+ *
+ * The explicit shape catches a column rename upstream.
+ * Every text column is nullable in the publisher's own DDL except the ones marked
+ * `NOT NULL` there, and an absent value is SQL `NULL` rather than an empty string:
+ * the measured file holds no empty string in any column read here.
+ */
+export interface AddressGeoPackageDatabase {
+	gpkg_contents: {
+		table_name: string
+		data_type: string
+	}
+	address: {
+		objectid: number
+		inspireid: string
+		locator_designator_1_designator: string | null
+		locator_designator_2_designator: string | null
+		locator_designator_3_designator: string | null
+		component_postaldescriptor: string | null
+		component_thoroughfarename: string | null
+	}
+	thoroughfarename: {
+		inspireid: string | null
+		name_name: string
+	}
+	postaldescriptor: {
+		inspireid: string | null
+		postcode: string | null
+		postname: string | null
+	}
+}
+
+/**
+ * Joins Denmark's floor and door designators into the one `unit` value an address line states.
+ *
+ * Klimadatastyrelsen writes the floor in `locator_designator_2_designator`
+ * (`st` for `stuen`, the ground floor, or a storey number) and the door in
+ * `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.
+ *
+ * @returns The joined designator, or the empty string when the publisher states neither.
+ */
+export function composeUnitDesignator(floor: string | null, door: string | null): string {
+	const trimmedFloor = (floor ?? "").trim()
+	const trimmedDoor = (door ?? "").trim()
+
+	if (!trimmedFloor) return trimmedDoor
+
+	return composeHouseNumber(trimmedFloor, trimmedDoor, " ")
+}
+
+export function createDKInspireAdapter(): CorpusAdapter {
+	return {
+		id: DK_INSPIRE_ADAPTER_ID,
+		defaultLicense: DK_INSPIRE_DEFAULT_LICENSE,
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.DKInspireAddresses,
+		surface: SurfaceOrigin.Rendered,
+		description:
+			"DK INSPIRE Addresses (Klimadatastyrelsen): house-number-level street addresses for Denmark, " +
+			"read from the published GeoPackage.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && !DK_INSPIRE_COUNTRIES.includes(opts.country)) {
+				throw new UnsupportedCountryError(DK_INSPIRE_ADAPTER_ID, DK_INSPIRE_COUNTRIES, opts.country)
+			}
+
+			const inputPath = opts.inputPath.toString()
+
+			// A published database is read-only, and `DatabaseClient`'s teardown is synchronous,
+			// so the handle is taken with `using` rather than `await using`.
+			using db = new DatabaseClient<AddressGeoPackageDatabase>(inputPath, { readOnly: true })
+
+			const declared = (await db.selectFrom("gpkg_contents").select("table_name").execute()).map(
+				(row) => row.table_name
+			)
+
+			const missing = DK_INSPIRE_REQUIRED_TABLES.filter((table) => !declared.includes(table))
+
+			// A database that declares none of these tables is a different file
+			// rather than an empty one, and saying so names what was opened.
+			if (missing.length) {
+				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.
+			const stream = db
+				.selectFrom("address as a")
+				.leftJoin("thoroughfarename as t", "t.inspireid", "a.component_thoroughfarename")
+				.leftJoin("postaldescriptor as p", "p.inspireid", "a.component_postaldescriptor")
+				.select([
+					"a.inspireid as inspireid",
+					"a.locator_designator_1_designator as house",
+					"a.locator_designator_2_designator as floor",
+					"a.locator_designator_3_designator as door",
+					"a.component_thoroughfarename as thoroughfareReference",
+					"a.component_postaldescriptor as postalReference",
+					"t.name_name as street",
+					"p.postcode as postcode",
+					"p.postname as postname",
+				])
+				// The order is the emission order, so two runs over one file agree byte for byte.
+				.orderBy("a.objectid")
+				.stream(STREAM_CHUNK_ROWS)
+
+			let emitted = 0
+			let unaligned = 0
+
+			try {
+				for await (const record of stream) {
+					if (opts.signal?.aborted) break
+
+					if (opts.limit !== undefined && emitted >= opts.limit) break
+
+					// 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) {
+						throw new UnresolvedAddressComponentError(
+							record.inspireid,
+							"component_thoroughfarename",
+							record.thoroughfareReference
+						)
+					}
+
+					if (record.postcode === null && record.postname === null) {
+						throw new UnresolvedAddressComponentError(
+							record.inspireid,
+							"component_postaldescriptor",
+							record.postalReference
+						)
+					}
+
+					const house = (record.house ?? "").trim()
+					const street = record.street.trim()
+					const unit = composeUnitDesignator(record.floor, record.door)
+					const postcode = (record.postcode ?? "").trim()
+					const locality = (record.postname ?? "").trim()
+
+					const components: CanonicalRow["components"] = {}
+
+					if (house) {
+						components.house_number = house
+					}
+
+					components.street = street
+
+					if (unit) {
+						components.unit = unit
+					}
+
+					if (postcode) {
+						components.postcode = postcode
+					}
+
+					if (locality) {
+						components.locality = locality
+					}
+
+					const rendered = formatAddressRow(components, "DK", { singleLine: true })
+
+					if (!rendered) {
+						unaligned += 1
+
+						continue
+					}
+
+					const { raw, components: aligned } = rendered
+					const seed = record.inspireid.trim()
+
+					const sourceID = seed ? `${DK_INSPIRE_ADAPTER_ID}-${seed}` : stableSourceID(DK_INSPIRE_ADAPTER_ID, aligned)
+
+					yield {
+						raw,
+						components: aligned,
+						country: "DK",
+						// Danish is the language of every address in the file, and the file
+						// covers one jurisdiction, so the locale is constant.
+						locale: "da-DK",
+						source: DK_INSPIRE_ADAPTER_ID,
+						source_id: sourceID,
+						corpus_version: "",
+						license: DK_INSPIRE_DEFAULT_LICENSE,
+					}
+
+					emitted++
+				}
+			} finally {
+				// A row the layout could not render is a drop, so the count is stated
+				// rather than left to be read off a smaller total.
+				if (unaligned > 0) {
+					process.stderr.write(
+						`  ${DK_INSPIRE_ADAPTER_ID}: ${unaligned} rows did not align against the Danish layout and were dropped, ${emitted} kept\n`
+					)
+				}
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const dkInspireAdapter = createDKInspireAdapter()

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

@@ -0,0 +1,321 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Fetch Denmark's INSPIRE Addresses GeoPackage for the `dk-inspire` adapter.
+ *
+ * Denmark is one of the member states that serves the Addresses (AD) theme as a predefined-dataset
+ * ATOM feed rather than as a WFS, so `#tools/fetch/inspire-addresses` — which pages a WFS and joins
+ * its feature types locally — does not reach it. This module reads the feed, downloads the one
+ * dataset it offers and extracts the GeoPackage.
+ *
+ * The acquisition belongs under a `tools/` root. `@mailwoman/corpus` is one of the
+ * `TOOLING_PACKAGES` in `dependency-cruiser.config.mjs`, which keep their tooling under `lib/`, so
+ * this module sits beside `#fr/tools/fetch/ban` rather than in an `sdk/` root the workspace does
+ * not declare.
+ *
+ * Klimadatastyrelsen states CC BY 4.0 for this theme, and the address-source register elects it. The
+ * model card must attribute Klimadatastyrelsen.
+ *
+ * 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
+ *    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
+ *    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.
+ * 4. The entry's own `length="4291699"` understates the real 101,406,038 bytes by 23 times. The
+ *    download is never sized from the feed.
+ * 5. The feed's `<updated>` is 2020-12-24 and the entry's 2022-10-06, both stale against the file's
+ *    own 2026-09-27 modification date, so a freshness check cannot read the feed's timestamps. This
+ *    module compares the downloaded zip's sha256 against its manifest instead.
+ *
+ * The linked OpenSearch description parameterises only `spatial_dataset_identifier_code`, `crs` and
+ * `language`, and offers no spatial subsetting, so there is no way to fetch part of Denmark. The
+ * feed holds one entry covering the whole country.
+ */
+
+/* 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 { ByteFormatter } from "@mailwoman/core/fs/formatters"
+import { pathExists, statPath } from "@mailwoman/core/fs/readers"
+import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
+import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip"
+import { sha256File } from "@mailwoman/core/hash"
+import { childElement, childElements, type MarkupElement, streamMarkupElements } from "@mailwoman/core/html/elements"
+
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { readManifest, streamBodyToFile, writeManifest } from "#tools/fetch/download"
+
+/**
+ * The ATOM service document for Denmark's Addresses theme.
+ */
+export const DK_ADDRESSES_FEED_URL = "https://www2.sdfe.dk/INSPIRE/feeds/Addresses.xml"
+
+/**
+ * The adapter slug this module fetches for, and the directory it writes under.
+ */
+const SLUG = "dk-inspire"
+
+/**
+ * The zip member the adapter reads.
+ */
+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.
+ */
+const REAL_FILENAME_PARAMETER = "realfilename"
+
+/**
+ * The smallest plausible zip.
+ * Anything smaller is an error page rather than the dataset.
+ *
+ * The real file is 101,406,038 bytes, and this floor only separates a body from a page.
+ */
+const MINIMUM_DATASET_BYTES = 1_000_000
+
+/**
+ * What the feed states about its one dataset.
+ */
+export interface AddressesFeedEntry {
+	/**
+	 * The entry's title, `DK INSPIRE Addresses` in the measured feed.
+	 */
+	title: string
+	/**
+	 * The download URL, with the member named so the host serves the file rather than its landing page.
+	 */
+	downloadURL: string
+	/**
+	 * The media type the entry advertises, `application/geopackage+sqlite3` in the measured feed.
+	 */
+	mediaType: string | null
+}
+
+/**
+ * Read the one dataset entry out of the feed.
+ *
+ * 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 hrefs escape the ampersand between query parameters, so a reader has to decode entities.
+ *
+ * The parser does both.
+ * XML mode is required: the entry's links self-close, and HTML mode leaves them open.
+ *
+ * @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.
+ */
+export async function readAddressesFeed(xml: string, feedURL: string): Promise<AddressesFeedEntry> {
+	async function* oneChunk(): AsyncIterable<string> {
+		yield xml
+	}
+
+	// The feed holds one entry covering the whole country, so the first is the dataset.
+	let entry: MarkupElement | undefined
+
+	for await (const found of streamMarkupElements(oneChunk(), "entry", { xml: true })) {
+		entry ??= found
+	}
+
+	if (!entry) {
+		throw new Error(`${feedURL}: the feed holds no <entry>, so the dataset it offers could not be read.`)
+	}
+
+	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.
+	const alternate = childElements(entry, "link").find(
+		(link: MarkupElement) => (link.attributes.rel ?? "").toLowerCase() === "alternate"
+	)
+
+	if (!alternate) {
+		throw new Error(
+			`${feedURL}: the entry titled "${title}" carries no rel="alternate" link, so its dataset URL could not be read.`
+		)
+	}
+
+	const href = alternate.attributes.href
+
+	if (!href) {
+		throw new Error(`${feedURL}: the entry titled "${title}" carries an alternate link with no href.`)
+	}
+
+	return {
+		title,
+		// The parser decodes `&amp;` in an attribute value, so the href arrives with
+		// its query parameters already separated by a bare `&`.
+		downloadURL: datasetURLOf(href),
+		mediaType: alternate.attributes.type ?? null,
+	}
+}
+
+/**
+ * Name the zip member on a weblink URL, so the host serves the file instead of its landing page.
+ *
+ * A URL that already names one is answered unchanged, so a publisher that starts writing
+ * the complete URL into the feed does not get the parameter twice.
+ */
+export function datasetURLOf(href: string): string {
+	if (href.includes(`${REAL_FILENAME_PARAMETER}=`)) return href
+
+	return `${href}&${REAL_FILENAME_PARAMETER}=${encodeURIComponent("DK_INSPIRE_Addresses.zip")}`
+}
+
+export type FetchDKAddressesOptions = BaseFetchOptions
+
+/**
+ * Download Denmark's Addresses GeoPackage and leave it beside a manifest recording its sha256.
+ *
+ * Re-runnable: a run whose manifest sha256 still matches the extracted GeoPackage
+ * reuses that file and makes no request.
+ */
+export async function fetchDKAddresses(
+	options: FetchDKAddressesOptions,
+	report?: (line: string) => void
+): Promise<FetchSummary> {
+	const destDir = options.outRoot(SLUG)
+
+	await makeDirectories(destDir)
+
+	const gpkgDest = destDir(DK_ADDRESSES_GEOPACKAGE_MEMBER)
+	const zipDest = destDir("DK_INSPIRE_Addresses.zip")
+	const manifestPath = destDir("MANIFEST.json")
+
+	report?.(`=== ${SLUG}`)
+
+	// MARK: Idempotency check
+	//
+	// The feed's own timestamps are older than the file it serves, so they cannot decide this.
+	// The extracted GeoPackage's digest can.
+
+	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
+
+	if (recorded?.sha256 && recorded.filename) {
+		const recordedPath = destDir(recorded.filename)
+
+		if ((await pathExists(recordedPath)) && (await sha256File(recordedPath)) === recorded.sha256) {
+			report?.("  ✓ Already current (sha256 matches MANIFEST) — skipping download.")
+
+			return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] }
+		}
+	}
+
+	// MARK: Read the feed
+
+	report?.(`  Reading ${DK_ADDRESSES_FEED_URL} ...`)
+
+	const feedResponse = await fetch(DK_ADDRESSES_FEED_URL, { redirect: "follow" })
+
+	if (!feedResponse.ok) {
+		report?.(`  ✗ HTTP ${feedResponse.status} reading the feed`)
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	// `text()` reads the whole decoded body.
+	// The `content-length` header on this host reports the compressed length,
+	// so it is neither read nor checked against what arrived.
+	const xml = await feedResponse.text()
+
+	// Characters rather than bytes: the feed's 3,130 bytes decode to 3,125 characters,
+	// because the Danish text in it is multi-byte.
+	// Its content-length header reports the compressed length, 1,455, rather than either of those.
+	report?.(`  Feed decoded to ${xml.length} characters`)
+
+	const entry = await readAddressesFeed(xml, DK_ADDRESSES_FEED_URL)
+
+	report?.(`  Entry: ${entry.title} (${entry.mediaType ?? "no advertised type"})`)
+	report?.(`  Dataset: ${entry.downloadURL}`)
+
+	// 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.
+
+	const datasetResponse = await fetch(entry.downloadURL, { redirect: "follow" })
+
+	if (!datasetResponse.ok) {
+		report?.(`  ✗ HTTP ${datasetResponse.status} downloading the dataset`)
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	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.
+	if (contentType.includes("text/html")) {
+		report?.(`  ✗ The dataset URL answered ${contentType}, which is the weblink's landing page rather than the file`)
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	const zipBytes = await streamBodyToFile(datasetResponse, zipDest)
+
+	report?.(`  Downloaded: ${ByteFormatter.formatIEC(zipBytes)} (${zipBytes} bytes)`)
+
+	if (zipBytes < MINIMUM_DATASET_BYTES) {
+		report?.(`  ✗ Response too small (${zipBytes} bytes) — probable error page`)
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	// MARK: Extract the GeoPackage
+
+	const entries = await listZipEntries(zipDest)
+	const member = entries.find((zipEntry) => zipEntry.name.endsWith(".gpkg"))
+
+	if (!member) {
+		report?.("  Members in the archive:")
+
+		for (const zipEntry of entries) {
+			report?.(`    ${zipEntry.name}`)
+		}
+
+		report?.("  ✗ The archive holds no .gpkg member — inspect the listing above and update this module")
+
+		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
+	}
+
+	report?.(`  Extracting ${member.name} (${ByteFormatter.formatIEC(member.uncompressedSize)}) ...`)
+
+	await extractZipEntry(zipDest, member.name, gpkgDest)
+
+	const gpkgSize = (await statPath(gpkgDest)).size
+	const gpkgSha = await sha256File(gpkgDest)
+
+	await removePathIfPresent(zipDest)
+
+	report?.("  Removed the archive (the GeoPackage is kept)")
+
+	// MARK: Write the manifest
+
+	const manifest: SourceManifest = {
+		source_url: entry.downloadURL,
+		downloaded_at: new Date().toISOString(),
+		filename: DK_ADDRESSES_GEOPACKAGE_MEMBER,
+		sha256: gpkgSha,
+		bytes: gpkgSize,
+	}
+
+	await writeManifest(manifestPath, manifest)
+
+	report?.(`  ✓ ${ByteFormatter.formatIEC(gpkgSize)}  sha256=${gpkgSha}`)
+	report?.(`  MANIFEST written to ${manifestPath}`)
+
+	return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] }
+}