@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/de/recipes/locale.ts

@@ -3,42 +3,41 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `german` slice recipe — German coverage rows from REAL OpenAddresses tuples (Berlin + Saxony,
- *   cached zips). Each sampled tuple is rendered via {@link synthesizeGermanRow} in BOTH orders —
- *   `--intl-fraction` (default 0.4) in international order (house-first / postcode-after-city), the
- *   rest in idiomatic German order — then aligned to BIO. Generate-mode: it builds a tuple pool
- *   from the cached zips, then draws `--count` rows from it with the passed `random` (so the emit
- *   stream matches the legacy reservoir-sample loop). Ported from scripts/build-german-slice.mjs.
+ * `german` recipe: German coverage rows from real OpenAddresses tuples (Berlin and Saxony, cached
+ * zips). Each sampled tuple renders through {@link renderGermanRow} in both orders, with
+ * `--intl-fraction` (default 0.4) in international order and the rest in idiomatic German order.
+ * Generate mode builds a tuple pool from the cached zips, then draws `--count` rows with the passed
+ * `random`.
  *
- *   ORDER ROBUSTNESS (2026-06-06): mixing the two renderings stops a native-only slice from teaching
- *   German order so well it reads the US/feed-order eval as a "collapse". See
- *   docs/articles/evals/resolver-geo/2026-06-06-anchor-pilot.md (the order-artifact correction).
+ * The combined renderings keep native-only recipe output from over-teaching German order.
+ * Over-teaching German order appears as a collapse on the US/feed-order eval.
  *
- *   TWO REGISTERS THE OA TUPLES DO NOT CARRY (#1946). A comma-free single line — `Neusser Str. 12 Nippes
- *   50733 Köln`, the dictation / one-field-form register — segments as ONE unit at stage 2, and with one
- *   segment the placetype-pair prior never fires, so the model reads `Nippes` as a second street and the
- *   one-value-per-tag projection deletes it. `--comma-free-fraction` renders that many native-order rows
- *   with `" "` as the line separator. And OA rows have no district at all, so `--ortsteil-fraction` rows
- *   borrow a WOF Ortsteil of the tuple's own locality as `dependent_locality` — 67,532 DE neighbourhoods
- *   carry a locality ancestor in the admin database, `Köln-Nippes` among them. The German spelling is
- *   recovered from the `names` table ({@link ortsteilSurface}): WOF's `spr.name` for DE neighbourhoods is
- *   the ASCII-folded label (`Bocklemuend`), which no German ever types.
+ * Two registers are absent from the OA tuples. A comma-free single line (`Neusser Str. 12 Nippes 50733
+ * Köln`) segments as one unit at stage 2. With one segment, the placetype-pair prior never fires.
+ * The model then reads `Nippes` as a second street. The one-value-per-tag projection deletes it.
+ * `--comma-free-fraction` renders that many native-order rows with `" "` as the line separator. OA
+ * rows also lack a district, so `--ortsteil-fraction` rows borrow a WOF Ortsteil of the tuple's
+ * own locality as `dependent_locality`. The German spelling is recovered from the `names` table
+ * ({@link ortsteilSurface}) because WOF's `spr.name` for DE neighborhoods is the ascii-folded label.
  */
 
 import { dataRootPath } from "@mailwoman/core/data-root"
 import { pathExists } from "@mailwoman/core/fs/readers"
+import { stringifyJSON } from "@mailwoman/core/json"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
+import { wofDatabasePath } from "@mailwoman/resolver-wof-sqlite/paths"
 import type { WOFDatabase } from "@mailwoman/resolver-wof-sqlite/schema"
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import type { PathBuilderLike } from "path-ts"
 
-import { stableSourceID } from "#adapters/utils"
+import { stableSourceID } from "#adapters/source-id"
 import { readZippedCSVRecords, type CorpusRecipe } from "#recipes/scaffold"
-import { synthesizeGermanRow, type LocaleBaseTuple } from "#synthesizers/locale"
+import { defaultRecipeSource } from "#recipes/sources"
+import { renderGermanRow, type LocaleBaseTuple } from "#surfaces/locale"
 import { alignRow } from "#utils"
 
 /**
- * A German OA source (cached zip) + the Bundesland the file covers (OA's REGION column is empty for DE).
+ * A German OA source (cached zip) + the Bundesland the file covers (OA's region column is empty for DE).
  */
 interface GermanSource {
 	zip: PathBuilderLike
@@ -47,9 +46,13 @@ interface GermanSource {
 }
 
 /**
- * `region` is the Bundesland the source covers. OA's REGION column is empty for DE, but the region is implied by the
- * per-state file — the international order needs it for the "City, Region Postcode" tail (v0.9.3 / #327). berlin.csv →
- * Berlin (a city-state, region==locality); sn/statewide → Sachsen.
+ * Each source's `region` is the Bundesland the file covers.
+ *
+ * OA's region column is empty for DE, so the region comes from the per-state file.
+ * The international order needs it for the "City, Region Postcode" tail.
+ *
+ * The Berlin file is a city-state whose region equals its locality.
+ * The Saxony file is Sachsen.
  */
 const SOURCES: GermanSource[] = [
 	{ zip: dataRootPath("oa-cache", "de__berlin.zip"), csv: "de/berlin.csv", region: "Berlin" },
@@ -57,10 +60,12 @@ const SOURCES: GermanSource[] = [
 ]
 
 /**
- * The two ASCII spellings WOF uses for one German label, so a `names.deu` row can be matched to the `spr.name` it
- * spells. WOF folds `Bocklemünd` to `Bocklemuend` in one record and `Schöneberg` to `Schoneberg` in another — the
- * transliteration (`ö` → `oe`, `ß` → `ss`) and the plain diacritic strip (`ö` → `o`) both occur — so a match is against
- * either form, lower-cased.
+ * The two ascii spellings WOF uses for one German label, so a `names.deu` row
+ * can be matched to the `spr.name` it spells.
+ *
+ * WOF folds `Bocklemünd` to `Bocklemuend` in one record and `Schöneberg` to `Schoneberg`
+ * in another — the transliteration (`ö` → `oe`, `ß` → `ss`) and the plain diacritic strip
+ * (`ö` → `o`) both occur — so a match is against either form, lower-cased.
  */
 function foldGerman(surface: string): [transliterated: string, stripped: string] {
 	const lower = surface.toLowerCase()
@@ -94,12 +99,15 @@ function sameGermanLabel(left: string, right: string): boolean {
 /**
  * The surface an Ortsteil is written with in an address, from WOF's rows for it.
  *
- * `spr.name` for a DE neighbourhood is the ASCII-folded label; the `names` rows in `deu` carry the German spelling
- * beside unrelated labels for co-located features (`Bocklemuend` → `Bocklemünd`, `Jüdischer Friedhof Bocklemünd`,
- * `Menara-Garten`). The German name is the one that spells the same label as `spr.name` under either of WOF's ASCII
- * folds ({@link foldGerman}); with none, `spr.name` stands. WOF also prefixes some Ortsteile with their city
- * (`Köln-Nippes`), a form no envelope carries once the city is its own line, so a leading `<locality>-` is dropped when
- * something is left after it.
+ * `spr.name` for a DE neighborhood is the ascii-folded label.
+ * The `names` rows in `deu` contain the German spelling beside unrelated labels for co-located
+ * features (`Bocklemuend` → `Bocklemünd`, `Jüdischer Friedhof Bocklemünd`, `Menara-Garten`).
+ *
+ * The German name is the one that spells the same label as `spr.name` under either of
+ * WOF's ascii folds ({@link foldGerman}); with none, `spr.name` stands.
+ *
+ * WOF also prefixes some Ortsteile with their city (`Köln-Nippes`), a form absent from the envelope
+ * once the city is its own line, so a leading `<locality>-` is dropped when something is left after it.
  */
 export function ortsteilSurface(sprName: string, deuNames: readonly string[], locality: string): string {
 	const german = deuNames.find((name) => sameGermanLabel(name, sprName)) ?? sprName
@@ -111,11 +119,14 @@ export function ortsteilSurface(sprName: string, deuNames: readonly string[], lo
 }
 
 /**
- * Every current DE neighbourhood with a locality ancestor, keyed by the folded locality name → Ortsteil surfaces. Empty
- * when the admin database is not readable; the recipe then emits no Ortsteil rows and says so, rather than failing a
- * build over an optional register.
+ * Every current DE neighborhood with a locality ancestor, keyed by the folded
+ * locality name → Ortsteil surfaces.
+ *
+ * Empty when the admin database is not readable.
+ * The recipe then emits no Ortsteil rows and reports that result, rather than
+ * failing a build over an optional register.
  */
-async function readOrtsteilPool(adminDB: string): Promise<Map<string, string[]>> {
+async function readOrtsteilPool(adminDB: PathBuilderLike): Promise<Map<string, string[]>> {
 	const pool = new Map<string, string[]>()
 
 	if (!(await pathExists(adminDB))) return pool
@@ -180,7 +191,7 @@ async function readGermanTuples(source: GermanSource): Promise<LocaleBaseTuple[]
 		if (!street || !locality) continue
 		const house_number = row.number ?? ""
 		const postcode = row.postcode ?? ""
-		// OA's REGION column is empty for DE — fall back to the source's Bundesland (set per file).
+		// OA's region column is empty for DE — fall back to the source's Bundesland (set per file).
 		const region = row.region || source.region || ""
 		const key = `${house_number}|${street}|${locality}|${postcode}`.toLowerCase()
 
@@ -193,12 +204,11 @@ async function readGermanTuples(source: GermanSource): Promise<LocaleBaseTuple[]
 }
 
 /**
- * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
- * and `description` below for the surface form it generates.
+ * Recipe registered with the corpus builder.
  */
 export const germanRecipe: CorpusRecipe = {
 	name: "german",
-	description: "German coverage rows from real OA tuples (Berlin/Saxony), both orders → synthesizeGermanRow",
+	description: "German coverage rows from real OA tuples (Berlin/Saxony), both orders → renderGermanRow",
 	mode: "generate",
 	options: [
 		{ flag: "--intl-fraction <f>", description: "Fraction rendered international order. Default 0.4" },
@@ -214,13 +224,12 @@ export const germanRecipe: CorpusRecipe = {
 		{
 			flag: "--admin-db <path>",
 			description:
-				"WOF admin database for the Ortsteil pool. Default $MAILWOMAN_DATA_ROOT/wof/admin-global-priority-importance.db",
+				"WOF admin database for the Ortsteil pool. Default $MAILWOMAN_DATA_ROOT/db/wof/admin-global-priority-importance.db",
 		},
 	],
 	async run(opts, write) {
-		// Emit PRNG: the legacy build-german-slice.mjs seeded mulberry32(opts.seed).
 		const random = makeMulberry32(opts.seed)
-		const source = opts.sourceName ?? "synth-german"
+		const source = opts.sourceName ?? defaultRecipeSource("synth-german")
 		const intlFraction = opts.intlFraction ?? 0.4
 		const commaFreeFraction = opts.commaFreeFraction ?? 0.3
 		const ortsteilFraction = opts.ortsteilFraction ?? 0.3
@@ -235,7 +244,7 @@ export const germanRecipe: CorpusRecipe = {
 			}
 		}
 
-		const adminDB = opts.adminDB ?? String(dataRootPath("wof", "admin-global-priority-importance.db"))
+		const adminDB = opts.adminDB ?? wofDatabasePath("admin-global-priority-importance.db")
 		const ortsteile = ortsteilFraction > 0 ? await readOrtsteilPool(adminDB) : new Map<string, string[]>()
 
 		if (ortsteilFraction > 0) {
@@ -248,7 +257,6 @@ export const germanRecipe: CorpusRecipe = {
 
 		const count = opts.count ?? 4000
 
-		// Pool real tuples from every German source, then sample `count` rows from it.
 		const pool: LocaleBaseTuple[] = []
 
 		for (const s of SOURCES) {
@@ -258,7 +266,7 @@ export const germanRecipe: CorpusRecipe = {
 
 			for (const x of t) {
 				pool.push(x)
-			} // NOT pool.push(...t) — spreading ~840K args overflows the stack
+			} // not pool.push(...t) — spreading ~840K args overflows the stack
 		}
 
 		if (!pool.length) {
@@ -274,11 +282,13 @@ export const germanRecipe: CorpusRecipe = {
 
 		while (emitted < count && guard++ < count * 6) {
 			const drawn = pool[Math.floor(random() * N)]!
-			// Per-row order: `--intl-fraction` of rows render house-first / postcode-after-city (the US/feed
-			// layout), the rest in idiomatic German order. Same components either way.
+			// Per-row order: `--intl-fraction` of rows render house-first / postcode-after-city
+			// (the US/feed layout), the rest in idiomatic German order.
+			// Same components either way.
 			const order = random() < intlFraction ? "international" : "native"
-			// The two registers OA never wrote (#1946), each drawn independently of the order so every combination
-			// occurs: an Ortsteil borrowed from the tuple's own locality, and a native line with no commas.
+			// OA does not provide these two registers.
+			// Draw each independently of the order so every combination occurs: an Ortsteil
+			// borrowed from the tuple's own locality or a native line with no commas.
 			const localOrtsteile = ortsteile.get(drawn.locality.toLowerCase())
 
 			const ortsteil =
@@ -288,7 +298,7 @@ export const germanRecipe: CorpusRecipe = {
 
 			const base: LocaleBaseTuple = ortsteil ? { ...drawn, dependent_locality: ortsteil } : drawn
 			const separator = order === "native" && random() < commaFreeFraction ? " " : ", "
-			const synth = synthesizeGermanRow(base, { random, order, separator })
+			const synth = renderGermanRow(base, { random, order, separator })
 
 			if (!synth) {
 				skipped++
@@ -296,10 +306,10 @@ export const germanRecipe: CorpusRecipe = {
 				continue
 			}
 
-			// --golden: emit per-locale-f1 eval rows ({raw, components}) instead of aligned BIO. `order`
-			// rides along so the eval can stratify native vs international.
+			// --golden: emit per-locale-f1 eval rows ({raw, components}) instead of aligned BIO.
+			// `order` accompanies each row so the eval can stratify native vs international.
 			if (opts.golden) {
-				write(JSON.stringify({ raw: synth.raw, components: synth.components, country: "DE", order }) + "\n")
+				write(stringifyJSON({ raw: synth.raw, components: synth.components, country: "DE", order }))
 
 				emitted++
 
@@ -333,13 +343,13 @@ export const germanRecipe: CorpusRecipe = {
 			}
 
 			write(
-				JSON.stringify({
+				stringifyJSON({
 					...aligned.row,
 					synth_method: "german",
 					synth_order: order,
 					synth_separator: separator === " " ? "space" : "comma",
 					synth_base_id: null,
-				}) + "\n"
+				})
 			)
 
 			emitted++

package/lib/directory.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file The one place a corpus version becomes a directory name.
+ *
+ *   Three writers composed `corpus-v${version}` independently, so a `--corpus-version` value already
+ *   carrying the prefix produced `corpus-vv0.7.0-de-holdout` on disk and 695 files were re-stamped to
+ *   repair it. The CLI now refuses such a value through `isCorpusVersion`, and this function is the
+ *   other half: one composer, so a later change to the layout moves one line.
+ */
+
+import { stringifyJSON } from "@mailwoman/core/json"
+
+/**
+ * The directory name a corpus version is written under.
+ *
+ * @param corpusVersion The version by itself, without the `corpus-v` prefix.
+ * @throws When the version already includes the prefix.
+ * The same name composition yields `corpus-vv…`.
+ */
+export function corpusDirectoryName(corpusVersion: string): string {
+	if (corpusVersion.startsWith("v")) {
+		throw new Error(
+			`corpusDirectoryName: ${stringifyJSON(corpusVersion)} already carries a leading "v". Composing the ` +
+				`name would yield "corpus-v${corpusVersion}". Pass the version alone, as "0.7.0-de-holdout".`
+		)
+	}
+
+	return `corpus-v${corpusVersion}`
+}

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()