@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/tools/sub/venue/head-nouns.ts

@@ -3,28 +3,22 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   @file Head-noun derivation for the sub-venue lexicon — proposing the ADDRESSED form of a designator
- *   from the encyclopaedic label a vocabulary source carries.
+ * @file Head-noun derivation for the sub-venue lexicon — proposing the addressed form of a designator
+ * from the encyclopaedic label a vocabulary source provides.
  *
- *   Wikidata's label for a concept is the encyclopaedic name (`terminal aeroportuaria`, `letištní
- *   terminál`, `havalimanı terminali`), while the addressed form is the bare head (`Terminal`,
- *   `Terminál`, `Terminali`). Nothing can promote the encyclopaedic form, so the head has to be
- *   extracted before the curation pass has anything to decide about — that gap is why the first wave of
- *   this table shipped 1,014 uncurated surfaces.
- *
- *   Everything derived lands `curated: false`. A derivation is a HYPOTHESIS about what the addressed
- *   form is; a locale's own data is what confirms or kills it.
+ * Everything derived lands `curated: false`, because a derivation is a hypothesis a locale's own data confirms or kills.
  */
 
 import { isPresent } from "@mailwoman/core/objects"
 
-import type { SubVenueSurface } from "#tools/sub/venue/table"
+import type { SubVenueSurface } from "#subvenue/table"
 
 /**
- * Diacritic-flattened ASCII fold, for comparing a Slavic or Turkish inflection against its Latin root.
+ * Diacritic-flattened ascii fold, for comparing a Slavic or Turkish inflection against its Latin root.
  *
- * Deliberately `\p{Diacritic}` rather than `@mailwoman/normalize/fold`'s `stripCombiningMarks` (`\p{M}`): the two
- * classes diverge outside plain diacritics, and {@link HEAD_NOUN_PREFIX_FLOOR} was calibrated against this exact fold.
+ * Deliberately `\p{Diacritic}` rather than `@mailwoman/normalize/fold`'s
+ * `stripCombiningMarks` (`\p{M}`), because the two diverge outside plain diacritics
+ * and {@link HEAD_NOUN_PREFIX_FLOOR} was calibrated against this fold.
  */
 function asciiFold(text: string): string {
 	return text
@@ -34,74 +28,50 @@ function asciiFold(text: string): string {
 }
 
 /**
- * How many leading characters two ASCII-folded forms must share for one to count as the other's inflection.
+ * How many leading characters two ascii-folded forms must share for one to count as the other's inflection.
  *
- * Five, or the id's own length when that is shorter (`hall`, `gate`, `wing`, `pier` are four). Measured against the
- * committed Wikidata pull: at five, `terminal`/`terminál`/`terminale`/`terminali`/`terminála`/`terminalo` are all
- * accepted for `terminal` while `campo` and `campws` are both rejected for `campus` (they share four). At six the
- * Spanish `satélite` is lost; at four, Italian `campo` is admitted and it means FIELD.
+ * Five, or the id's own length when shorter.
+ * A limit of six loses Spanish `satélite`.
+ * A limit of four admits Italian `campo`, which means field.
  */
 const HEAD_NOUN_PREFIX_FLOOR = 5
 
 /**
- * The shortest substring a non-Latin head-noun candidate may be. Two: `航站` and `터미널` are both real, `楼` alone is
- * "building" and would fire on every Chinese building name.
+ * The shortest substring a non-Latin head-noun candidate may be.
+ *
+ * Two, because `楼` by itself means "building" and would fire on every Chinese building name.
  */
 const NON_LATIN_HEAD_MIN_LENGTH = 2
 
 /**
- * How many head-noun candidates one non-Latin record+language group may contribute. Six — enough to carry `ターミナル`,
- * `ターミナルビル` and `旅客ターミナル` together, capped because the substring lattice of a nine-character label is large and, ranked
- * by attesting-surface count, nothing past the sixth has more than the minimum two.
+ * How many head-noun candidates one non-Latin record+language group may contribute.
+ *
+ * Six, capped because the substring lattice of a nine-character label is large
+ * and no entry past the sixth attests more than two surfaces.
  */
 const NON_LATIN_HEAD_CANDIDATE_CAP = 6
 
 /**
- * Latin-script test — the scripts an ASCII-folded prefix comparison against a Latin designator id can work on.
+ * The scripts an ascii-folded prefix comparison against a Latin designator id can work on.
  */
 const LATIN_PHRASE = /^[\p{Script=Latin}\d\s\p{P}]+$/u
 
 /**
- * The scripts the shared-substring derivation is allowed to run on: Han, Hiragana, Katakana, Hangul.
+ * The scripts the shared-substring derivation may run on: Han, Hiragana, Katakana, Hangul.
  *
- * NARROWER than "not Latin", and the narrowing was earned. Run over every non-Latin phrase in the table, the derivation
- * produced 90 fragments of Cyrillic, Greek, Arabic, Thai, Burmese and Tamil words — `сгра`, `град`, `κτίρ`,
- * `ิ่งก่อสร้า` — because those languages have exactly one surface per concept and the only substrings shared inside a
- * group are pieces of one word. Every one of them was unusable, and none could ever be counted: `poi.db` is four
- * countries and this wave's extracts are GB, DE, FR, ES and JP, so nothing in reach attests a Thai or Burmese surface.
- * Deriving a candidate no available source can confirm is not a hypothesis, it is table weight.
+ * Narrower than a general non-Latin filter.
+ * A wider run produced unusable fragments in six scripts: Cyrillic, Greek, Arabic, Thai, Burmese or Tamil.
+ * No available extract attests those surfaces.
  */
 const SHARED_SUBSTRING_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u
 
 /**
- * Derive the HEAD NOUN of every multi-part surface, so `terminal aeroportuaria` contributes the form anyone actually
- * writes on an envelope.
- *
- * The problem this solves is the whole reason wave 1 shipped 1,014 uncurated surfaces: Wikidata's label for a concept
- * is the ENCYCLOPAEDIC name (`terminal aeroportuaria`, `letištní terminál`, `havalimanı terminali`), while the
- * addressed form is the bare head (`Terminal`, `Terminál`, `Terminali`). Nothing can promote the encyclopaedic form, so
- * the head has to be extracted before the curation pass has anything to decide about.
+ * Derive the head noun of every multi-part surface, so `terminal aeroportuaria`
+ * contributes the form anyone actually writes on an envelope.
  *
- * Two derivations, because the table holds two kinds of writing:
- *
- * - **Latin script — the COGNATE test.** A token is the head when its ASCII fold shares {@link HEAD_NOUN_PREFIX_FLOOR}
- *   leading characters with the designator's own canonical id. Nothing subtler survived contact with the data: an
- *   earlier version matched a token against any SINGLE-TOKEN surface of the record, and because Dutch `universiteit` is
- *   a one-token surface of `campus`, it derived `universitario`, `universitaire`, `üniversite` and twenty more as head
- *   nouns of `campus`. Those are the MODIFIER half of the label, and admitting them would have taught the harvest to
- *   read "Ciudad Universitaria" as sub-venue structure.
- * - **Non-Latin script — the SHARED-SUBSTRING test.** The cognate test cannot reach a script the id is not written in,
- *   and for Han and Kana a token split finds nothing at all. So every substring of length ≥
- *   {@link NON_LATIN_HEAD_MIN_LENGTH} occurring in at least two DISTINCT surfaces of the same record and primary
- *   language becomes a candidate, ranked by how many surfaces carry it. Japanese yields `ターミナル` (in all five `ja`
- *   terminal labels) ahead of `ターミナルビル` (three); Chinese yields `航站`, `航站楼`, `航站樓`. Where the script DOES space its
- *   words (Korean, Greek, Cyrillic) a candidate must be a whole token, so `공항 터미널` ∩ `공항터미널` gives `터미널` and never a
- *   fragment.
- *
- * The non-Latin branch deliberately emits SEVERAL candidates instead of picking one. Choosing between `航站` and `航站楼`
- * from Wikidata alone is guesswork; the Japan extract answers it by counting, and the promotion ledger records which
- * count won. Everything derived lands `curated: false` — the derivation is a hypothesis about what the addressed form
- * is, and a locale's own data is what confirms or kills it.
+ * Latin script uses a cognate test against the designator's own canonical id.
+ * Han and Kana use a shared substring, because a token split finds no boundary there.
+ * Everything derived lands `curated: false`.
  */
 export function deriveHeadNounSurfaces(surfaces: readonly SubVenueSurface[]): SubVenueSurface[] {
 	const derived = new Map<string, SubVenueSurface>()
@@ -127,8 +97,6 @@ export function deriveHeadNounSurfaces(surfaces: readonly SubVenueSurface[]): Su
 		})
 	}
 
-	// ── Spacing scripts: prefix-match a token against a single-token surface of the same record ──────
-	// Latin script: a token that is a cognate of the designator's own canonical id.
 	for (const surface of surfaces) {
 		if (!LATIN_PHRASE.test(surface.phrase)) continue
 
@@ -148,14 +116,13 @@ export function deriveHeadNounSurfaces(surfaces: readonly SubVenueSurface[]): Su
 		}
 	}
 
-	// Non-Latin script: substrings shared by two or more surfaces of the same record + language.
 	const groups = new Map<string, Set<string>>()
 
 	for (const surface of surfaces) {
 		if (!SHARED_SUBSTRING_SCRIPT.test(surface.phrase)) continue
 
-		// Group `zh`, `zh-cn`, `zh-hant` together: they are writing systems for one vocabulary, and the
-		// simplified/traditional pair is exactly the evidence a shared substring needs.
+		// Group `zh`, `zh-cn`, and `zh-hant` as writing systems for one vocabulary.
+		// The simplified/traditional pair supports a shared substring.
 		const key = `${surface.recordID} ${surface.lang.split(/[-_]/u)[0]!}`
 		const pool = groups.get(key) ?? new Set<string>()
 		pool.add(surface.phrase)
@@ -184,9 +151,6 @@ export function deriveHeadNounSurfaces(surfaces: readonly SubVenueSurface[]): Su
 	return [...derived.values()]
 }
 
-/**
- * Length of the shared leading run of two strings.
- */
 function commonPrefixLength(a: string, b: string): number {
 	const limit = Math.min(a.length, b.length)
 	let i = 0
@@ -199,16 +163,15 @@ function commonPrefixLength(a: string, b: string): number {
 }
 
 /**
- * Substrings occurring in at least two DISTINCT members of `pool`, ranked by that count and then by length, capped at
- * {@link NON_LATIN_HEAD_CANDIDATE_CAP}.
+ * Substrings occurring in at least two distinct members of `pool`, ranked by that count
+ * then length, capped at {@link NON_LATIN_HEAD_CANDIDATE_CAP}.
  *
- * A candidate never spans whitespace, and in a pool whose members contain whitespace a candidate must be a whole token
- * of some member. That is what keeps Korean `공항 터미널` from contributing a fragment straddling the space.
+ * A candidate never spans whitespace.
+ * Where a pool member has spaces, the candidate must be a whole token.
  *
- * MAXIMAL candidates only: one contained in a longer candidate carried by the SAME number of surfaces is dropped, since
- * counting can never separate the two. Every one of `ターミナル`'s five ja labels also contains `ターミ`, `ターミナ` and `ミナル`, so
- * without this the group contributes four indistinguishable candidates and the Japan harvest returns four identical
- * counts. `航站` survives next to `航站楼` because six surfaces carry it against that one's two.
+ * This keeps Korean `공항 터미널` from contributing a fragment across the space.
+ * Maximal candidates only: one contained in a longer candidate produced by the same
+ * number of surfaces is dropped, since counting can never separate the two.
  */
 function sharedSubstringCandidates(pool: ReadonlySet<string>): string[] {
 	const phrases = [...pool]

package/lib/tools/sub/venue/lexicon.ts

@@ -3,50 +3,19 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   @file Build the sub-venue designator lexicon (#35) — the vocabulary a corpus slice and, eventually,
- *   the span proposer read to recognize `Terminal 5`, `North Terminal`, `Concourse B`, `ターミナル1` as
- *   venue-INTERIOR structure. This is the assembly: the record schema lives in `sub-venue/table.ts`, the
- *   implementation in its siblings, and the curation decisions in `sub-venue-promotions.ts`.
- *
- *   Reads the fetch outputs (`mailwoman corpus fetch wikidata-subvenue`, a JSONL of
- *   `@mailwoman/osm/sdk`'s `SubVenueSourceRow`s per region, and the Overture slice of `poi.db` via
- *   `overture-subvenue.ts`) and emits one committed JSON table.
- *
- *   ── Determinism ──────────────────────────────────────────────────────────────────────────────────
- *   {@link buildSubVenueLexicon} is a PURE function of its inputs with a stable sort on every array, so
- *   a regenerate against the same fetch outputs is byte-identical. No timestamp is emitted for the same
- *   reason `taxonomy.json` carries none — a clock in the artifact makes every regenerate a diff.
- *   Vintages live in `sources[]`, taken from the fetch manifests.
- *
- *   ── Where the stages live ────────────────────────────────────────────────────────────────────────
- *   Each stage carries the measurements that shaped it; the order they run in is
- *   {@link buildSubVenueLexicon}'s own docstring, and it is required.
- *
- *   - `sub-venue/table.ts` — the emitted record schema plus the shipped seed vocabulary.
- *   - `sub-venue/surfaces.ts` — phrase normalization, the phrase → record index, and the name-match
- *     operator that gates the harvest.
- *   - `sub-venue/wikidata.ts` — the designator-label SPARQL payload turned into surfaces.
- *   - `sub-venue/head-nouns.ts` — the addressed form derived from an encyclopaedic label.
- *   - `sub-venue/harvest.ts` — the harvestable row shape, its JSONL reader, and the attestation pass.
- *
- *   ── What `curated: false` means, and how a surface stops being it ────────────────────────────────
- *   Every machine-derived surface lands `curated: false`, and {@link SubVenueLexiconTable} consumers
- *   that gate parsing MUST filter to `curated: true`. A surface becomes curated ONLY by matching a
- *   {@link SubVenuePromotion} in `sub-venue-promotions.ts` — a per-designator, per-LOCALE decision
- *   carrying the census that backs it. Promotion is per-locale because the same token is a designator in
- *   one language and a disaster in another: `hall` is `Halle 2` at Frankfurt and `Village Hall` at 3,205
- *   British bus stops.
+ *   @file Builds the sub-venue designator lexicon from Wikidata, OSM and Overture fetch outputs.
  */
 
-import { readLocalJSONFile, statPath } from "@mailwoman/core/fs/readers"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import { statPath } from "@mailwoman/core/fs/readers/stat"
 import { writeLocalFile } from "@mailwoman/core/fs/writers"
+import { prettyJSON } from "@mailwoman/core/json"
 import { isoDate } from "@mailwoman/core/utils"
-import { basename, join } from "path-ts"
+import { basename, PathBuilder, type PathBuilderLike } from "path-ts"
 
-import { extractAttestedPhrases, readSubVenueJSONL, type SubVenueHarvestRow } from "#tools/sub/venue/harvest"
-import { deriveHeadNounSurfaces } from "#tools/sub/venue/head-nouns"
-import { SUBVENUE_PROMOTIONS, type SubVenuePromotion } from "#tools/sub/venue/promotions"
-import { buildSurfaceIndex } from "#tools/sub/venue/surfaces"
+import { extractAttestedPhrases, readSubVenueJSONL, type SubVenueHarvestRow } from "#subvenue/harvest"
+import { SUBVENUE_PROMOTIONS, type SubVenuePromotion } from "#subvenue/promotions"
+import { buildSurfaceIndex } from "#subvenue/surfaces"
 import {
 	CONCEPT_QIDS,
 	type IdentifierShape,
@@ -60,32 +29,24 @@ import {
 	type SubVenueModifier,
 	type SubVenueSurface,
 	SUBVENUE_LEXICON_VERSION,
-} from "#tools/sub/venue/table"
+} from "#subvenue/table"
+import { deriveHeadNounSurfaces } from "#tools/sub/venue/head-nouns"
 import { surfacesFromWikidata } from "#tools/sub/venue/wikidata"
 
-export * from "#tools/sub/venue/harvest"
-export * from "#tools/sub/venue/head-nouns"
-export * from "#tools/sub/venue/surfaces"
-export * from "#tools/sub/venue/table"
-export * from "#tools/sub/venue/wikidata"
-
 /**
- * Apply the curation decisions to a surface list, IN PLACE on a copy.
+ * Returns a copy of the surfaces with `curated: true` set on each surface that a promotion matches.
  *
- * A promotion binds `(designatorID, phrase, locale)`. A surface matches when it names the same record with the same
- * phrase and its language is the locale's language OR the untagged `und` — the default `name` tag carries no language,
- * and a German extract's untagged `Halle 2` is German.
+ * A promotion matches a surface with the same record id and phrase whose language
+ * is the promotion's language or `und`.
+ * An extract surface must also come from the promotion's region.
  *
- * REGION is the subtle half. A surface attested in an extract carries that extract's region and matches only its own
- * locale. A surface with `region: ""` is region-FREE — a Wikidata label or a derived head noun — and a promotion
- * reaches it only when no REJECTION exists for the same designator, phrase and language anywhere else. That guard is
- * not decoration: `pier` is promoted for en-GB and rejected for en-US, and without it the en-GB decision would curate
- * the region-free English surface and hand `Pier 1 Imports` the promotion en-US was refused. Where no rejection
- * competes — `terminal` in `es`, `ターミナル` in `ja` — the region-free surface is the whole point, since a language's
- * designator does not stop at a border.
+ * A surface without a region, such as a Wikidata label, matches only when no rejection
+ * exists for the same designator, phrase and language in any region.
+ * For example, `pier` is promoted for en-GB and rejected for en-US,
+ * so the region-free English `pier` stays uncurated.
  *
- * Rejections mark nothing themselves. They exist in `promotions[]` as the record of a decision taken, so the next
- * reader meets en-GB `hall`'s 3,204 bus stops before re-proposing it, not after.
+ * Rejections never mark a surface.
+ * They stay in the table as a record of the decision.
  */
 export function applyPromotions(
 	surfaces: readonly SubVenueSurface[],
@@ -122,7 +83,7 @@ export function applyPromotions(
 }
 
 /**
- * One harvestable input: rows plus the stamp they carry into the table.
+ * One harvest input with the source and region stamped on its surfaces.
  */
 export interface SubVenueHarvest {
 	rows: readonly SubVenueHarvestRow[]
@@ -131,41 +92,42 @@ export interface SubVenueHarvest {
 }
 
 /**
- * Everything {@link buildSubVenueLexicon} needs, already parsed. Keeping the builder off the filesystem is what makes it
- * deterministic and testable without fixtures on disk.
+ * The parsed inputs of {@link buildSubVenueLexicon}, which never reads the filesystem.
  */
 export interface BuildSubVenueLexiconInput {
 	/**
-	 * The raw `designator-labels.json` SPARQL envelope, or `null` to build the seed-only table.
+	 * The raw `designator-labels.json` SPARQL response, or `null` to build the seed-only table.
 	 */
 	wikidata: unknown | null
 	/**
-	 * Every harvestable source, in the order they should contribute. Order matters only for the surface INDEX: a source
-	 * can match a phrase an earlier source introduced, never a later one.
+	 * The harvest inputs in contribution order.
+	 *
+	 * Each harvest can match only phrases that exist before it runs, including those from earlier harvests.
 	 */
 	harvests: readonly SubVenueHarvest[]
 	/**
-	 * Provenance rows, copied off the fetch manifests by the caller.
+	 * Provenance rows that the caller copies from the fetch manifests.
 	 */
 	sources: readonly SubVenueLexiconSource[]
 	/**
-	 * Curation decisions. Defaults to the committed {@link SUBVENUE_PROMOTIONS}; pass an empty array to build the
-	 * pre-curation table (which is what the promotion census itself is taken against).
+	 *
+	 * An empty array builds the uncurated table.
+	 *
+	 * @defaultValue {@linkcode SUBVENUE_PROMOTIONS}
 	 */
 	promotions?: readonly SubVenuePromotion[]
 }
 
 /**
- * Build the lexicon table. PURE and deterministic — same inputs, byte-identical output.
+ * Builds the lexicon table deterministically, so identical inputs produce identical output.
  *
- * Order of operations is required in three places:
+ * Three ordering rules apply:
  *
- * 1. Seed surfaces are inserted before anything else, so `terminal` indexes to the `terminal` designator rather than to
- *    whichever Wikidata alias sorts first.
- * 2. Head nouns are derived AFTER Wikidata and BEFORE the harvests, because `ターミナル` has to exist as a surface before a
- *    Japanese extract can be searched for it. That ordering is the entire reason the Japan harvest finds anything — see
- *    `PROVENANCE.md`.
- * 3. Promotions are applied LAST, over the union, so a decision can promote a surface whichever source produced it.
+ * 1. Seed surfaces come first, so `terminal` indexes to the `terminal` designator
+ *    instead of a Wikidata alias.
+ * 2. Head nouns are derived after Wikidata and before the harvests, because a harvest
+ *    can find only phrases such as `ターミナル` that already exist as surfaces.
+ * 3. Promotions apply last, so they can curate a surface from any source.
  */
 export function buildSubVenueLexicon(input: BuildSubVenueLexiconInput): SubVenueLexiconTable {
 	const designators: SubVenueDesignator[] = SHIPPED_DESIGNATOR_SEED.map((seed) => ({
@@ -199,8 +161,7 @@ export function buildSubVenueLexicon(input: BuildSubVenueLexiconInput): SubVenue
 		byID.set(record.id, record)
 	}
 
-	// A Wikidata concept id is provenance for the designator it names, whether or not the concept
-	// contributed a usable surface.
+	// A designator records its Wikidata concept id even when the concept contributes no surface.
 	for (const [id, qid] of Object.entries(CONCEPT_QIDS)) {
 		const record = byID.get(id)
 
@@ -223,7 +184,7 @@ export function buildSubVenueLexicon(input: BuildSubVenueLexiconInput): SubVenue
 			lang: "en",
 			region: "",
 			source: "seed",
-			// The English designator IS the shipped vocabulary — curated by construction.
+			// Shipped English designators count as curated.
 			curated: d.shipped,
 			observations: 0,
 			context: {},
@@ -262,8 +223,7 @@ export function buildSubVenueLexicon(input: BuildSubVenueLexiconInput): SubVenue
 	const promotions = [...(input.promotions ?? SUBVENUE_PROMOTIONS)]
 	const curated = applyPromotions(surfaces, promotions)
 
-	// Deterministic order everywhere. `localeCompare` matches the tie-break discipline
-	// `generate-taxonomy.ts` and `build-brands.ts` already use.
+	// Every array is sorted so that the output is stable.
 	designators.sort((a, b) => a.id.localeCompare(b.id))
 	modifiers.sort((a, b) => a.id.localeCompare(b.id))
 
@@ -298,15 +258,16 @@ export function buildSubVenueLexicon(input: BuildSubVenueLexiconInput): SubVenue
 }
 
 /**
- * Serialize the table the way the committed artifact stores it: pretty-printed, trailing newline. Run `oxfmt` over the
- * result before committing — repo law is that committed JSON is oxfmt-clean, which `JSON.stringify` cannot reproduce.
+ * Serializes the table as pretty-printed JSON.
+ *
+ * Run `oxfmt` over the written file before committing, because committed JSON must match oxfmt's output.
  */
 export function serializeSubVenueLexicon(table: SubVenueLexiconTable): string {
-	return JSON.stringify(table, null, 2) + "\n"
+	return prettyJSON(table)
 }
 
 /**
- * The Wikidata fetch manifest's shape, narrowed to the fields the lexicon copies into `sources[]`.
+ * The fields of the Wikidata fetch manifest that the lexicon copies into `sources[]`.
  */
 interface WikidataFetchManifest {
 	endpoint?: string
@@ -316,42 +277,48 @@ interface WikidataFetchManifest {
 }
 
 /**
- * One OSM extract to harvest: the JSONL path plus the ISO country its rows describe.
+ * One OSM extract to harvest, with the ISO country code of its rows.
  */
 export interface SubVenueExtractInput {
 	path: string
 	region: string
 }
 
+/**
+ * Options for {@link generateSubVenueLexicon}.
+ */
 export interface GenerateSubVenueLexiconOptions {
 	/**
-	 * Directory holding the `mailwoman corpus fetch wikidata-subvenue` output. Omit to build the seed-only table.
+	 * The output directory of `mailwoman corpus fetch wikidata-subvenue`.
+	 *
+	 * Without it, the function builds the seed-only table.
 	 */
-	wikidataDir?: string
+	wikidataDir?: PathBuilderLike
 	/**
-	 * OSM extract JSONLs, one per region.
+	 * OSM extract JSONL files, one per region.
 	 */
 	extracts?: readonly SubVenueExtractInput[]
 	/**
-	 * Already-read Overture rows (`readOvertureSubVenues`), grouped by the caller. Kept as a parameter rather than a path
-	 * so this function stays free of a 3.9 GB database dependency — the CLI opens `poi.db`, this assembles.
+	 * Overture rows that the caller already read with `readOvertureSubVenues`.
+	 *
+	 * The caller opens `poi.db`, so this function does not depend on the database.
 	 */
 	overtureRows?: readonly (SubVenueHarvestRow & { country: string })[]
 	/**
-	 * `poi.db`'s layer vintage, for `sources[]`. Only read when `overtureRows` is non-empty.
+	 * The `poi.db` layer vintage.
+	 * The builder uses it only when `overtureRows` is non-empty.
 	 */
 	overtureVintage?: string
 	/**
-	 * Where the table is written.
+	 * The path of the written table.
 	 */
 	outPath: string
 }
 
 /**
- * Read the fetch outputs, build the table, and write it.
+ * Reads the fetch outputs, builds the table with {@link buildSubVenueLexicon}, and writes it.
  *
- * The IO half only — every decision lives in {@link buildSubVenueLexicon}, which is pure. Run `oxfmt` over `outPath`
- * afterwards; repo law is that committed JSON is oxfmt-clean.
+ * Run `oxfmt` over `outPath` afterwards, because committed JSON must match oxfmt's output.
  */
 export async function generateSubVenueLexicon(options: GenerateSubVenueLexiconOptions): Promise<SubVenueLexiconTable> {
 	const sources: SubVenueLexiconSource[] = []
@@ -359,9 +326,11 @@ export async function generateSubVenueLexicon(options: GenerateSubVenueLexiconOp
 	let wikidata: unknown = null
 
 	if (options.wikidataDir) {
-		wikidata = await readLocalJSONFile<unknown>(join(options.wikidataDir, "designator-labels.json"))
+		const wikidataDir = PathBuilder.from(options.wikidataDir)
+
+		wikidata = await readLocalJSONFile<unknown>(wikidataDir("designator-labels.json"))
 
-		const manifest = await readLocalJSONFile<WikidataFetchManifest>(join(options.wikidataDir, "MANIFEST.json"))
+		const manifest = await readLocalJSONFile<WikidataFetchManifest>(wikidataDir("MANIFEST.json"))
 
 		const labelFile = manifest.files?.find((f) => f.filename === "designator-labels.json")
 
@@ -369,8 +338,7 @@ export async function generateSubVenueLexicon(options: GenerateSubVenueLexiconOp
 			id: "wikidata",
 			origin: manifest.endpoint ?? "https://query.wikidata.org/sparql",
 			license: manifest.license ?? "CC0",
-			// The DATE only. A full ISO timestamp would make every re-fetch a diff in the committed artifact for
-			// no information a reader of a vocabulary table can act on.
+			// The table stores only the date so that a re-fetch on the same day produces no diff.
 			retrieved: (manifest.downloaded_at ?? "").slice(0, 10),
 			rows: labelFile?.rows ?? 0,
 		})
@@ -383,24 +351,17 @@ export async function generateSubVenueLexicon(options: GenerateSubVenueLexiconOp
 
 		sources.push({
 			id: `osm:${extract.region.toLowerCase()}`,
-			// The extract's NAME, never its path. `AGENTS.md` forbids re-hardcoding the lab data root
-			// anywhere, and a committed artifact carrying `/mnt/playpen/...` would do exactly that while
-			// telling a reader on another machine nothing. `great-britain` identifies the Geofabrik region,
-			// which is the fact that matters.
+			// The origin records the Geofabrik region name, because a local path would leak the data root.
 			origin: `OpenStreetMap via Geofabrik (${basename(extract.path, ".jsonl")})`,
 			license: "ODbL (OpenStreetMap)",
-			// The extract's mtime — when the rows were produced. `corpus/AGENTS.md`'s standing warning that
-			// a file's mtime is not its DATA's vintage applies to a downloaded archive; this file is a build
-			// output of ours, so its mtime is exactly the right number.
+			// The extract is a local build output, so its mtime is when its rows were produced.
 			retrieved: isoDate((await statPath(extract.path)).mtime),
 			rows: rows.length,
 		})
 	}
 
 	if (options.overtureRows?.length) {
-		// Overture rows carry their own country, so they are harvested per REGION rather than in one pass —
-		// a `region` on the surface is the axis promotion is decided on and a mixed-country bucket would
-		// make it meaningless.
+		// Promotions match on region, so the function harvests Overture rows one country at a time.
 		const byCountry = new Map<string, SubVenueHarvestRow[]>()
 
 		for (const row of options.overtureRows) {

package/lib/tools/sub/venue/wikidata.ts

@@ -3,23 +3,23 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   @file The Wikidata leg of the sub-venue lexicon — turning the designator-label SPARQL payload into
+ *   @file The Wikidata leg of the sub-venue lexicon — turning the designator-label sparql payload into
  *   surfaces.
  *
  *   Reads an already-parsed payload rather than issuing a query: the acquisition lives in
  *   `fetch/wikidata-subvenue.ts`, and keeping the conversion a pure function of parsed input is what
  *   lets the builder stay deterministic and testable with no network and no fixture on disk.
  *
- *   Wikidata gives a CONCEPT NAME per language, not a designator as addressed. Q849706's Spanish label
+ *   Wikidata gives a concept name per language rather than a designator as addressed. Q849706's Spanish label
  *   is `terminal aeroportuaria`; the addressed form is `Terminal`. So every surface produced here lands
  *   `curated: false`, and the head-noun derivation is what proposes the addressed form from it.
  */
 
-import { normalizeSurface } from "#tools/sub/venue/surfaces"
-import { CONCEPT_QIDS, type SubVenueSurface } from "#tools/sub/venue/table"
+import { normalizeSurface } from "#subvenue/surfaces"
+import { CONCEPT_QIDS, type SubVenueSurface } from "#subvenue/table"
 
 /**
- * The SPARQL results envelope, narrowed to the columns the designator-label query produces.
+ * The sparql results envelope, narrowed to the columns the designator-label query produces.
  */
 interface SPARQLBinding {
 	item?: { value: string }
@@ -35,9 +35,11 @@ interface SPARQLEnvelope {
 /**
  * Turn the Wikidata designator-label payload into surfaces.
  *
- * A row is dropped when its language tag is empty (an untagged literal, which Wikidata occasionally carries), when the
- * QID maps to no designator in {@link CONCEPT_QIDS}, or when the normalized phrase is empty. Everything that survives
- * lands `curated: false` — see the module docstring.
+ * Wikidata sometimes returns an untagged literal.
+ * The builder drops that row when its language tag is empty, when the QID maps to no
+ * designator in {@link CONCEPT_QIDS}, or when the normalized phrase is empty.
+ *
+ * Everything that survives lands `curated: false` — see the module docstring.
  */
 export function surfacesFromWikidata(
 	payload: unknown,
@@ -61,8 +63,9 @@ export function surfacesFromWikidata(
 		if (!phrase) continue
 
 		const source = binding.kind?.value === "alt" ? "wikidata:alt" : "wikidata:label"
-		// A concept can carry the same string as both a label and an alias, and across dialect subtags
-		// (`zh`, `zh-cn`, `zh-hans` all say 航站楼). Key the dedupe on the tuple that identifies a row.
+		// A concept can use the same string as a label and an alias.
+		// Dialect subtags can also repeat a phrase (`zh`, `zh-cn`, `zh-hans` all use 航站楼).
+		// Key the dedupe on the tuple that identifies a row.
 		const key = `${phrase}\0${recordID}\0${lang}\0${source}`
 
 		if (seen.has(key)) continue