@mailwoman/corpus 10.1.0 → 10.2.0

package/lib/recipes/venue.ts

@@ -0,0 +1,347 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `venue` recipe. A real venue name written as the whole query, and the same name followed by a
+ *   locality drawn from the country's admin tuples. The rows teach the model that
+ *   `Manchester Art Gallery` is a venue rather than a locality and a region, which the venue-head
+ *   prior in `@mailwoman/neural` also asserts, so the model and the prior agree.
+ *
+ *   Venue names come from the Overture place-names Parquet file the venue-head table is built
+ *   from, which holds `name`, `category` and `country` for every place at confidence 0.85 or
+ *   higher. The file has no locality column, so the locality row joins a name to a tuple of the
+ *   same country and asserts no fact about where the venue stands, so its surface is
+ *   `SurfaceOrigin.Composed`. The bare row is the publisher's own string, so its surface is
+ *   `SurfaceOrigin.Attested`.
+ *
+ *   A bare row needs a name of two or more words. A one-word name such as `Blackwell` or `Roadside`
+ *   is written as a bare query only beside a locality, because a lone unknown word is the shape of a
+ *   bare locality and a row that labels it `venue` would teach against bare-locality recall.
+ *
+ *   A name that equals a locality of the country's tuples, or whose written row is an input on a
+ *   gauntlet board, is refused.
+ */
+
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
+import { venueHeadLexicon } from "@mailwoman/poi-taxonomy/venue-heads"
+import type { PathBuilderLike } from "path-ts"
+
+import { normalizeGauntletSurface, readGauntletInputs } from "#gauntlet-inputs"
+import { type DisposableDuckDB, escapeSQLString, openDuckDB } from "#parquet/duckdb"
+import {
+	alignAndWrite,
+	readTuples,
+	recipeSourceID,
+	type CorpusRecipe,
+	type RecipeTuple,
+	type WriteRecipeLine,
+} from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { SourceRegister } from "#registers"
+import { countryToLocale } from "#synthesizers/utils"
+import { SurfaceOrigin } from "#types"
+
+/**
+ * The Overture release the venue-head table is built from, so the two read one name population.
+ */
+export const DEFAULT_VENUE_NAMES: PathBuilderLike = dataRootPath(
+	"overture",
+	"2026-09-23.1",
+	"place-names",
+	"names.parquet"
+)
+
+/**
+ * Venue names drawn per country when `--count` is absent.
+ */
+export const DEFAULT_NAMES_PER_COUNTRY = 20_000
+
+/**
+ * Share of locality rows that also carry the region when `--venue-region-fraction` is absent.
+ */
+export const DEFAULT_REGION_FRACTION = 0.5
+
+/**
+ * The two written shapes.
+ */
+export const VenueTemplate = {
+	/**
+	 * The venue name as the whole query.
+	 */
+	Bare: "venue-bare",
+	/**
+	 * The venue name, a comma, and a locality of the same country.
+	 */
+	Locality: "venue-locality",
+} as const
+
+/**
+ * One of {@linkcode VenueTemplate}.
+ */
+export type VenueTemplate = (typeof VenueTemplate)[keyof typeof VenueTemplate]
+
+const LICENSE =
+	"CDLA-Permissive-2.0 — Overture Maps places names; the locality comes from CC-BY / public-domain admin tuples"
+
+const BARE_PROVENANCE = {
+	register: SourceRegister.Overture,
+	surface: SurfaceOrigin.Attested,
+	// The names file has no record id column.
+	baseSourceID: null,
+}
+
+const LOCALITY_PROVENANCE = {
+	register: SourceRegister.Overture,
+	surface: SurfaceOrigin.Composed,
+	baseSourceID: null,
+}
+
+/**
+ * A head lookup for one country, the shape `venueHeadLexicon` returns.
+ */
+export interface VenueHeadSuffixLookup {
+	suffix(word: string): number | null
+}
+
+const SPACELESS_SCRIPT_RE = /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Script=Thai}]+$/u
+
+/**
+ * Characters a spaceless-script name needs before it is written as a bare query.
+ *
+ * A two-character name such as `東京` is the length of a city name, and the head the table recognizes is
+ * the name's last character, so a name shorter than this is a head with one character of stem.
+ */
+export const MIN_SPACELESS_BARE_CHARACTERS = 3
+
+/**
+ * Whether a name may be written as the whole query.
+ *
+ * In a spaced script the name needs two or more words, and at least one word
+ * with a letter, so `24 7` and `A1` stay out.
+ * In a script written without spaces a name is one word, so it qualifies when it has three or more
+ * characters and ends in a venue head the table holds for the country, as `国立西洋美術館` ends in `館`.
+ *
+ * A spaceless name the table does not recognize is written beside a locality only.
+ */
+export function isBareVenueName(name: string, heads?: VenueHeadSuffixLookup): boolean {
+	const words = name.trim().split(/\s+/u)
+
+	if (words.length >= 2) return words.some((word) => /\p{L}{2,}/u.test(word))
+
+	const word = words[0]!
+
+	return (
+		Boolean(heads) &&
+		[...word].length >= MIN_SPACELESS_BARE_CHARACTERS &&
+		SPACELESS_SCRIPT_RE.test(word) &&
+		heads!.suffix(word) !== null
+	)
+}
+
+/**
+ * The comparison key for a name against the country's localities.
+ */
+export function venueNameKey(name: string): string {
+	return name.normalize("NFC").trim().toLowerCase().replaceAll(/\s+/gu, " ")
+}
+
+/**
+ * Admin tuples grouped by country, with the locality set each country's names are checked against.
+ */
+export interface CountryTuples {
+	tuples: RecipeTuple[]
+	localities: Set<string>
+}
+
+/**
+ * The ISO 3166-1 alpha-2 code of a tuple's country.
+ *
+ * `corpus tuples` writes the code under `cc` and the display name under `country`.
+ * Older tuples files write the code under `country`.
+ * A tuple with neither form returns `null`.
+ */
+export function tupleCountryCode(tuple: RecipeTuple): string | null {
+	for (const value of [tuple.cc, tuple.country]) {
+		if (typeof value === "string" && /^[A-Za-z]{2}$/u.test(value.trim())) return value.trim().toUpperCase()
+	}
+
+	return null
+}
+
+/**
+ * Groups the admin tuples by country and keeps those with a locality.
+ */
+export async function groupTuplesByCountry(input: PathBuilderLike): Promise<Map<string, CountryTuples>> {
+	const byCountry = new Map<string, CountryTuples>()
+
+	for await (const tuple of readTuples(input)) {
+		const country = tupleCountryCode(tuple)
+
+		if (!country || !tuple.locality) continue
+		let entry = byCountry.get(country)
+
+		if (!entry) {
+			entry = { tuples: [], localities: new Set() }
+			byCountry.set(country, entry)
+		}
+
+		entry.tuples.push(tuple)
+		entry.localities.add(venueNameKey(tuple.locality))
+	}
+
+	return byCountry
+}
+
+/**
+ * Reads up to `limit` distinct names of one country from the Overture names file.
+ *
+ * The order is a hash of the name and the seed, so one seed draws one sample and a second seed another.
+ */
+export async function readVenueNames(
+	db: DisposableDuckDB,
+	venueNames: PathBuilderLike,
+	country: string,
+	limit: number,
+	seed: number
+): Promise<string[]> {
+	const result = await db.runAndReadAll(
+		`SELECT DISTINCT name FROM read_parquet('${escapeSQLString(String(venueNames))}')
+		WHERE country = '${escapeSQLString(country)}' AND name IS NOT NULL AND length(trim(name)) >= 3
+		ORDER BY hash(name, ${Math.floor(seed)}) LIMIT ${Math.floor(limit)}`
+	)
+
+	return result.getRows().map((row) => String(row[0]))
+}
+
+interface EmitContext {
+	write: WriteRecipeLine
+	source: { bare: string; locality: string }
+	boardInputs: ReadonlySet<string>
+	random: () => number
+	stats: { emitted: number; skipped: number; contaminated: number }
+}
+
+function emit(
+	context: EmitContext,
+	raw: string,
+	components: Record<string, string>,
+	country: string,
+	template: VenueTemplate,
+	idParts: Record<string, string | undefined>
+): void {
+	if (context.boardInputs.has(normalizeGauntletSurface(raw))) {
+		context.stats.contaminated++
+
+		return
+	}
+
+	const source = template === VenueTemplate.Bare ? context.source.bare : context.source.locality
+
+	const ok = alignAndWrite(
+		context.write,
+		{
+			raw,
+			components,
+			country,
+			locale: countryToLocale(country),
+			source,
+			source_id: recipeSourceID(source, { ...idParts, template }),
+			corpus_version: "0.12.0",
+			license: LICENSE,
+		},
+		template,
+		template === VenueTemplate.Bare ? BARE_PROVENANCE : LOCALITY_PROVENANCE
+	)
+
+	if (ok) {
+		context.stats.emitted++
+	} else {
+		context.stats.skipped++
+	}
+}
+
+/**
+ * Recipe registered with the corpus builder.
+ *
+ * `--input` supplies locality, region and country tuples, and every country
+ * in it with venue names is covered.
+ * `--count` caps the names drawn per country.
+ * `--venue-names` points at the Overture names file.
+ */
+export const venueRecipe: CorpusRecipe = {
+	name: "venue",
+	description: "A real venue name as the whole query, and the name beside a locality of its country",
+	mode: "tuples",
+	options: [
+		{ flag: "--venue-names <parquet>", description: `Overture place-names file (default ${DEFAULT_VENUE_NAMES})` },
+		{ flag: "--count <n>", description: `venue names per country (default ${DEFAULT_NAMES_PER_COUNTRY})` },
+		{
+			flag: "--venue-region-fraction <share>",
+			description: `locality rows that also carry the region (default ${DEFAULT_REGION_FRACTION})`,
+		},
+	],
+	async run(opts, write) {
+		if (!opts.input) throw new Error("venue recipe requires --input <tuples.jsonl>")
+		const random = makeMulberry32(opts.seed)
+		const venueNames = opts.venueNames ?? DEFAULT_VENUE_NAMES
+		const perCountry = opts.count ?? DEFAULT_NAMES_PER_COUNTRY
+		const regionFraction = opts.venueRegionFraction ?? DEFAULT_REGION_FRACTION
+		const byCountry = await groupTuplesByCountry(opts.input)
+		const boardInputs = await readGauntletInputs()
+
+		const context: EmitContext = {
+			write,
+			source: {
+				bare: opts.sourceName ? `${opts.sourceName}-bare` : defaultRecipeSource("synth-venue-bare"),
+				locality: opts.sourceName ? `${opts.sourceName}-locality` : defaultRecipeSource("synth-venue-locality"),
+			},
+			boardInputs,
+			random,
+			stats: { emitted: 0, skipped: 0, contaminated: 0 },
+		}
+
+		let read = 0
+
+		using db = await openDuckDB({ threads: 4 })
+
+		for (const [country, { tuples, localities }] of byCountry) {
+			const names = await readVenueNames(db, venueNames, country, perCountry, opts.seed)
+			const heads = venueHeadLexicon(country)
+
+			for (const name of names) {
+				read++
+
+				if (localities.has(venueNameKey(name))) {
+					context.stats.skipped++
+
+					continue
+				}
+
+				const tuple = tuples[Math.floor(random() * tuples.length)]!
+				const locality = tuple.locality!
+				const withRegion = Boolean(tuple.region) && random() < regionFraction
+				const components: Record<string, string> = { venue: name, locality }
+				let raw = `${name}, ${locality}`
+
+				if (withRegion) {
+					components.region = tuple.region!
+					raw = `${raw}, ${tuple.region}`
+				}
+
+				emit(context, raw, components, country, VenueTemplate.Locality, {
+					name,
+					locality,
+					region: withRegion ? tuple.region : undefined,
+				})
+
+				if (isBareVenueName(name, heads)) {
+					emit(context, name, { venue: name }, country, VenueTemplate.Bare, { name })
+				}
+			}
+		}
+
+		return { read, ...context.stats }
+	},
+}

package/lib/recipes.ts

@@ -39,6 +39,7 @@ import { streetBareRecipe } from "#recipes/street/bare"
 import { subVenueRecipe } from "#recipes/sub/venue"
 import { trailingRegionRecipe } from "#recipes/trailing-region"
 import { unitRecipe } from "#recipes/unit"
+import { venueRecipe } from "#recipes/venue"
 import { sgRegisterRecipe } from "#sg/recipes/register"
 import { siBareVillageRecipe } from "#si/recipes/bare-village"
 import { bdRegisterRecipe, pkRegisterRecipe } from "#south-asia/recipes/register"
@@ -84,6 +85,7 @@ const RECIPES: readonly CorpusRecipe[] = [
 	boundaryStressRecipe,
 	anchorAbsorptionRecipe,
 	subVenueRecipe,
+	venueRecipe,
 ]
 
 /**
@@ -94,8 +96,8 @@ export const RECIPES_BY_NAME: ReadonlyMap<string, CorpusRecipe> = new Map(RECIPE
 /**
  * Look up a recipe by its `<recipe>` name.
  */
-export function getRecipe(name: string): CorpusRecipe | undefined {
-	return RECIPES_BY_NAME.get(name)
+export function getRecipe(name: string): CorpusRecipe | null {
+	return RECIPES_BY_NAME.get(name) ?? null
 }
 
 /**

package/lib/registers.ts

@@ -61,8 +61,10 @@ export const SourceRegister = {
 	 */
 	CuzkInspireAddresses: "cz-cuzk-inspire-addresses",
 	/**
-	 * Suomen ympäristökeskus' Ryhti built-environment system, whose building address data
-	 * covers Åland's sixteen municipalities beside the Finnish mainland in one national file.
+	 * Suomen ympäristökeskus' Ryhti built-environment system.
+	 *
+	 * Its building address data covers Åland's sixteen municipalities beside the
+	 * Finnish mainland in one national file.
 	 *
 	 * The prefix is the publisher's own country, as `fr-ban`'s is.
 	 */
@@ -136,7 +138,7 @@ export const SourceRegister = {
 	 * The INSPIRE Addresses theme of the Diputación Foral de Bizkaia.
 	 *
 	 * Coverage is the province of Bizkaia, as 112 municipality archives.
-	 * The archives carry addresses alone, and the features they reference are served
+	 * The archives hold addresses only, and the features they reference are served
 	 * by the publisher's WFS rather than by the ATOM feed.
 	 */
 	BizkaiaInspireAddresses: "es-bizkaia-inspire-ad",
@@ -149,8 +151,8 @@ export const SourceRegister = {
 	/**
 	 * The INSPIRE Addresses theme of the Gobierno de Navarra.
 	 *
-	 * The province is split across 272 zipped GML partitions, each titled `Address Navarra`
-	 * rather than named for a municipality.
+	 * The province is split across 272 zipped GML partitions, each titled
+	 * `Address Navarra` The title states no municipality.
 	 */
 	NavarraInspireAddresses: "es-navarra-inspire-ad",
 	/**
@@ -166,7 +168,7 @@ export const SourceRegister = {
 	 * of Public Contracts, reached through the Open Contracting Partnership's Data Registry.
 	 *
 	 * Every address in the release belongs to a contracting authority or a paying office,
-	 * because the `supplier` role carries no address object.
+	 * because the `supplier` role holds no address object.
 	 */
 	ANACContracts: "it-anac-ocds-contracts",
 	/**

package/lib/ro/adapters/retea-scolara/adapter.ts

@@ -6,7 +6,7 @@
  * `ro-retea-scolara`: Romania's school network (`Rețea școlară`), the Ministry of Education's list of every
  * education unit for a school year, read for each unit's postal address.
  *
- * Input is the publisher's own workbook, one sheet named `Export`, as data.gov.ro serves it for the
+ * Input is the publisher's own workbook, one sheet titled `Export`, as data.gov.ro serves it for the
  * dataset `69392a50-5750-4a54-90c1-d461de44da6d`. Three rows precede the header. The adapter finds the
  * header by its `Strada` cell rather than by position, because the preamble is a generation timestamp
  * whose length the publisher does not fix.
@@ -23,7 +23,7 @@
  *   has none, on 601 and 180 units. Both are read as absent. A range such as `12-14` is a house number.
  * - `Cod postal` holds a six-digit Romanian postcode on 17,484 units. A value of any other length is
  *   left out of the row rather than refusing the row, because the address is complete without it.
- * - `Judet PJ` holds the county as a two-letter code. The row carries no region, because libaddressinput's
+ * - `Judet PJ` holds the county as a two-letter code. The row holds no region, because libaddressinput's
  *   Romanian layout places the county between postcode and locality, and this reader has no source for
  *   the county name in the form an address prints it.
  *
@@ -32,7 +32,7 @@
  * ## Organizations only
  *
  * Every unit is a school, kindergarten, children's club, county inspectorate or similar public body, and
- * the sheet carries no natural person's address. The venue is the institution's name.
+ * the sheet holds no natural person's address. The venue is the institution's name.
  *
  * ## Identity and license
  *
@@ -42,7 +42,7 @@
  * data.gov.ro publishes the dataset under `CC-BY-4.0`, the license its CKAN record names for the
  * publisher `Ministerul Educației`. CC BY 4.0 requires credit, a link to the license and a statement that
  * changes were made, so every row records the license and {@linkcode RO_RETEA_SCOLARA_ATTRIBUTION} is the
- * credit the model card carries.
+ * credit the model card records.
  */
 
 import { formatAddressRow } from "@mailwoman/codex/address/format"
@@ -90,7 +90,7 @@ export const ReteaScolaraRefusal = {
 	 */
 	LocalityAbsent: "row:locality-absent",
 	/**
-	 * The unit states neither a street nor a house number, so the locality alone would be a place name.
+	 * The unit states neither a street nor a house number, so the locality by itself would be a place name.
 	 */
 	PremiseAbsent: "row:premise-absent",
 	/**

package/lib/ro/tools/fetch/retea-scolara.ts

@@ -14,7 +14,7 @@
 
 import { APIClient } from "@mailwoman/core/api"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { tryStat } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"

package/lib/runner.ts

@@ -97,7 +97,7 @@ export interface RunAdapterOptions {
 	/**
 	 * Base-2 logarithm of the fingerprint table's slot count.
 	 *
-	 * Defaults to {@linkcode DEFAULT_DEDUP_SLOTS_LOG2}.
+	 * @defaultValue {@linkcode DEFAULT_DEDUP_SLOTS_LOG2}
 	 * A test sets it low to keep the allocation small.
 	 */
 	dedupSlotsLog2?: number
@@ -131,8 +131,9 @@ export interface RunAdapterOptions {
 	/**
 	 * Yielded-row interval at which `onProgress` fires.
 	 *
-	 * Defaults to 1000 rows per callback.
 	 * The runner always emits a terminal update.
+	 *
+	 * @defaultValue `1000` rows per callback.
 	 */
 	progressEvery?: number
 }
@@ -194,7 +195,7 @@ export interface AdapterRunManifest {
 export async function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunManifest> {
 	const { adapter, outputDir, corpusVersion } = opts
 	// A caller that passes its own map reads the counts back from it.
-	// Otherwise the runner supplies one, so every manifest carries the adapter's drop reasons.
+	// Otherwise the runner supplies one, so every manifest records the adapter's drop reasons.
 	const dropped = opts.adapterOptions.dropped ?? new Map<string, number>()
 	const adapterOptions: AdapterOptions = { ...opts.adapterOptions, dropped }
 	const progressEvery = opts.progressEvery ?? 1000

package/lib/sg/recipes/register.ts

@@ -125,7 +125,7 @@ export function renderSGRegister(row: SGRow, random: () => number, register?: SG
 	const street = random() < P_ABBREVIATE ? abbreviateSGStreet(street0) : street0
 	const drawn = random()
 	const building = isBuildingName(row.unit) ? titleCaseIfUpper(row.unit) : null
-	const draw = register === undefined ? drawn : REGISTER_DRAW[register]
+	const draw = register ? REGISTER_DRAW[register] : drawn
 
 	let raw: string
 	let rendered: SGRegister

package/lib/sg/tools/fetch/acra.ts

@@ -8,7 +8,7 @@
  */
 
 import { BYTES_PER_KIB } from "@mailwoman/core/fs/formatters"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { sleep } from "@mailwoman/core/utils/sleep"
@@ -60,7 +60,7 @@ async function readJSON<T>(url: string): Promise<T> {
  *
  * The function returns `undefined` when polling runs out of attempts.
  */
-async function signedURLFor(datasetID: string): Promise<string | undefined> {
+async function signedURLFor(datasetID: string): Promise<string | null> {
 	await readJSON(`${DOWNLOAD_API}/${datasetID}/initiate-download`)
 
 	for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt++) {
@@ -70,7 +70,7 @@ async function signedURLFor(datasetID: string): Promise<string | undefined> {
 		if (poll.data?.status === "DOWNLOAD_SUCCESS" && poll.data.url) return poll.data.url
 	}
 
-	return undefined
+	return null
 }
 
 function filenameFor(name: string, datasetID: string): string {

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

@@ -15,7 +15,7 @@
  *
  * The reference form is a WFS stored-query URL: an `ad:component` href is
  * `…/ad/ows?…&storedQuery_id=urn:ogc:def:query:OGC-WFS::GetFeatureById&id=AdminUnitName.199`, and
- * that `id` parameter equals the target's `gml:id` exactly, which a `GetFeatureById` fetch of
+ * that `id` parameter equals the target's `gml:id` exactly. A `GetFeatureById` fetch of
  * `AdminUnitName.199` confirms. `componentJoinKey` reads it. Each reference also repeats its target's
  * value in `xlink:title`, as Czechia's does, and the adapter reads none of those titles. Three of an
  * address's references are `ad:AdminUnitName` features whose titles are a region, a district and a
@@ -37,7 +37,7 @@
  * 1,000 times, `buildingIdentifier` 334 times, and the street count was also exactly 334.
  *
  * The same publisher serves its register's own rendered address through `ra:address` on the same
- * GeoServer, which is what pins the composition. Three records, matched by street, number and postcode:
+ * GeoServer. That rendering pins the composition. Three records, matched by street, number and postcode:
  *
  * | `addressNumber` | `buildingIdentifier` | street | `fulladdress` |
  * | --- | --- | --- | --- |
@@ -46,7 +46,7 @@
  * | `142` | (absent) | (absent) | `142,Sikenička,94359` |
  *
  * So the number is `addressNumber` by itself, or `addressNumber/buildingIdentifier` where the
- * orientation number exists, which is the publisher's own `annotation` field verbatim. A street-less
+ * orientation number exists. That is the publisher's own `annotation` field verbatim. A street-less
  * address is ordinary rather than a defect: 666 of those 1,000 referenced no `ad:ThoroughfareName`.
  *
  * The place names come from two types. `ad:AdminUnitName` at `4thOrder` is the municipality and is
@@ -155,19 +155,20 @@ const MUNICIPALITY_LEVEL = "4thOrder"
  */
 interface ReferencedValue {
 	/**
-	 * The feature's element name, which decides where its value goes.
+	 * The feature's element name.
+	 * It decides where its value goes.
 	 */
 	readonly type: string
 
 	/**
-	 * The street name, place name or postcode the feature states.
+	 * The street name, place name or postcode the feature states, null when it states none.
 	 */
-	readonly value?: string
+	readonly value: string | null
 
 	/**
 	 * The administrative level an `ad:AdminUnitName` states, such as `4thOrder`.
 	 */
-	readonly level?: string
+	readonly level: string | null
 }
 
 /**
@@ -175,18 +176,18 @@ interface ReferencedValue {
  */
 function referencedValue(feature: MarkupElement): ReferencedValue {
 	if (feature.name === "ad:ThoroughfareName") {
-		return { type: feature.name, value: thoroughfareName(feature) }
+		return { type: feature.name, value: thoroughfareName(feature), level: null }
 	}
 
 	if (feature.name === "ad:PostalDescriptor") {
-		return { type: feature.name, value: postalDescriptorCode(feature) }
+		return { type: feature.name, value: postalDescriptorCode(feature), level: null }
 	}
 
 	if (feature.name === "ad:AdminUnitName") {
 		return { type: feature.name, value: placeName(feature), level: adminUnitLevel(feature) }
 	}
 
-	return { type: feature.name, value: placeName(feature) }
+	return { type: feature.name, value: placeName(feature), level: null }
 }
 
 /**
@@ -196,12 +197,12 @@ function referencedValue(feature: MarkupElement): ReferencedValue {
  * number, and the two are joined by a solidus where it does.
  * The table in this module's header reads that off three records of the publisher's `ra:address` layer.
  *
- * @returns The number, or undefined when the publisher states no `addressNumber`.
+ * @returns The number, or null when the publisher states no `addressNumber`.
  */
-export function slovakHouseNumber(byType: ReadonlyMap<string, readonly string[]>): string | undefined {
+export function slovakHouseNumber(byType: ReadonlyMap<string, readonly string[]>): string | null {
 	const descriptive = designator(byType, "addressNumber")
 
-	if (!descriptive) return undefined
+	if (!descriptive) return null
 
 	const orientation = designator(byType, "buildingIdentifier")
 
@@ -273,26 +274,23 @@ export function createSKInspireAdapter(): CorpusAdapter {
 }
 
 /**
- * One address's row, or `undefined` when it holds too little to render.
+ * One address's row, or `null` when it holds too little to render.
  *
  * The component index is complete before this is called, so a reference that
  * resolves to no feature raises rather than being deferred.
  */
-function composeRow(
-	address: MarkupElement,
-	referenced: ReadonlyMap<string, ReferencedValue>
-): CanonicalRow | undefined {
-	const addressID = address.attributes["gml:id"]?.trim()
+function composeRow(address: MarkupElement, referenced: ReadonlyMap<string, ReferencedValue>): CanonicalRow | null {
+	const addressID = address.attributes["gml:id"]?.trim() ?? null
 	const voided = voidDesignatorTypes(address)
 
 	for (const type of ["addressNumber", "buildingIdentifier"]) {
 		if (voided.has(type)) throw new VoidDesignatorError(SK_INSPIRE_ADAPTER_ID, addressID, type)
 	}
 
-	let street: string | undefined
-	let postcode: string | undefined
-	let municipality: string | undefined
-	let settlement: string | undefined
+	let street: string | null = null
+	let postcode: string | null = null
+	let municipality: string | null = null
+	let settlement: string | null = null
 
 	for (const href of componentHrefs(address)) {
 		const key = componentJoinKey(href)
@@ -313,7 +311,7 @@ function composeRow(
 
 	const place = municipality ?? settlement
 
-	if (!place) return undefined
+	if (!place) return null
 
 	const components: CanonicalRow["components"] = {}
 	const house = slovakHouseNumber(designatorsByType(address))
@@ -326,8 +324,8 @@ function composeRow(
 		components.street = street
 	}
 
-	// The settlement part is a dependent locality only where it names something other
-	// than the municipality, which 101 of 426 address-area references do.
+	// The settlement part is a dependent locality only where it differs from the
+	// municipality. 101 of 426 address-area references do.
 	if (settlement && municipality && settlement !== municipality) {
 		components.dependent_locality = settlement
 	}
@@ -340,7 +338,7 @@ function composeRow(
 
 	const rendered = formatAddressRow(components, "SK", { singleLine: true })
 
-	if (!rendered) return undefined
+	if (!rendered) return null
 
 	const { raw, components: aligned } = rendered