@mailwoman/corpus 9.3.0 → 10.0.0

package/out/tools/sub/venue/harvest.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   @file The harvest side of the sub-venue lexicon: what one row of a harvestable source looks like,
+ *   how a file of them is read back, and what a pass over them extracts — attested surfaces plus the
+ *   measured shape of each designator's identifier half.
+ *
+ *   {@link SubVenueHarvestRow} is SOURCE-NEUTRAL, and verified so: an Overture Places row from the
+ *   `airport_terminal` category is `{ designatorID, name }` and fits unchanged. It is declared here
+ *   rather than imported so the builder does not take a dependency on `@mailwoman/osm` (which
+ *   `@mailwoman/corpus` does not depend on) just to name a shape it reads from a file.
+ *
+ *   Two measurements shape {@link extractAttestedPhrases}, and both are the reason it is safe to run
+ *   over raw OSM at all:
+ *
+ *   **A feature's `name` is usually the VENUE's name, not a sub-venue phrase.** On the Berlin extract
+ *   (2,060 matched features) a `railway=platform` is named `Stendaler Straße` and an `amenity=university`
+ *   is named `Hertie School`; across 250,116 named Great Britain features only 6,003 (2.40%) contain a
+ *   designator token at all. So names are not harvested wholesale — a name contributes only when it
+ *   CONTAINS a phrase already in the surface index, which is what makes `Terminal E (Untere Ebene)`
+ *   evidence and `Otto Lilienthal Flughafen Berlin Tegel` not.
+ *
+ *   **A matched phrase belongs to the record the PHRASE names, not the record the ROW carries.**
+ *   Attributing every hit to `row.designatorID` — the rule that matched the FEATURE — produced `west →
+ *   platform`, `hall → platform` and `biggin → platform` on the GB extract, because a bus stop tagged
+ *   `public_transport=platform` is named "Village Hall" or "West Kensington"; 108 of 133 OSM-derived
+ *   surfaces named a different record than the one they pointed at. Attribution therefore runs through
+ *   the index, and the row's own designator is kept as `context` — exactly the axis a confound board
+ *   needs, since a `hall` seen on a platform is a confound and a `hall` seen on a terminal is evidence.
+ */
+import { type SurfaceIndex } from "#tools/sub/venue/surfaces";
+import type { IdentifierShape, SubVenueSurface } from "#tools/sub/venue/table";
+/**
+ * One row of a harvestable source, as read back off JSONL or out of a layer database.
+ *
+ * SOURCE-NEUTRAL by design, and verified so in wave 2: an Overture Places row from the `airport_terminal` category is
+ * `{ designatorID, name }` and fits unchanged. What did NOT fit was the harvest function's hardcoded `osm:name` source
+ * stamp — see `overture-subvenue.ts`'s docstring. 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. Carried 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 slice 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 declare function classifyIdentifier(ref: string): string;
+/**
+ * Options for one harvest pass — which source stamp its surfaces carry and which region they were attested in.
+ *
+ * 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 also decides ATTRIBUTION: a hit is a surface of the record the PHRASE names, and the row's
+ * own designator is recorded as `context`.
+ *
+ * Returns surfaces with real `observations` counts, so the lexicon can rank `terminal` above a phrase attested once.
+ */
+export declare function extractAttestedPhrases(rows: Iterable<SubVenueHarvestRow>, index: SurfaceIndex, options?: HarvestOptions): {
+    surfaces: SubVenueSurface[];
+    identifierShapes: IdentifierShape[];
+};
+/**
+ * Read a JSONL file of {@link SubVenueHarvestRow}s. Blank lines and unparseable rows are skipped rather than fatal — an
+ * extract is a build output, and one malformed line should not cost the whole lexicon.
+ */
+export declare function readSubVenueJSONL(path: string): Promise<SubVenueHarvestRow[]>;
+//# sourceMappingURL=harvest.d.ts.map

package/out/tools/sub/venue/harvest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest.d.ts","sourceRoot":"","sources":["../../../../lib/tools/sub/venue/harvest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE9E;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAYD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAClC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,cAAmB,GAC1B;IAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAAC,gBAAgB,EAAE,eAAe,EAAE,CAAA;CAAE,CAiFtE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAmBnF"}

package/out/tools/sub/venue/harvest.js

@@ -0,0 +1,168 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   @file The harvest side of the sub-venue lexicon: what one row of a harvestable source looks like,
+ *   how a file of them is read back, and what a pass over them extracts — attested surfaces plus the
+ *   measured shape of each designator's identifier half.
+ *
+ *   {@link SubVenueHarvestRow} is SOURCE-NEUTRAL, and verified so: an Overture Places row from the
+ *   `airport_terminal` category is `{ designatorID, name }` and fits unchanged. It is declared here
+ *   rather than imported so the builder does not take a dependency on `@mailwoman/osm` (which
+ *   `@mailwoman/corpus` does not depend on) just to name a shape it reads from a file.
+ *
+ *   Two measurements shape {@link extractAttestedPhrases}, and both are the reason it is safe to run
+ *   over raw OSM at all:
+ *
+ *   **A feature's `name` is usually the VENUE's name, not a sub-venue phrase.** On the Berlin extract
+ *   (2,060 matched features) a `railway=platform` is named `Stendaler Straße` and an `amenity=university`
+ *   is named `Hertie School`; across 250,116 named Great Britain features only 6,003 (2.40%) contain a
+ *   designator token at all. So names are not harvested wholesale — a name contributes only when it
+ *   CONTAINS a phrase already in the surface index, which is what makes `Terminal E (Untere Ebene)`
+ *   evidence and `Otto Lilienthal Flughafen Berlin Tegel` not.
+ *
+ *   **A matched phrase belongs to the record the PHRASE names, not the record the ROW carries.**
+ *   Attributing every hit to `row.designatorID` — the rule that matched the FEATURE — produced `west →
+ *   platform`, `hall → platform` and `biggin → platform` on the GB extract, because a bus stop tagged
+ *   `public_transport=platform` is named "Village Hall" or "West Kensington"; 108 of 133 OSM-derived
+ *   surfaces named a different record than the one they pointed at. Attribution therefore runs through
+ *   the index, and the row's own designator is kept as `context` — exactly the axis a confound board
+ *   needs, since a `hall` seen on a platform is a confound and a `hall` seen on a terminal is evidence.
+ */
+import { readLocalTextFile } from "@mailwoman/core/fs/readers";
+import { parseJSONStrict } from "@mailwoman/core/json";
+import { TextSpliterator } from "spliterator";
+import { nameContainsSurfaces } from "#tools/sub/venue/surfaces";
+/**
+ * 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) {
+    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, not "all" and not one. The field exists so a slice 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, not a census.
+ */
+const IDENTIFIER_EXAMPLES_PER_SHAPE = 8;
+/**
+ * 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 also decides ATTRIBUTION: a hit is a surface of the record the PHRASE names, and the row's
+ * own 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, index, options = {}) {
+    const source = options.source ?? "osm";
+    const region = options.region ?? "";
+    /**
+     * `phrase\0lang\0source` → { count, context }.
+     */
+    const surfaceCounts = new Map();
+    /**
+     * `designatorID\0shape` → { count, examples }.
+     */
+    const shapes = new Map();
+    const note = (phrase, lang, sourceTag, context) => {
+        const key = `${phrase}\0${lang}\0${sourceTag}`;
+        const entry = surfaceCounts.get(key) ?? { count: 0, context: new Map() };
+        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 carries 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() };
+            entry.count++;
+            if (entry.examples.size < IDENTIFIER_EXAMPLES_PER_SHAPE) {
+                entry.examples.add(row.ref.trim());
+            }
+            shapes.set(key, entry);
+        }
+    }
+    const surfaces = [...surfaceCounts].map(([key, entry]) => {
+        const [phrase, lang, sourceTag] = key.split("\0");
+        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 = [...shapes].map(([key, entry]) => {
+        const [designatorID, shape] = key.split("\0");
+        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. Blank lines and unparseable rows are skipped rather than fatal — an
+ * extract is a build output, and one malformed line should not cost the whole lexicon.
+ */
+export async function readSubVenueJSONL(path) {
+    const out = [];
+    // `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))) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(parseJSONStrict(trimmed));
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=harvest.js.map

package/out/tools/sub/venue/harvest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest.js","sourceRoot":"","sources":["../../../../lib/tools/sub/venue/harvest.ts"],"names":[],"mappings":"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"}

package/out/tools/sub/venue/head-nouns.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ *
+ *   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.
+ */
+import type { SubVenueSurface } from "#tools/sub/venue/table";
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function deriveHeadNounSurfaces(surfaces: readonly SubVenueSurface[]): SubVenueSurface[];
+//# sourceMappingURL=head-nouns.d.ts.map

package/out/tools/sub/venue/head-nouns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-nouns.d.ts","sourceRoot":"","sources":["../../../../lib/tools/sub/venue/head-nouns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAuD7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,eAAe,EAAE,CA+E9F"}

package/out/tools/sub/venue/head-nouns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"head-nouns.js","sourceRoot":"","sources":["../../../../lib/tools/sub/venue/head-nouns.ts"],"names":[],"mappings":"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"}

package/out/tools/sub/venue/lexicon.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ */
+import { type SubVenueHarvestRow } from "#tools/sub/venue/harvest";
+import { type SubVenuePromotion } from "#tools/sub/venue/promotions";
+import { type SubVenueLexiconSource, type SubVenueLexiconTable, type SubVenueSurface } from "#tools/sub/venue/table";
+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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function applyPromotions(surfaces: readonly SubVenueSurface[], promotions: readonly SubVenuePromotion[]): SubVenueSurface[];
+/**
+ * One harvestable input: rows plus the stamp they carry into the table.
+ */
+export interface SubVenueHarvest {
+    rows: readonly SubVenueHarvestRow[];
+    source?: string;
+    region?: string;
+}
+/**
+ * Everything {@link buildSubVenueLexicon} needs, already parsed. Keeping the builder off the filesystem is what makes it
+ * deterministic and testable without fixtures on disk.
+ */
+export interface BuildSubVenueLexiconInput {
+    /**
+     * The raw `designator-labels.json` SPARQL envelope, 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.
+     */
+    harvests: readonly SubVenueHarvest[];
+    /**
+     * Provenance rows, copied off the fetch manifests by the caller.
+     */
+    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).
+     */
+    promotions?: readonly SubVenuePromotion[];
+}
+/**
+ * Build the lexicon table. PURE and deterministic — same inputs, byte-identical output.
+ *
+ * Order of operations is required in three places:
+ *
+ * 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.
+ */
+export declare function buildSubVenueLexicon(input: BuildSubVenueLexiconInput): SubVenueLexiconTable;
+/**
+ * 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.
+ */
+export declare function serializeSubVenueLexicon(table: SubVenueLexiconTable): string;
+/**
+ * One OSM extract to harvest: the JSONL path plus the ISO country its rows describe.
+ */
+export interface SubVenueExtractInput {
+    path: string;
+    region: string;
+}
+export interface GenerateSubVenueLexiconOptions {
+    /**
+     * Directory holding the `mailwoman corpus fetch wikidata-subvenue` output. Omit to build the seed-only table.
+     */
+    wikidataDir?: string;
+    /**
+     * OSM extract JSONLs, 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.
+     */
+    overtureRows?: readonly (SubVenueHarvestRow & {
+        country: string;
+    })[];
+    /**
+     * `poi.db`'s layer vintage, for `sources[]`. Only read when `overtureRows` is non-empty.
+     */
+    overtureVintage?: string;
+    /**
+     * Where the table is written.
+     */
+    outPath: string;
+}
+/**
+ * Read the fetch outputs, build the table, and write 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.
+ */
+export declare function generateSubVenueLexicon(options: GenerateSubVenueLexiconOptions): Promise<SubVenueLexiconTable>;
+//# sourceMappingURL=lexicon.d.ts.map

package/out/tools/sub/venue/lexicon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexicon.d.ts","sourceRoot":"","sources":["../../../../lib/tools/sub/venue/lexicon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAOH,OAAO,EAA6C,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAE7G,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAEzF,OAAO,EAQN,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAEzB,KAAK,eAAe,EAEpB,MAAM,wBAAwB,CAAA;AAG/B,cAAc,0BAA0B,CAAA;AACxC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,SAAS,eAAe,EAAE,EACpC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GACtC,eAAe,EAAE,CA6BnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC;;OAEG;IACH,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IACxB;;;OAGG;IACH,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;IACpC;;OAEG;IACH,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,oBAAoB,CAgI3F;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAE5E;AAYD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,8BAA8B;IAC9C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC1C;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC,kBAAkB,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAA;IACpE;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAyEpH"}