@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/adapters/wof/admin/json/adapter.ts

@@ -9,7 +9,7 @@
  *   `packages/corpus/lib/adapters/wof-admin/`, removed in this same change) was replaced by this
  *   one because the SQLite distribution path was unworkable for the real corpus build:
  *
- *   1. `dist.whosonfirst.org/sqlite/` is dead (NXDOMAIN); the Geocode-Earth mirror is the only one.
+ *   1. `dist.whosonfirst.org/sqlite/` is dead (nxdomain); the Geocode-Earth mirror is the only one.
  *   2. The Geocode-Earth-hosted postalcode DB tags every row `mz:is_current = -1` ("unknown but treated
  *        as active"); the SQLite adapter's `is_current = 1` predicate emitted zero rows.
  *   3. The `names` table in the SQLite distribution is empty — localized `name:*` variants live in a
@@ -20,7 +20,7 @@
  *   Input: a directory containing one or more cloned `whosonfirst-data-admin-<cc>` GitHub repos. Each
  *   repo has `data/XXX/YYY/ZZZ/<wof-id>.geojson` files; `**\/*.geojson` walks the tree recursively.
  *   Alternate-geometry siblings (`-alt-*`) are skipped — they're separate exports of the same
- *   record, not new records.
+ *   record rather than new records.
  *
  *   Per record, the adapter emits one row per `(name-variant, hierarchy-variant)` pair:
  *
@@ -49,16 +49,17 @@ import {
 	nameSlotsFor as wofNameSlotsFor,
 	type WOFVariantSpec,
 } from "#adapters/wof/json-rows"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
-import { buildAncestryIndex, walkFeatures, type WOFRecord } from "#utils"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
+import { buildAncestorNameIndex, walkFeatures, type AncestorNames, type WOFRecord } from "#utils"
 
 /**
  * Map a WOF placetype to a Mailwoman `ComponentTag`, or `undefined` to skip.
  *
- * Per-adapter deliberately (the postalcode adapter carries its own): each table is a record FILTER for its adapter's
- * emission set, not a shared vocabulary.
+ * Per-adapter deliberately (the postalcode adapter has its own): each table is a record
+ * filter for its adapter's emission set rather than a shared vocabulary.
  */
-function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | undefined {
+function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | null {
 	switch (placetype) {
 		case "country":
 		case "nation":
@@ -78,32 +79,37 @@ function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag
 		case "microhood":
 			return "dependent_locality"
 		default:
-			return undefined
+			return null
 	}
 }
 
 /**
  * Compute the hierarchy variants for a record given its ancestry chain and the chosen `selfName`.
  *
- * `selfName` is the surface form to use for the record's own component (locality / region / country / subregion).
- * Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*` localized value for variant slots;
- * ancestor names always come from the ancestor's canonical `wof:name`.
+ * `selfName` is the surface form to use for the record's own component
+ * (locality / region / country / subregion).
+ * Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*`
+ * localized value for variant slots.
  *
- * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the OpenCage template produces the
- * canonicalized form (`"United States of America"`), matching the legacy SQLite adapter's behavior.
+ * Ancestor names always come from the ancestor's canonical `wof:name`.
+ *
+ * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the
+ * OpenCage template produces the canonicalized form (`"United States of America"`),
+ * matching the legacy SQLite adapter's behavior.
  */
-export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: string): WOFVariantSpec[] {
+export function variantsFor(row: WOFRecord, ancestry: AncestorNames, selfName: string): WOFVariantSpec[] {
 	const selfTag = placetypeToTag(row.placetype)
 
 	if (!selfTag) return []
 
-	// Every variant here is a gazetteer hierarchy — `Paris`, `Paris, Île-de-France`, `Paris, Île-de-France, France` —
-	// and several steps are not addresses at all. See `WOFVariantSpec.hierarchy`.
+	// Every variant here is a gazetteer hierarchy — `Paris`, `Paris, Île-de-France`,
+	// `Paris, Île-de-France, France` — and several steps are not addresses at all.
+	// See `WOFVariantSpec.hierarchy`.
 	const hierarchy = true
 
-	const region = ancestry.find((a) => placetypeToTag(a.placetype) === "region")
-	const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country")
-	const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country
+	const region = ancestry.region
+	const country = ancestry.country
+	const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country ?? row.country
 
 	const variants: WOFVariantSpec[] = []
 
@@ -116,7 +122,7 @@ export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: str
 				variants.push({
 					hierarchy,
 					suffix: "with-region",
-					components: { [selfTag]: selfName, region: region.name },
+					components: { [selfTag]: selfName, region },
 				})
 			}
 
@@ -124,7 +130,7 @@ export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: str
 				variants.push({
 					hierarchy,
 					suffix: "with-region-country",
-					components: { [selfTag]: selfName, region: region.name, country: countryDisplay },
+					components: { [selfTag]: selfName, region, country: countryDisplay },
 				})
 			} else if (!region && country) {
 				variants.push({
@@ -169,9 +175,11 @@ export function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: str
 }
 
 /**
- * Build the per-record name-slot list. The canonical `"default"` slot uses the OpenCage-canonical country form when the
- * record is itself a country (matches SQLite-adapter behavior); every other placetype's default slot uses `wof:name`
- * verbatim.
+ * Build the per-record name-slot list.
+ *
+ * The canonical `"default"` slot uses the OpenCage-canonical country form
+ * when the record is itself a country (matches SQLite-adapter behavior);
+ * every other placetype's default slot uses `wof:name` verbatim.
  */
 export function nameSlotsFor(rec: WOFRecord): Array<{ key: string; value: string }> {
 	return wofNameSlotsFor(rec, {
@@ -183,29 +191,36 @@ export function nameSlotsFor(rec: WOFRecord): Array<{ key: string; value: string
 }
 
 /**
- * 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.
+ * 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 WOF_ADMIN_ADAPTER_ID = "wof-admin"
 
 /**
- * Construct the wof-admin JSON-bundle adapter. The adapter is stateless across runs; calling this twice with the same
- * input directory produces byte-identical `canonical.jsonl` (records are emitted in sorted `wof:id` order to be
- * insensitive to filesystem walk ordering).
+ * Construct the wof-admin JSON-bundle adapter.
+ *
+ * The adapter is stateless across runs.
+ * Two calls with the same input directory produce byte-identical `canonical.jsonl`
+ * (records are emitted in sorted `wof:id` order to be insensitive to filesystem walk ordering).
  */
 export function createWOFAdminAdapter(): CorpusAdapter {
 	return {
 		id: WOF_ADMIN_ADAPTER_ID,
 		defaultLicense: "CC0-1.0",
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.WhosOnFirst,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"Who's On First admin GeoJSON bundles (countries, regions, counties, localities) — multi-name variants per record.",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
 			// Pass 1: scan every GeoJSON file once, build the in-memory record index.
-			// We keep only records whose placetype maps to a ComponentTag — irrelevant placetypes
-			// (campus, county-region hybrids on which Mailwoman has no opinion) are dropped here so
-			// they don't inflate the ancestry index. Country-filtered runs prune to the matching
-			// country code too; the ancestors of a same-country record live in the same admin repo.
+			// We keep only records whose placetype maps to a ComponentTag — irrelevant
+			// placetypes (campus, county-region hybrids on which Mailwoman has no opinion)
+			// are dropped here so they don't inflate the ancestry index.
+			// Country-filtered runs prune to the matching country code too.
+			// The ancestors of a same-country record live in the same admin repo.
 			const byID = new Map<number, WOFRecord>()
 
 			for await (const rec of walkFeatures(opts.inputPath, { signal: opts.signal })) {
@@ -217,9 +232,9 @@ export function createWOFAdminAdapter(): CorpusAdapter {
 				byID.set(rec.id, rec)
 			}
 
-			const ancestry = buildAncestryIndex(byID)
+			const ancestry = buildAncestorNameIndex(byID, placetypeToTag)
 
-			// Pass 2: emit rows in sorted-id order for deterministic JSONL.
+			// Pass 2: emit rows in sorted-id order for deterministic jsonl.
 			yield* emitWOFJSONRows({
 				records: byID,
 				ancestry,

package/lib/adapters/wof/json-rows.ts

@@ -5,15 +5,17 @@
  * @file Deterministic canonical-row emission shared by WOF GeoJSON adapters.
  */
 
-import { formatAddressRow } from "@mailwoman/codex/address-format"
-import { isLargestFirstSystem, lineJoinForCountry } from "@mailwoman/codex/address-layouts"
+import { formatAddressRow } from "@mailwoman/codex/address/format"
+import { isLargestFirstSystem, lineJoinForCountry } from "@mailwoman/codex/address/layouts"
 import type { ComponentTag } from "@mailwoman/codex/component"
 
 import type { AdapterOptions, CanonicalRow } from "#types"
-import { normalizeNameKey, type WOFRecord } from "#utils"
+import { normalizeNameKey, type AncestorNames, type WOFRecord } from "#utils"
 
 /**
- * The order an admin hierarchy is written in, smallest unit first. A country that writes largest-first reverses it.
+ * The order an admin hierarchy is written in, smallest unit first.
+ *
+ * A country that writes largest-first reverses it.
  */
 const HIERARCHY_ORDER: readonly ComponentTag[] = [
 	"postcode",
@@ -25,9 +27,13 @@ const HIERARCHY_ORDER: readonly ComponentTag[] = [
 ]
 
 /**
- * Render an admin-hierarchy variant: the components it carries, in hierarchy order, joined the way the country joins a
- * line. This is a gazetteer QUERY rather than a postal address, which is why it does not go through a layout — a
- * country whose postal layout drops the region would collapse `Paris, Île-de-France` back into `Paris`.
+ * Render an admin-hierarchy variant: the components it contains, in hierarchy order,
+ * joined the way the country joins a line.
+ *
+ * This adapter emits a gazetteer query.
+ * It follows the gazetteer path without a postal layout.
+ *
+ * A country whose postal layout drops the region would collapse `Paris, Île-de-France` back into `Paris`.
  */
 function renderHierarchy(
 	components: Partial<Record<ComponentTag, string>>,
@@ -54,12 +60,17 @@ function renderHierarchy(
 /**
  * Display name for the country, keyed by ISO 3166-1 alpha-2.
  *
- * Must be the **OpenCage-canonical** surface form: the `address-formatter` library expands some country names en route
- * to its output (e.g. `"United States"` → `"United States of America"`). If `components.country` and the formatted
- * `raw` disagree, alignment will fail downstream. Keying off the canonical form keeps the two in lockstep.
+ * Must be the **OpenCage-canonical** surface form: the `address-formatter` library expands some
+ * country names en route to its output (e.g. `"United States"` → `"United States of America"`).
+ * If `components.country` and the formatted `raw` disagree, alignment will fail downstream.
+ *
+ * The canonical form keeps the two in lockstep.
  *
- * Phase 1 US + FR only; extend as new locales come online. Missing countries fall back to the country row's `wof:name`,
- * accepting the alignment risk for non-canonicalized names.
+ * Phase 1 US + FR only.
+ * Extend as new locales come online.
+ *
+ * A missing country uses the country row's `wof:name`; this preserves the
+ * alignment risk for non-canonicalized names.
  */
 export const COUNTRY_DISPLAY_NAME: Record<string, string> = {
 	US: "United States of America",
@@ -67,7 +78,9 @@ export const COUNTRY_DISPLAY_NAME: Record<string, string> = {
 }
 
 /**
- * BCP-47 locale defaulting for the corpus row's `locale` field. Defaulted by country.
+ * BCP-47 locale defaulting for the corpus row's `locale` field.
+ *
+ * Defaulted by country.
  */
 export const LOCALE_BY_COUNTRY: Record<string, string> = {
 	US: "en-US",
@@ -78,29 +91,33 @@ export interface WOFVariantSpec {
 	suffix: string
 	components: Partial<Record<ComponentTag, string>>
 	/**
-	 * Render this variant as an ADMIN HIERARCHY rather than as a postal address.
+	 * Render this variant as an admin hierarchy rather than as a postal address.
 	 *
-	 * A hierarchy variant is a query — `Paris`, then `Paris, Île-de-France`, then `Paris, Île-de-France, France` — and
-	 * several of its steps are not addresses at all. France's postal layout carries no region, so rendering `{ locality,
-	 * region }` through it prints `Paris` and the whole variant collapses into the one below it.
+	 * A hierarchy variant is a query — `Paris`, then `Paris, Île-de-France`, then
+	 * `Paris, Île-de-France, France` — and several of its steps are not addresses at all.
+	 * France's postal layout has no region, so rendering `{ locality, region }` through
+	 * it prints `Paris` and the whole variant collapses into the one below it.
 	 *
-	 * So the hierarchy is joined in its own order: smallest unit first, or largest first for the systems that write that
-	 * way, with the country's own separator.
+	 * So the hierarchy is joined in its own order: smallest unit first, or largest first
+	 * for the systems that write that way, with the country's own separator.
 	 */
 	hierarchy?: boolean
 }
 
 export interface NameSlotOptions {
 	/**
-	 * Canonical surface for the record's own `"default"` slot. Default `rec.name` verbatim; the admin adapter substitutes
-	 * the OpenCage-canonical {@link COUNTRY_DISPLAY_NAME} for country records.
+	 * Canonical surface for the record's own `"default"` slot.
+	 *
+	 * The admin adapter substitutes the OpenCage-canonical {@link COUNTRY_DISPLAY_NAME} for country records.
+	 *
+	 * @defaultValue `rec.name` verbatim.
 	 */
 	canonicalName?: (rec: WOFRecord) => string
 }
 
 /**
- * Build the per-record name-slot list: the canonical `"default"` slot, then every `name:*` variant deduplicated against
- * it so a redundant `"default"`-equivalent row is not emitted under a localized key.
+ * Build the per-record name-slot list: the canonical `"default"` slot, then every `name:*` variant
+ * deduplicated against it so a redundant `"default"`-equivalent row is not emitted under a localized key.
  */
 export function nameSlotsFor(rec: WOFRecord, options: NameSlotOptions = {}): Array<{ key: string; value: string }> {
 	const canonicalSelfName = options.canonicalName?.(rec) ?? rec.name
@@ -119,15 +136,29 @@ export function nameSlotsFor(rec: WOFRecord, options: NameSlotOptions = {}): Arr
 
 interface EmitWOFJSONRowsOptions {
 	records: ReadonlyMap<number, WOFRecord>
-	ancestry: ReadonlyMap<number, WOFRecord[]>
+	/**
+	 * The ancestor names each record's variants read, rather than its ancestor records.
+	 *
+	 * A record absent from the map resolves to an empty set of ancestor names.
+	 * Records with no resolvable ancestor produce the same value.
+	 */
+	ancestry: ReadonlyMap<number, AncestorNames>
 	adapterOptions: AdapterOptions
 	adapterID: string
 	localeByCountry: Readonly<Record<string, string>>
 	shouldEmit?: (record: WOFRecord) => boolean
 	nameSlotsFor: (record: WOFRecord) => Array<{ key: string; value: string }>
-	variantsFor: (record: WOFRecord, ancestry: WOFRecord[], selfName: string) => WOFVariantSpec[]
+	variantsFor: (record: WOFRecord, ancestry: AncestorNames, selfName: string) => WOFVariantSpec[]
 }
 
+/**
+ * The value a record uses in place of ancestor names when its ancestors do not resolve.
+ *
+ * Frozen and shared, because the emitter reaches it once per such record
+ * and constructing a fresh object per row would allocate one per name slot.
+ */
+const NO_ANCESTORS: AncestorNames = Object.freeze({})
+
 /**
  * Emit aligned rows in WOF-id order, enforcing the adapter limit across all name and hierarchy variants.
  */
@@ -152,7 +183,7 @@ export function* emitWOFJSONRows(options: EmitWOFJSONRowsOptions): Generator<Can
 		if (!shouldEmit(record)) continue
 
 		for (const slot of slotsForRecord(record)) {
-			for (const variant of variantsFor(record, ancestry.get(id) ?? [], slot.value)) {
+			for (const variant of variantsFor(record, ancestry.get(id) ?? NO_ANCESTORS, slot.value)) {
 				if (adapterOptions.limit !== undefined && emitted >= adapterOptions.limit) return
 
 				const rendered = variant.hierarchy

package/lib/adapters/wof/postalcode-json/adapter.ts

@@ -3,38 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `wof-postalcode`: Who's On First postalcode GeoJSON-bundle adapter.
+ *   Emits corpus rows from Who's On First postalcode GeoJSON repositories.
  *
- *   **Phase 1.5.1 pivot.** Replaces the previous SpatiaLite-backed implementation (formerly at
- *   `packages/corpus/lib/adapters/wof-postalcode/`, removed in this same change). The rationale is
- *   in `wof-admin-json/adapter.ts` and in `DECISIONS.md` — short version: the SQLite distribution
- *   mirror is dead, the live distro tags every postcode row `mz:is_current = -1` which the old
- *   `is_current = 1` predicate excluded, and localized `name:*` variants don't ship in the SQLite
- *   export at all.
+ *   The input directory must hold the `whosonfirst-data-postalcode-<cc>` repositories and the matching
+ *   `whosonfirst-data-admin-<cc>` repositories. Postcode records point to their ancestors by `wof:parent_id`, so the
+ *   admin records must be in the same walk.
  *
- *   Input: a directory containing one or more cloned `whosonfirst-data-postalcode-<cc>` repos plus
- *   the relevant `whosonfirst-data-admin-<cc>` repos (postcode records reference admin ancestry by
- *   `wof:parent_id`, so the locality / region / country records must be in the same walk for the
- *   ancestry chain to resolve). The corpus pipeline clones all four repos under
- *   `/data/corpus/sources/wof/repos/` and points the adapter at that root.
+ *   Each postcode record produces one row per pair of name slot and hierarchy variant. The name slots are the canonical
+ *   `wof:name` (slot `default`) plus any `name:*` variants. The hierarchy variants are the postcode by itself, then with
+ *   locality, region and country added in turn. Ancestor names always use the canonical `wof:name`.
  *
- *   Per live postalcode record, the adapter emits one row per `(name-variant, hierarchy-variant)`
- *   pair:
- *
- *   - **Name variants**: canonical `wof:name` (slot key `default`, typically the postcode digits
- *       themselves) plus any `name:*` variants on the postcode feature. In practice WOF postcode
- *       records rarely carry localized name variants, so this expansion is usually a no-op — but
- *       the code path stays symmetric with the admin adapter for consistency.
- *   - **Hierarchy variants** (unchanged from the SQLite adapter): self, +locality, +locality+region,
- *       +locality+region+country.
- *
- *   `source_id` is `wof-postalcode-<wof_id>-<name-slot>-<hierarchy-variant>`. Ancestor names always
- *   come from the ancestor's canonical `wof:name`; this adapter does NOT iterate ancestor name
- *   variants (e.g. it does not emit `"75008 Париж"` even when Paris has a `name:rus_x_preferred`).
- *   That cross-product belongs to a future synthesis pass; emitting it here would multiply row
- *   counts ~10× without a clear training-value story.
- *
- *   License: CC0.
+ *   `source_id` has the form `wof-postalcode-<wof_id>-<name-slot>-<hierarchy-variant>`.
  */
 
 import type { ComponentTag } from "@mailwoman/codex/component"
@@ -47,37 +26,45 @@ import {
 	nameSlotsFor as wofNameSlotsFor,
 	type WOFVariantSpec,
 } from "#adapters/wof/json-rows"
-import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+import { SourceRegister } from "#registers"
+import { AddressRole, type AdapterOptions, type CanonicalRow, type CorpusAdapter, SurfaceOrigin } from "#types"
 import { US_STATE_BY_ABBREVIATION } from "#us/fips-state"
-import { buildAncestryIndex, walkFeatures, type WOFRecord } from "#utils"
+import { buildAncestorNameIndex, walkFeatures, type AncestorNames, type WOFRecord } from "#utils"
 
 /**
- * US state name → USPS alpha-2, the surface form a US postal address carries.
+ * Maps a lowercase US state name to its USPS code.
  *
- * WOF names the region in full (`Oregon`); the layout renders whatever it is given, because a layout is an ORDER and
- * not a vocabulary. Choosing the surface form is therefore this adapter's decision, and the postal one is the code.
+ * WOF stores full state names such as `Oregon`, and the address layout prints components unchanged.
+ * The adapter substitutes the USPS code so the row matches how a US postal address is written.
  */
 const US_STATE_ABBREVIATION_BY_NAME: ReadonlyMap<string, string> = new Map(
 	Object.values(US_STATE_BY_ABBREVIATION).map((state) => [state.name.toLowerCase(), state.abbreviation])
 )
 
 /**
- * The region surface form to print for `country`, given the name WOF carries.
+ * Returns the region text to print.
+ *
+ * The adapter converts US state names to USPS codes.
+ * Other names pass through.
  */
 function regionSurface(country: string, name: string): string {
+	// country-branch: the codex holds a name-to-code table for US states only.
+	// The WOF admin database's `place_abbr` holds codes for ten countries
+	// and an ISO 3166-2 table would cover every country.
+	// The tree holds neither as a lookup yet.
 	if (country !== "US") return name
 
 	return US_STATE_ABBREVIATION_BY_NAME.get(name.trim().toLowerCase()) ?? name
 }
 
 /**
- * Map a WOF placetype to a Mailwoman `ComponentTag`, or `undefined` to skip.
+ * Maps a WOF placetype to a component tag, or returns `undefined` for a placetype this adapter skips.
  *
- * Per-adapter deliberately (the admin adapter carries its own): each table is a record FILTER for its adapter's
- * emission set — this one keeps `postalcode` plus the ancestry placetypes its variants render — not a shared
- * vocabulary.
+ * The mapping also filters records, so it covers only `postalcode`
+ * and the ancestor placetypes the variants use.
+ * The admin adapter keeps its own mapping.
  */
-function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | undefined {
+function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | null {
 	switch (placetype) {
 		case "country":
 		case "nation":
@@ -90,35 +77,36 @@ function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag
 		case "postalcode":
 			return "postcode"
 		default:
-			return undefined
+			return null
 	}
 }
 
 /**
- * Compute hierarchy variants for a postcode record. `selfName` is the postcode surface form (canonical `wof:name` for
- * the `default` slot, a `name:*` localized variant otherwise).
+ * Builds the hierarchy variants for a postcode record, or returns an empty list for any other placetype.
+ *
+ * `selfName` is the postcode text for the current name slot.
  */
-export function postcodeVariantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: string): WOFVariantSpec[] {
+export function postcodeVariantsFor(row: WOFRecord, ancestry: AncestorNames, selfName: string): WOFVariantSpec[] {
 	if (placetypeToTag(row.placetype) !== "postcode") return []
 
-	const locality = ancestry.find((a) => placetypeToTag(a.placetype) === "locality")
-	const region = ancestry.find((a) => placetypeToTag(a.placetype) === "region")
-	const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country")
-	const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country
+	const locality = ancestry.locality
+	const region = ancestry.region
+	const country = ancestry.country
+	const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country ?? row.country
 
 	const variants: WOFVariantSpec[] = [{ suffix: "self", components: { postcode: selfName } }]
 
 	if (locality) {
 		variants.push({
 			suffix: "with-locality",
-			components: { postcode: selfName, locality: locality.name },
+			components: { postcode: selfName, locality },
 		})
 	}
 
 	if (locality && region) {
 		variants.push({
 			suffix: "with-locality-region",
-			components: { postcode: selfName, locality: locality.name, region: region.name },
+			components: { postcode: selfName, locality, region },
 		})
 	}
 
@@ -127,8 +115,8 @@ export function postcodeVariantsFor(row: WOFRecord, ancestry: WOFRecord[], selfN
 			suffix: "with-locality-region-country",
 			components: {
 				postcode: selfName,
-				locality: locality.name,
-				region: regionSurface(row.country, region.name),
+				locality,
+				region: regionSurface(row.country, region),
 				country: countryDisplay,
 			},
 		})
@@ -138,30 +126,35 @@ export function postcodeVariantsFor(row: WOFRecord, ancestry: WOFRecord[], selfN
 }
 
 /**
- * Build the per-record name-slot list. The `default` slot uses `wof:name` verbatim (postcode digits); subsequent slots
- * come from `name:*` variants dedup'd against the default.
+ * Returns a record's name slots.
+ *
+ * The `default` slot holds `wof:name` unchanged.
+ * The other slots hold `name:*` variants that differ from it.
  */
 export function nameSlotsFor(rec: WOFRecord): Array<{ key: string; value: string }> {
 	return wofNameSlotsFor(rec)
 }
 
 /**
- * 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.
+ * The source ID on rows from this adapter.
  */
 export const WOF_POSTALCODE_ADAPTER_ID = "wof-postalcode"
 
+/**
+ * Creates the WOF postalcode adapter.
+ */
 export function createWOFPostalcodeAdapter(): CorpusAdapter {
 	return {
 		id: WOF_POSTALCODE_ADAPTER_ID,
 		defaultLicense: "CC0-1.0",
+		addressRole: AddressRole.Premise,
+		register: SourceRegister.WhosOnFirst,
+		surface: SurfaceOrigin.Rendered,
 		description:
 			"Who's On First postalcode GeoJSON bundles (postcode → locality/region pairs). Ancestor names from sibling admin repos.",
 
 		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
-			// Pass 1: full walk. We keep every record whose placetype maps to a ComponentTag — the
-			// postcode adapter needs locality / region / country admin records in the index so it
-			// can resolve postcode ancestry, even though it only emits rows for postcode records.
+			// The index keeps admin records as well as postcodes so that postcode ancestry resolves.
 			const byID = new Map<number, WOFRecord>()
 
 			for await (const rec of walkFeatures(opts.inputPath, { signal: opts.signal })) {
@@ -173,9 +166,18 @@ export function createWOFPostalcodeAdapter(): CorpusAdapter {
 				byID.set(rec.id, rec)
 			}
 
-			const ancestry = buildAncestryIndex(byID)
+			const ancestry = buildAncestorNameIndex(byID, placetypeToTag)
+
+			// The adapter read admin records so postcode ancestry resolves.
+			// The index above now holds the three ancestor names read by each postcode variant.
+			// Their removal here releases every admin record's `nameVariants` map before the emit pass.
+			// `shouldEmit` skipped those records anyway.
+			for (const [id, record] of byID) {
+				if (placetypeToTag(record.placetype) !== "postcode") {
+					byID.delete(id)
+				}
+			}
 
-			// Pass 2: emit postcode rows only, sorted by id for determinism.
 			yield* emitWOFJSONRows({
 				records: byID,
 				ancestry,