@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/runner.ts

@@ -3,106 +3,143 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Adapter runner — drives a `CorpusAdapter` to completion and writes intermediate JSONL + a
- *   per-slice manifest.
- *
- *   Output layout under `outputDir`:
- *
- *   ```
- *   <outputDir>/<adapter.id>/
- *   canonical.jsonl       # one row per line, in emission order
- *   MANIFEST.json         # adapter id, version, row count, sha256, license, started_at, ended_at
- * ```
- *
- *   The runner is responsible for everything an adapter is **not** responsible for:
- *
- *   - Stamping `corpus_version` on every row (adapters must NOT set it).
- *   - Applying `canonicalDedupKey` and skipping duplicates.
- *   - Streaming sha256 over JSONL bytes so the manifest checksum doesn't require a re-read.
- *   - Honoring backpressure on the output write stream.
- *   - Counting + emitting periodic progress to an optional callback.
- *   - Honoring `signal` (delegates to adapter's iteration boundary).
- *
- *   The runner does NOT perform alignment, tokenization, synthesis, or slicing into Parquet. Those
- *   steps run later, consuming the JSONL slices this writes.
+ *   Adapter runner — drives a `CorpusAdapter` to completion and writes `canonical.jsonl` plus a
+ *   `MANIFEST.json` per adapter. It does not align, tokenize, synthesize, or write Parquet.
  */
 
+import { isAlpha2CodeShape } from "@mailwoman/codex/country"
 import { openWriteStream, type WriteStream } from "@mailwoman/core/fs/streams"
 import { writeLocalJSONFile, makeDirectories } from "@mailwoman/core/fs/writers"
-import { join, type PathBuilderLike } from "path-ts"
+import { stringifyJSON } from "@mailwoman/core/json"
+import { type PathBuilderLike, resolvePathBuilder } from "path-ts"
 
-import { canonicalDedupKey, streamingSha256, type AdapterRegistry, type StreamingHasher } from "#adapters/utils"
+import { canonicalDedupKey } from "#adapters/dedup-key"
+import type { AdapterRegistry } from "#adapters/registry"
+import { streamingSha256, type StreamingHasher } from "#adapters/sha256-stream"
+import { FingerprintSet } from "#fingerprints"
 import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
 
 /**
  * Snapshot of the runner's state, emitted on every progress tick.
  */
 export interface RunnerProgress {
-	/**
-	 * Adapter being driven.
-	 */
 	adapterID: string
 
 	/**
-	 * Total rows the adapter has yielded (before dedup).
+	 * Total rows the adapter has yielded, before dedup.
 	 */
 	yielded: number
 
-	/**
-	 * Rows actually written to JSONL (after dedup).
-	 */
 	written: number
 
-	/**
-	 * Bytes written to JSONL so far.
-	 */
 	bytes: number
 
-	/**
-	 * Wall-clock milliseconds since the run started.
-	 */
 	elapsed_ms: number
 }
 
 /**
- * Per-invocation options for `runAdapter`.
+ * Base-2 logarithm of the fingerprint table's slot count.
+ *
+ * 2^27 slots hold 93,952,409 keys before the load limit.
+ * The largest measured adapter has 57,570,829 distinct keys.
+ * The table occupies 2.0 GiB outside the V8 heap.
  */
-export interface RunAdapterOptions {
+export const DEFAULT_DEDUP_SLOTS_LOG2 = 27
+
+/**
+ * How many distinct dedup keys a `Set`-backed run holds before it stops adding new ones.
+ *
+ * A V8 `Set` refuses a 16,777,216th entry outright, so this cap was a real bound rather than a preference.
+ * It applies only to a run that opts out of the fingerprint table
+ * through {@linkcode RunAdapterOptions.dedupMaxSize}.
+ */
+export const DEFAULT_DEDUP_MAX_SIZE = 10_000_000
+
+/**
+ * Where a run held its dedup keys.
+ */
+export const DedupStore = {
 	/**
-	 * Adapter to drive.
+	 * 128-bit fingerprints in a flat `Uint32Array`, bounded by the array the run sized.
 	 */
-	adapter: CorpusAdapter
+	FingerprintTable: "fingerprint-table",
 
 	/**
-	 * Options handed to the adapter (input path, country filter, limit, signal).
+	 * A V8 `Set` of key strings, capped because V8 refuses a 16,777,216th entry.
 	 */
+	CappedSet: "capped-set",
+} as const
+
+export type DedupStore = (typeof DedupStore)[keyof typeof DedupStore]
+
+export interface RunAdapterOptions {
+	adapter: CorpusAdapter
+
 	adapterOptions: AdapterOptions
 
 	/**
-	 * Root output directory; the runner creates `<outputDir>/<adapter.id>/` under it.
+	 * Hold dedup keys in a V8 `Set` capped at this many, rather than in a fingerprint table.
+	 *
+	 * The cap is what the fingerprint table replaces.
+	 * A run that sets this reproduces the pre-2026-09-28 behavior.
+	 *
+	 * Past the cap, the runner still drops a duplicate of a key it holds
+	 * and writes a duplicate of a key first seen after the cap.
+	 *
+	 * Over `v0.7.0-de-holdout` that wrote 1,490,992 duplicate rows across three adapters.
+	 * A test sets it low to reach exhaustion in a few rows.
+	 *
+	 * After reaching the cap, the runner still drops duplicates for keys already in the set.
+	 * It writes duplicates for keys first seen after the cap.
+	 */
+	dedupMaxSize?: number
+
+	/**
+	 * Base-2 logarithm of the fingerprint table's slot count.
+	 *
+	 * @defaultValue {@linkcode DEFAULT_DEDUP_SLOTS_LOG2}
+	 * A test sets it low to keep the allocation small.
+	 */
+	dedupSlotsLog2?: number
+
+	/**
+	 * Root output directory.
+	 * The runner creates `<outputDir>/<adapter.id>/` under it.
 	 */
 	outputDir: PathBuilderLike
 
 	/**
-	 * Corpus version stamped onto every row. Locked together with the tokenizer version.
+	 * Corpus version stamped onto every row, locked together with the tokenizer version.
 	 */
 	corpusVersion: string
 
 	/**
-	 * Optional progress callback. Invoked every `progressEvery` rows yielded (default 1000) and once at the end of the
-	 * run. Errors thrown from this callback abort the run.
+	 * The `source` id stamped on every emitted row, when it differs from the adapter's own id.
+	 *
+	 * A source id is a wire identifier keyed by `source_weights`, so re-using a name a built
+	 * corpus already contains makes this run's rows indistinguishable from that corpus's.
+	 * When absent, rows use `adapter.id`.
+	 */
+	sourceName?: string
+
+	/**
+	 * Invoked every `progressEvery` rows yielded and once at the end.
+	 * A thrown error aborts the run.
 	 */
 	onProgress?: (snapshot: RunnerProgress) => void
 
 	/**
-	 * Yielded-row interval at which `onProgress` fires. Defaults to 1000. The terminal tick is always emitted regardless
-	 * of this value.
+	 * Yielded-row interval at which `onProgress` fires.
+	 *
+	 * The runner always emits a terminal update.
+	 *
+	 * @defaultValue `1000` rows per callback.
 	 */
 	progressEvery?: number
 }
 
 /**
- * Return value of `runAdapter`: the same shape as `MANIFEST.json` on disk.
+ * Return value of `runAdapter`, the same shape as the manifest written to disk.
  */
 export interface AdapterRunManifest {
 	adapter_id: string
@@ -112,6 +149,38 @@ export interface AdapterRunManifest {
 	yielded: number
 	written: number
 	deduped: number
+	/**
+	 * Input records the adapter refused or trimmed before yielding, keyed by reason.
+	 *
+	 * See {@link AdapterOptions.dropped} for the key shapes.
+	 * An empty object means the adapter does not count its drops, so the number it dropped is unmeasured.
+	 */
+	dropped: Record<string, number>
+	/**
+	 * The `yielded` count at which the dedup set stopped growing, or `null` where it never did.
+	 *
+	 * A run reporting a number here deduplicated its rows completely up to that point.
+	 * After that point, it still drops duplicates for keys already held.
+	 *
+	 * It writes duplicates for keys first seen after the cap.
+	 * `deduped` by itself cannot identify which, so a consumer comparing two builds'
+	 * duplicate counts needs this beside it.
+	 */
+	dedup_exhausted_at_yielded: number | null
+	/**
+	 * How the run held its dedup keys: `fingerprint-table` or `capped-set`.
+	 *
+	 * The two reach different row counts on the same input, so a consumer comparing
+	 * two builds needs to know which each used.
+	 * `capped-set` writes a duplicate of any key first seen after its cap.
+	 */
+	dedup_store: DedupStore
+	/**
+	 * Distinct dedup keys the run held at the end.
+	 *
+	 * Under `fingerprint-table` this is a fingerprint count, so two keys sharing all 128 bits count once.
+	 */
+	dedup_keys: number
 	bytes: number
 	sha256: string
 	jsonl_path: string
@@ -121,30 +190,38 @@ export interface AdapterRunManifest {
 }
 
 /**
- * Drive a single adapter to completion.
- *
- * Returns the manifest describing the run. Writes `canonical.jsonl` + `MANIFEST.json` under `outputDir/<adapter.id>/`.
- * Throws if the output directory cannot be created, if a row arrives with a missing required field, or if the abort
- * signal fires.
+ * Drive a single adapter to completion, writing its jsonl and manifest under `outputDir/<adapter.id>/`.
  */
 export async function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunManifest> {
-	const { adapter, adapterOptions, outputDir, corpusVersion } = opts
+	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 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
 
-	const adapterDir = join(outputDir, adapter.id)
+	const adapterDir = resolvePathBuilder(outputDir, adapter.id)
 	await makeDirectories(adapterDir)
 
-	const jsonlPath = join(adapterDir, "canonical.jsonl")
-	const manifestPath = join(adapterDir, "MANIFEST.json")
+	const jsonlPath = adapterDir("canonical.jsonl")
+	const manifestPath = adapterDir("MANIFEST.json")
 
 	const startedAt = new Date()
 	const t0 = performance.now()
 
 	const stream = openWriteStream(jsonlPath, { encoding: "utf8" })
 	const hasher: StreamingHasher = streamingSha256()
-	const seen = new Set<string>()
-	const DEDUP_MAX_SIZE = 10_000_000
+
+	// The `Set` path serves callers that cannot accept a fingerprint collision dropping a legitimate row.
+	// A test also uses it to reach the capped behavior in three rows.
+	// Every other run takes the table.
+	// Its entry count is bounded by the array it sized rather than by V8's `Set` limit.
+	const capped = opts.dedupMaxSize !== undefined
+	const seen = capped ? new Set<string>() : null
+	const fingerprints = capped ? null : new FingerprintSet(opts.dedupSlotsLog2 ?? DEFAULT_DEDUP_SLOTS_LOG2)
+	const dedupMaxSize = opts.dedupMaxSize ?? DEFAULT_DEDUP_MAX_SIZE
 	let dedupExhausted = false
+	let dedupExhaustedAtYielded: number | null = null
 
 	let yielded = 0
 	let written = 0
@@ -169,30 +246,61 @@ export async function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunMan
 			yielded++
 			assertEmittedRow(adapter, row)
 
-			const stamped: CanonicalRow = { ...row, corpus_version: corpusVersion }
+			const stamped: CanonicalRow = {
+				...row,
+				// The rename is the runner's, after `assertEmittedRow` has held the adapter to emitting its own id.
+				source: opts.sourceName ?? row.source,
+				corpus_version: corpusVersion,
+				addressRole: row.addressRole ?? adapter.addressRole,
+				// `register` is nullable and null is a statement rather than an absence,
+				// so only an undefined field takes the adapter's declaration.
+				register: row.register === undefined ? adapter.register : row.register,
+				surface: row.surface ?? adapter.surface,
+			}
+
 			const key = canonicalDedupKey(stamped)
 
-			if (!dedupExhausted) {
-				if (seen.has(key)) {
+			if (fingerprints) {
+				// The table holds every key the run has seen, so a duplicate is refused wherever it arrives.
+				if (!fingerprints.add(key)) {
 					if (yielded % progressEvery === 0) {
 						emitProgress()
 					}
 
 					continue
 				}
+			} else if (seen) {
+				// The membership test runs whether or not the set is full.
+				// The cap stops the set from growing.
+				// The set still rejects every duplicate of a key it holds.
+				// Without the membership test at the cap, duplicates of the first
+				// `dedupMaxSize` keys passed through.
+				// This ordering keeps those duplicates out.
+				if (seen.has(key)) {
+					if (yielded % progressEvery === 0) {
+						emitProgress()
+					}
 
-				if (seen.size >= DEDUP_MAX_SIZE) {
-					dedupExhausted = true
+					continue
+				}
 
-					process.stderr.write(
-						`  runner: dedup set full at ${DEDUP_MAX_SIZE.toLocaleString()} — skipping dedup for remaining rows\n`
-					)
-				} else {
-					seen.add(key)
+				if (!dedupExhausted) {
+					if (seen.size >= dedupMaxSize) {
+						dedupExhausted = true
+						dedupExhaustedAtYielded = yielded
+
+						process.stderr.write(
+							`  runner: dedup set full at ${dedupMaxSize.toLocaleString()} keys after ${yielded.toLocaleString()} ` +
+								`yielded rows — a later row duplicating a key already held is still dropped, and a duplicate of ` +
+								`a key first seen from here on is written\n`
+						)
+					} else {
+						seen.add(key)
+					}
 				}
 			}
 
-			const line = `${JSON.stringify(stamped)}\n`
+			const line = `${stringifyJSON(stamped)}\n`
 			hasher.update(line)
 			bytes += Buffer.byteLength(line, "utf8")
 
@@ -211,6 +319,10 @@ export async function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunMan
 		await once(stream, "close")
 	}
 
+	// Every adapter honors `signal` by returning instead, so without this a truncated
+	// `canonical.jsonl` would be recorded as a finished run.
+	adapterOptions.signal?.throwIfAborted()
+
 	const endedAt = new Date()
 	const elapsed_ms = performance.now() - t0
 	emitProgress()
@@ -223,9 +335,13 @@ export async function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunMan
 		yielded,
 		written,
 		deduped: yielded - written,
+		dropped: Object.fromEntries([...dropped].toSorted(([a], [b]) => a.localeCompare(b))),
+		dedup_exhausted_at_yielded: dedupExhaustedAtYielded,
+		dedup_store: fingerprints ? DedupStore.FingerprintTable : DedupStore.CappedSet,
+		dedup_keys: fingerprints?.size ?? seen?.size ?? 0,
 		bytes,
 		sha256: hasher.digest(),
-		jsonl_path: jsonlPath,
+		jsonl_path: jsonlPath.toString(),
 		started_at: startedAt.toISOString(),
 		ended_at: endedAt.toISOString(),
 		elapsed_ms,
@@ -237,10 +353,7 @@ export async function runAdapter(opts: RunAdapterOptions): Promise<AdapterRunMan
 }
 
 /**
- * Drive every adapter in a registry sequentially. Stops on the first failure (caller can filter the registry before
- * calling if partial-failure is desired).
- *
- * Returns the manifests in registry insertion order.
+ * Drive every adapter in a registry sequentially, stopping on the first failure.
  */
 export async function runAllAdapters(
 	registry: AdapterRegistry,
@@ -263,13 +376,9 @@ export async function runAllAdapters(
 	return out
 }
 
-/**
- * Validate an emitted row. Cheap; runs once per row. Catches adapter bugs early so the JSONL doesn't end up
- * half-malformed.
- */
 function assertEmittedRow(adapter: CorpusAdapter, row: CanonicalRow): void {
 	if (row.source !== adapter.id) {
-		throw new Error(`adapter ${adapter.id}: row.source must equal adapter.id (got ${JSON.stringify(row.source)})`)
+		throw new Error(`adapter ${adapter.id}: row.source must equal adapter.id (got ${stringifyJSON(row.source)})`)
 	}
 
 	if (!row.source_id) {
@@ -284,15 +393,43 @@ function assertEmittedRow(adapter: CorpusAdapter, row: CanonicalRow): void {
 		throw new Error(`adapter ${adapter.id}: row.country is empty for source_id=${row.source_id}`)
 	}
 
+	// `country_weights` and every country filter use this value.
+	// Validate its ISO 3166-1 alpha-2 shape.
+	// `ZZ` and `XK` are legitimate codes even though ISO membership does not list them.
+	if (!isAlpha2CodeShape(row.country)) {
+		throw new Error(
+			`adapter ${adapter.id}: row.country ${stringifyJSON(row.country)} is not two upper-case letters ` +
+				`for source_id=${row.source_id}. ISO 3166-1 alpha-2 is the shape country_weights and every ` +
+				`country filter key on, so a code outside it trains on nothing and matches no filter.`
+		)
+	}
+
 	if (!row.license) {
 		throw new Error(`adapter ${adapter.id}: row.license is empty for source_id=${row.source_id}`)
 	}
 }
 
 /**
- * Promise-ify a single event emission. Used to await `drain` / `close` on the write stream. Exported for `build.ts`,
- * whose stage streams await `close` the same way; unlike a bare two-listener race, the loser listener is detached so a
- * long-lived stream does not accumulate one orphan handler per wait.
+ * Resolve once everything written to `stream` so far has reached the file.
+ *
+ * A zero-length write acts as a barrier.
+ * Its callback runs after earlier queued writes.
+ *
+ * A caller can then record a byte offset for the bytes in the file.
+ * `drain` fires only when the buffer was full.
+ *
+ * `bytesWritten` excludes queued data.
+ * Neither value answers when all earlier writes have reached the file.
+ */
+export function flushStream(stream: WriteStream): Promise<void> {
+	return new Promise((resolve, reject) => {
+		stream.write("", (error) => (error ? reject(error) : resolve()))
+	})
+}
+
+/**
+ * Promise-ify a single `drain` or `close` emission, detaching the loser listener
+ * so a long-lived stream does not accumulate an orphan handler per wait.
  */
 export function once(emitter: WriteStream, event: "drain" | "close"): Promise<void> {
 	return new Promise((resolve, reject) => {

package/lib/sg/recipes/register.ts

@@ -3,35 +3,22 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `sg-register` slice recipe — the forms a person in Singapore types, rendered over the Overture-SG register rows
- *   (#2204 §4). The base `overture` source carries the register's own shape, `990 OLD CHOA CHU KANG ROAD, 699814,
- *   Singapore`, and the Latin model has no register for the three forms that dominate typed Singapore addresses:
- *
- *   - the HDB block line, `Blk 123 Ang Mo Kio Ave 3 #05-67 Singapore 560123` — `Blk` in front of the block number (the
- *     register's `number`), a floor-unit `#NN-NN` after the street, the country name as the locality;
- *   - the bracketed postcode, `123 Ang Mo Kio Ave 3 S(560123)` — the form the postal service prints;
- *   - the building-led line, `National Shooting Centre, 990 Old Choa Chu Kang Road, Singapore 699814` — the register's
- *     `unit` field holds the BUILDING or ESTATE name on 91,818 of 142,210 rows, which the adapter refuses as a unit and
- *     this recipe renders as a `venue` when it reads as a building rather than an estate.
- *
- *   Every value in `components` is a verbatim substring of `raw`, aligned by {@link alignAndWrite}. The floor-unit is
- *   SYNTHESIZED (the register carries one on a single row): floor 01–30, unit 01–399, zero-padded — the shape, not a
- *   real occupancy. `Blk` and the `S(` `)` around a postcode are untagged, as the board's `sg-cs-blk-12-kallang-ave`
- *   row expects (`house_number: "12"`). Streets arrive upper-case and are rendered title-cased; a third abbreviate the
- *   generic (`Avenue` → `Ave`, `Road` → `Rd`, …) the way a typed line does.
- *
- *   Run: mailwoman corpus slice sg-register --input <overture-sg.corpus.jsonl> --count N --seed S
+ *   Renders Overture Singapore address rows in the forms that people type, such as HDB block lines and `S(560123)` postcodes.
  */
 
+import { stringifyJSON } from "@mailwoman/core/json"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
+import { titleCaseIfUpper } from "spliterator"
 
-import { titlecase } from "#au/adapters/gnaf/assemble"
-import { alignAndWrite, type CorpusRecipe, readTuples, sliceSourceID } from "#recipes/scaffold"
+import { alignAndWrite, type CorpusRecipe, readTuples, recipeSourceID } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { SourceRegister } from "#registers"
+import { SurfaceOrigin } from "#types"
 
-const SOURCE = "synth-sg-register"
+const SOURCE = defaultRecipeSource("synth-sg-register")
 
 /**
- * The register's generics and the abbreviation a typed line uses for each.
+ * Street generics and their typed abbreviations.
  */
 const GENERIC_ABBREVIATIONS: ReadonlyArray<readonly [full: string, short: string]> = [
 	["Avenue", "Ave"],
@@ -48,27 +35,26 @@ const GENERIC_ABBREVIATIONS: ReadonlyArray<readonly [full: string, short: string
 ]
 
 /**
- * Estate and area names the register's `unit` field carries beside building names. A name ending in one of these is an
- * estate, which no one writes in front of an address line; a name without one reads as a building and is rendered as a
- * `venue`.
+ * Name endings that mark an estate or area in the source `unit` field.
+ *
+ * People do not write an estate name before an address line, so the recipe
+ * renders only building names as a `venue`.
  */
 const ESTATE_TAILS = ["ESTATE", "CONSERVATION AREA", "HILLS", "PARK", "GARDENS", "GARDEN", "HEIGHTS", "GROVE", "VILLE"]
 
-/**
- * Share of rows per register. The block line and the bracketed postcode are the two the Latin model has never seen; the
- * official line keeps the register's own shape in the mix so the block forms train beside it.
- */
+// The official form receives the probability left after the block, bracketed-postcode and building-led forms.
 const P_BLOCK = 0.4
 const P_BRACKET_POSTCODE = 0.25
 const P_BUILDING_LED = 0.15
 const P_ABBREVIATE = 0.35
 const P_UPPER = 0.1
 
+// The source rarely includes a floor-unit, so the recipe synthesizes one within these bounds.
 const FLOOR_MAX = 30
 const UNIT_MAX = 399
 
 /**
- * The draw value that lands each register in the branch order below, for a caller that names the form.
+ * The draw value that selects each form in {@link renderSGRegister} when a caller requests that form.
  */
 const REGISTER_DRAW: Record<SGRegister, number> = {
 	block: 0,
@@ -78,15 +64,8 @@ const REGISTER_DRAW: Record<SGRegister, number> = {
 }
 
 /**
- * `OLD CHOA CHU KANG ROAD` → `Old Choa Chu Kang Road`; an already-mixed value is returned as it is. The register writes
- * every street and building name upper-case, the same convention as G-NAF, so the G-NAF title-caser serves both.
- */
-export function titleCaseSGName(name: string): string {
-	return name === name.toUpperCase() ? titlecase(name) : name
-}
-
-/**
- * Abbreviate the street's generic, wherever it sits (`Ang Mo Kio Avenue 3` → `Ang Mo Kio Ave 3`).
+ * Abbreviates the first street generic that the street contains, such as
+ * `Ang Mo Kio Avenue 3` to `Ang Mo Kio Ave 3`.
  */
 export function abbreviateSGStreet(street: string): string {
 	for (const [full, short] of GENERIC_ABBREVIATIONS) {
@@ -99,8 +78,9 @@ export function abbreviateSGStreet(street: string): string {
 }
 
 /**
- * Whether the register's `unit` value names a building rather than an estate — the building-led register's lead. A name
- * carrying a digit, a parenthesized abbreviation (`DIABETES & METABOLISM CENTRE (DMC)`) or one word only is not one.
+ * Reports whether the source `unit` value looks like a building name that can lead a line.
+ *
+ * The check rejects `NIL`, single words, values with a digit or parenthesis, plus estate names.
  */
 export function isBuildingName(unit: string): boolean {
 	const value = unit.trim().toUpperCase()
@@ -118,12 +98,12 @@ interface SGRow {
 }
 
 /**
- * The four typed forms this recipe renders.
+ * The four typed forms that this recipe renders.
  */
 export type SGRegister = "official" | "block" | "bracket_postcode" | "building_led"
 
 /**
- * One rendered register: the raw line plus the components it carries, every value a substring of the line.
+ * One rendered line with its components, each of which is a substring of `raw`.
  */
 export interface SGRegisterRendering {
 	raw: string
@@ -132,16 +112,20 @@ export interface SGRegisterRendering {
 }
 
 /**
- * Render one register form for one register row. Pure: every random draw comes through `random`. A `register` names the
- * form to render instead of drawing one, for a board that wants a balanced spread; `building_led` still needs a
- * building-shaped `unit` and falls back to `official` without one.
+ * Renders one source row in a sampled or requested form.
+ *
+ * All randomness comes from `random`.
+ * A requested `building_led` form falls back to `official` when the row's `unit` is not a building name.
+ *
+ * A requested `block` form falls back to `bracket_postcode` when the row's number is not a block number.
+ * `Blk` and the `S(` and `)` around a postcode stay untagged.
  */
 export function renderSGRegister(row: SGRow, random: () => number, register?: SGRegister): SGRegisterRendering {
-	const street0 = titleCaseSGName(row.street)
+	const street0 = titleCaseIfUpper(row.street)
 	const street = random() < P_ABBREVIATE ? abbreviateSGStreet(street0) : street0
 	const drawn = random()
-	const building = isBuildingName(row.unit) ? titleCaseSGName(row.unit) : null
-	const draw = register === undefined ? drawn : REGISTER_DRAW[register]
+	const building = isBuildingName(row.unit) ? titleCaseIfUpper(row.unit) : null
+	const draw = register ? REGISTER_DRAW[register] : drawn
 
 	let raw: string
 	let rendered: SGRegister
@@ -182,7 +166,9 @@ export function renderSGRegister(row: SGRow, random: () => number, register?: SG
 }
 
 /**
- * Slice recipe registered with the corpus builder — see the file header for the registers and why each is here.
+ * Renders each Overture Singapore corpus row from `--input` once in a sampled typed form.
+ *
+ * The recipe skips rows without a street, a block-style number, or a six-digit postcode.
  */
 export const sgRegisterRecipe: CorpusRecipe = {
 	name: "sg-register",
@@ -227,7 +213,7 @@ export const sgRegisterRecipe: CorpusRecipe = {
 			if (opts.golden) {
 				const golden = { raw: rendering.raw, components: rendering.components, country: "SG", locale: "en-SG" }
 
-				write(JSON.stringify(golden) + "\n")
+				write(stringifyJSON(golden))
 
 				emitted++
 				registers[rendering.register] = (registers[rendering.register] ?? 0) + 1
@@ -243,12 +229,20 @@ export const sgRegisterRecipe: CorpusRecipe = {
 					country: "SG",
 					locale: "en-SG",
 					source,
-					source_id: sliceSourceID(source, { raw: rendering.raw }),
+					source_id: recipeSourceID(source, { raw: rendering.raw }),
 					corpus_version: "0.1.0",
 					license:
 						"CDLA-Permissive-2.0 — Overture Maps addresses over the Singapore Open Data Licence 1.0 (OneMap / Singapore Land Authority)",
 				},
-				`sg-register:${rendering.register}`
+				`sg-register:${rendering.register}`,
+				// The values come from Overture and the recipe chose only their arrangement,
+				// so the Overture record behind each row is what `baseSourceID` names
+				// when the tuples file includes its id.
+				{
+					register: SourceRegister.Overture,
+					surface: SurfaceOrigin.Composed,
+					baseSourceID: tuple.sourceID ?? null,
+				}
 			)
 
 			if (ok) {