@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/nl/tools/fetch/kadaster.ts

@@ -0,0 +1,298 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Downloads the INSPIRE Addresses theme Kadaster publishes for the Netherlands.
+ *
+ *   ## One feed and one file
+ *
+ *   PDOK serves an ATOM download service with a single entry, and that entry's one data link is the
+ *   whole country. There is no service document above it and no dataset feed below it, so the
+ *   resolution is one request:
+ *
+ *       adressen_inspire_geharmoniseerd.xml  →  addresses.gml.gz
+ *
+ *   The entry's `<id>` names a sibling feed, `adressen_inspire_geharmoniseerd_epsg4258.xml`, which
+ *   answers HTTP 404. A reader that followed the `<id>` rather than the `rel="alternate"` link would
+ *   therefore raise on that 404, so this one reads the link.
+ *
+ *   ## Why the download stays compressed
+ *
+ *   `#nl/adapters/kadaster/adapter` inflates `.gml.gz` through `gunzipChunks` as it streams. The
+ *   member is 29,677,448,685 bytes against the download's 819,465,603, so inflating it here would
+ *   cost 36 times the disk for no reader that wants it.
+ *
+ *   ## Freshness
+ *
+ *   The entry's `<updated>` is the signal recorded in the manifest. A skip requires the feed to
+ *   state an `<updated>` value:
+ *   where it states none both sides read `null`, an equality test would hold, and a download of
+ *   unknown age would be kept for as long as the feed stayed silent.
+ */
+
+import { APIClient, assertNoOGCServiceException } from "@mailwoman/core/api"
+import { ByteFormatter } from "@mailwoman/core/fs/formatters"
+import { tryStat } from "@mailwoman/core/fs/readers"
+import { makeDirectories } from "@mailwoman/core/fs/writers"
+import { sha256File } from "@mailwoman/core/hash"
+import { PathBuilder, type PathBuilderLike } from "path-ts"
+
+import { NL_KADASTER_ADAPTER_ID, NL_KADASTER_DEFAULT_LICENSE } from "#nl/adapters/kadaster/adapter"
+import { feedChunks, linkWithRel, readAtomFeed } from "#tools/fetch/atom"
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
+
+/**
+ * The ATOM download service for the theme, which holds the country's one entry.
+ */
+export const NL_KADASTER_FEED_URL = "https://service.pdok.nl/kadaster/ad/atom/adressen_inspire_geharmoniseerd.xml"
+
+/**
+ * The name the download is written under, which is what the adapter's `inputPath` states.
+ *
+ * The publisher's own name for the file.
+ * The adapter reads a `.gml.gz` by inflating it, so the suffix is load-bearing.
+ */
+export const NL_KADASTER_DOWNLOAD_FILENAME = "addresses.gml.gz"
+
+/**
+ * The attribution recorded in the manifest.
+ *
+ * CC0 1.0 reserves no act and owes no attribution clause, so this is the credit the
+ * repository chooses to carry rather than a condition of the grant.
+ */
+export const NL_KADASTER_ATTRIBUTION = "Kadaster"
+
+const SLUG = NL_KADASTER_ADAPTER_ID
+
+/**
+ * What one run recorded.
+ *
+ * `feed_updated` is the entry's own `<updated>`.
+ * A later run downloads again when that value changes, which is what the ATOM
+ * pattern offers in place of an HTTP validator.
+ *
+ * `rights` is the license URL the feed states, recorded so a change of terms is
+ * visible in the artifact rather than only in the register.
+ */
+export interface NLKadasterManifest extends SourceManifest {
+	feed_url: string
+	feed_updated: string | null
+	rights: string | null
+	license: string
+	attribution: string
+}
+
+/**
+ * Per-invocation options.
+ */
+export interface DownloadNLKadasterOptions {
+	outputDir: PathBuilderLike
+	/**
+	 * Downloads the file even where the feed reports the recorded `<updated>`.
+	 */
+	force?: boolean
+	retries?: number
+	retryDelayMs?: number
+	signal?: AbortSignal
+	report?: (line: string) => void
+}
+
+/**
+ * Where the download is, and what the feed states about it.
+ */
+export interface NLKadasterPublication {
+	downloadURL: string
+	/**
+	 * The entry's own `<updated>`, or `null` where the feed states none.
+	 *
+	 * `updated` sits on the Atom entry as well as on the feed, and this reads
+	 * the entry that carried the data link.
+	 * The feed reported `2026-09-02T11:45:47Z` when this reader was written.
+	 */
+	feedUpdated: string | null
+	/**
+	 * The entry's `<rights>`, or `null` where it states none.
+	 */
+	rights: string | null
+	/**
+	 * The byte count the link claims, or `null` where it claims none.
+	 *
+	 * Never taken as the size of the download: the bytes recorded in the manifest
+	 * are counted off the delivered body.
+	 */
+	claimedBytes: number | null
+}
+
+/**
+ * Reads the feed and answers the one entry's data link.
+ *
+ * Raises where the feed lists no entry, or where its entry offers no data link.
+ * The alternative would return `{fetched: 0, skipped: 0, failed: 0}`, which a caller
+ * reads as a fetch that completed and found the publisher empty.
+ *
+ * Separate from {@linkcode downloadNLKadaster} because the resolution is the part a test can drive.
+ * The download runs on global `fetch`, which a unit test cannot intercept.
+ */
+export async function readNLKadasterPublication(
+	client: Pick<APIClient, "fetch">,
+	options: { signal?: AbortSignal; report?: (line: string) => void } = {}
+): Promise<NLKadasterPublication> {
+	const { report } = options
+
+	report?.(`=== ${SLUG}: reading ${NL_KADASTER_FEED_URL}`)
+
+	const { data: feedXML } = await client.fetch<string>({
+		url: NL_KADASTER_FEED_URL,
+		timeout: 120_000,
+		signal: options.signal,
+	})
+
+	assertNoOGCServiceException(String(feedXML), `${SLUG} download service feed`)
+
+	const feed = await readAtomFeed(feedChunks(String(feedXML)))
+
+	const offered = feed.entries.flatMap((entry) => {
+		const link = linkWithRel(entry.links, "enclosure") ?? linkWithRel(entry.links, "alternate")
+
+		return link ? [{ entry, link }] : []
+	})[0]
+
+	if (!offered) {
+		throw new Error(
+			`${SLUG}: the feed offers no download through a rel="enclosure" or rel="alternate" link, ` +
+				`so no file can be resolved. It listed ${feed.entries.length} entries.`
+		)
+	}
+
+	return {
+		downloadURL: offered.link.href,
+		feedUpdated: offered.entry.updated || null,
+		rights: offered.entry.rights,
+		claimedBytes: offered.link.length,
+	}
+}
+
+/**
+ * Whether the file on disk is the one the feed currently offers.
+ *
+ * A skip requires the feed to state an `<updated>` value.
+ * Where it states none, both sides read `null` and an equality test would hold,
+ * which would keep a download of unknown age for as long as the feed stayed silent.
+ *
+ * Downloading 782 MiB again is the slower error and the recoverable one.
+ */
+export function nlKadasterPublicationIsRecorded(
+	recorded: NLKadasterManifest,
+	bytesOnDisk: number,
+	publication: NLKadasterPublication
+): boolean {
+	if (publication.feedUpdated === null) return false
+
+	return recorded.feed_updated === publication.feedUpdated && recorded.bytes === bytesOnDisk
+}
+
+/**
+ * Resolves the feed to its one file and downloads it.
+ */
+export async function downloadNLKadaster(
+	client: Pick<APIClient, "fetch">,
+	options: DownloadNLKadasterOptions
+): Promise<FetchSummary> {
+	const { report } = options
+	const destDir = PathBuilder.from(options.outputDir)
+	const downloadPath = destDir(NL_KADASTER_DOWNLOAD_FILENAME)
+	const manifestPath = destDir("MANIFEST.json")
+
+	// Resolved before the directory is made, so a publisher that answers with an
+	// exception report leaves no empty source directory behind.
+	const publication = await readNLKadasterPublication(client, { signal: options.signal, report })
+
+	await makeDirectories(destDir)
+
+	const recorded = await readManifest<NLKadasterManifest>(manifestPath)
+	const stat = await tryStat(downloadPath)
+
+	if (!options.force && recorded && stat && nlKadasterPublicationIsRecorded(recorded, stat.size, publication)) {
+		report?.(`  present, and the feed reports the recorded updated ${publication.feedUpdated}`)
+
+		return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] }
+	}
+
+	report?.(
+		`  download: ${publication.downloadURL}` +
+			(publication.claimedBytes === null
+				? ""
+				: ` (the feed claims ${ByteFormatter.formatIEC(publication.claimedBytes)})`)
+	)
+
+	const { bytes } = await downloadToFile({
+		url: publication.downloadURL,
+		dest: downloadPath,
+		retries: options.retries,
+		retryDelayMs: options.retryDelayMs,
+		report,
+	})
+
+	const sha256 = await sha256File(downloadPath)
+
+	report?.(`  ✓ ${ByteFormatter.formatIEC(bytes)}  sha256=${sha256}`)
+
+	const manifest: NLKadasterManifest = {
+		source_url: publication.downloadURL,
+		feed_url: NL_KADASTER_FEED_URL,
+		filename: NL_KADASTER_DOWNLOAD_FILENAME,
+		bytes,
+		sha256,
+		feed_updated: publication.feedUpdated,
+		rights: publication.rights,
+		license: NL_KADASTER_DEFAULT_LICENSE,
+		attribution: NL_KADASTER_ATTRIBUTION,
+		downloaded_at: new Date().toISOString(),
+	}
+
+	await writeManifest(manifestPath, manifest)
+
+	report?.(`  MANIFEST written to ${manifestPath}`)
+
+	return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] }
+}
+
+/**
+ * The path `#nl/adapters/kadaster/adapter` reads, given the root a fetch wrote under.
+ */
+export function nlKadasterInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike {
+	return outRoot(SLUG, NL_KADASTER_DOWNLOAD_FILENAME)
+}
+
+/**
+ * Per-invocation options for the registry entry.
+ */
+export interface FetchNLKadasterOptions extends BaseFetchOptions {
+	force?: boolean
+	retries?: number
+	retryDelayMs?: number
+	signal?: AbortSignal
+}
+
+/**
+ * The registry entry.
+ */
+export async function fetchNLKadaster(
+	options: FetchNLKadasterOptions,
+	report?: (line: string) => void
+): Promise<FetchSummary> {
+	await using client = new APIClient({ displayName: SLUG, 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 downloadNLKadaster(client, {
+		outputDir: options.outRoot(SLUG),
+		force: options.force,
+		retries: options.retries,
+		retryDelayMs: options.retryDelayMs,
+		signal: options.signal,
+		report,
+	})
+}

package/lib/no/adapters/matrikkelen/adapter.ts

@@ -0,0 +1,187 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `matrikkelen`: Kartverket's `Matrikkelen - Adresse` CSV adapter, covering Norway and Svalbard.
+ *
+ * Input is a semicolon-separated CSV from Geonorge, published per area beside a whole-country
+ * extract. Both carry the same 46 columns, so one reader serves either. The adapter reads
+ * `adressenavn` as the street, `nummer` and `bokstav` as the house number, and `postnummer` with
+ * `poststed` as the postcode and its postal place.
+ *
+ * A row's country comes from `kommunenummer` rather than from the caller. Svalbard is municipality
+ * 2100 and is its own ISO 3166-1 jurisdiction, so the dataset's own area list is what separates the
+ * two: Geonorge offers Svalbard as `kommune` 2100 and `fylke` 21 beside the `landsdekkende` whole of
+ * the mainland.
+ *
+ * Kartverket states CC BY 4.0 for this dataset across five agreeing metadata fields, so the adapter
+ * records that license on every row and the model card must attribute Kartverket.
+ *
+ * The adapter streams with `CSVSpliterator.fromAsync`, so the 2.6M-row mainland extract never sits
+ * in memory. It honors `opts.limit`, `opts.signal` and `opts.country`.
+ */
+
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { CSVSpliterator } from "spliterator"
+
+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 MATRIKKELEN_ADAPTER_ID = "matrikkelen"
+
+/**
+ * The municipality number Kartverket gives Svalbard.
+ *
+ * Every other number in the dataset belongs to a mainland municipality.
+ * Jan Mayen has no entry, although ISO 3166-1 assigns `SJ` to it as well as to Svalbard.
+ */
+const SVALBARD_MUNICIPALITY = "2100"
+
+/**
+ * Every jurisdiction this adapter emits, checked against a caller's `--country`.
+ */
+export const MATRIKKELEN_COUNTRIES: readonly string[] = ["NO", "SJ"]
+
+/**
+ * The subset of the 46 columns the adapter consults.
+ *
+ * The explicit shape catches a column rename early.
+ * The first column's name carries a byte-order mark in the published file, and the
+ * adapter reads `adresseId` instead, so no field here depends on that spelling.
+ */
+interface MatrikkelenRow {
+	kommunenummer: string
+	adressetype: string
+	adressenavn: string
+	nummer: string
+	bokstav: string
+	adresseTekst: string
+	postnummer: string
+	poststed: string
+	adresseId: string
+}
+
+/**
+ * The country a row belongs to, read from its municipality number.
+ */
+export function countryOfMunicipality(kommunenummer: string): string {
+	return kommunenummer.trim() === SVALBARD_MUNICIPALITY ? "SJ" : "NO"
+}
+
+export function createMatrikkelenAdapter(): CorpusAdapter {
+	return {
+		id: MATRIKKELEN_ADAPTER_ID,
+		defaultLicense: "CC-BY-4.0",
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.MatrikkelenAdresse,
+		surface: SurfaceOrigin.Rendered,
+		description: "Matrikkelen - Adresse (Kartverket): street-level addresses for Norway and Svalbard.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && !MATRIKKELEN_COUNTRIES.includes(opts.country)) {
+				throw new UnsupportedCountryError(MATRIKKELEN_ADAPTER_ID, MATRIKKELEN_COUNTRIES, opts.country)
+			}
+
+			const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+				normalizeKeys: false,
+				columnDelimiter: ";",
+			})
+
+			let emitted = 0
+			let cadastral = 0
+
+			try {
+				for await (const record of rows as AsyncIterable<MatrikkelenRow>) {
+					if (opts.signal?.aborted) break
+
+					if (opts.limit !== undefined && emitted >= opts.limit) break
+
+					const country = countryOfMunicipality(record.kommunenummer ?? "")
+
+					if (opts.country && country !== opts.country) continue
+
+					// A `matrikkeladresse` addresses a cadastral unit rather than a street, so its
+					// `adresseTekst` reads as a farm name and a holding number, such as `Øvrabø, 124/1`.
+					// It carries no street to align, and the mainland file holds 34,522 of
+					// them against 2,568,832 `vegadresse` rows.
+					if ((record.adressetype ?? "").trim() !== "vegadresse") {
+						cadastral += 1
+
+						continue
+					}
+
+					const street = (record.adressenavn ?? "").trim()
+					// Kartverket splits `12B` into `nummer` 12 and `bokstav` B, and writes
+					// them joined with no separator in `adresseTekst`.
+					const house = composeHouseNumber(record.nummer ?? "", record.bokstav ?? "")
+					const postcode = (record.postnummer ?? "").trim()
+					const locality = (record.poststed ?? "").trim()
+
+					if (!street) continue
+
+					if (!postcode && !locality) continue
+
+					const components: CanonicalRow["components"] = {}
+
+					if (house) {
+						components.house_number = house
+					}
+
+					components.street = street
+
+					if (postcode) {
+						components.postcode = postcode
+					}
+
+					if (locality) {
+						components.locality = locality
+					}
+
+					const rendered = formatAddressRow(components, country, { singleLine: true })
+
+					if (!rendered) continue
+
+					const { raw, components: aligned } = rendered
+					const seed = (record.adresseId ?? "").trim()
+
+					const sourceID = seed ? `${MATRIKKELEN_ADAPTER_ID}-${seed}` : stableSourceID(MATRIKKELEN_ADAPTER_ID, aligned)
+
+					yield {
+						raw,
+						components: aligned,
+						country,
+						// Norwegian is the language of both jurisdictions' addresses,
+						// and Bokmål is the written form Kartverket publishes.
+						locale: `nb-${country}`,
+						source: MATRIKKELEN_ADAPTER_ID,
+						source_id: sourceID,
+						corpus_version: "",
+						license: "CC-BY-4.0",
+					}
+
+					emitted++
+				}
+			} finally {
+				if (cadastral > 0) {
+					process.stderr.write(
+						`  matrikkelen: ${cadastral} matrikkeladresse rows carry no street and were dropped, ${emitted} kept\n`
+					)
+				}
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const matrikkelenAdapter = createMatrikkelenAdapter()

package/lib/no/recipes/fragment.ts

@@ -2,47 +2,28 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `no-fragment` — the Norwegian house-number-licence change (Track B, 2026-07-16). The mirror of
- *   `fr-fragment`, which earned +50pp on the same defect shape in French.
- *
- *   WHY THIS EXISTS AND `no-street-led` DOES NOT SUFFICE. Board 3 (the NO digit board) measured that
- *   `synth-no-street-led`'s three forms — all carrying postcode+city — are ALREADY at 0.940-0.968 on
- *   a model with zero Norwegian rows. The headroom is in the forms that slice never emits:
- *
- *     bare-street-hn   "Hallingrudveien 32"     0.693   — no postcode competing, still fails 31%
- *     slash-hn         "Øvrabø 124/1"           0.650   — cadastral gnr/bnr, ONE component
- *
- *   THE MECHANISM the board exposed: `Hallingrudveien 32` -> locality + postcode, while
- *   `Hallingrudveien 32, 3370 Vikersund` parses perfectly. The street loses its street reading and
- *   the digit loses its anchor TOGETHER. That is Track A's bare-street LICENCE in Norwegian — the
- *   model will not read a street without its postcode/locality partner — not a digit-ownership prior.
- *   fr-fragment fixed exactly this in French by teaching the street WITHOUT its partners.
- *
- *   THE COUNTER-DISTRIBUTION IS THE POINT (fr-fragment's lesson, and board 2's bare-locality guard).
- *   Teaching bare `{street} {number}` alone lets the model satisfy every row by flipping its default
- *   from "bare toponym -> locality" to "bare toponym -> street", trading one broken prior for
- *   another. Two counter-classes hold the line:
- *     - bare LOCALITIES (no street) so "bare -> street" is not free.
- *     - bare POSTCODES so the model does not learn to stop emitting postcode to win the digit — the
- *       board 3 bare-pc negative class (1.000) must HOLD.
- *
- *   SLASH HAZARD, pinned deliberately: NO `124/1` is ONE house_number (cadastral gnr/bnr). AU
- *   `12/345` is TWO (unit + house_number). This slice teaches the Norwegian reading; a future AU
- *   intra-word-split slice (B5) must not generalize over it. The two are locale-restricted by design.
- *
- *   SPLIT: `--exclude-surfaces` REQUIRED (throws otherwise) — the digit board's reserved surface
- *   list. Diacritic-KEEPING normalizer, matching the board (see the norm docstring).
  */
 
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 import { TextSpliterator } from "spliterator"
 
-import { alignAndWrite, foldNOSurface, readTuples, type CorpusRecipe, sliceSourceID } from "#recipes/scaffold"
+import {
+	alignAndWrite,
+	foldNOSurface,
+	readTuples,
+	requireRegister,
+	type CorpusRecipe,
+	recipeSourceID,
+} from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { SurfaceOrigin } from "#types"
 
 /**
- * Title-case a Kartverket ALL-CAPS locality (HELLVIK -> Hellvik); #690, all-caps is OOD.
+ * Resolved once, because `source_id` includes the source as its prefix and a pair
+ * that disagreed would name a source no row of this output declares.
  */
+const NO_FRAGMENT_SOURCE = defaultRecipeSource("synth-no-fragment")
+
 const titleNO = (value: string): string =>
 	value
 		.split(/\s+/)
@@ -50,13 +31,12 @@ const titleNO = (value: string): string =>
 		.join(" ")
 
 /**
- * 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.
+ * Norwegian fragment recipe.
  */
 export const noFragmentRecipe: CorpusRecipe = {
 	name: "no-fragment",
 	description:
-		"NO street fragments — the house-number-licence change (Track B): '«st» «n»' / bare «st» with NO postcode partner, + bare-locality & bare-postcode counters",
+		"NO street fragments — the house-number-license change (Track B): '«st» «n»' / bare «st» with NO postcode partner, + bare-locality & bare-postcode counters",
 	mode: "tuples",
 	options: [
 		{
@@ -66,7 +46,8 @@ export const noFragmentRecipe: CorpusRecipe = {
 		},
 		{
 			flag: "--bare-street-prob <n>",
-			description: "Share of street rows emitted as a BARE street, no number (default 0.30 — the pure licence signal)",
+			description:
+				"Share of street rows emitted as a bare street without a house number, the pure license signal (default 0.30)",
 		},
 		{
 			flag: "--counter-prob <n>",
@@ -89,7 +70,7 @@ export const noFragmentRecipe: CorpusRecipe = {
 		if (!excludePath) {
 			throw new Error(
 				"no-fragment: --exclude-surfaces is REQUIRED. Pass the NO digit board's reserved list " +
-					"(mailwoman/eval-harness/fixtures/no-digits.surfaces.txt) or this slice trains on its own eval set. " +
+					"(mailwoman/eval-harness/fixtures/no-digits.surfaces.txt) or this recipe trains on its own eval set. " +
 					"Source-disjoint by street SURFACE is the split discipline; there is no safe default."
 			)
 		}
@@ -97,10 +78,8 @@ export const noFragmentRecipe: CorpusRecipe = {
 		const excluded = new Set<string>()
 
 		for await (const line of TextSpliterator.fromAsync(excludePath)) {
-			const trimmed = line.trim()
-
-			if (trimmed && !trimmed.startsWith("#")) {
-				excluded.add(trimmed)
+			if (!line.startsWith("#")) {
+				excluded.add(line)
 			}
 		}
 
@@ -111,8 +90,6 @@ export const noFragmentRecipe: CorpusRecipe = {
 		const longNumberBoost = Math.max(1, Math.floor(opts.longNumberBoost ?? 1))
 		const longNumberMinDigits = opts.longNumberMinDigits ?? 3
 
-		// Harvested from the tuples — every NO row carries its locality and postcode, so the two
-		// counter-classes need no second source.
 		const localities = new Set<string>()
 		const postcodes = new Set<string>()
 
@@ -123,28 +100,35 @@ export const noFragmentRecipe: CorpusRecipe = {
 		let emitSeq = 0
 
 		const emit = (raw: string, components: Record<string, string>, klass: string): void => {
-			// emitSeq keeps every emit distinct — knob 3 emits N copies of one long-number row, and
-			// (components, read) alone would collide their source_id and let downstream dedup drop the boost.
-			const source_id = sliceSourceID("synth-no-fragment", { ...components, k: klass, v: `${read}:${emitSeq++}` })
+			const source_id = recipeSourceID(NO_FRAGMENT_SOURCE, { ...components, k: klass, v: `${read}:${emitSeq++}` })
 
 			const canonical = {
 				raw,
 				components,
 				country: "NO",
 				locale: "nb-NO",
-				source: "synth-no-fragment",
+				source: NO_FRAGMENT_SOURCE,
 				source_id,
 				corpus_version: "0.11.0",
 				license: "Synthetic — no-fragment; (street, number, postcode, city) from OpenAddresses NO / Kartverket",
 			}
 
-			if (alignAndWrite(write, canonical, "no-fragment")) {
+			if (alignAndWrite(write, canonical, "no-fragment", NO_FRAGMENT_PROVENANCE)) {
 				emitted++
 			} else {
 				skipped++
 			}
 		}
 
+		const NO_FRAGMENT_PROVENANCE = {
+			register: requireRegister(opts, "no-fragment"),
+			surface: SurfaceOrigin.Composed,
+			// `emit` is a closure over the run rather than over one tuple, so this cannot name a per-row record.
+			// The tuples file has no `sourceID` either.
+			// Both inputs are required to populate this field (#2359).
+			baseSourceID: null,
+		}
+
 		for await (const tuple of readTuples(opts.input!)) {
 			read++
 			const street = String(tuple.street ?? "").trim()
@@ -166,16 +150,12 @@ export const noFragmentRecipe: CorpusRecipe = {
 				continue
 			}
 
-			// THE SPLIT. A surface on the digit board never enters training.
 			if (excluded.has(foldNOSurface(street))) {
 				contaminated++
 
 				continue
 			}
 
-			// COUNTER-DISTRIBUTION — drawn from the harvested pools, not this row's street. Half bare
-			// localities (so "bare -> street" is not free), half bare postcodes (so the model does not
-			// stop emitting postcode to win the digit — board 3's bare-pc must hold).
 			if (random() < counterProb) {
 				if (random() < 0.5 && localities.size) {
 					const loc = [...localities][Math.floor(random() * localities.size)]!
@@ -190,15 +170,11 @@ export const noFragmentRecipe: CorpusRecipe = {
 				continue
 			}
 
-			// THE SIGNAL. A street with NO postcode/locality partner. Either bare, or street+number —
-			// both are the forms board 3 measured as the headroom (bare-street-hn 0.693, slash-hn 0.650).
 			if (!number || random() < bareStreetProb) {
 				emit(street, { street }, "bare-street")
 			} else {
 				const klass = number.includes("/") ? "slash-hn" : "street-hn"
-				// knob 3: the failing class is street + LONG number (Leppdalsvegen 1285 -> postcode). The
-				// digit count, not the slash, is what tips the length prior toward postcode. Oversample
-				// those rows to fight the prior with volume and teach the street/number boundary directly.
+
 				const digits = (number.match(/\d/g) ?? []).length
 				const copies = digits >= longNumberMinDigits ? longNumberBoost : 1