@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/cz/tools/fetch/cuzk.ts

@@ -0,0 +1,699 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Harvest ČÚZK's INSPIRE Addresses archives into the directory `#cz/adapters/cuzk/adapter` reads.
+ *
+ * ČÚZK serves the Addresses (AD) theme as a two-level ATOM service rather than as a WFS. The
+ * service document at `https://atom.cuzk.gov.cz/AD/AD.xml` holds one entry per municipality, each
+ * pointing at a dataset feed, and each dataset feed offers that municipality's addresses as a
+ * zipped GML in two projections. Measured 2026-10-02: the service document answered HTTP 200 with
+ * 8,373,817 bytes holding 6,258 entries, sha256
+ * `9b1d51a721ab601fa74307cce5ce20f74d12dd29512f87be29cd1072f0a2d83b`.
+ *
+ * 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.
+ *
+ * Every one of the service document's `rights` elements reads `žádné podmínky neplatí`, INSPIRE's
+ * controlled value for no conditions applying to access and use, and the address-source register
+ * elects it on that basis. `#cz/adapters/cuzk/adapter` records the same value on every row.
+ *
+ * Four properties of this service decide the harvest's shape, and each was measured rather than
+ * assumed:
+ *
+ * 1. **The service document carries each municipality's file modification time.** An entry's
+ *    `<updated>` equals the archive's `Last-Modified` to the second, checked on six municipalities
+ *    on 2026-10-02 — `584061` reads `2026-06-04T02:19:33+02:00` against
+ *    `Thu, 04 Jun 2026 00:19:33 GMT`, and `531529`, `551481`, `545031`, `587044` and `584282`
+ *    agree the same way. So one 8.4 MB request states the freshness of all 6,258 archives, and a
+ *    re-run requests only the municipalities whose stated time moved. The alternative — a
+ *    conditional request per municipality — costs 6,258 round trips to learn the same thing.
+ * 2. **The download URL is composed from a base the feed itself declares.** The service document's
+ *    own `rel="next"` links are `https://services.cuzk.gov.cz/gml/inspire/ad/epsg-4258` and
+ *    `…/epsg-5514`, and a dataset feed's `alternate` link for the same municipality is that base
+ *    plus `/<code>.zip`. Composing from the declared base rather than reading 6,258 dataset feeds
+ *    halves the harvest's requests. {@linkcode HarvestCzCuzkOptions.resolveThroughDatasetFeed}
+ *    reads the publisher's own href instead, for a run that will not compose a URL.
+ * 3. **The `type` attribute describes the data rather than the file.** A dataset feed's link
+ *    advertises `application/gml+xml` while the host serves `application/zip`, so the GML is inside
+ *    the archive and the advertised type cannot decide what to write. The archive is stored as it
+ *    arrives: the adapter opens it with `adm-zip`, because at least one archive's central directory
+ *    records its member's size as the ZIP64 sentinel `0xFFFFFFFF`.
+ * 4. **A dataset feed's `length` is accurate here, and is still not used.** `584061.zip` claims
+ *    24,846 bytes and the host's `content-length` says 24,846. Denmark's feed understates its file
+ *    by 23 times, so every byte count this module records is counted off the delivered body.
+ *
+ * The archives are small — a systematic sample of 50 of the 6,258 municipalities on 2026-10-02 ran
+ * from 5,236 to 1,642,586 bytes with a median of 16,591 — so the harvest is bound by round trips
+ * rather than by bandwidth, and it is dispatched serially through one `APIClient`. ČÚZK publishes
+ * no rate limit. {@linkcode CZ_CUZK_REQUEST_INTERVAL_MS} holds the harvest to four requests per
+ * second against one government host, which is under half of the ten per second the same 50
+ * requests measured, and a caller that has asked ČÚZK for more raises it.
+ */
+
+/* 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 } 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 { stringifyJSON } from "@mailwoman/core/json"
+import { PathBuilder, type PathBuilderLike } from "path-ts"
+
+import { CZ_CUZK_ADAPTER_ID, CZ_CUZK_LICENSE } from "#cz/adapters/cuzk/adapter"
+import type { AtomFeed, AtomLink } from "#tools/fetch/atom"
+import { feedChunks, linkWithRel, readAtomFeed } from "#tools/fetch/atom"
+import type { BaseFetchOptions, FetchSummary, SourceCollectionManifest, SourceManifest } from "#tools/fetch/download"
+import { loadCollectionFiles, writeManifest } from "#tools/fetch/download"
+
+/**
+ * The ATOM service document listing one dataset feed per municipality.
+ */
+export const CZ_CUZK_SERVICE_FEED_URL = "https://atom.cuzk.gov.cz/AD/AD.xml"
+
+/**
+ * The directory the harvest writes under, which is the adapter's `inputPath`.
+ */
+const SLUG = CZ_CUZK_ADAPTER_ID
+
+/**
+ * The attribution the model card must carry for this source.
+ */
+export const CZ_CUZK_ATTRIBUTION = "Český úřad zeměměřický a katastrální (ČÚZK), INSPIRE téma Adresy"
+
+/**
+ * The two projections the service offers, keyed by the path segment the feed's own base URL ends in.
+ *
+ * The adapter reads either.
+ * `epsg-4258` is ETRS89, in degrees, and is the projection the adapter's
+ * component joins were verified against.
+ */
+export const CZ_CUZK_PROJECTIONS = {
+	"epsg-4258": "ETRS89",
+	"epsg-5514": "S-JTSK",
+} as const
+
+/**
+ * One of {@linkcode CZ_CUZK_PROJECTIONS}.
+ */
+export type CzCuzkProjection = keyof typeof CZ_CUZK_PROJECTIONS
+
+/**
+ * The minimum spacing between two requests to `services.cuzk.gov.cz`, in milliseconds.
+ *
+ * Four requests per second.
+ * A systematic sample of 50 archives on 2026-10-02 answered a serial `HEAD` in 100 ms each,
+ * so this leaves the host more than half the rate it demonstrated.
+ */
+export const CZ_CUZK_REQUEST_INTERVAL_MS = 250
+
+/**
+ * The first two bytes of every zip archive, `PK`.
+ *
+ * The check is on the signature rather than on a size, because an error page
+ * and a small municipality are told apart by what the body is rather than by
+ * how long it is: the smallest archive in the 2026-10-02 sample is 5,236 bytes,
+ * and a size floor between the two would be a number fitted to that sample.
+ */
+const ZIP_SIGNATURE = "PK"
+
+/**
+ * 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 a 6,258-entry document 6,258 times.
+ * At this interval an interruption re-fetches at most this many archives that are already on disk.
+ */
+const MANIFEST_INTERVAL = 25
+
+/**
+ * One municipality's dataset, as the service document states it.
+ */
+export interface CzMunicipalityDataset {
+	/**
+	 * The municipality code, which is both the `obec` code and the archive's file name stem.
+	 */
+	code: string
+	/**
+	 * The entry's title, `INSPIRE - adresní místa - obec: Unkovice [584061]`.
+	 */
+	title: string
+	/**
+	 * The `<updated>` the service document states, which is this archive's modification time.
+	 */
+	updated: string
+	/**
+	 * The dataset feed for this municipality, which lists the same data in both projections.
+	 */
+	datasetFeedURL: string
+	/**
+	 * The archive, composed from the base the feed declares for the requested projection.
+	 */
+	downloadURL: string
+	/**
+	 * The file name the archive is written under, which is what the adapter globs.
+	 */
+	filename: string
+}
+
+/**
+ * The trailing numeric component of an INSPIRE dataset identifier code,
+ * `CZ-00025712-CUZK_AD_584061` → `584061`.
+ */
+const IDENTIFIER_CODE_SUFFIX = /_(\d+)$/u
+
+/**
+ * The municipality code a title states in brackets, `… obec: Unkovice [584061]` → `584061`.
+ */
+const TITLE_CODE = /\[(\d+)\]\s*$/u
+
+/**
+ * The municipality code of one entry, read from its INSPIRE identifier and checked against its title.
+ *
+ * Both spellings are read because the code is the file name the archive is composed
+ * and stored under, so a disagreement between the publisher's two statements of it
+ * would silently store one municipality's addresses under another's name.
+ *
+ * @throws When either statement is missing or the two disagree, which reads as a change
+ * in the publisher's layout rather than as a municipality without a code.
+ */
+export function municipalityCodeOf(entry: { title: string; identifierCode: string | null }): string {
+	const fromIdentifier = IDENTIFIER_CODE_SUFFIX.exec(entry.identifierCode ?? "")?.[1]
+	const fromTitle = TITLE_CODE.exec(entry.title)?.[1]
+
+	if (!fromIdentifier) {
+		throw new Error(
+			`${CZ_CUZK_SERVICE_FEED_URL}: the entry titled "${entry.title}" states the dataset identifier ` +
+				`${stringifyJSON(entry.identifierCode)}, which ends in no municipality code`
+		)
+	}
+
+	if (!fromTitle) {
+		throw new Error(
+			`${CZ_CUZK_SERVICE_FEED_URL}: the entry titled "${entry.title}" states no municipality code in brackets, ` +
+				`so its identifier's ${fromIdentifier} could not be checked against the title`
+		)
+	}
+
+	if (fromIdentifier !== fromTitle) {
+		throw new Error(
+			`${CZ_CUZK_SERVICE_FEED_URL}: the entry titled "${entry.title}" states municipality ${fromTitle} in its ` +
+				`title and ${fromIdentifier} in its dataset identifier, so the archive it names is ambiguous`
+		)
+	}
+
+	return fromIdentifier
+}
+
+/**
+ * The base URL the feed declares for one projection.
+ *
+ * Matched on the href's last path segment rather than on the link's `title`,
+ * because the segment is the EPSG code itself while the title is a Czech-language label.
+ *
+ * @throws When the feed declares no base for the requested projection, naming the ones it does
+ * declare, so a publisher that moves its files reports itself instead of composing a dead URL.
+ */
+export function projectionBaseURL(feed: AtomFeed, projection: CzCuzkProjection): string {
+	const bases = feed.links.filter((link: AtomLink) => link.rel === "next")
+	const found = bases.find((link) => link.href.replace(/\/+$/u, "").endsWith(`/${projection}`))
+
+	if (!found) {
+		throw new Error(
+			`${CZ_CUZK_SERVICE_FEED_URL}: the feed declares no download base ending in /${projection}. ` +
+				`Its rel="next" links are ${bases.length ? bases.map((link) => link.href).join(", ") : "absent"}.`
+		)
+	}
+
+	return found.href.replace(/\/+$/u, "")
+}
+
+/**
+ * The municipalities the service document lists, with the archive URL for one projection.
+ *
+ * @throws When the feed lists no entry, when two entries claim one municipality code — which
+ * would make one archive overwrite the other — or when an entry carries no dataset feed link.
+ */
+export function readCzCuzkServiceFeed(feed: AtomFeed, projection: CzCuzkProjection): readonly CzMunicipalityDataset[] {
+	if (!feed.entries.length) {
+		throw new Error(
+			`${CZ_CUZK_SERVICE_FEED_URL}: the service document holds no <entry>, so the municipalities it offers ` +
+				`could not be read`
+		)
+	}
+
+	const base = projectionBaseURL(feed, projection)
+	const datasets: CzMunicipalityDataset[] = []
+	const seen = new Set<string>()
+
+	for (const entry of feed.entries) {
+		const code = municipalityCodeOf(entry)
+
+		if (seen.has(code)) {
+			throw new Error(
+				`${CZ_CUZK_SERVICE_FEED_URL}: municipality ${code} is listed twice, so one of the two archives ` +
+					`would overwrite the other`
+			)
+		}
+
+		seen.add(code)
+
+		// The entry's `alternate` link is its dataset feed.
+		// The `describedby` link beside it is the ISO 19139 metadata record.
+		// Reading either as the other costs a request that answers XML of the wrong kind.
+		const datasetFeed = linkWithRel(entry.links, "alternate")
+
+		if (!datasetFeed?.href) {
+			throw new Error(
+				`${CZ_CUZK_SERVICE_FEED_URL}: the entry for municipality ${code} carries no rel="alternate" link, ` +
+					`so its dataset feed could not be read`
+			)
+		}
+
+		datasets.push({
+			code,
+			title: entry.title,
+			updated: entry.updated,
+			datasetFeedURL: datasetFeed.href,
+			downloadURL: `${base}/${code}.zip`,
+			filename: `${code}.zip`,
+		})
+	}
+
+	return datasets
+}
+
+/**
+ * The archive link a dataset feed states for one projection.
+ *
+ * Read only when {@linkcode HarvestCzCuzkOptions.resolveThroughDatasetFeed} is set.
+ * The feed holds one entry per projection, each with one `alternate` link, and the projection is
+ * identified by the href's own path segment for the same reason {@linkcode projectionBaseURL} uses it.
+ *
+ * @throws When the dataset feed states no link for the requested projection.
+ */
+export function datasetFeedArchiveURL(feed: AtomFeed, projection: CzCuzkProjection, context: string): string {
+	for (const entry of feed.entries) {
+		const link = linkWithRel(entry.links, "alternate")
+
+		if (link?.href.includes(`/${projection}/`)) return link.href
+	}
+
+	throw new Error(
+		`${context}: the dataset feed states no alternate link under /${projection}/, so the archive for that ` +
+			`projection could not be read`
+	)
+}
+
+/**
+ * One archive, as the harvest's manifest records it.
+ *
+ * {@linkcode SourceManifest}'s five fields plus what a re-run needs: the modification time
+ * the service document stated for this municipality, and the one the host served it under.
+ */
+export interface CzCuzkArchiveEntry extends SourceManifest {
+	municipality_code: string
+	/**
+	 * The `<updated>` the service document stated when this archive was fetched.
+	 *
+	 * A later run that reads the same value for this municipality leaves the file alone.
+	 * This is the field that makes the harvest resumable without a request per municipality.
+	 */
+	feed_updated: string
+	/**
+	 * The `Last-Modified` the host served the archive under, or `null` where it served none.
+	 *
+	 * Recorded rather than compared: {@linkcode CzCuzkArchiveEntry.feed_updated}
+	 * answers the same question without a request.
+	 */
+	last_modified: string | null
+}
+
+/**
+ * The harvest's `MANIFEST.json`.
+ */
+export interface CzCuzkHarvestManifest extends SourceCollectionManifest {
+	/**
+	 * The projection the archives in this directory are in.
+	 *
+	 * Recorded because the two projections share a file name, so a directory holding
+	 * both would be read by the adapter as two copies of every address.
+	 */
+	projection: CzCuzkProjection
+	/**
+	 * 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: CzCuzkArchiveEntry[]
+}
+
+export interface HarvestCzCuzkOptions {
+	/**
+	 * Where the archives and the manifest are written, which is the adapter's `inputPath`.
+	 */
+	outputDir: PathBuilderLike
+	/**
+	 * Which projection to harvest.
+	 * Defaults to `epsg-4258`.
+	 */
+	projection?: CzCuzkProjection
+	/**
+	 * Harvest only these municipality codes, for a probe or for a repair of named municipalities.
+	 *
+	 * 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.
+	 *
+	 * A bounded run rather than all 6,258.
+	 */
+	limit?: number
+	/**
+	 * Take each archive's URL from its own dataset feed instead of composing it
+	 * from the base the service document declares.
+	 *
+	 * Costs one extra request per municipality and asks the publisher rather than composing.
+	 */
+	resolveThroughDatasetFeed?: 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`.
+	 * This re-hashes, which reads every archive in the directory.
+	 */
+	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, and the first is what saves 6,258 requests: the service
+ * document states the same modification time it stated when the file was fetched,
+ * the file is still there, and it is still the length that was recorded for it.
+ */
+async function isCurrent(
+	recorded: CzCuzkArchiveEntry | undefined,
+	dataset: CzMunicipalityDataset,
+	path: PathBuilderLike,
+	verifyDigests: boolean
+): Promise<boolean> {
+	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
+}
+
+/**
+ * Harvest the municipalities the service document lists into `options.outputDir`.
+ *
+ * The client is injected so the harvest is testable without the network and so a caller
+ * decides the pacing. {@linkcode fetchCzCuzk} is the registry entry point and supplies both.
+ *
+ * @returns What was fetched, what was already current, and which municipality codes failed.
+ */
+export async function harvestCzCuzk(
+	client: Pick<APIClient, "fetch">,
+	options: HarvestCzCuzkOptions
+): Promise<FetchSummary> {
+	const { report, signal } = options
+	const projection = options.projection ?? "epsg-4258"
+	const destDir = PathBuilder.from(options.outputDir)
+	const manifestPath = destDir("MANIFEST.json")
+
+	await makeDirectories(destDir)
+
+	// MARK: Read the service document
+	//
+	// One request, and it states the modification time of every archive the service offers.
+
+	report?.(`=== ${SLUG}: reading ${CZ_CUZK_SERVICE_FEED_URL}`)
+
+	const { data: serviceXML } = await client.fetch<string>({
+		method: "GET",
+		url: CZ_CUZK_SERVICE_FEED_URL,
+		responseType: "text",
+	})
+
+	// The service document shares the http 200 an exception report arrives on.
+	assertNoOGCServiceException(serviceXML, `${SLUG} service document`)
+
+	const feed = await readAtomFeed(feedChunks(serviceXML))
+	const listed = readCzCuzkServiceFeed(feed, projection)
+
+	report?.(`  ${listed.length} municipalities listed, projection ${projection} (${CZ_CUZK_PROJECTIONS[projection]})`)
+
+	const wanted = selectMunicipalities(listed, options)
+
+	report?.(`  ${wanted.selected.length} selected for this run`)
+
+	// MARK: Fetch what the feed describes anew
+
+	const previous = await loadCollectionFiles(manifestPath)
+	const files = new Map<string, CzCuzkArchiveEntry>()
+
+	// 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 CzCuzkArchiveEntry)
+	}
+
+	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: CzCuzkHarvestManifest = {
+			source: SLUG,
+			source_url: CZ_CUZK_SERVICE_FEED_URL,
+			license: CZ_CUZK_LICENSE,
+			attribution: CZ_CUZK_ATTRIBUTION,
+			downloaded_at: new Date().toISOString(),
+			projection,
+			municipalities_listed: listed.length,
+			files: [...files.values()].toSorted((left, right) =>
+				left.municipality_code < right.municipality_code ? -1 : left.municipality_code > right.municipality_code ? 1 : 0
+			),
+		}
+
+		await writeManifest(manifestPath, manifest)
+	}
+
+	for (const dataset of wanted.selected) {
+		if (signal?.aborted) break
+
+		const dest = destDir(dataset.filename)
+
+		if (await isCurrent(files.get(dataset.filename), dataset, dest, options.verifyDigests ?? false)) {
+			skipped++
+
+			continue
+		}
+
+		try {
+			const entry = await fetchArchive(client, dataset, {
+				projection,
+				dest,
+				resolveThroughDatasetFeed: options.resolveThroughDatasetFeed ?? false,
+			})
+
+			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()
+		}
+	}
+
+	await writeHarvestManifest()
+
+	report?.(`=== ${SLUG} summary`)
+	report?.(`fetched: ${fetched}`)
+	report?.(`skipped: ${skipped} (the feed states the modification time 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 CzMunicipalityDataset[],
+	options: Pick<HarvestCzCuzkOptions, "municipalities" | "limit">
+): { selected: readonly CzMunicipalityDataset[]; unknown: readonly string[] } {
+	let selected = listed
+	const unknown: string[] = []
+
+	if (options.municipalities) {
+		const byCode = new Map(listed.map((dataset) => [dataset.code, dataset]))
+		const found: CzMunicipalityDataset[] = []
+
+		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 archive is stored as it arrives.
+ * The adapter opens it, because ČÚZK writes the ZIP64 sentinel into at least one central
+ * directory and `adm-zip` inflates the member instead of trusting it.
+ *
+ * @throws When the body does not begin with a zip signature.
+ * An error page served under http 200 is the body that fails this check.
+ * An html page is therefore never written to disk under a `.zip` name.
+ */
+async function fetchArchive(
+	client: Pick<APIClient, "fetch">,
+	dataset: CzMunicipalityDataset,
+	options: { projection: CzCuzkProjection; dest: PathBuilderLike; resolveThroughDatasetFeed: boolean }
+): Promise<CzCuzkArchiveEntry> {
+	let url = dataset.downloadURL
+
+	if (options.resolveThroughDatasetFeed) {
+		const { data: datasetXML } = await client.fetch<string>({
+			method: "GET",
+			url: dataset.datasetFeedURL,
+			responseType: "text",
+		})
+
+		assertNoOGCServiceException(datasetXML, `${SLUG} dataset feed ${dataset.code}`)
+
+		url = datasetFeedArchiveURL(
+			await readAtomFeed(feedChunks(datasetXML)),
+			options.projection,
+			`${SLUG} dataset feed ${dataset.code}`
+		)
+	}
+
+	const response = await client.fetch<ArrayBuffer>({
+		method: "GET",
+		url,
+		responseType: "arraybuffer",
+	})
+
+	const bytes = Buffer.from(response.data)
+
+	// The signature rather than a length: the advertised `type` is `application/gml+xml` on
+	// a body the host serves as `application/zip`, so neither header settles what arrived.
+	if (bytes.subarray(0, ZIP_SIGNATURE.length).toString("latin1") !== ZIP_SIGNATURE) {
+		throw new Error(
+			`${url} answered ${bytes.byteLength} bytes that do not begin with a zip signature, ` +
+				`so the body is not the archive`
+		)
+	}
+
+	await writeLocalFile(bytes, options.dest)
+
+	// A stubbed transport may answer without headers at all, so the record of what the
+	// host served the archive under is read defensively rather than indexed.
+	const headers = response.headers as Record<string, string> | undefined
+
+	return {
+		municipality_code: dataset.code,
+		filename: dataset.filename,
+		source_url: url,
+		downloaded_at: new Date().toISOString(),
+		sha256: sha256Hex(bytes),
+		bytes: bytes.byteLength,
+		feed_updated: dataset.updated,
+		last_modified: headers?.["last-modified"] ?? null,
+	}
+}
+
+export interface FetchCzCuzkOptions
+	extends
+		BaseFetchOptions,
+		Pick<
+			HarvestCzCuzkOptions,
+			"projection" | "municipalities" | "limit" | "resolveThroughDatasetFeed" | "verifyDigests" | "signal"
+		> {
+	/**
+	 * The minimum spacing between two requests, in milliseconds.
+	 *
+	 * Defaults to {@linkcode CZ_CUZK_REQUEST_INTERVAL_MS}.
+	 */
+	minRequestIntervalMs?: number
+}
+
+/**
+ * Harvest ČÚZK's INSPIRE Addresses archives into `<outRoot>/cz-cuzk/`.
+ *
+ * Re-runnable: a municipality whose recorded modification time still matches the service
+ * document's and whose archive is still on disk at the recorded length costs no request.
+ *
+ * A full harvest is 6,259 requests — the service document plus one per municipality —
+ * and an estimated 396 MB, from a mean of 63,337 bytes over a systematic sample
+ * of 50 of the 6,258 archives on 2026-10-02.
+ * The sample ran from 5,236 to 1,642,586 bytes, so the total is an estimate from
+ * 50 measurements rather than a measurement of all 6,258.
+ */
+export async function fetchCzCuzk(options: FetchCzCuzkOptions, report?: (line: string) => void): Promise<FetchSummary> {
+	await using client = new APIClient({
+		displayName: SLUG,
+		minRequestIntervalMs: options.minRequestIntervalMs ?? CZ_CUZK_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 harvestCzCuzk(client, {
+		outputDir: options.outRoot(SLUG),
+		projection: options.projection,
+		municipalities: options.municipalities,
+		limit: options.limit,
+		resolveThroughDatasetFeed: options.resolveThroughDatasetFeed,
+		verifyDigests: options.verifyDigests,
+		signal: options.signal,
+		report,
+	})
+}