@mailwoman/corpus 10.0.0 → 10.1.0

package/out/utils/wof-json.d.ts

@@ -3,31 +3,16 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Shared utilities for the `wof-admin` / `wof-postalcode` GeoJSON-bundle adapters.
- *
- *   The Phase 1.5.1 pivot moved both adapters off the SpatiaLite distribution (dead mirror, empty
- *   `names` table) and onto the per-record GeoJSON bundles published as
- *   `github.com/whosonfirst-data/whosonfirst-data-{admin,postalcode}-<cc>` repos. Each repo carries
- *   a tree of `data/<3>/<3>/<3>/<wof-id>.geojson` files plus alternate-geometry siblings like
- *   `<id>-alt-quattroshapes.geojson`. The adapter only consumes the canonical record (no `-alt-`
- *   files); the alternate geometries are irrelevant to the name/hierarchy concerns Phase 1 cares
- *   about.
- *
- *   This module provides:
- *
- *   - `WOFRecord`: the lightweight per-feature shape both adapters carry in their ancestry index.
- *   - `walkFeatures`: streaming directory walk → parsed `WOFRecord`s (skips alt files, bad JSON,
- *       deprecated records).
- *   - `buildAncestryIndex`: in-memory ancestry chain construction (`Map<id, ancestors[]>`).
- *   - `extractNameVariants`: pulls `name:*` localized name lists off a feature's properties.
- *   - `normalizeNameKey`: turns `"name:eng_x_colloquial"` into `"name-eng-x-colloquial"` for safe use
- *       in `source_id` suffixes.
- *
- *   `is_current` semantics follow WOF + Pelias: `mz:is_current` ∈ {`1`, `-1`} are live; `0` is
- *   superseded. WOF's official postalcode distribution stamps every row with `-1` ("unknown but
- *   treated as active"), which is why the previous SpatiaLite adapter's `is_current = 1` filter
- *   silently emitted zero rows from the real corpus.
+ * Shared utilities for the `wof-admin` / `wof-postalcode` GeoJSON-bundle adapters. They read the
+ * per-record bundles published as `github.com/whosonfirst-data/whosonfirst-data-{admin,postalcode}-<cc>`
+ * repos: a tree of `data/<3>/<3>/<3>/<wof-id>.geojson` files plus alternate-geometry siblings like
+ * `<id>-alt-quattroshapes.geojson`, of which only the canonical record is consumed.
+ *
+ * `is_current` semantics follow WOF + Pelias: `mz:is_current` ∈ {`1`, `-1`} are live and `0` is
+ * superseded. WOF's official postalcode distribution stamps every row `-1` ("unknown but treated as
+ * active"), so an `is_current = 1` filter silently emits zero rows from the real corpus.
  */
+import type { PathBuilderLike } from "path-ts";
 /**
  * A WOF GeoJSON feature, as published by the per-record bundles.
  */
@@ -37,77 +22,118 @@ export interface WOFFeature {
     properties?: Record<string, unknown> | null;
 }
 /**
- * Lightweight in-memory shape both adapters keep per record. Geometry is intentionally dropped — it's 95% of the file
- * weight and the adapters never consult it.
+ * Lightweight in-memory shape both adapters keep per record.
+ *
+ * Geometry is intentionally dropped because the adapters never consult it.
  */
 export interface WOFRecord {
     id: number;
     parent_id: number | null;
-    /**
-     * Canonical `wof:name` of the record.
-     */
     name: string;
     placetype: string;
     /**
-     * ISO 3166-1 alpha-2 from `wof:country`.
+     * ISO 3166-1 alpha-2 from `wof:country`, upper-cased on read.
+     *
+     * The standard's codes are upper case.
+     * The publisher's spelling can differ.
+     *
+     * A consumer such as the `--country NL` filter compares the two strings directly.
      */
     country: string;
     /**
      * Localized name variants from `name:*` properties.
      *
-     * Keys are the raw `name:eng_x_preferred` form; values are the first non-empty string from the underlying array (WOF
-     * stores variants as arrays even when only one form is present). The canonical `wof:name` is NOT included here —
-     * adapters add a synthetic `"default"` slot for it.
+     * Keys are the raw `name:eng_x_preferred` form.
+     * Values are the first non-empty string from the underlying array, because WOF
+     * stores variants as arrays even when only one form is present.
+     *
+     * The canonical `wof:name` is not included — adapters add a synthetic `"default"` slot for it.
      */
     nameVariants: Map<string, string>;
 }
 /**
- * `mz:is_current` ∈ {`1`, `-1`} → keep. `0` → drop.
+ * `mz:is_current` ∈ {`1`, `-1`} → keep, `0` → drop.
  *
- * Real WOF postalcode distros tag every row `-1` ("unknown but treated as active"); the Pelias importer accepts `-1`
- * alongside `1`. Tightening the predicate to `= 1` is the trap: the postalcode distros then contribute ZERO rows to the
- * corpus, silently, with nothing raised to notice it by.
+ * Real WOF postalcode distros tag every row `-1` ("unknown but treated as active") and the
+ * Pelias importer accepts `-1` alongside `1`; tightening the predicate to `= 1` makes the
+ * postalcode distros contribute zero rows to the corpus, silently, with no error to notice it by.
  */
 export declare function isCurrentFeature(props: Record<string, unknown>): boolean;
 /**
- * Pull `name:*` localized variants off a WOF feature's properties. WOF stores variants as arrays (`["Saint
- * Petersburg"]`); we lift the first non-empty string. Multiple-value variants (rare; usually historical aliases) are
- * not split into separate rows by this helper — adapters can opt in by iterating the underlying array if they need it.
+ * Pull `name:*` localized variants off a WOF feature's properties, lifting the first
+ * non-empty string from the array WOF stores them in (`["Saint Petersburg"]`);
+ * Multiple-value variants are rare and usually historical aliases.
+ *
+ * This function keeps them together.
+ * An adapter that needs separate values can iterate the underlying array.
  */
 export declare function extractNameVariants(props: Record<string, unknown>): Map<string, string>;
 /**
- * Turn a `name:*` property key into a hyphen-safe suffix fragment for `source_id`.
- *
- * `"name:eng_x_colloquial"` → `"name-eng-x-colloquial"`. `:` and `_` both become `-` because both collide with the
- * existing source_id separator vocabulary and downstream consumers split on `-`.
+ * Turn a `name:*` property key into a hyphen-safe suffix fragment for `source_id`
+ * (`"name:eng_x_colloquial"` → `"name-eng-x-colloquial"`); both `:` and `_` become `-`
+ * because both collide with the separator vocabulary downstream consumers split on.
  */
 export declare function normalizeNameKey(rawKey: string): string;
 /**
- * Stream every canonical GeoJSON file under `repoDir` and yield parsed `WOFRecord`s.
+ * Stream every canonical GeoJSON file under `repoDir` and yield parsed `WOFRecord`s;
+ * `repoDir` may be a single cloned `whosonfirst-data-*` repo or a parent holding several
+ * (the corpus pipeline clones all four into a shared `wof/repos/` root).
  *
- * `repoDir` may point at a single cloned `whosonfirst-data-*` repo OR at a parent directory holding several such repos
- * (the corpus pipeline clones all four into a shared `wof/repos/` root and runs the adapter against that root).
- * `**\/*.geojson` walks the whole tree; `-alt-` siblings are skipped since they're alternate-geometry exports, not new
- * records.
+ * `-alt-` siblings are skipped as alternate-geometry exports.
+ * They do not represent new records.
  *
- * Errors per-file (unreadable, malformed JSON, missing properties) are swallowed so one bad file doesn't poison a 3 GB
- * walk. Adapters can add stricter validation downstream if they need it.
+ * Per-file errors (unreadable files, malformed JSON, or missing properties) are swallowed
+ * so one bad file does not poison a multi-gigabyte walk.
  */
-export declare function walkFeatures(repoDir: string, opts?: {
+export declare function walkFeatures(repoDir: PathBuilderLike, opts?: {
     signal?: AbortSignal;
 }): AsyncIterable<WOFRecord>;
 /**
- * Build an in-memory ancestry index: `Map<wof_id, [parent, grandparent, ...]>` walking `parent_id` upward and stopping
- * at the first missing link. A cycle guard halts at any re-visit (defensive — WOF data is acyclic by construction but
- * corrupt fixtures shouldn't infinite-loop the adapter).
+ * The component tags a variant builder looks an ancestor up by.
+ *
+ * Measured over both adapters on 2026-09-28: `variantsFor` reads the nearest `region`
+ * and `country` ancestor, `postcodeVariantsFor` reads the nearest `locality`, `region` and `country`,
+ * and each one reads the ancestor's `placetype` to classify it and its `name` to use it.
+ * No caller reads an ancestor's `nameVariants`, `id`, `parent_id` or `country`.
+ */
+export declare const ANCESTOR_NAME_TAGS: readonly ["locality", "region", "country"];
+/**
+ * The nearest ancestor's `wof:name` per tag in {@linkcode ANCESTOR_NAME_TAGS}.
+ *
+ * A tag with no ancestor has no key.
+ * `ancestry.find(…) === undefined` expresses that state.
+ */
+export type AncestorNames = Partial<Record<(typeof ANCESTOR_NAME_TAGS)[number], string>>;
+/**
+ * The ancestor names each record needs, keyed by `wof:id`.
+ *
+ * The predecessor index held one array of record references per record, so a run over the 13,274,691
+ * admin records of `v0.7.0-de-holdout` allocated 13.3 million arrays alongside the record index.
+ * This holds at most three strings per record instead.
+ *
+ * Each string is the same object the ancestor already holds, so the index costs
+ * one small object per record without copying a name.
+ *
+ * The adapter's second pass reads only this.
+ * `wof-postalcode` keeps admin records in its record index solely so postcode ancestry resolves.
+ * It can release them once this index is built.
+ *
+ * Nearest wins: the walk goes upward from the record's parent and the first ancestor
+ * carrying a tag sets it, matching the `ancestry.find` the builders used.
+ */
+export type AncestorNameIndex = Map<number, AncestorNames>;
+/**
+ * Resolves {@linkcode AncestorNameIndex} from a record index.
+ *
+ * `tagOf` maps a WOF placetype to a component tag, or returns a value outside
+ * {@linkcode ANCESTOR_NAME_TAGS} for a placetype no builder looks up.
+ * It is a parameter because `placetypeToTag` lives with the adapters and this module does not import them.
  *
- * Records whose ancestors aren't in `byID` (e.g. an FR locality whose region wasn't included in the cloned repo set)
- * get a shorter chain; the variant emission gracefully degrades.
+ * The walk stops at the first `parent_id` absent from `byID`, and a cycle guard halts at any re-visit.
+ * WOF data is acyclic by construction.
+ * The guard keeps a corrupt fixture from looping the adapter.
  *
- * `wof-admin-jp`'s `chainOf` walks the same parent-child relation over SQLite `spr` rows with an
- * outside-the-preloaded-set fallback query — a different substrate with a different escape hatch, kept separate on
- * purpose.
+ * A record whose ancestors are absent resolves the tags it can reach rather than failing.
  */
-export type AncestryIndex = Map<number, WOFRecord[]>;
-export declare function buildAncestryIndex(byID: Map<number, WOFRecord>): AncestryIndex;
+export declare function buildAncestorNameIndex(byID: ReadonlyMap<number, WOFRecord>, tagOf: (placetype: string) => string | null | undefined): AncestorNameIndex;
 //# sourceMappingURL=wof-json.d.ts.map

package/out/utils/wof-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wof-json.d.ts","sourceRoot":"","sources":["../../lib/utils/wof-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAKxE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBvF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AA+CD;;;;;;;;;;GAUG;AACH,wBAAuB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAAG,aAAa,CAAC,SAAS,CAAC,CA0BlH;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;AAEpD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,aAAa,CAuB9E"}
+{"version":3,"file":"wof-json.d.ts","sourceRoot":"","sources":["../../lib/utils/wof-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;OAQG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAKxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAcvF;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAiDD;;;;;;;;;;GAUG;AACH,wBAAuB,YAAY,CAClC,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACjC,aAAa,CAAC,SAAS,CAAC,CA2B1B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,YAAI,UAAU,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;AAExF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GACrD,iBAAiB,CA+BnB"}

package/out/utils/wof-json.js

@@ -3,40 +3,24 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Shared utilities for the `wof-admin` / `wof-postalcode` GeoJSON-bundle adapters.
+ * Shared utilities for the `wof-admin` / `wof-postalcode` GeoJSON-bundle adapters. They read the
+ * per-record bundles published as `github.com/whosonfirst-data/whosonfirst-data-{admin,postalcode}-<cc>`
+ * repos: a tree of `data/<3>/<3>/<3>/<wof-id>.geojson` files plus alternate-geometry siblings like
+ * `<id>-alt-quattroshapes.geojson`, of which only the canonical record is consumed.
  *
- *   The Phase 1.5.1 pivot moved both adapters off the SpatiaLite distribution (dead mirror, empty
- *   `names` table) and onto the per-record GeoJSON bundles published as
- *   `github.com/whosonfirst-data/whosonfirst-data-{admin,postalcode}-<cc>` repos. Each repo carries
- *   a tree of `data/<3>/<3>/<3>/<wof-id>.geojson` files plus alternate-geometry siblings like
- *   `<id>-alt-quattroshapes.geojson`. The adapter only consumes the canonical record (no `-alt-`
- *   files); the alternate geometries are irrelevant to the name/hierarchy concerns Phase 1 cares
- *   about.
- *
- *   This module provides:
- *
- *   - `WOFRecord`: the lightweight per-feature shape both adapters carry in their ancestry index.
- *   - `walkFeatures`: streaming directory walk → parsed `WOFRecord`s (skips alt files, bad JSON,
- *       deprecated records).
- *   - `buildAncestryIndex`: in-memory ancestry chain construction (`Map<id, ancestors[]>`).
- *   - `extractNameVariants`: pulls `name:*` localized name lists off a feature's properties.
- *   - `normalizeNameKey`: turns `"name:eng_x_colloquial"` into `"name-eng-x-colloquial"` for safe use
- *       in `source_id` suffixes.
- *
- *   `is_current` semantics follow WOF + Pelias: `mz:is_current` ∈ {`1`, `-1`} are live; `0` is
- *   superseded. WOF's official postalcode distribution stamps every row with `-1` ("unknown but
- *   treated as active"), which is why the previous SpatiaLite adapter's `is_current = 1` filter
- *   silently emitted zero rows from the real corpus.
+ * `is_current` semantics follow WOF + Pelias: `mz:is_current` ∈ {`1`, `-1`} are live and `0` is
+ * superseded. WOF's official postalcode distribution stamps every row `-1` ("unknown but treated as
+ * active"), so an `is_current = 1` filter silently emits zero rows from the real corpus.
  */
 import { readLocalTextFile } from "@mailwoman/core/fs/readers";
 import { tryParsingJSON } from "@mailwoman/core/json";
 import { Globerator } from "spliterator/node/fs";
 /**
- * `mz:is_current` ∈ {`1`, `-1`} → keep. `0` → drop.
+ * `mz:is_current` ∈ {`1`, `-1`} → keep, `0` → drop.
  *
- * Real WOF postalcode distros tag every row `-1` ("unknown but treated as active"); the Pelias importer accepts `-1`
- * alongside `1`. Tightening the predicate to `= 1` is the trap: the postalcode distros then contribute ZERO rows to the
- * corpus, silently, with nothing raised to notice it by.
+ * Real WOF postalcode distros tag every row `-1` ("unknown but treated as active") and the
+ * Pelias importer accepts `-1` alongside `1`; tightening the predicate to `= 1` makes the
+ * postalcode distros contribute zero rows to the corpus, silently, with no error to notice it by.
  */
 export function isCurrentFeature(props) {
     const raw = props["mz:is_current"];
@@ -44,37 +28,45 @@ export function isCurrentFeature(props) {
     return n !== 0;
 }
 /**
- * Pull `name:*` localized variants off a WOF feature's properties. WOF stores variants as arrays (`["Saint
- * Petersburg"]`); we lift the first non-empty string. Multiple-value variants (rare; usually historical aliases) are
- * not split into separate rows by this helper — adapters can opt in by iterating the underlying array if they need it.
+ * Pull `name:*` localized variants off a WOF feature's properties, lifting the first
+ * non-empty string from the array WOF stores them in (`["Saint Petersburg"]`);
+ * Multiple-value variants are rare and usually historical aliases.
+ *
+ * This function keeps them together.
+ * An adapter that needs separate values can iterate the underlying array.
  */
 export function extractNameVariants(props) {
     const out = new Map();
     for (const [key, value] of Object.entries(props)) {
         if (!key.startsWith("name:"))
             continue;
-        const candidate = Array.isArray(value)
-            ? value.find((v) => typeof v === "string" && v.trim().length > 0)
-            : typeof value === "string" && value.trim().length
-                ? value
-                : undefined;
+        const candidate = firstNonBlankString(value);
         if (candidate) {
-            out.set(key, candidate.trim());
+            out.set(key, candidate);
         }
     }
     return out;
 }
+function firstNonBlankString(value) {
+    for (const candidate of Array.isArray(value) ? value : [value]) {
+        if (typeof candidate !== "string")
+            continue;
+        const normalized = candidate.trim();
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+}
 /**
- * Turn a `name:*` property key into a hyphen-safe suffix fragment for `source_id`.
- *
- * `"name:eng_x_colloquial"` → `"name-eng-x-colloquial"`. `:` and `_` both become `-` because both collide with the
- * existing source_id separator vocabulary and downstream consumers split on `-`.
+ * Turn a `name:*` property key into a hyphen-safe suffix fragment for `source_id`
+ * (`"name:eng_x_colloquial"` → `"name-eng-x-colloquial"`); both `:` and `_` become `-`
+ * because both collide with the separator vocabulary downstream consumers split on.
  */
 export function normalizeNameKey(rawKey) {
     return rawKey.replaceAll(/[:_]/g, "-");
 }
 /**
- * Result of parsing a single GeoJSON file. `null` means "skip this row" (any reason).
+ * Parse a single GeoJSON feature; `null` means skip this row for any reason.
  */
 function recordFromFeature(feature) {
     if (!feature || feature.type !== "Feature" || !feature.properties)
@@ -90,9 +82,10 @@ function recordFromFeature(feature) {
     const placetype = props["wof:placetype"];
     if (typeof placetype !== "string" || !placetype)
         return null;
-    const country = props["wof:country"];
-    if (typeof country !== "string" || !country)
+    const rawCountry = props["wof:country"];
+    if (typeof rawCountry !== "string" || !rawCountry)
         return null;
+    const country = rawCountry.toUpperCase();
     if (!isCurrentFeature(props))
         return null;
     const parentRaw = props["wof:parent_id"];
@@ -111,21 +104,22 @@ function recordFromFeature(feature) {
     };
 }
 /**
- * Stream every canonical GeoJSON file under `repoDir` and yield parsed `WOFRecord`s.
+ * Stream every canonical GeoJSON file under `repoDir` and yield parsed `WOFRecord`s;
+ * `repoDir` may be a single cloned `whosonfirst-data-*` repo or a parent holding several
+ * (the corpus pipeline clones all four into a shared `wof/repos/` root).
  *
- * `repoDir` may point at a single cloned `whosonfirst-data-*` repo OR at a parent directory holding several such repos
- * (the corpus pipeline clones all four into a shared `wof/repos/` root and runs the adapter against that root).
- * `**\/*.geojson` walks the whole tree; `-alt-` siblings are skipped since they're alternate-geometry exports, not new
- * records.
+ * `-alt-` siblings are skipped as alternate-geometry exports.
+ * They do not represent new records.
  *
- * Errors per-file (unreadable, malformed JSON, missing properties) are swallowed so one bad file doesn't poison a 3 GB
- * walk. Adapters can add stricter validation downstream if they need it.
+ * Per-file errors (unreadable files, malformed JSON, or missing properties) are swallowed
+ * so one bad file does not poison a multi-gigabyte walk.
  */
 export async function* walkFeatures(repoDir, opts = {}) {
     for await (const filePath of Globerator.from("**/*.geojson", {
         cwd: repoDir,
+        absolute: true,
         exclude: ["**/*-alt-*.geojson"],
-        // Preserve the recursive fast-glob walk this replaces: bundle repositories can expose data through a link.
+        // Bundle repositories can expose their data through a link.
         followSymlinks: true,
         signal: opts.signal,
     })) {
@@ -145,10 +139,32 @@ export async function* walkFeatures(repoDir, opts = {}) {
         }
     }
 }
-export function buildAncestryIndex(byID) {
+/**
+ * The component tags a variant builder looks an ancestor up by.
+ *
+ * Measured over both adapters on 2026-09-28: `variantsFor` reads the nearest `region`
+ * and `country` ancestor, `postcodeVariantsFor` reads the nearest `locality`, `region` and `country`,
+ * and each one reads the ancestor's `placetype` to classify it and its `name` to use it.
+ * No caller reads an ancestor's `nameVariants`, `id`, `parent_id` or `country`.
+ */
+export const ANCESTOR_NAME_TAGS = ["locality", "region", "country"];
+/**
+ * Resolves {@linkcode AncestorNameIndex} from a record index.
+ *
+ * `tagOf` maps a WOF placetype to a component tag, or returns a value outside
+ * {@linkcode ANCESTOR_NAME_TAGS} for a placetype no builder looks up.
+ * It is a parameter because `placetypeToTag` lives with the adapters and this module does not import them.
+ *
+ * The walk stops at the first `parent_id` absent from `byID`, and a cycle guard halts at any re-visit.
+ * WOF data is acyclic by construction.
+ * The guard keeps a corrupt fixture from looping the adapter.
+ *
+ * A record whose ancestors are absent resolves the tags it can reach rather than failing.
+ */
+export function buildAncestorNameIndex(byID, tagOf) {
     const index = new Map();
     for (const [id, rec] of byID) {
-        const chain = [];
+        const names = {};
         const guard = new Set([id]);
         let cur = rec.parent_id;
         while (cur !== null && cur > 0) {
@@ -157,11 +173,16 @@ export function buildAncestryIndex(byID) {
                 break;
             if (guard.has(parent.id))
                 break;
-            chain.push(parent);
+            const tag = tagOf(parent.placetype);
+            for (const wanted of ANCESTOR_NAME_TAGS) {
+                if (tag === wanted && names[wanted] === undefined) {
+                    names[wanted] = parent.name;
+                }
+            }
             guard.add(parent.id);
             cur = parent.parent_id;
         }
-        index.set(id, chain);
+        index.set(id, names);
     }
     return index;
 }

package/out/utils/wof-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"wof-json.js","sourceRoot":"","sources":["../../lib/utils/wof-json.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wof-json.js","sourceRoot":"","sources":["../../lib/utils/wof-json.ts"],"names":[],"mappings":"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"}

package/out/{utils/index.js → utils.d.ts}

@@ -6,9 +6,8 @@
 export * from "#utils/align";
 export * from "#build";
 export * from "#utils/golden";
-export * from "#utils/parquet";
 export * from "#utils/license";
 export * from "#utils/split";
 export * from "#utils/tokenize";
 export * from "#utils/wof-json";
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=utils.d.ts.map

package/out/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../lib/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA"}

package/out/{utils/index.d.ts → utils.js}

@@ -6,9 +6,8 @@
 export * from "#utils/align";
 export * from "#build";
 export * from "#utils/golden";
-export * from "#utils/parquet";
 export * from "#utils/license";
 export * from "#utils/split";
 export * from "#utils/tokenize";
 export * from "#utils/wof-json";
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=utils.js.map

package/out/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../lib/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA"}

package/out/ve/recipes/reviewed-postcode-tail.d.ts

@@ -3,15 +3,16 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   A bounded, reviewed source for Venezuela's `locality postcode, region` convention (#1821).
- *   Bulk sources yielded zero Venezuelan tuples, so this recipe reads four reviewed facts and applies
- *   only transformations that do not create another postcode-to-place join.
+ *   Renders four hand-reviewed Venezuelan postcode facts in the `locality postcode, region` order.
  */
+import type { PathBuilderLike } from "path-ts";
 import { type CorpusRecipe } from "#recipes/scaffold";
 /**
- * A separate sampler bucket so a receipt measures these reviewed after-locality rows and no other postcode placement.
+ * The source label for these rows.
+ *
+ * The rows get their own sampler bucket so an eval can measure them apart from other postcode placements.
  */
-export declare const REVIEWED_POSTCODE_TAIL_SOURCE = "synth-reviewed-postcode-tail";
+export declare const REVIEWED_POSTCODE_TAIL_SOURCE: string;
 interface ReviewedTupleProvenance {
     publisher: string;
     url: string;
@@ -19,6 +20,9 @@ interface ReviewedTupleProvenance {
     reviewStatus: "reviewed";
     sourceLicenseNote: string;
 }
+/**
+ * One reviewed postcode fact and the source it was read from.
+ */
 export interface ReviewedPostcodeTuple {
     id: string;
     locality: string;
@@ -36,11 +40,25 @@ interface Variant {
     raw: string;
     components: Record<string, string>;
 }
+/**
+ * Returns the path of the committed reviewed-tuple data file.
+ */
 export declare function defaultReviewedPostcodeTuplePath(): string;
-export declare function readReviewedPostcodeTuples(path?: string): Promise<ReviewedPostcodeTuple[]>;
+/**
+ * Reads and validates the reviewed tuples.
+ *
+ * @throws When the file does not hold exactly four complete, unique, reviewed tuples.
+ */
+export declare function readReviewedPostcodeTuples(path?: PathBuilderLike): Promise<ReviewedPostcodeTuple[]>;
+/**
+ * Returns the surface variants of one tuple.
+ *
+ * Every variant reuses the tuple's own locality, postcode and region, so no variant
+ * pairs a postcode with a place the review did not cover.
+ */
 export declare function reviewedPostcodeTailVariants(tuple: ReviewedPostcodeTuple): Variant[];
 /**
- * Emit bounded surface variants of the committed reviewed facts without constructing another geographic join.
+ * The corpus recipe that emits every variant of every reviewed tuple.
  */
 export declare const reviewedPostcodeTailRecipe: CorpusRecipe;
 export {};

package/out/ve/recipes/reviewed-postcode-tail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reviewed-postcode-tail.d.ts","sourceRoot":"","sources":["../../../lib/ve/recipes/reviewed-postcode-tail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAiB,KAAK,YAAY,EAAiB,MAAM,mBAAmB,CAAA;AAEnF;;GAEG;AACH,eAAO,MAAM,6BAA6B,iCAAiC,CAAA;AAO3E,UAAU,uBAAuB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,UAAU,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,WAAW,CAAA;IACpB,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,OAAO,CAAA;IACf,iBAAiB,EAAE,gBAAgB,CAAA;IACnC,UAAU,EAAE,uBAAuB,CAAA;CACnC;AAQD,KAAK,SAAS,GACX,mBAAmB,GACnB,sBAAsB,GACtB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,eAAe,CAAA;AAElB,UAAU,OAAO;IAChB,EAAE,EAAE,SAAS,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAID,wBAAgB,gCAAgC,IAAI,MAAM,CAEzD;AAED,wBAAsB,0BAA0B,CAC/C,IAAI,SAAqC,GACvC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAsClC;AAID,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,EAAE,CAkCpF;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,YAkCxC,CAAA"}
+{"version":3,"file":"reviewed-postcode-tail.d.ts","sourceRoot":"","sources":["../../../lib/ve/recipes/reviewed-postcode-tail.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAiB,KAAK,YAAY,EAAkB,MAAM,mBAAmB,CAAA;AAKpF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAsD,CAAA;AAIhG,UAAU,uBAAuB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,UAAU,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,WAAW,CAAA;IACpB,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,OAAO,CAAA;IACf,iBAAiB,EAAE,gBAAgB,CAAA;IACnC,UAAU,EAAE,uBAAuB,CAAA;CACnC;AAQD,KAAK,SAAS,GACX,mBAAmB,GACnB,sBAAsB,GACtB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,eAAe,CAAA;AAElB,UAAU,OAAO;IAChB,EAAE,EAAE,SAAS,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAID;;GAEG;AACH,wBAAgB,gCAAgC,IAAI,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC/C,IAAI,GAAE,eAAoD,GACxD,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAsClC;AAID;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,EAAE,CAkCpF;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,YA2CxC,CAAA"}