@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/south-asia/recipes/register.ts

@@ -3,43 +3,50 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `pk-register` and `bd-register` slice recipes — the typed forms of Pakistan and Bangladesh the country templates do
- *   not render, over the OpenStreetMap corpus JSONL the `osm` adapter reads (#1744, the F8 family). The adapter's own
- *   rows carry the template shape (`4 38th Street, DHA Phase 6, Karachi`; `24 Road 104, Dhaka - 1207`); these two carry
- *   the register:
+ *   `pk-register` and `bd-register` recipes, the typed forms of Pakistan and Bangladesh the country
+ *   templates do not render, over the OpenStreetMap corpus jsonl the `osm` adapter reads. The
+ *   adapter's own rows use the template shape (`4 38th Street, DHA Phase 6, Karachi`) and
+ *   (`24 Road 104, Dhaka - 1207`). These two represent the register:
  *
- *   - the HOUSE line, `House 4, Street 25, F-7/2, Islamabad` and `House 34, Road 4, Sector 9, Uttara, Dhaka 1230` —
- *     `House` in front of the number (untagged, the same rule as Singapore's `Blk`), the numbered street, the scheme or
- *     sector as the dependent locality, the city;
- *   - the PLAIN line with the trailing postcode and no dash, `58 Kalabagan 1st Ln, Dhaka 1205` — what a person types,
- *     where the template writes `Dhaka - 1205`.
+ *   - the house line, `House 4, Street 25, F-7/2, Islamabad` and `House 34, Road 4, Sector 9, Uttara,
+ *     Dhaka 1230`, with `House` in front of the number (untagged, the same rule as Singapore's `Blk`),
+ *     the numbered street, the scheme or sector as dependent locality, then the city
+ *   - the plain line with the trailing postcode and no dash, `58 Kalabagan 1st Ln, Dhaka 1205`, which
+ *     is what a person types where the template writes `Dhaka - 1205`
  *
- *   Islamabad's sector codes (`F-7/2`, `G-10/3`) are the one synthesized value: the register carries them on a handful
- *   of rows, mostly inside `addr:city` (`F7/2 Islamabad`), so a row whose city is Islamabad and whose scheme is unknown
- *   draws one from the capital's grid. Every other value is the row's own. The components are the `osm` adapter's
- *   mapping (`componentsForOSMRow`), so the two surfaces cannot disagree about what a field means.
+ *   Islamabad's sector codes (`F-7/2`, `G-10/3`) are the one synthesized value. The register contains
+ *   them on a handful of rows, mostly inside `addr:city` (`F7/2 Islamabad`), so a row whose city is
+ *   Islamabad and whose scheme is unknown draws one from the capital's grid. Every other value is the
+ *   row's own. The components are the `osm` adapter's mapping (`componentsForOSMRow`), so the two
+ *   surfaces cannot disagree about what a field means.
  *
- *   ⚠ ODbL: the rows inherit OpenStreetMap's share-alike license, and `--exclude-share-alike` drops them.
+ *   ODbL: the rows inherit OpenStreetMap's share-alike license. A corpus build run under
+ *   `LicensePolicy.ShareAlikeFree` refuses them.
  *
  *   Run: mailwoman corpus slice pk-register --input <osm-pk.corpus.jsonl> --count N --seed S
  */
 
+import { stringifyJSON } from "@mailwoman/core/json"
 import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 
 import { componentsForOSMRow, OSM_LICENSE, sameName } from "#adapters/osm/adapter"
-import { alignAndWrite, type CorpusRecipe, readTuples, type SliceRecipeOpts, sliceSourceID } from "#recipes/scaffold"
-import type { CanonicalRow } from "#types"
+import { alignAndWrite, type CorpusRecipe, readTuples, type RecipeOptions, recipeSourceID } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
+import { SourceRegister } from "#registers"
+import { type CanonicalRow, SurfaceOrigin } from "#types"
 
 /**
- * Islamabad's residential sectors: the lettered rows E to I, the numbered columns the Capital Development Authority has
- * developed, and the four sub-sectors each splits into.
+ * Islamabad's residential sectors: the lettered rows E to I and the numbered columns
+ * developed by the Capital Development Authority.
+ * Each column splits into four sub-sectors.
  */
 const ISLAMABAD_SECTOR_ROWS = ["E", "F", "G", "I"] as const
 const ISLAMABAD_SECTOR_COLUMNS = [6, 7, 8, 9, 10, 11] as const
 const ISLAMABAD_SUB_SECTORS = [1, 2, 3, 4] as const
 
 /**
- * Share of rows rendered in the house register; the rest take the plain line.
+ * Share of rows rendered in the house register.
+ * The rest take the plain line.
  */
 const P_HOUSE = 0.55
 
@@ -68,8 +75,9 @@ export function drawIslamabadSector(random: () => number): string {
 }
 
 /**
- * Render one register line from the adapter's components. Returns null when the row has no house number or no locality:
- * both registers need the two.
+ * Render one register line from the adapter's components.
+ *
+ * @returns Null when the row has no house number or no locality: both registers need the two.
  */
 export function renderSouthAsiaRegister(
 	components: CanonicalRow["components"],
@@ -110,7 +118,9 @@ export function renderSouthAsiaRegister(
 }
 
 function makeRecipe(name: string, country: "PK" | "BD", locale: string, description: string): CorpusRecipe {
-	const source = `synth-${name}`
+	// The value is composed and read through the table rather than written out in the composition.
+	// so the vocabulary flip is one constant and a name the table does not record refuses here.
+	const source = defaultRecipeSource(`synth-${name}`)
 
 	return {
 		name,
@@ -123,7 +133,7 @@ function makeRecipe(name: string, country: "PK" | "BD", locale: string, descript
 				description: `The OpenStreetMap ${country} corpus JSONL (osm-${country.toLowerCase()}.corpus.jsonl)`,
 			},
 		],
-		async run(opts: SliceRecipeOpts, write) {
+		async run(opts: RecipeOptions, write) {
 			if (!opts.input) {
 				throw new Error(`${name}: --input <osm-${country.toLowerCase()}.corpus.jsonl> is required`)
 			}
@@ -151,7 +161,7 @@ function makeRecipe(name: string, country: "PK" | "BD", locale: string, descript
 				}
 
 				if (opts.golden) {
-					write(JSON.stringify({ raw: rendering.raw, components: rendering.components, country, locale }) + "\n")
+					write(stringifyJSON({ raw: rendering.raw, components: rendering.components, country, locale }))
 
 					emitted++
 					registers[rendering.register] = (registers[rendering.register] ?? 0) + 1
@@ -167,11 +177,20 @@ function makeRecipe(name: string, country: "PK" | "BD", locale: string, descript
 						country,
 						locale,
 						source: sourceName,
-						source_id: sliceSourceID(sourceName, { raw: rendering.raw }),
+						source_id: recipeSourceID(sourceName, { raw: rendering.raw }),
 						corpus_version: "0.1.0",
 						license: OSM_LICENSE,
 					},
-					`${name}:${rendering.register}`
+					`${name}:${rendering.register}`,
+					// The components come from the OpenStreetMap corpus jsonl the `osm` adapter wrote.
+					// This recipe re-orders them into the typed forms, so the address is real
+					// and the line is the recipe's.
+					// The OSM record is what `baseSourceID` names when the tuples file includes its id.
+					{
+						register: SourceRegister.OpenStreetMap,
+						surface: SurfaceOrigin.Composed,
+						baseSourceID: tuple.sourceID ?? null,
+					}
 				)
 
 				if (ok) {

package/lib/subvenue/harvest.ts

@@ -0,0 +1,251 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   @file This module defines harvestable source rows and reads them from files. Each pass extracts
+ *   attested surfaces and measures the identifier half of each designator.
+ *
+ *   {@link SubVenueHarvestRow} accepts rows from any source. An Overture Places row in the
+ *   `airport_terminal` category has the shape `{ designatorID, name }` and fits unchanged. The type is
+ *   declared here so the builder can read source rows without importing `@mailwoman/osm`. The corpus
+ *   package has no dependency on that package.
+ *
+ *   Two measurements shape {@link extractAttestedPhrases}. They show why it can run over raw OSM:
+ *
+ *   **Most feature names describe the venue.** In the Berlin extract, 2,060 matched features include a
+ *   `railway=platform` with the name `Stendaler Straße`. An `amenity=university` has the name `Hertie School`.
+ *   Among 250,116 Great Britain features with names, 6,003 (2.40%) contain a designator token. A name adds a surface
+ *   when it contains a phrase already in the surface index. `Terminal E (Untere Ebene)` qualifies. The full
+ *   venue name `Otto Lilienthal Flughafen Berlin Tegel` does not.
+ *
+ *   **The matched phrase determines which record receives the surface.** Every hit attributed to
+ *   `row.designatorID`, the rule that matched the feature, produced `west → platform`, `hall → platform`, and
+ *   `biggin → platform` on the GB extract. A bus stop tagged `public_transport=platform` can have the label
+ *   "Village Hall" or "West Kensington". Of 133 OSM-derived surfaces, 108 referred to records other than the
+ *   ones identified by the phrases. Attribution now follows the surface index. The row's designator stays in `context`.
+ *   A confound board can then distinguish `hall` found on a platform from `hall` found on a terminal.
+ */
+
+import { readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { parseJSONStrict } from "@mailwoman/core/json"
+import { TextSpliterator } from "spliterator"
+
+import { nameContainsSurfaces, type SurfaceIndex } from "#subvenue/surfaces"
+import type { IdentifierShape, SubVenueSurface } from "#subvenue/table"
+
+/**
+ * One row of a harvestable source, as read back off jsonl or out of a layer database.
+ *
+ * This type accepts rows from any source.
+ * An Overture Places row in the `airport_terminal` category has the shape
+ * `{ designatorID, name }` and fits unchanged.
+ *
+ * The harvest function's hardcoded `osm:name` source stamp did not fit that input.
+ * See `overture-subvenue.ts` for the source handling.
+ *
+ * Declared locally so the builder does not import `@mailwoman/osm`
+ * (which `@mailwoman/corpus` does not depend on) just to name a shape it reads from a file.
+ */
+export interface SubVenueHarvestRow {
+	/**
+	 * The designator the source's rule assigned to the feature.
+	 *
+	 * Not necessarily the record a matched phrase names.
+	 * See this file's header on phrase attribution.
+	 * Passed into {@link SubVenueSurface.context}.
+	 */
+	designatorID: string
+	/**
+	 * `venue` (station, airport, campus) or `sub_venue`, when the source's rule assigns one.
+	 *
+	 * The harvest itself does not read it.
+	 * The sub-venue recipe fills its venue slot from it.
+	 */
+	tier?: string
+	name?: string | null
+	ref?: string | null
+	localizedNames?: Record<string, string>
+}
+
+/**
+ * Classify an OSM `ref` into an {@link IdentifierShape} class.
+ *
+ * The classes are the ones Berlin's gates actually produced, plus the two aviation forms
+ * the corpus task names (`Terminal 2F` is digit-letter, `Concourse B` is letter).
+ * `range` covers both separators OSM uses for a gate serving more than one stand: `16-18` and `0/1`.
+ */
+export function classifyIdentifier(ref: string): string {
+	const value = ref.trim()
+
+	if (/^[0-9]+$/.test(value)) return "digit"
+
+	if (/^[A-Za-z]$/.test(value)) return "letter"
+
+	if (/^[A-Za-z]+[0-9]+$/.test(value)) return "letter-digit"
+
+	if (/^[0-9]+[A-Za-z]+$/.test(value)) return "digit-letter"
+
+	if (/^[0-9A-Za-z]+\s*[-/]\s*[0-9A-Za-z]+$/.test(value)) return "range"
+
+	return "other"
+}
+
+/**
+ * How many real `ref` values each {@link IdentifierShape} keeps.
+ *
+ * Eight rather than "all" and not one.
+ * The field exists so a recipe author can see what a class actually contains.
+ *
+ * GB's `other` class turned out to be semicolon multi-values (`1.2.3`, `13.14`),
+ * which one example would have hidden and which the class name does not say.
+ *
+ * Eight fits a terminal line and covers the variety inside every class the GB extract produced.
+ * The count lives in `observations`; this is a sample rather than a census.
+ */
+const IDENTIFIER_EXAMPLES_PER_SHAPE = 8
+
+/**
+ * Options for one harvest pass.
+ *
+ * They set the source stamp and region recorded on each surface.
+ *
+ * Both default to the OSM/unknown-region values wave 1 hardcoded, so an existing caller is unchanged.
+ */
+export interface HarvestOptions {
+	/**
+	 * Source family: `osm` yields `osm:name` / `osm:name:<lang>`, `overture` yields `overture:name`.
+	 */
+	source?: string
+	/**
+	 * ISO 3166-1 alpha-2 of the extract or partition.
+	 *
+	 * `""` when unknown.
+	 */
+	region?: string
+}
+
+/**
+ * Harvest attested phrases and identifier shapes out of a source's rows.
+ *
+ * `index` gates the name harvest.
+ * A name contributes only when it contains a phrase already in the table.
+ *
+ * That filter is the whole reason this function is safe to run over raw OSM:
+ * see this file's header for the Berlin measurement that motivated it.
+ *
+ * The index decides which record receives each hit.
+ * The row's designator is recorded as `context`.
+ *
+ * @returns Surfaces with real `observations` counts, so the lexicon can rank
+ * `terminal` above a phrase attested once.
+ */
+export function extractAttestedPhrases(
+	rows: Iterable<SubVenueHarvestRow>,
+	index: SurfaceIndex,
+	options: HarvestOptions = {}
+): { surfaces: SubVenueSurface[]; identifierShapes: IdentifierShape[] } {
+	const source = options.source ?? "osm"
+	const region = options.region ?? ""
+	/**
+	 * `phrase\0lang\0source` → { count, context }.
+	 */
+	const surfaceCounts = new Map<string, { count: number; context: Map<string, number> }>()
+	/**
+	 * `designatorID\0shape` → { count, examples }.
+	 */
+	const shapes = new Map<string, { count: number; examples: Set<string> }>()
+
+	const note = (phrase: string, lang: string, sourceTag: string, context: string): void => {
+		const key = `${phrase}\0${lang}\0${sourceTag}`
+		const entry = surfaceCounts.get(key) ?? { count: 0, context: new Map<string, number>() }
+
+		entry.count++
+		entry.context.set(context, (entry.context.get(context) ?? 0) + 1)
+		surfaceCounts.set(key, entry)
+	}
+
+	for (const row of rows) {
+		if (row.name) {
+			for (const hit of nameContainsSurfaces(row.name, index)) {
+				// `und` — the default `name` tag has no language.
+				// Overture's `name` is the same: a primary name in whatever language the place uses, untagged.
+				note(hit, "und", `${source}:name`, row.designatorID)
+			}
+		}
+
+		for (const [lang, localized] of Object.entries(row.localizedNames ?? {})) {
+			for (const hit of nameContainsSurfaces(localized, index)) {
+				note(hit, lang, `${source}:name:${lang}`, row.designatorID)
+			}
+		}
+
+		if (row.ref) {
+			const shape = classifyIdentifier(row.ref)
+			const key = `${row.designatorID}\0${shape}`
+			const entry = shapes.get(key) ?? { count: 0, examples: new Set<string>() }
+
+			entry.count++
+
+			if (entry.examples.size < IDENTIFIER_EXAMPLES_PER_SHAPE) {
+				entry.examples.add(row.ref.trim())
+			}
+
+			shapes.set(key, entry)
+		}
+	}
+
+	const surfaces: SubVenueSurface[] = [...surfaceCounts].map(([key, entry]) => {
+		const [phrase, lang, sourceTag] = key.split("\0") as [string, string, string]
+		const record = index.get(phrase)!
+
+		return {
+			phrase,
+			recordID: record.recordID,
+			recordKind: record.recordKind,
+			lang,
+			region,
+			source: sourceTag,
+			curated: false,
+			observations: entry.count,
+			context: Object.fromEntries([...entry.context].toSorted((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))),
+		}
+	})
+
+	const identifierShapes: IdentifierShape[] = [...shapes].map(([key, entry]) => {
+		const [designatorID, shape] = key.split("\0") as [string, string]
+
+		return {
+			designatorID,
+			region,
+			shape,
+			observations: entry.count,
+			examples: [...entry.examples].toSorted((a, b) => a.localeCompare(b)),
+		}
+	})
+
+	return { surfaces, identifierShapes }
+}
+
+/**
+ * Read a jsonl file of {@link SubVenueHarvestRow}s.
+ *
+ * The reader skips blank lines and rows it cannot parse.
+ * A malformed line does not stop lexicon generation.
+ */
+export async function readSubVenueJSONL(path: string): Promise<SubVenueHarvestRow[]> {
+	const out: SubVenueHarvestRow[] = []
+
+	// `TextSpliterator` rather than `split("\n")`.
+	// A whole-country extract runs to 250,000 lines (52 MB for Great Britain), and materializing
+	// every segment before reading the first is exactly what the repo lint rule exists to prevent.
+	for (const line of TextSpliterator.from(await readLocalTextFile(path))) {
+		try {
+			out.push(parseJSONStrict<SubVenueHarvestRow>(line))
+		} catch {
+			continue
+		}
+	}
+
+	return out
+}

package/lib/{tools/sub/venue → subvenue}/promotions.ts

@@ -3,99 +3,68 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The sub-venue curation ledger (#35 wave 2) — every decision taken about whether a designator
- *   surface may be used for parsing IN A GIVEN LOCALE, with the census that backs it.
- *
- *   This file is HAND-AUTHORED. `sub-venue-lexicon.ts` is a pure function of its sources; nothing in it
- *   can decide that Spanish `terminal` is safe and British `hall` is not, because that judgement is
- *   about the confounds a token has in a language, and a confound is a fact about the world rather than
- *   about the data. What the builder does is APPLY these decisions — {@link SUBVENUE_PROMOTIONS} is the
- *   only thing that ever sets `curated: true` on a machine-derived surface.
- *
- *   ── Why every decision is per-LOCALE ─────────────────────────────────────────────────────────────
- *   Wave 1 measured `hall` at 3,274 hits in the Great Britain extract and stopped there, which reads as
- *   a verdict on the word. It is not. Re-censused per region 2026-08-05, the same token is a British
- *   disaster and a German designator, and no single global flag can express that. The rule this file
- *   enforces: a promotion names a designator, a phrase, AND a locale, and it is earned by a count taken
- *   in that locale's own data.
- *
- *   ── What "real" and "confound" mean in the numbers below ─────────────────────────────────────────
- *   Each census counts the surface's occurrences in one region's extract and splits them two ways:
- *
- *   - **real** — the phrase sits in a name that is genuinely venue-interior structure, judged by the
- *     rule designator of the feature carrying it (`terminal`, `gate`, `campus`) and by the name taking a
- *     `<designator> <identifier>` or `<modifier> <designator>` shape.
- *   - **confound** — everything else, and the `confoundNote` says WHAT it is. A count with no note is
- *     not a census; "3,274 hits" told nobody that 3,205 of them were bus stops named after a village
- *     hall.
- *
- *   The instrument is `context` on {@link SubVenueSurface} plus the name-shape split; both are
- *   reproducible from the committed extracts, and `PROVENANCE.md` records the commands.
- *
- *   ── A rejection is a deliverable ─────────────────────────────────────────────────────────────────
- *   Rejections stay in this table forever. They are what stops the next contributor re-proposing
- *   `hall` for en-GB from the same Wikidata concept that proposed it the first time.
+ *   The hand-authored ledger of per-locale decisions on sub-venue designator surfaces.
  */
 
 /**
- * One curation decision.
+ * One curation decision about a designator phrase in one locale.
+ *
+ * Decisions are per locale because the same token can be a designator in one language
+ * and a common confound in another.
  */
 export interface SubVenuePromotion {
 	/**
-	 * The {@link SubVenueDesignator.id} the phrase is a surface of.
+	 * The {@link SubVenueDesignator.id} that the phrase belongs to.
 	 */
 	designatorID: string
 	/**
-	 * The exact normalized surface being decided on — `halle`, not `hall`, when the German form is at issue.
+	 * The exact normalized phrase, such as `halle` for the German form of `hall`.
 	 */
 	phrase: string
 	/**
-	 * BCP-47-ish `<lang>-<REGION>`. The region half is matched against a surface's `region` and the language half against
-	 * its `lang`, so `de-DE` reaches both a German Wikidata label (region-free) and a German extract's untagged name.
+	 * A `<lang>-<region>` locale.
+	 *
+	 * The language part matches a surface's `lang`, and the region part matches its `region`.
 	 */
 	locale: string
 	decision: "promote" | "reject"
 	/**
-	 * Set when the board's verdict is valid ONLY under a syntactic shape — the machine-readable half of a shape-separable
-	 * confound. `identifier-required` means the phrase is promoted solely in `<phrase> <identifier>` position (Halle 8);
-	 * bare occurrences stay unpromoted. A consumer that reads promotions MUST honour this field: the de-DE `halle` board
-	 * (2026-08-05 five-whys review) is the founding case — its 168-hit confound includes the CITY Halle (Saale), and the
-	 * 32/32-real enumeration that justified promotion was an enumeration of the identifier-bearing shape, not of the
-	 * phrase. Absent = the promotion holds in any shape.
+	 * A shape restriction on a promotion.
+	 *
+	 * `identifier-required` promotes the phrase only as `<phrase> <identifier>`, such as `Halle 8`.
+	 * Consumers must honor it, because the bare German `Halle` is also a city.
+	 * Without this field, the promotion holds in any shape.
 	 */
 	shape?: "identifier-required"
 	/**
-	 * Occurrences judged genuine venue-interior structure in that locale's census.
+	 * The count of census hits that are real venue-interior structure.
 	 */
 	real: number
 	/**
-	 * Occurrences judged confound.
+	 * The count of census hits that are confounds.
 	 */
 	confound: number
 	/**
-	 * What the confound half IS. Required prose — a bare number is not a board.
+	 * A description of what the confound hits are.
 	 */
 	confoundNote: string
 	/**
-	 * Which extract or dataset the census was taken over, and when.
+	 * The extract or dataset that the census counted, plus the census date.
 	 */
 	census: string
 }
 
 /**
- * The ledger. Sorted by designator, then locale, then phrase in the emitted artifact; source order here is grouped by
- * designator for reading.
+ * Every curation decision, grouped by designator.
+ *
+ * This ledger is the only input that sets `curated: true` on a machine-derived surface.
+ * Rejections stay in the ledger so the system can reject duplicate proposals until new evidence arrives.
  *
- * ── A rejection of a SHIPPED designator is ADVISORY ──────────────────────────────────────────────
- * `neural/venue-structure.ts` ships `wing`, `terminal`, `concourse` and six more as a FLAT English vocabulary with no
- * locale gate. Nothing in this table can un-ship them: the `wing` / en-US rejection below tells a slice author which
- * locale to exclude from a generated line, and does not stop the span proposer from firing on "Red Wing". Giving the
- * shipped vocabulary a per-locale gate is the largest thing the slice will want that does not exist yet.
+ * The span proposer in `packages/neural/lib/venue-structure.ts` ships its English designators
+ * without a locale gate, so a rejection here guides recipes only and does not stop the proposer.
  */
 export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
-	// ── wing ────────────────────────────────────────────────────────────────────────────────────────
-	// The designator the corpus task's board rests on (`West Wing` is the one modifier case that
-	// already parses), and the cleanest per-locale split in the whole exercise.
+	// wing
 	{
 		designatorID: "wing",
 		phrase: "wing",
@@ -134,14 +103,12 @@ export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
 		real: 0,
 		confound: 26,
 		confoundNote:
-			"Wing Chun and Wing Tsun martial-arts clubs, 15 of 26. Nothing in the French slice of the layer is a " +
+			"Wing Chun and Wing Tsun martial-arts clubs, 15 of 26. Nothing in the French partition of the layer is a " +
 			"building wing.",
 		census: "poi.db 2026-05-20.0, full scan 2026-08-05 (FR partition, 721,352 rows)",
 	},
 
-	// ── hall ────────────────────────────────────────────────────────────────────────────────────────
-	// Wave 1 flagged `hall` as per-locale poison on a GB number alone. Two locales measured; both
-	// reject, and for DIFFERENT reasons, which is the part worth keeping.
+	// hall
 	{
 		designatorID: "hall",
 		phrase: "hall",
@@ -204,9 +171,8 @@ export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
 		census: "france.jsonl 2026-08-05 (251,260 rows), 40 hits; all 19 shape hits enumerated",
 	},
 
-	// ── gate ────────────────────────────────────────────────────────────────────────────────────────
-	// The English surface ships and is deliberately NOT modifier-eligible. These decide its localized
-	// forms, and the two land on opposite sides for a reason worth keeping.
+	// gate: the English surface ships without modifier eligibility.
+	// These entries cover its localized forms.
 	{
 		designatorID: "gate",
 		phrase: "flugsteig",
@@ -238,9 +204,7 @@ export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
 		census: "france.jsonl 2026-08-05 (251,260 rows), 946 hits; all 36 shape hits enumerated",
 	},
 
-	// ── pier ────────────────────────────────────────────────────────────────────────────────────────
-	// New in wave 2, and the second clean per-locale split: promotable in en-GB, killed in en-US by a
-	// furniture chain whose name is exactly the designator+identifier shape.
+	// pier
 	{
 		designatorID: "pier",
 		phrase: "pier",
@@ -269,9 +233,8 @@ export const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[] = [
 		census: "poi.db 2026-05-20.0, full 13,681,698-row scan 2026-08-05",
 	},
 
-	// ── terminal ────────────────────────────────────────────────────────────────────────────────────
-	// The English surface already ships. These promote the LOCALIZED forms, which is what a non-English
-	// slice line needs and what wave 1 had none of.
+	// terminal: the English surface ships.
+	// These entries cover its localized forms.
 	{
 		designatorID: "terminal",
 		phrase: "terminal",

package/lib/subvenue/surfaces.ts

@@ -0,0 +1,94 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * @file Surface-form primitives for the sub-venue lexicon. They normalize phrases and index records by phrase.
+ * They also decide whether a feature name contains a known designator.
+ *
+ * The two matching rules depend on script. Both narrowings are required.
+ */
+
+import { normalizeWhitespace } from "@mailwoman/core/strings/format"
+
+import type { SubVenueSurface } from "#subvenue/table"
+
+/**
+ * Scripts whose case is meaningful to fold.
+ * Everything else is left as written.
+ */
+const CASE_FOLDING_SCRIPT = /^[\p{Script=Latin}\p{Script=Cyrillic}\p{Script=Greek}\d\s\p{P}]+$/u
+
+/**
+ * Scripts written without spaces between words, where a token split cannot find a
+ * designator and a substring test is the correct operator.
+ *
+ * Han, Hiragana and Katakana.
+ * Hangul is excluded because Korean does space its words.
+ *
+ * The Germanic-compound argument that keeps {@link nameContainsSurfaces}
+ * token-bounded for Latin does not transfer here.
+ */
+const NON_SPACING_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u
+
+/**
+ * Normalize a surface for the table by trimming, collapsing internal whitespace,
+ * then lowercasing only when the string is entirely in a bicameral script.
+ */
+export function normalizeSurface(text: string): string {
+	const trimmed = normalizeWhitespace(text)
+
+	return CASE_FOLDING_SCRIPT.test(trimmed) ? trimmed.toLowerCase() : trimmed
+}
+
+/**
+ * A phrase-to-record index keyed by the normalized phrase.
+ * It attributes a matched phrase to its record.
+ */
+export type SurfaceIndex = ReadonlyMap<string, { recordID: string; recordKind: "designator" | "modifier" }>
+
+/**
+ * Index the surfaces accumulated so far by phrase.
+ *
+ * First writer wins, so a seed record beats a Wikidata alias that happens to collide.
+ */
+export function buildSurfaceIndex(surfaces: readonly SubVenueSurface[]): SurfaceIndex {
+	const index = new Map<string, { recordID: string; recordKind: "designator" | "modifier" }>()
+
+	for (const surface of surfaces) {
+		if (index.has(surface.phrase)) continue
+		index.set(surface.phrase, { recordID: surface.recordID, recordKind: surface.recordKind })
+	}
+
+	return index
+}
+
+/**
+ * Every known phrase found in `name`, as whole-token runs for spacing scripts
+ * and as substrings for non-spacing ones.
+ *
+ * Latin matching is token-bounded rather than substring, so `Nordterminal` is a deliberate miss.
+ * Han and Kana have no word boundaries, so the longest known substring is the correct operator there.
+ */
+export function nameContainsSurfaces(name: string, index: SurfaceIndex): string[] {
+	const normalized = normalizeSurface(name)
+	const hits = new Set<string>()
+
+	for (const token of normalized.split(/[\s,()/]+/u)) {
+		const stripped = token.replaceAll(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "")
+
+		if (stripped && index.has(stripped)) {
+			hits.add(stripped)
+		}
+	}
+
+	if (NON_SPACING_SCRIPT.test(normalized)) {
+		for (const [phrase] of index) {
+			if (NON_SPACING_SCRIPT.test(phrase) && normalized.includes(phrase)) {
+				hits.add(phrase)
+			}
+		}
+	}
+
+	return [...hits]
+}