@mailwoman/corpus 9.1.0 → 9.3.0

package/out/tools/sub-venue-lexicon.js

@@ -0,0 +1,283 @@
+/**
+ * @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 { readLocalJSONFile, statPath } from "@mailwoman/core/fs/readers";
+import { writeLocalFile } from "@mailwoman/core/fs/writers";
+import { isoDate } from "@mailwoman/core/utils";
+import { basename, join } from "path-ts";
+import { SUBVENUE_PROMOTIONS } from "#tools/sub-venue-promotions";
+import { extractAttestedPhrases, readSubVenueJSONL } from "#tools/sub-venue/harvest";
+import { deriveHeadNounSurfaces } from "#tools/sub-venue/head-nouns";
+import { buildSurfaceIndex } from "#tools/sub-venue/surfaces";
+import { CONCEPT_QIDS, LexiconTier, PROPOSED_DESIGNATORS, SHIPPED_DESIGNATOR_SEED, SHIPPED_MODIFIER_SEED, SUBVENUE_LEXICON_VERSION, } from "#tools/sub-venue/table";
+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.
+ *
+ * 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 function applyPromotions(surfaces, promotions) {
+    const language = (locale) => locale.split("-")[0];
+    const region = (locale) => locale.split("-")[1] ?? "";
+    const rejectedLanguages = new Set(promotions
+        .filter((promotion) => promotion.decision === "reject")
+        .map((promotion) => `${promotion.designatorID} ${promotion.phrase} ${language(promotion.locale)}`));
+    const promoted = promotions.filter((promotion) => promotion.decision === "promote");
+    return surfaces.map((surface) => {
+        if (surface.curated)
+            return surface;
+        const hit = promoted.some((promotion) => {
+            if (promotion.designatorID !== surface.recordID || promotion.phrase !== surface.phrase)
+                return false;
+            const lang = language(promotion.locale);
+            if (surface.lang !== lang && surface.lang !== "und")
+                return false;
+            if (surface.region === region(promotion.locale))
+                return true;
+            return surface.region === "" && !rejectedLanguages.has(`${promotion.designatorID} ${promotion.phrase} ${lang}`);
+        });
+        return hit ? { ...surface, curated: true } : surface;
+    });
+}
+/**
+ * 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 function buildSubVenueLexicon(input) {
+    const designators = SHIPPED_DESIGNATOR_SEED.map((seed) => ({
+        id: seed.id,
+        tier: LexiconTier.SubVenue,
+        modifierEligible: seed.modifierEligible,
+        shipped: true,
+        provenance: [...seed.provenance],
+    }));
+    const byID = new Map(designators.map((d) => [d.id, d]));
+    for (const proposed of PROPOSED_DESIGNATORS) {
+        const existing = byID.get(proposed.id);
+        if (existing) {
+            existing.provenance = [...new Set([...existing.provenance, ...proposed.provenance])];
+            continue;
+        }
+        const record = {
+            id: proposed.id,
+            tier: proposed.tier,
+            modifierEligible: false,
+            shipped: false,
+            provenance: [...proposed.provenance],
+        };
+        designators.push(record);
+        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.
+    for (const [id, qid] of Object.entries(CONCEPT_QIDS)) {
+        const record = byID.get(id);
+        if (record) {
+            record.provenance = [...new Set([...record.provenance, `wikidata:${qid}`])];
+        }
+    }
+    const modifiers = SHIPPED_MODIFIER_SEED.map((id) => ({
+        id,
+        shipped: true,
+        provenance: ["codex:directionals"],
+    }));
+    const surfaces = [
+        ...designators.map((d) => ({
+            phrase: d.id,
+            recordID: d.id,
+            recordKind: "designator",
+            lang: "en",
+            region: "",
+            source: "seed",
+            // The English designator IS the shipped vocabulary — curated by construction.
+            curated: d.shipped,
+            observations: 0,
+            context: {},
+        })),
+        ...modifiers.map((m) => ({
+            phrase: m.id,
+            recordID: m.id,
+            recordKind: "modifier",
+            lang: "en",
+            region: "",
+            source: "seed",
+            curated: true,
+            observations: 0,
+            context: {},
+        })),
+    ];
+    if (input.wikidata) {
+        surfaces.push(...surfacesFromWikidata(input.wikidata));
+    }
+    surfaces.push(...deriveHeadNounSurfaces(surfaces));
+    const identifierShapes = [];
+    for (const harvest of input.harvests) {
+        const attested = extractAttestedPhrases(harvest.rows, buildSurfaceIndex(surfaces), {
+            source: harvest.source,
+            region: harvest.region,
+        });
+        surfaces.push(...attested.surfaces);
+        identifierShapes.push(...attested.identifierShapes);
+    }
+    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.
+    designators.sort((a, b) => a.id.localeCompare(b.id));
+    modifiers.sort((a, b) => a.id.localeCompare(b.id));
+    curated.sort((a, b) => a.phrase.localeCompare(b.phrase) ||
+        a.recordID.localeCompare(b.recordID) ||
+        a.lang.localeCompare(b.lang) ||
+        a.region.localeCompare(b.region) ||
+        a.source.localeCompare(b.source));
+    return {
+        version: SUBVENUE_LEXICON_VERSION,
+        sources: input.sources.toSorted((a, b) => a.id.localeCompare(b.id)),
+        designators,
+        modifiers,
+        surfaces: curated,
+        identifierShapes: identifierShapes.toSorted((a, b) => a.designatorID.localeCompare(b.designatorID) ||
+            a.region.localeCompare(b.region) ||
+            a.shape.localeCompare(b.shape)),
+        promotions: promotions.toSorted((a, b) => a.designatorID.localeCompare(b.designatorID) ||
+            a.locale.localeCompare(b.locale) ||
+            a.phrase.localeCompare(b.phrase)),
+    };
+}
+/**
+ * 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 function serializeSubVenueLexicon(table) {
+    return JSON.stringify(table, null, 2) + "\n";
+}
+/**
+ * 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 async function generateSubVenueLexicon(options) {
+    const sources = [];
+    const harvests = [];
+    let wikidata = null;
+    if (options.wikidataDir) {
+        wikidata = await readLocalJSONFile(join(options.wikidataDir, "designator-labels.json"));
+        const manifest = await readLocalJSONFile(join(options.wikidataDir, "MANIFEST.json"));
+        const labelFile = manifest.files?.find((f) => f.filename === "designator-labels.json");
+        sources.push({
+            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.
+            retrieved: (manifest.downloaded_at ?? "").slice(0, 10),
+            rows: labelFile?.rows ?? 0,
+        });
+    }
+    for (const extract of options.extracts ?? []) {
+        const rows = await readSubVenueJSONL(extract.path);
+        harvests.push({ rows, source: "osm", region: extract.region });
+        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.
+            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.
+            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.
+        const byCountry = new Map();
+        for (const row of options.overtureRows) {
+            const bucket = byCountry.get(row.country) ?? [];
+            bucket.push(row);
+            byCountry.set(row.country, bucket);
+        }
+        for (const [country, rows] of [...byCountry].toSorted((a, b) => a[0].localeCompare(b[0]))) {
+            harvests.push({ rows, source: "overture", region: country });
+        }
+        sources.push({
+            id: "overture",
+            origin: "Overture Maps Foundation places, via the poi.db spatial layer",
+            license: "CDLA-Permissive-2.0",
+            retrieved: options.overtureVintage ?? "",
+            rows: options.overtureRows.length,
+        });
+    }
+    const table = buildSubVenueLexicon({ wikidata, harvests, sources });
+    await writeLocalFile(serializeSubVenueLexicon(table), options.outPath);
+    return table;
+}
+//# sourceMappingURL=sub-venue-lexicon.js.map

package/out/tools/sub-venue-lexicon.js.map

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

package/out/tools/sub-venue-promotions.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @copyright Sister Software
+ * @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.
+ */
+/**
+ * One curation decision.
+ */
+export interface SubVenuePromotion {
+    /**
+     * The {@link SubVenueDesignator.id} the phrase is a surface of.
+     */
+    designatorID: string;
+    /**
+     * The exact normalized surface being decided on — `halle`, not `hall`, when the German form is at issue.
+     */
+    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.
+     */
+    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.
+     */
+    shape?: "identifier-required";
+    /**
+     * Occurrences judged genuine venue-interior structure in that locale's census.
+     */
+    real: number;
+    /**
+     * Occurrences judged confound.
+     */
+    confound: number;
+    /**
+     * What the confound half IS. Required prose — a bare number is not a board.
+     */
+    confoundNote: string;
+    /**
+     * Which extract or dataset the census was taken over, and when.
+     */
+    census: string;
+}
+/**
+ * The ledger. Sorted by designator, then locale, then phrase in the emitted artifact; source order here is grouped by
+ * designator for reading.
+ *
+ * ── 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.
+ */
+export declare const SUBVENUE_PROMOTIONS: readonly SubVenuePromotion[];
+//# sourceMappingURL=sub-venue-promotions.d.ts.map

package/out/tools/sub-venue-promotions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-venue-promotions.d.ts","sourceRoot":"","sources":["../../lib/tools/sub-venue-promotions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAA;IAC7B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,iBAAiB,EA2O3D,CAAA"}