@mailwoman/corpus 9.1.0 → 9.3.0

package/out/tools/fetch/tiger-full.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiger-full.js","sourceRoot":"","sources":["../../../lib/tools/fetch/tiger-full.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAClE;;;;;;;;;;;;;;;;;;;GAmBG;AACH;kGACkG;AAClG,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAA;AACnD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAGxC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAEnF;;;GAGG;AACH;;GAEG;AACH,MAAM,OAAO,GAAG,GAAG,CAAA;AAEnB;;GAEG;AACH,MAAM,aAAa,GAAG,GAAG,CAAA;AAEzB,MAAM,cAAc,GAAG,sDAAsD,CAAA;AA4B7E;;GAEG;AACH,KAAK,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC1C,MAAM,MAAM,GAAG,MAAM,YAAY,CAA+B,YAAY,CAAC,CAAA;IAE7E,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;QACxC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YAChB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;QAChF,CAAC;IACF,CAAC;IAED,OAAO,GAAG,CAAA;AACX,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,WAAmB,EAAE,aAAqB;IACrF,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAE3C,IAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa;QAAE,OAAO,KAAK,CAAA;IAE/D,OAAO,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,WAAW,CAAA;AAChD,CAAC;AAMD;;GAEG;AACH,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,IAAY;IACtD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC/B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtG,IAAI,MAAM,GAAG,OAAO,IAAI,MAAM,IAAI,aAAa,EAAE,CAAC;QACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,MAAM,EAAE,EAAE,CAAA;IACzD,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;IAEzC,IAAI,KAAK,GAAG,aAAa,EAAE,CAAC;QAC3B,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAA;QAE/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,KAAK,SAAS,EAAE,CAAA;IACrE,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAA;IAErC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,OAA8B,EAC9B,MAA+B;IAE/B,MAAM,aAAa,GAAG,CAAC,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACtG,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;IACjE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAA;IAEtC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;IAC9D,MAAM,eAAe,CAAC,WAAW,CAAC,CAAA;IAElC,+CAA+C;IAE/C,MAAM,EAAE,CAAC,uDAAuD,CAAC,CAAA;IAEjE,sGAAsG;IACtG,gEAAgE;IAChE,MAAM,UAAU,GAAG,MAAM,IAAI,SAAS,CAAC;QACtC,WAAW,EAAE,eAAe;QAC5B,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE,EAAE;KACrD,CAAC;SACA,KAAK,CAAS,EAAE,GAAG,EAAE,GAAG,cAAc,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;SACnF,IAAI,CAAC,iBAAiB,CAAC,CAAA;IAEzB,MAAM,IAAI,GAAG,UAAU,CAAA;IACvB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IACtF,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAA;IACpC,MAAM,EAAE,CAAC,WAAW,aAAa,gDAAgD,CAAC,CAAA;IAElF,gDAAgD;IAChD,uFAAuF;IACvF,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAA;IAE9C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QACpC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAC5C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChB,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,MAAM,EAAE,CAAC,WAAW,UAAU,CAAC,IAAI,8BAA8B,CAAC,CAAA;IAElE,0CAA0C;IAE1C,IAAI,YAAY,GAAG,CAAC,CAAA;IACpB,IAAI,YAAY,GAAG,CAAC,CAAA;IACpB,IAAI,iBAAiB,GAAG,CAAC,CAAA;IACzB,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,iBAAiB,GAAG,CAAC,CAAA;IACzB,MAAM,WAAW,GAAa,EAAE,CAAA;IAEhC,8DAA8D;IAC9D,MAAM,YAAY,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAA;IAEtD,KAAK,MAAM,SAAS,IAAI,YAAY,EAAE,CAAC;QACtC,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAEnD,gFAAgF;QAChF,IAAI,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,MAAM,EAAE,CAAC,aAAa,SAAS,qCAAqC,WAAW,CAAC,MAAM,YAAY,CAAC,CAAA;YACnG,iBAAiB,IAAI,WAAW,CAAC,MAAM,CAAA;YAEvC,SAAQ;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC,CAAA;QACxD,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC/B,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAA;QAEpD,wDAAwD;QACxD,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,YAAY,CAAC,CAAA;QAEvD,MAAM,EAAE,CAAC,aAAa,SAAS,MAAM,WAAW,CAAC,MAAM,WAAW,CAAC,CAAA;QAEnE,iDAAiD;QACjD,MAAM,OAAO,GAAyC,EAAE,CAAA;QAExD,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;YAClC,MAAM,GAAG,GAAG,GAAG,cAAc,IAAI,KAAK,EAAE,CAAA;YACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YAEjC,yCAAyC;YACzC,IAAI,KAAK,IAAI,CAAC,MAAM,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBACtE,MAAM,EAAE,CAAC,qBAAqB,KAAK,EAAE,CAAC,CAAA;gBAEtC,YAAY,EAAE,CAAA;gBAEd,SAAQ;YACT,CAAC;YAED,IAAI,MAAM,EAAE,CAAC;gBACZ,MAAM,EAAE,CAAC,kBAAkB,GAAG,EAAE,CAAC,CAAA;gBAEjC,YAAY,EAAE,CAAA;gBAEd,SAAQ;YACT,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5B,CAAC;QAED,IAAI,MAAM;YAAE,SAAQ;QAEpB,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,SAAQ;QAE7B,+EAA+E;QAC/E,MAAM,OAAO,GAAmB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACtE,IAAI,MAAM,GAAG,CAAC,CAAA;QAEd,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;YACxF,OAAO,IAAI,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,MAAM,EAAE,CAAA;gBAElB,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM;oBAAE,OAAM;gBAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAE,CAAA;gBACxB,gDAAgD;gBAChD,MAAM,KAAK,CAAC,WAAW,CAAC,CAAA;gBACxB,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;YACvD,CAAC;QACF,CAAC,CAAC,CAAA;QAEF,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAE1B,mCAAmC;QACnC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,MAAM,EAAE,CACP,QAAQ,MAAM,CAAC,QAAQ,KAAK,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAC5G,CAAA;gBAED,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;gBAExG,YAAY,EAAE,CAAA;gBACd,iBAAiB,IAAI,MAAM,CAAC,KAAK,CAAA;YAClC,CAAC;iBAAM,CAAC;gBACP,MAAM,EAAE,CAAC,UAAU,MAAM,CAAC,QAAQ,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;gBAEzD,WAAW,EAAE,CAAA;gBACb,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAClC,CAAC;QACF,CAAC;QAED,yFAAyF;QACzF,MAAM,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;QAEhG,MAAM,WAAW,GAAG;YACnB,UAAU,EAAE,SAAS;YACrB,UAAU,EAAE,UAAU,EAAE;YACxB,cAAc,EAAE,cAAc;YAC9B,QAAQ;SACR,CAAA;QAED,MAAM,aAAa,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;IAC/C,CAAC;IAED,gBAAgB;IAEhB,MAAM,EAAE,CAAC,iBAAiB,CAAC,CAAA;IAC3B,MAAM,EAAE,CAAC,iCAAiC,aAAa,EAAE,CAAC,CAAA;IAC1D,MAAM,EAAE,CAAC,iCAAiC,iBAAiB,wBAAwB,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC/G,MAAM,EAAE,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAA;IACzD,MAAM,EAAE,CAAC,iCAAiC,YAAY,EAAE,CAAC,CAAA;IACzD,MAAM,EAAE,CAAC,iCAAiC,WAAW,EAAE,CAAC,CAAA;IAExD,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,CAAC,iCAAiC,aAAa,CAAC,SAAS,CAAC,iBAAiB,CAAC,KAAK,iBAAiB,GAAG,CAAC,CAAA;IAC/G,CAAC;IAED,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,EAAE,CAAC,YAAY,WAAW,uCAAuC,CAAC,CAAA;IACzE,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,iBAAiB,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA;AAC9G,CAAC"}

package/out/tools/fetch/wikidata-subvenue.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the multilingual sub-venue designator vocabulary from Wikidata (#35 wave 1).
+ *
+ *   Source : https://query.wikidata.org/sparql (the Wikidata Query Service).
+ *   License: CC0. Wikidata's data is public-domain dedicated, so nothing rides on a derived slice.
+ *            Tier A.
+ *
+ *   ## The pull is CLASS labels, not instance names — and that inversion is the whole design
+ *
+ *   The obvious read of "Wikidata for localized designators" is: fetch every airport terminal entity
+ *   and read its name in each language. That turned out to be the wrong query. Wikidata
+ *   knows 246 items that are `instance of / subclass of*` airport terminal, carrying 775 labels
+ *   between them (measured 2026-08-04), and most of those labels are proper names that translate
+ *   verbatim — `TWA Flight Center` is spelled `TWA Flight Center` in fifteen languages. The
+ *   instance layer is thin and its localization is mostly a no-op.
+ *
+ *   The DESIGNATOR is the label of the CLASS. `wd:Q849706` ("airport terminal") is labelled `Terminal`
+ *   in German, `terminal aéroportuaire` in French, `ターミナルビル` in Japanese, `航站楼` in Chinese —
+ *   and `skos:altLabel` adds the aliases (`Abfertigungsgebäude`, `Flughafenterminal`, `aerostazione`).
+ *   Eight concept ids yield 877 label+alias rows across 174 languages, which is the vocabulary the
+ *   corpus task asked for and the instance query does not contain. {@link SUBVENUE_CONCEPTS} is that
+ *   list of ids; {@link buildDesignatorLabelQuery} is that query.
+ *
+ *   Instance labels are fetched too ({@link buildTerminalInstanceQuery}), for a different job: they
+ *   are ATTESTED USAGE — evidence of how a designator combines with a modifier or an identifier in
+ *   running text. 775 rows is small, and it is a validation set, not a vocabulary.
+ *
+ *   ## What a caller must NOT do with the output
+ *
+ *   A class label is a CONCEPT NAME, not a designator as written in an address. Q849706's Spanish
+ *   label is `terminal aeroportuaria` and its French is `terminal d'aéroport`; nobody writes either on
+ *   an envelope, they write `Terminal`. Q247739's Spanish is `puerta de embarque` where the addressed
+ *   form is `Puerta`. So this fetch produces CANDIDATE SURFACES that need a head-noun/curation pass
+ *   before any of them reaches `neural/venue-structure.ts`'s designator vocabulary — the lexicon
+ *   builder marks every one `curated: false` and the burden of promotion is on a human. Wiring the raw
+ *   pull straight into the span proposer would admit multi-word phrases that match nothing and, worse,
+ *   admit `hall` in a language where it names an ordinary room.
+ *
+ *   ## Why `APIClient` here when the OurAirports sibling uses `downloadToFile`
+ *
+ *   This is the API-request side of `AGENTS.md`'s split: small JSON bodies, several calls per run, and
+ *   a host that publishes a rate policy and enforces it with 429s. Pacing, bounded `Retry-After`-aware
+ *   retry, response caching and `ResourceError` mapping all earn their keep, so it extends
+ *   {@link APIClient}. `ourairports.ts` is four static file transfers off a CDN and correctly does not.
+ *
+ *   WDQS also REQUIRES a descriptive `User-Agent` naming the tool and a contact — an anonymous or
+ *   library-default agent is blocked outright by the Wikimedia user-agent policy. See
+ *   {@link WIKIDATA_USER_AGENT}.
+ *
+ *   Invoke via `mailwoman corpus fetch wikidata-subvenue --out-root <path>`.
+ */
+import { APIClient, type ClockLike } from "@mailwoman/core/api";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
+/**
+ * The SPARQL endpoint. Public, no credential.
+ */
+export declare const WDQS_ENDPOINT = "https://query.wikidata.org/sparql";
+/**
+ * The `User-Agent` every request carries.
+ *
+ * NOT decoration. The Wikimedia user-agent policy blocks requests whose agent is absent, generic, or a library default,
+ * and WDQS enforces it — an unidentified client gets a 403 that no amount of retrying fixes. The policy asks for a tool
+ * name, a URL, and a contact address, all three of which are here.
+ */
+export declare const WIKIDATA_USER_AGENT = "mailwoman/1.0 (https://github.com/sister-software/mailwoman; teffen@sister.software) corpus-subvenue-fetch";
+/**
+ * One Wikidata concept whose labels are a designator's multilingual surface set.
+ *
+ * `designatorID` is the mailwoman-side vocabulary term, matching `neural/venue-structure.ts`'s
+ * `VENUE_STRUCTURE_DESIGNATORS` wherever the two overlap. `qid` was resolved by `wbsearchentities` and hand-checked
+ * against the entity's English description (recorded below) on 2026-08-04 — a QID picked by search alone is how you end
+ * up pulling the labels of a Bronx neighbourhood called Concourse.
+ *
+ * `wing` is ABSENT and that is a finding, not an oversight: Wikidata has no clean concept for "wing of a building".
+ * `wbsearchentities` for "wing" returns a surname, two English villages, a rugby position and a drone company. Since
+ * `wing` is the single most valuable designator in the arc — `West Wing` is the one modifier case that already parses,
+ * and `East Wing` is the one that does not — its localized surfaces have to come from somewhere else. See the wave-1
+ * report.
+ */
+export interface SubVenueConcept {
+    designatorID: string;
+    qid: string;
+    /**
+     * The entity's English description, recorded so a future reader can tell at a glance whether the QID still names what
+     * we think it names.
+     */
+    gloss: string;
+}
+/**
+ * The concept table. Eight ids, each verified against its English description on 2026-08-04.
+ */
+export declare const SUBVENUE_CONCEPTS: readonly SubVenueConcept[];
+/**
+ * Build the class-label query: `rdfs:label` and `skos:altLabel` for every concept, in every language, tagged with which
+ * of the two it came from so the lexicon can rank a label above an alias.
+ *
+ * `VALUES` rather than a property path over the whole class tree — the concept list is closed and hand-verified, and a
+ * `wdt:P279*` walk from `building` would drag in every structure type on earth.
+ */
+export declare function buildDesignatorLabelQuery(concepts?: readonly SubVenueConcept[]): string;
+/**
+ * Build the instance-label query — every item that is an `instance of` (through any `subclass of` chain) an airport
+ * terminal, with all of its labels. Measured at 246 items / 775 labels on 2026-08-04, well inside WDQS's 60-second
+ * budget.
+ *
+ * A caveat worth knowing before trusting a row: Wikidata's P31 on these is not clean. `Q1322696` (Kigali International
+ * Airport) is typed as an airport terminal, so the result set mixes AIRPORTS in with terminals. The consumer filters;
+ * this module fetches what the query returns.
+ */
+export declare function buildTerminalInstanceQuery(classQID?: string): string;
+/**
+ * The SPARQL JSON results shape, narrowed to the two column types these queries produce.
+ */
+export interface SPARQLResults {
+    results: {
+        bindings: Array<Record<string, {
+            type: string;
+            value: string;
+            "xml:lang"?: string;
+        }>>;
+    };
+}
+/**
+ * Whether a decoded body is a SPARQL results envelope. Used as the cache's write validator so an HTML error page served
+ * under a 200 is never persisted for the next run to destructure into `undefined`.
+ */
+export declare function isSPARQLResults(value: unknown): value is SPARQLResults;
+export interface CreateWikidataClientOptions {
+    /**
+     * On-disk response-cache root. Defaults to a `http-cache` directory beside the fetch output.
+     */
+    cacheDir: string;
+    /**
+     * Time source powering the pacer and the retry backoff. Defaults to the system clock; tests inject a fake so no suite
+     * ever sleeps a real second.
+     */
+    clock?: ClockLike;
+    /**
+     * Axios overrides, merged over this client's defaults. THE TEST INJECTION POINT — pass an `adapter` and no live call
+     * is made. Overriding `headers` wholesale would drop the required `User-Agent`, so don't.
+     */
+    axios?: ConstructorParameters<typeof APIClient>[0]["axios"];
+}
+/**
+ * A Wikidata Query Service client: paced, retrying, disk-cached, and correctly identified.
+ */
+export declare class WikidataClient extends APIClient {
+    /**
+     * Run one SPARQL query and return its results envelope.
+     */
+    query(sparql: string): Promise<SPARQLResults>;
+}
+/**
+ * Construct a {@link WikidataClient} with every default resolved.
+ */
+export declare function createWikidataClient(options: CreateWikidataClientOptions): WikidataClient;
+export type FetchWikidataSubVenueOptions = BaseFetchOptions;
+/**
+ * Run both queries and write their raw SPARQL JSON into `<outRoot>/wikidata-subvenue/`, with a `MANIFEST.json` carrying
+ * the endpoint, the exact queries, the concept table, row counts and sha256s.
+ *
+ * The RAW envelope is written rather than a reshaped one on purpose: the lexicon build is a separate, pure step
+ * (`sub-venue-lexicon.ts`) and keeping the fetch output byte-faithful to what WDQS served means a lexicon regeneration
+ * never needs the network.
+ */
+export declare function fetchWikidataSubVenue(options: FetchWikidataSubVenueOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=wikidata-subvenue.d.ts.map

package/out/tools/fetch/wikidata-subvenue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wikidata-subvenue.d.ts","sourceRoot":"","sources":["../../../lib/tools/fetch/wikidata-subvenue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAM/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAK3E;;GAEG;AACH,eAAO,MAAM,aAAa,sCAAsC,CAAA;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,+GAC6E,CAAA;AAkC7G;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EASvD,CAAA;AAOD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,GAAE,SAAS,eAAe,EAAsB,GAAG,MAAM,CAU1G;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,GAAE,MAA2B,GAAG,MAAM,CAMxF;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE;QACR,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC,CAAA;KACrF,CAAA;CACD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,MAAM,WAAW,2BAA2B;IAC3C;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;CAC3D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC5C;;OAEG;IACU,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAQ1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,cAAc,CAkCzF;AAED,MAAM,MAAM,4BAA4B,GAAG,gBAAgB,CAAA;AA0C3D;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,4BAA4B,EACrC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CA+CvB"}

package/out/tools/fetch/wikidata-subvenue.js

@@ -0,0 +1,274 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the multilingual sub-venue designator vocabulary from Wikidata (#35 wave 1).
+ *
+ *   Source : https://query.wikidata.org/sparql (the Wikidata Query Service).
+ *   License: CC0. Wikidata's data is public-domain dedicated, so nothing rides on a derived slice.
+ *            Tier A.
+ *
+ *   ## The pull is CLASS labels, not instance names — and that inversion is the whole design
+ *
+ *   The obvious read of "Wikidata for localized designators" is: fetch every airport terminal entity
+ *   and read its name in each language. That turned out to be the wrong query. Wikidata
+ *   knows 246 items that are `instance of / subclass of*` airport terminal, carrying 775 labels
+ *   between them (measured 2026-08-04), and most of those labels are proper names that translate
+ *   verbatim — `TWA Flight Center` is spelled `TWA Flight Center` in fifteen languages. The
+ *   instance layer is thin and its localization is mostly a no-op.
+ *
+ *   The DESIGNATOR is the label of the CLASS. `wd:Q849706` ("airport terminal") is labelled `Terminal`
+ *   in German, `terminal aéroportuaire` in French, `ターミナルビル` in Japanese, `航站楼` in Chinese —
+ *   and `skos:altLabel` adds the aliases (`Abfertigungsgebäude`, `Flughafenterminal`, `aerostazione`).
+ *   Eight concept ids yield 877 label+alias rows across 174 languages, which is the vocabulary the
+ *   corpus task asked for and the instance query does not contain. {@link SUBVENUE_CONCEPTS} is that
+ *   list of ids; {@link buildDesignatorLabelQuery} is that query.
+ *
+ *   Instance labels are fetched too ({@link buildTerminalInstanceQuery}), for a different job: they
+ *   are ATTESTED USAGE — evidence of how a designator combines with a modifier or an identifier in
+ *   running text. 775 rows is small, and it is a validation set, not a vocabulary.
+ *
+ *   ## What a caller must NOT do with the output
+ *
+ *   A class label is a CONCEPT NAME, not a designator as written in an address. Q849706's Spanish
+ *   label is `terminal aeroportuaria` and its French is `terminal d'aéroport`; nobody writes either on
+ *   an envelope, they write `Terminal`. Q247739's Spanish is `puerta de embarque` where the addressed
+ *   form is `Puerta`. So this fetch produces CANDIDATE SURFACES that need a head-noun/curation pass
+ *   before any of them reaches `neural/venue-structure.ts`'s designator vocabulary — the lexicon
+ *   builder marks every one `curated: false` and the burden of promotion is on a human. Wiring the raw
+ *   pull straight into the span proposer would admit multi-word phrases that match nothing and, worse,
+ *   admit `hall` in a language where it names an ordinary room.
+ *
+ *   ## Why `APIClient` here when the OurAirports sibling uses `downloadToFile`
+ *
+ *   This is the API-request side of `AGENTS.md`'s split: small JSON bodies, several calls per run, and
+ *   a host that publishes a rate policy and enforces it with 429s. Pacing, bounded `Retry-After`-aware
+ *   retry, response caching and `ResourceError` mapping all earn their keep, so it extends
+ *   {@link APIClient}. `ourairports.ts` is four static file transfers off a CDN and correctly does not.
+ *
+ *   WDQS also REQUIRES a descriptive `User-Agent` naming the tool and a contact — an anonymous or
+ *   library-default agent is blocked outright by the Wikimedia user-agent policy. See
+ *   {@link WIKIDATA_USER_AGENT}.
+ *
+ *   Invoke via `mailwoman corpus fetch wikidata-subvenue --out-root <path>`.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { buildDiskStorage } from "@mailwoman/core/api/disk-storage";
+import { makeDirectories, writeLocalFile } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { join } from "path-ts";
+import { writeManifest } from "#tools/fetch/download";
+const SLUG = "wikidata-subvenue";
+/**
+ * The SPARQL endpoint. Public, no credential.
+ */
+export const WDQS_ENDPOINT = "https://query.wikidata.org/sparql";
+/**
+ * The `User-Agent` every request carries.
+ *
+ * NOT decoration. The Wikimedia user-agent policy blocks requests whose agent is absent, generic, or a library default,
+ * and WDQS enforces it — an unidentified client gets a 403 that no amount of retrying fixes. The policy asks for a tool
+ * name, a URL, and a contact address, all three of which are here.
+ */
+export const WIKIDATA_USER_AGENT = "mailwoman/1.0 (https://github.com/sister-software/mailwoman; teffen@sister.software) corpus-subvenue-fetch";
+/**
+ * Minimum spacing between dispatches, in milliseconds.
+ *
+ * WDQS's published limit is expressed as processing-time budget rather than a request rate, and this run issues fewer
+ * than a dozen queries total, so the number is chosen for politeness rather than to sit against a ceiling: one query
+ * per second is far inside anything WDQS objects to, and at this volume the whole fetch still completes in seconds.
+ *
+ * Set as `minRequestIntervalMs` rather than `requestsPerMinute` deliberately — `AGENTS.md` records that
+ * `requestsPerMinute` is a BUDGET model whose cooldown lets N requests go out back to back, so it does not deliver N
+ * per minute and is not the check that holds a rate. The interval is.
+ */
+const WDQS_MIN_REQUEST_INTERVAL_MS = 1000;
+/**
+ * Per-attempt socket-inactivity timeout. WDQS's own query timeout is 60 seconds and it answers with a 500 when a query
+ * exceeds it, so a client timeout below that would turn a server-side timeout into a client-side one and lose the error
+ * body that says which query was too expensive.
+ */
+const WDQS_REQUEST_TIMEOUT_MS = 90_000;
+/**
+ * Total attempts (including the first) before giving up on a 429/5xx.
+ */
+const WDQS_MAX_ATTEMPTS = 3;
+/**
+ * How long a cached SPARQL response stays fresh. A week: the class labels this pulls change on the timescale at which
+ * someone edits a Wikidata concept's German alias, which is to say rarely, and a re-run inside a working session should
+ * not re-ask.
+ */
+const WDQS_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * The concept table. Eight ids, each verified against its English description on 2026-08-04.
+ */
+export const SUBVENUE_CONCEPTS = [
+    { designatorID: "terminal", qid: "Q849706", gloss: "airport terminal — part of an airport" },
+    { designatorID: "gate", qid: "Q247739", gloss: "gate — airport facility for passenger loading/unloading" },
+    { designatorID: "concourse", qid: "Q862212", gloss: "concourse — place where pathways or roads meet" },
+    { designatorID: "campus", qid: "Q209465", gloss: "campus — cluster of buildings used by an educational institution" },
+    { designatorID: "building", qid: "Q41176", gloss: "building — structure with a roof and walls" },
+    { designatorID: "arcade", qid: "Q186637", gloss: "arcade — covered walk enclosed by a line of arches" },
+    { designatorID: "hall", qid: "Q240854", gloss: "hall — large enclosed room" },
+    { designatorID: "satellite", qid: "Q15990706", gloss: "satellite terminal — detached airport building" },
+];
+/**
+ * The class whose instances are fetched for attested-usage evidence: airport terminal.
+ */
+const TERMINAL_CLASS_QID = "Q849706";
+/**
+ * Build the class-label query: `rdfs:label` and `skos:altLabel` for every concept, in every language, tagged with which
+ * of the two it came from so the lexicon can rank a label above an alias.
+ *
+ * `VALUES` rather than a property path over the whole class tree — the concept list is closed and hand-verified, and a
+ * `wdt:P279*` walk from `building` would drag in every structure type on earth.
+ */
+export function buildDesignatorLabelQuery(concepts = SUBVENUE_CONCEPTS) {
+    const values = concepts.map((c) => `wd:${c.qid}`).join(" ");
+    return `SELECT ?item ?lang ?label ?kind WHERE {
+  VALUES ?item { ${values} }
+  { ?item rdfs:label ?label . BIND("label" AS ?kind) }
+  UNION
+  { ?item skos:altLabel ?label . BIND("alt" AS ?kind) }
+  BIND(LANG(?label) AS ?lang)
+}`;
+}
+/**
+ * Build the instance-label query — every item that is an `instance of` (through any `subclass of` chain) an airport
+ * terminal, with all of its labels. Measured at 246 items / 775 labels on 2026-08-04, well inside WDQS's 60-second
+ * budget.
+ *
+ * A caveat worth knowing before trusting a row: Wikidata's P31 on these is not clean. `Q1322696` (Kigali International
+ * Airport) is typed as an airport terminal, so the result set mixes AIRPORTS in with terminals. The consumer filters;
+ * this module fetches what the query returns.
+ */
+export function buildTerminalInstanceQuery(classQID = TERMINAL_CLASS_QID) {
+    return `SELECT ?item ?lang ?label WHERE {
+  ?item wdt:P31/wdt:P279* wd:${classQID} .
+  ?item rdfs:label ?label .
+  BIND(LANG(?label) AS ?lang)
+}`;
+}
+/**
+ * Whether a decoded body is a SPARQL results envelope. Used as the cache's write validator so an HTML error page served
+ * under a 200 is never persisted for the next run to destructure into `undefined`.
+ */
+export function isSPARQLResults(value) {
+    return typeof value === "object" && value !== null && Array.isArray(value.results?.bindings);
+}
+/**
+ * A Wikidata Query Service client: paced, retrying, disk-cached, and correctly identified.
+ */
+export class WikidataClient extends APIClient {
+    /**
+     * Run one SPARQL query and return its results envelope.
+     */
+    async query(sparql) {
+        const url = new URL(WDQS_ENDPOINT);
+        url.searchParams.set("query", sparql);
+        const response = await this.fetch({ url: url.toString() });
+        return response.data;
+    }
+}
+/**
+ * Construct a {@link WikidataClient} with every default resolved.
+ */
+export function createWikidataClient(options) {
+    return new WikidataClient({
+        displayName: "Wikidata Query Service",
+        minRequestIntervalMs: WDQS_MIN_REQUEST_INTERVAL_MS,
+        retry: { maxAttempts: WDQS_MAX_ATTEMPTS },
+        clock: options.clock,
+        caching: {
+            storage: buildDiskStorage({
+                directory: options.cacheDir,
+                // `value.data` is the cached RESPONSE; `value.data.data` is its body. Passing the response here
+                // instead of the body is a silent-failure trap — the predicate returns false for every entry and
+                // every run re-fetches while logging "rejected by the configured validate() predicate". Caught
+                // on the first live run, 2026-08-04.
+                validate: (value) => isSPARQLResults(value.data?.data),
+            }),
+            ttl: WDQS_CACHE_TTL_MS,
+            // The TTL is chosen against Wikidata's edit cadence; letting a CDN header override it would
+            // silently replace that reasoning with whatever varnish in front of WDQS happens to send.
+            interpretHeader: false,
+        },
+        axios: {
+            headers: {
+                "User-Agent": WIKIDATA_USER_AGENT,
+                Accept: "application/sparql-results+json",
+            },
+            timeout: WDQS_REQUEST_TIMEOUT_MS,
+            responseType: "json",
+            // Axios hands back the RAW STRING when a body fails to parse unless this is off. WDQS serves an
+            // HTML error page under some failures, and returning that as `SPARQLResults` would surface as an
+            // `undefined` destructure far from the cause.
+            transitional: { silentJSONParsing: false },
+            ...options.axios,
+        },
+    });
+}
+/**
+ * Write a JSON payload and return its manifest entry.
+ */
+async function writePayload(destDir, filename, query, results) {
+    const path = join(destDir, filename);
+    const body = JSON.stringify(results, null, 2) + "\n";
+    await writeLocalFile(body, path);
+    return {
+        filename,
+        query,
+        rows: results.results.bindings.length,
+        sha256: await sha256File(path),
+        bytes: Buffer.byteLength(body),
+    };
+}
+/**
+ * Run both queries and write their raw SPARQL JSON into `<outRoot>/wikidata-subvenue/`, with a `MANIFEST.json` carrying
+ * the endpoint, the exact queries, the concept table, row counts and sha256s.
+ *
+ * The RAW envelope is written rather than a reshaped one on purpose: the lexicon build is a separate, pure step
+ * (`sub-venue-lexicon.ts`) and keeping the fetch output byte-faithful to what WDQS served means a lexicon regeneration
+ * never needs the network.
+ */
+export async function fetchWikidataSubVenue(options, report) {
+    const destDir = join(options.outRoot, SLUG);
+    await makeDirectories(destDir);
+    await using client = createWikidataClient({ cacheDir: join(destDir, "http-cache") });
+    const jobs = [
+        { filename: "designator-labels.json", query: buildDesignatorLabelQuery() },
+        { filename: "terminal-instance-labels.json", query: buildTerminalInstanceQuery() },
+    ];
+    const files = [];
+    const failedCodes = [];
+    let fetched = 0;
+    let failed = 0;
+    for (const job of jobs) {
+        report?.(`=== ${SLUG} / ${job.filename}`);
+        try {
+            const results = await client.query(job.query);
+            const entry = await writePayload(destDir, job.filename, job.query, results);
+            report?.(`  ${entry.rows} rows, ${entry.bytes} bytes`);
+            files.push(entry);
+            fetched++;
+        }
+        catch (error) {
+            report?.(`✗ ${job.filename}: ${error instanceof Error ? error.message : String(error)}`);
+            failedCodes.push(job.filename);
+            failed++;
+        }
+    }
+    const manifest = {
+        source: "Wikidata Query Service",
+        endpoint: WDQS_ENDPOINT,
+        license: "CC0",
+        user_agent: WIKIDATA_USER_AGENT,
+        downloaded_at: new Date().toISOString(),
+        concepts: SUBVENUE_CONCEPTS,
+        files,
+    };
+    await writeManifest(join(destDir, "MANIFEST.json"), manifest);
+    return { fetched, skipped: 0, failed, failedCodes };
+}
+//# sourceMappingURL=wikidata-subvenue.js.map

package/out/tools/fetch/wikidata-subvenue.js.map

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

package/out/tools/gb-title-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gb-title-case.d.ts","sourceRoot":"","sources":["../../lib/tools/gb-title-case.ts"],"names":[],"mappings":"AAkDA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBjD"}

package/out/tools/gb-title-case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gb-title-case.js","sourceRoot":"","sources":["../../lib/tools/gb-title-case.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;IAC5B,MAAM;IACN,IAAI;IACJ,OAAO;IACP,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,IAAI;IACJ,OAAO;IACP,KAAK;IACL,KAAK;IACL,IAAI;IACJ,GAAG;IACH,IAAI;CACJ,CAAC,CAAA;AAEF,SAAS,QAAQ,CAAC,IAAY,EAAE,OAAgB;IAC/C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAA;IAEhC,IAAI,CAAC,OAAO,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAErD,0FAA0F;IAC1F,OAAO,KAAK;SACV,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;QACrB,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAA;QAE5B,iDAAiD;QACjD,IAAI,GAAG,GAAG,CAAC,IAAI,OAAO,KAAK,GAAG;YAAE,OAAO,OAAO,CAAA;QAE9C,8CAA8C;QAC9C,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACpD,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAa;IACxC,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IACpB,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,OAAO,KAAK;SACV,KAAK,CAAC,KAAK,CAAC;SACZ,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACd,MAAM,KAAK,GAAG,KAAK;aACjB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,KAAK,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,CAAC;aACxE,IAAI,CAAC,GAAG,CAAC,CAAA;QAEX,SAAS,IAAI,CAAC,CAAA;QAEd,OAAO,KAAK,CAAA;IACb,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC;SACT,IAAI,EAAE,CAAA;AACT,CAAC"}

package/out/tools/golden-expand.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Generate golden-set candidate entries by LLM-driven surface-form synthesis from a verified-label
+ *   seed pulled out of the corpus's labeled test split.
+ *
+ *   ## Why this approach
+ *
+ *   The Phase 2 golden set has 74 entries; session-notes.md called for ≥500/locale. Manual curation
+ *   doesn't scale. Pure-LLM generation (invent raw + labels from scratch) is too noisy — labels
+ *   would be unverified.
+ *
+ *   This module takes the middle path:
+ *
+ *   1. **Seeds come from corpus-v0.2.0 test slice** — already through the alignment pipeline, so labels
+ *        are pipeline-verified.
+ *   2. **LLM only varies the surface form** — case, abbreviations, reordering, dropped components. The
+ *        component VALUES (locality string, postcode digits, etc.) are preserved verbatim.
+ *   3. **Programmatic validator drops hallucinations** — every component value must appear as a
+ *        substring (case-insensitive, whitespace-normalized) of the variant's raw. Failures dropped
+ *        silently; cost is wasted tokens, never bad-labeled golden entries.
+ *
+ *   ## Usage
+ *
+ *   ```sh
+ *   DEEPSEEK_API_KEY=sk-... \
+ *   mailwoman corpus golden expand \
+ *   --count 1000 \
+ *   --variants 5 \
+ *   --output data/eval/golden/candidates/expand-$(date +%Y%m%d-%H%M%S).jsonl
+ *   ```
+ *
+ *   ## Env
+ *
+ *   - `DEEPSEEK_API_KEY` — required for provider `deepseek`
+ *   - `ANTHROPIC_API_KEY` — required for provider `anthropic`
+ *
+ *   ## What this module does NOT do
+ *
+ *   - Does not commit anything or modify the versioned golden dir. Candidates land in
+ *       `data/eval/golden/candidates/` for operator review (skim, prune, then run
+ *       `mailwoman corpus golden promote`).
+ *   - Does not score the LLM's quality — that's an eyeball job after pilot lands.
+ *   - Does not retry hallucinated candidates. Cost of wasted tokens is trivial (~$0.0006/each).
+ */
+export interface ExpandGoldenOptions {
+    /**
+     * Corpus test slice path(s), comma-separated. Default: the v0.2.0 test slice under the data root.
+     */
+    corpus?: string;
+    /**
+     * Total seeds to process. Default `100` (pilot).
+     */
+    count?: number;
+    /**
+     * Variants requested per seed. Default `5`.
+     */
+    variants?: number;
+    /**
+     * JSONL output path. Default `data/eval/golden/candidates/expand-<ts>.jsonl`.
+     */
+    output?: string;
+    /**
+     * LLM provider. Default `deepseek`.
+     */
+    provider?: "deepseek" | "anthropic";
+    /**
+     * Model id. Default depends on provider.
+     */
+    model?: string;
+    /**
+     * Parallel LLM calls. Default `4`.
+     */
+    concurrency?: number;
+    /**
+     * Comma-separated source allow-list.
+     */
+    includeSources?: string;
+}
+export interface ExpandGoldenSummary {
+    seedsProcessed: number;
+    kept: number;
+    dropped: number;
+    errored: number;
+    outputPath: string;
+}
+export declare function expandGolden(options?: ExpandGoldenOptions, report?: (line: string) => void): Promise<ExpandGoldenSummary>;
+//# sourceMappingURL=golden-expand.d.ts.map

package/out/tools/golden-expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden-expand.d.ts","sourceRoot":"","sources":["../../lib/tools/golden-expand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAuDH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,CAAA;IACnC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IACnC,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;CAClB;AA0UD,wBAAsB,YAAY,CACjC,OAAO,GAAE,mBAAwB,EACjC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAkG9B"}