@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/out/candidate/ancestors/schema.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the candidate gazetteer's ancestors sidecar (`candidate_ancestor` +
+ *   `candidate_interval`) — the containment lineage the candidate table itself cannot answer, built
+ *   into the same `candidate.db` by `build-candidate.ts` and read by
+ *   {@link WOFCandidateTableLookup.ancestors}.
+ *
+ *   The sidecar stores denormalized closure rows. Each row represents one (place, ancestor) edge. The row includes the
+ *   parent's placetype, display name and folded key. The two consumers determine this layout:
+ *
+ *   1. The admin-coherence check needs the winner's chain as (placetype, name) pairs in one probe.
+ *      A fixed-slot `[id.8]` chain returns ids. Each id would then need a name lookup, but the artifact has no
+ *      per-id table. That design requires up to 8 indirections. The closure row requires none.
+ *   2. The account layer needs every candidate under a `name_key` enumerable with its chain from
+ *      one artifact probe ("present-but-outranked, discriminated by containment"). That is the
+ *      candidate probe (contiguous) followed by one `spr_id`-clustered closure probe per candidate
+ *      — each a handful of adjacent pages.
+ *
+ *   The artifact is read over HTTP byte ranges. A join to a dimension table scatters page fetches. A `without rowid`
+ *   B-tree clustered on `(spr_id, depth)` keeps a whole chain in 1–2 pages. The builder repeats parent strings to
+ *   avoid joins during reads.
+ *
+ *   `depth` is 1 for the nearest ancestor (deepest containment tier) and increases outward to the
+ *   country. This matches the nearest-first order that `ancestry.ts` serves for the FTS backend. Both backends'
+ *   `ancestors()` results therefore use the same order. The order within a place is deterministic:
+ *   containment depth descending (`placetypeDepth`), then ancestor id ascending, capped at
+ *   {@link MAX_ANCESTOR_DEPTH}. `parent_name_key` is the shared {@link normalizeLocalityForKey}
+ *   fold — the same fold `candidate.name_key` is built with, so a chain entry and a candidate key
+ *   compare under one normalizer.
+ *
+ *   `candidate_interval` stores pre/post-order labels over the canonical-parent forest. The builder assigns them
+ *   during construction. The predicate `a.pre <= d.pre and d.post <= a.post` tests whether `a` contains `d` in O(1)
+ *   time. It needs no chain scan or tier information. Descendants of `a` occupy the contiguous range
+ *   `pre between a.pre and a.post`. Interval labels add relabeling work to updates. This database is sealed and
+ *   read-only, so the builder can regenerate all labels together.
+ *
+ *   WOF places can have multiple parents because boundaries can be ambiguous or participate in multiple
+ *   hierarchies. `candidate_ancestor` stores every parent. Its closure rows hold the complete containment record.
+ *   One interval pair encodes only a tree. The interval forest therefore links each place to one canonical parent:
+ *   the depth-1 edge with the finest containment tier and lowest ancestor id. This follows the same MIN-based
+ *   stability convention as the candidate table's `region_id` stamp. A containment query about another hierarchy
+ *   must consult the closure rows. The interval result answers only whether a place is contained along the canonical
+ *   hierarchy.
+ *
+ *   absence semantics (meaning-of-zero): a place with no `candidate_interval` row has no recorded
+ *   ancestry in the source (extract-fed postcodes and localities, isolated places, cycle-skipped
+ *   rows). Absence is unverifiable, never a containment verdict.
+ */
+import { type Kysely } from "kysely";
+import type { CandidateDatabase } from "#candidate/schema";
+import type { NameKey } from "#street/normalize";
+/**
+ * The deepest chain the sidecar stores per place.
+ *
+ * WOF containment within the resolvable placetypes (country … microhood) never legitimately exceeds this.
+ * The build drops and counts anything past it as source noise rather than storing it.
+ */
+export declare const MAX_ANCESTOR_DEPTH = 8;
+/**
+ * The closure-row table's name — probed with `hasTable` by the reader, so an artifact
+ * predating the sidecar degrades to "no ancestors capability" rather than `no such table`.
+ */
+export declare const CANDIDATE_ANCESTOR_TABLE = "candidate_ancestor";
+/**
+ * The interval-label table's name — the closure table's seal-time sibling.
+ * Existence-restricted the same way.
+ */
+export declare const CANDIDATE_INTERVAL_TABLE = "candidate_interval";
+/**
+ * One (place, ancestor) edge, denormalized so a chain read is a single clustered probe (no join).
+ */
+export interface CandidateAncestorTable {
+    /**
+     * WOF id of the place whose chain this row belongs to — the same `spr_id` the candidate table resolves to.
+     */
+    spr_id: number;
+    /**
+     * 1 = nearest ancestor, increasing outward to the country. Deterministic within a place (containment depth
+     * descending, then ancestor id ascending), so `(spr_id, depth)` is a stable primary key across rebuilds.
+     */
+    depth: number;
+    /**
+     * WOF id of the ancestor.
+     */
+    parent_spr_id: number;
+    /**
+     * Small int from the shared `placetype_codes` dictionary (the same one the candidate table uses).
+     */
+    parent_placetype_id: number;
+    /**
+     * The ancestor's canonical display name.
+     *
+     * What {@link Ancestor.name} serves, matching the FTS backend's register.
+     */
+    parent_name: string;
+    /**
+     * The shared {@link normalizeLocalityForKey} fold of `parent_name` — comparable against
+     * `candidate.name_key` and against a query-side fold under one normalizer, by construction.
+     */
+    parent_name_key: NameKey;
+}
+/**
+ * Pre/post-order labels over the canonical-parent forest — one row per place with
+ * recorded ancestry (see the module docstring for absence semantics).
+ *
+ * `pre < post` always.
+ * Labels are unique across the artifact.
+ */
+export interface CandidateIntervalTable {
+    spr_id: number;
+    pre: number;
+    post: number;
+}
+/**
+ * The sidecar tables, for a `Kysely` view over the candidate DB.
+ *
+ * `CandidateDatabase` (candidate-schema.ts) extends this, so the builder's
+ * one typed client sees both families.
+ */
+export interface CandidateAncestorsDatabase {
+    candidate_ancestor: CandidateAncestorTable;
+    candidate_interval: CandidateIntervalTable;
+}
+/**
+ * The `candidate_ancestor` columns in clustered-key order.
+ *
+ * The first two columns form the primary key.
+ * The builder's positional `insert` binds values in this order.
+ *
+ * Keep in sync with {@link CandidateAncestorTable}.
+ */
+export declare const CANDIDATE_ANCESTOR_COLUMNS: readonly ["spr_id", "depth", "parent_spr_id", "parent_placetype_id", "parent_name", "parent_name_key"];
+/**
+ * Create the clustered closure table.
+ *
+ * The builder inserts in `(spr_id, depth)` order so the B-tree leaves are contiguous
+ * per place — the byte-range read discipline.
+ */
+export declare function createCandidateAncestorTable(db: Kysely<CandidateDatabase>): Promise<void>;
+/**
+ * Create the interval-label table.
+ *
+ * Small rows probed by primary key — the `without rowid` win case.
+ */
+export declare function createCandidateIntervalTable(db: Kysely<CandidateDatabase>): Promise<void>;
+/**
+ * One place's interval label.
+ * The shape both sides of a containment comparison read.
+ */
+export interface IntervalLabel {
+    pre: number;
+    post: number;
+}
+/**
+ * Does `outer` contain `inner` along the canonical hierarchy?
+ *
+ * Reflexive: a place contains itself (containment degenerates to identity,
+ * the same reading the admin-coherence check gives a self-match).
+ * The shared function for every consumer of the labels — a re-derived comparison risks
+ * disagreeing at exactly the strict/inclusive boundary this line settles.
+ */
+export declare function intervalContains(outer: IntervalLabel, inner: IntervalLabel): boolean;
+//# sourceMappingURL=schema.d.ts.map

package/out/candidate/ancestors/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../lib/candidate/ancestors/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AAKzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uBAAuB,CAAA;AAE5D;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uBAAuB,CAAA;AAE5D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,mBAAmB,EAAE,MAAM,CAAA;IAC3B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IAC1C,kBAAkB,EAAE,sBAAsB,CAAA;IAC1C,kBAAkB,EAAE,sBAAsB,CAAA;CAC1C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,YACtC,QAAQ,EACR,OAAO,EACP,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,iBAAiB,CACR,CAAA;AAEV;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAAC,EAAE,EAAE,MAAM,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAa/F;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,CAAC,EAAE,EAAE,MAAM,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/F;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAEpF"}

package/out/candidate/ancestors/schema.js

@@ -0,0 +1,131 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Typed schema for the candidate gazetteer's ancestors sidecar (`candidate_ancestor` +
+ *   `candidate_interval`) — the containment lineage the candidate table itself cannot answer, built
+ *   into the same `candidate.db` by `build-candidate.ts` and read by
+ *   {@link WOFCandidateTableLookup.ancestors}.
+ *
+ *   The sidecar stores denormalized closure rows. Each row represents one (place, ancestor) edge. The row includes the
+ *   parent's placetype, display name and folded key. The two consumers determine this layout:
+ *
+ *   1. The admin-coherence check needs the winner's chain as (placetype, name) pairs in one probe.
+ *      A fixed-slot `[id.8]` chain returns ids. Each id would then need a name lookup, but the artifact has no
+ *      per-id table. That design requires up to 8 indirections. The closure row requires none.
+ *   2. The account layer needs every candidate under a `name_key` enumerable with its chain from
+ *      one artifact probe ("present-but-outranked, discriminated by containment"). That is the
+ *      candidate probe (contiguous) followed by one `spr_id`-clustered closure probe per candidate
+ *      — each a handful of adjacent pages.
+ *
+ *   The artifact is read over HTTP byte ranges. A join to a dimension table scatters page fetches. A `without rowid`
+ *   B-tree clustered on `(spr_id, depth)` keeps a whole chain in 1–2 pages. The builder repeats parent strings to
+ *   avoid joins during reads.
+ *
+ *   `depth` is 1 for the nearest ancestor (deepest containment tier) and increases outward to the
+ *   country. This matches the nearest-first order that `ancestry.ts` serves for the FTS backend. Both backends'
+ *   `ancestors()` results therefore use the same order. The order within a place is deterministic:
+ *   containment depth descending (`placetypeDepth`), then ancestor id ascending, capped at
+ *   {@link MAX_ANCESTOR_DEPTH}. `parent_name_key` is the shared {@link normalizeLocalityForKey}
+ *   fold — the same fold `candidate.name_key` is built with, so a chain entry and a candidate key
+ *   compare under one normalizer.
+ *
+ *   `candidate_interval` stores pre/post-order labels over the canonical-parent forest. The builder assigns them
+ *   during construction. The predicate `a.pre <= d.pre and d.post <= a.post` tests whether `a` contains `d` in O(1)
+ *   time. It needs no chain scan or tier information. Descendants of `a` occupy the contiguous range
+ *   `pre between a.pre and a.post`. Interval labels add relabeling work to updates. This database is sealed and
+ *   read-only, so the builder can regenerate all labels together.
+ *
+ *   WOF places can have multiple parents because boundaries can be ambiguous or participate in multiple
+ *   hierarchies. `candidate_ancestor` stores every parent. Its closure rows hold the complete containment record.
+ *   One interval pair encodes only a tree. The interval forest therefore links each place to one canonical parent:
+ *   the depth-1 edge with the finest containment tier and lowest ancestor id. This follows the same MIN-based
+ *   stability convention as the candidate table's `region_id` stamp. A containment query about another hierarchy
+ *   must consult the closure rows. The interval result answers only whether a place is contained along the canonical
+ *   hierarchy.
+ *
+ *   absence semantics (meaning-of-zero): a place with no `candidate_interval` row has no recorded
+ *   ancestry in the source (extract-fed postcodes and localities, isolated places, cycle-skipped
+ *   rows). Absence is unverifiable, never a containment verdict.
+ */
+import { sql } from "kysely";
+/**
+ * The deepest chain the sidecar stores per place.
+ *
+ * WOF containment within the resolvable placetypes (country … microhood) never legitimately exceeds this.
+ * The build drops and counts anything past it as source noise rather than storing it.
+ */
+export const MAX_ANCESTOR_DEPTH = 8;
+/**
+ * The closure-row table's name — probed with `hasTable` by the reader, so an artifact
+ * predating the sidecar degrades to "no ancestors capability" rather than `no such table`.
+ */
+export const CANDIDATE_ANCESTOR_TABLE = "candidate_ancestor";
+/**
+ * The interval-label table's name — the closure table's seal-time sibling.
+ * Existence-restricted the same way.
+ */
+export const CANDIDATE_INTERVAL_TABLE = "candidate_interval";
+/**
+ * The `candidate_ancestor` columns in clustered-key order.
+ *
+ * The first two columns form the primary key.
+ * The builder's positional `insert` binds values in this order.
+ *
+ * Keep in sync with {@link CandidateAncestorTable}.
+ */
+export const CANDIDATE_ANCESTOR_COLUMNS = [
+    "spr_id",
+    "depth",
+    "parent_spr_id",
+    "parent_placetype_id",
+    "parent_name",
+    "parent_name_key",
+];
+/**
+ * Create the clustered closure table.
+ *
+ * The builder inserts in `(spr_id, depth)` order so the B-tree leaves are contiguous
+ * per place — the byte-range read discipline.
+ */
+export async function createCandidateAncestorTable(db) {
+    await db.schema
+        .createTable(CANDIDATE_ANCESTOR_TABLE)
+        .addColumn("spr_id", "integer", (c) => c.notNull())
+        .addColumn("depth", "integer", (c) => c.notNull())
+        .addColumn("parent_spr_id", "integer", (c) => c.notNull())
+        .addColumn("parent_placetype_id", "integer", (c) => c.notNull())
+        .addColumn("parent_name", "text", (c) => c.notNull())
+        .addColumn("parent_name_key", "text", (c) => c.notNull())
+        .addPrimaryKeyConstraint("candidate_ancestor_pk", ["spr_id", "depth"])
+        // `without rowid` has no first-class builder. The raw modifier is the idiomatic fallback.
+        .modifyEnd(sql `without rowid`)
+        .execute();
+}
+/**
+ * Create the interval-label table.
+ *
+ * Small rows probed by primary key — the `without rowid` win case.
+ */
+export async function createCandidateIntervalTable(db) {
+    await db.schema
+        .createTable(CANDIDATE_INTERVAL_TABLE)
+        .addColumn("spr_id", "integer", (c) => c.primaryKey())
+        .addColumn("pre", "integer", (c) => c.notNull())
+        .addColumn("post", "integer", (c) => c.notNull())
+        .modifyEnd(sql `without rowid`)
+        .execute();
+}
+/**
+ * Does `outer` contain `inner` along the canonical hierarchy?
+ *
+ * Reflexive: a place contains itself (containment degenerates to identity,
+ * the same reading the admin-coherence check gives a self-match).
+ * The shared function for every consumer of the labels — a re-derived comparison risks
+ * disagreeing at exactly the strict/inclusive boundary this line settles.
+ */
+export function intervalContains(outer, inner) {
+    return outer.pre <= inner.pre && inner.post <= outer.post;
+}
+//# sourceMappingURL=schema.js.map

package/out/candidate/ancestors/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../lib/candidate/ancestors/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAE,GAAG,EAAe,MAAM,QAAQ,CAAA;AAQzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAAoB,CAAA;AAE5D;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAAoB,CAAA;AA4D5D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC,QAAQ;IACR,OAAO;IACP,eAAe;IACf,qBAAqB;IACrB,aAAa;IACb,iBAAiB;CACR,CAAA;AAEV;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,EAA6B;IAC/E,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,wBAAwB,CAAC;SACrC,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClD,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACjD,SAAS,CAAC,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACzD,SAAS,CAAC,qBAAqB,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/D,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACpD,SAAS,CAAC,iBAAiB,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACxD,uBAAuB,CAAC,uBAAuB,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACtE,0FAA0F;SACzF,SAAS,CAAC,GAAG,CAAA,eAAe,CAAC;SAC7B,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,EAA6B;IAC/E,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,wBAAwB,CAAC;SACrC,SAAS,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SACrD,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAChD,SAAS,CAAC,GAAG,CAAA,eAAe,CAAC;SAC7B,OAAO,EAAE,CAAA;AACZ,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAoB,EAAE,KAAoB;IAC1E,OAAO,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAA;AAC1D,CAAC"}

package/out/candidate/ancestors/sidecar.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pass 3b of the candidate build — the containment sidecar (closure rows + interval labels).
+ */
+import type { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { PlaceAttrs } from "#candidate/place-attrs";
+import type { CandidateDatabase } from "#candidate/schema";
+import type { WOFDatabase } from "#schema";
+/**
+ * Build the ancestors sidecar (closure rows plus interval labels) from the source
+ * `ancestors` table, excluding self rows and placetypes outside the containment ladder.
+ * an edge to a parent with no current `spr` row is dropped and counted.
+ */
+export declare function buildAncestorsSidecar(ctx: {
+    src: DatabaseClient<WOFDatabase>;
+    out: DatabaseClient<CandidateDatabase>;
+    attrs: Map<number, PlaceAttrs>;
+    ptID: (pt: string | null) => number;
+    progress: (phase: string, message: string) => void;
+}): Promise<{
+    ancestorRows: number;
+    ancestorPlaces: number;
+    intervalPlaces: number;
+}>;
+//# sourceMappingURL=sidecar.d.ts.map

package/out/candidate/ancestors/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../../../lib/candidate/ancestors/sidecar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAW9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE;IAChD,GAAG,EAAE,cAAc,CAAC,WAAW,CAAC,CAAA;IAChC,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IACtC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC9B,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAClD,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAmKpF"}

package/out/candidate/{ancestors-sidecar.js → ancestors/sidecar.js}

@@ -4,17 +4,12 @@
  * @author Teffen Ellis, et al.
  * @file Pass 3b of the candidate build — the containment sidecar (closure rows + interval labels).
  */
-import { placetypeDepth } from "#ancestry/index";
-import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE, CANDIDATE_INTERVAL_TABLE, createCandidateAncestorTable, createCandidateIntervalTable, MAX_ANCESTOR_DEPTH, } from "#candidate-ancestors-schema";
+import { placetypeDepth } from "#ancestry";
+import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE, CANDIDATE_INTERVAL_TABLE, createCandidateAncestorTable, createCandidateIntervalTable, MAX_ANCESTOR_DEPTH, } from "#candidate/ancestors/schema";
 /**
- * Pass 3b — the ancestors sidecar: closure rows + interval labels (candidate-ancestors-schema.ts owns the encoding
- * decision and the DAG/absence semantics). Reads the same source `ancestors` table the region stamp reads,
- * denormalizing each edge with the parent's name/key from `attrs`, streamed `ORDER BY id` so the clustered `(spr_id,
- * depth)` insert is sorted — the contiguous-leaves discipline of the candidate table itself.
- *
- * Excluded by policy: self rows, and placetypes outside the containment ladder (continent, empire, …: `placetypeDepth` 0)
- * — they discriminate nothing a consumer of this sidecar checks. An edge to a parent with no current `spr` row has no
- * name to denormalize; it is dropped and counted rather than stored blind.
+ * Build the ancestors sidecar (closure rows plus interval labels) from the source
+ * `ancestors` table, excluding self rows and placetypes outside the containment ladder.
+ * an edge to a parent with no current `spr` row is dropped and counted.
  */
 export async function buildAncestorsSidecar(ctx) {
     const { src, out, attrs, ptID, progress } = ctx;
@@ -22,23 +17,22 @@ export async function buildAncestorsSidecar(ctx) {
     await createCandidateAncestorTable(ctx.out);
     await createCandidateIntervalTable(ctx.out);
     const insAncestor = out.prepare(`INSERT INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`);
-    // The canonical-parent forest the interval labels are computed over. One parent per place — the
-    // depth-1 edge (finest containment tier, lowest ancestor id; the `regionOf` MIN-stability
-    // convention). ALL parents stay in the closure rows; only the interval tree canonicalizes.
+    // One parent per place (the finest containment tier, lowest ancestor id) canonicalizes the interval tree.
+    // All parents stay in the closure rows.
     const canonicalParentOf = new Map();
     const childrenOf = new Map();
     const forest = new Set();
     let ancestorRows = 0;
     let ancestorPlaces = 0;
     let droppedParents = 0;
-    // Per-child edge buffer; the stream below is grouped by child id, so each flush owns one place.
+    // The stream is grouped by child id, so each flush owns one place.
     let childID = -1;
     let edges = [];
     const flush = () => {
         if (childID < 0 || !edges.length)
             return;
-        // Deterministic nearest-first: containment depth descending, then ancestor id ascending —
-        // the FTS backend's `ancestorLineage` ordering, made stable across rebuilds.
+        // Deterministic nearest-first: containment depth descending, then ancestor id ascending,
+        // matching the FTS backend's `ancestorLineage` ordering across rebuilds.
         edges.sort((a, b) => placetypeDepth(b.apt) - placetypeDepth(a.apt) || a.aid - b.aid);
         if (edges.length > MAX_ANCESTOR_DEPTH) {
             edges = edges.slice(0, MAX_ANCESTOR_DEPTH);
@@ -85,8 +79,8 @@ export async function buildAncestorsSidecar(ctx) {
     }
     flush();
     out.exec("COMMIT");
-    // Interval labels: pre/post-order DFS over the canonical-parent forest. Root order and child
-    // order are id-ascending so the labels are stable across rebuilds of the same source.
+    // Interval labels are a pre/post-order DFS over the canonical-parent forest, with root
+    // and child order id-ascending so labels stay stable across rebuilds.
     const preOf = new Map();
     const postOf = new Map();
     for (const kids of childrenOf.values()) {
@@ -105,8 +99,8 @@ export async function buildAncestorsSidecar(ctx) {
             const kids = childrenOf.get(top.id);
             if (kids && top.next < kids.length) {
                 const kid = kids[top.next++];
-                // Each child holds exactly one canonical parent, so a labeled node here means the
-                // grouping upstream broke — skip rather than corrupt the numbering.
+                // Each child holds exactly one canonical parent, so a labeled node means upstream grouping broke.
+                // Skip rather than corrupt the numbering.
                 if (preOf.has(kid))
                     continue;
                 preOf.set(kid, counter++);
@@ -118,9 +112,8 @@ export async function buildAncestorsSidecar(ctx) {
             }
         }
     }
-    // A canonical-parent CYCLE (corrupt source ancestry) leaves its members unreachable from any
-    // root: they simply receive no label, and containment against them reads unverifiable — the
-    // absence semantics the schema module states. Counted so a jump is visible across rebuilds.
+    // A canonical-parent cycle leaves its members unreachable from any root,
+    // so they receive no label and containment against them reads unverifiable.
     const cycleSkipped = forest.size - preOf.size;
     const insInterval = out.prepare(`INSERT INTO ${CANDIDATE_INTERVAL_TABLE} VALUES (?, ?, ?)`);
     const labeled = [...preOf.keys()];
@@ -137,4 +130,4 @@ export async function buildAncestorsSidecar(ctx) {
         (cycleSkipped ? `; ${cycleSkipped.toLocaleString()} places skipped (canonical-parent cycle)` : ""));
     return { ancestorRows, ancestorPlaces, intervalPlaces: preOf.size };
 }
-//# sourceMappingURL=ancestors-sidecar.js.map
+//# sourceMappingURL=sidecar.js.map

package/out/candidate/ancestors/sidecar.js.map

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

package/out/candidate/country-display-names.d.ts

@@ -2,26 +2,16 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 1b of the candidate build — fold ICU's country display names onto the country rows.
  */
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs";
 /**
- * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).
+ * Stages each country name that `Intl.DisplayNames` renders in the codex display-name
+ * locales as a non-primary key on that country's candidate row.
  *
- * A bare `格鲁吉亚` (Georgia the country) resolved to NOTHING while `佐治亚州` (Georgia the US state) resolved correctly, and
- * the model gave both the same wrong `locality` tag — so the tag was never the variable. Measured 2026-08-15: 140 of
- * 237 country rows are synthetic and carry a canonical English name and nothing else; WOF holds no Chinese country
- * names at all; and the GeoNames alias fold filters through a Latin-script regex, so neither existing source could ever
- * supply them.
+ * The row's display name is unchanged, so a query such as `格鲁吉亚` resolves to the existing Georgia row.
+ * When several country rows share an ISO code, the most populous one receives the keys.
  *
- * `Intl.DisplayNames` already knows every one — ~280 regions, ~5,244 surfaces, from the same ICU the runtime uses for
- * every other locale-sensitive operation. No download, no vendored corpus, no snapshot to drift.
- *
- * `is_primary = 0`: these are NAMES THE WORLD USES, not the country's canonical name. The display `name` stays whatever
- * the gazetteer already had, so resolving `格鲁吉亚` answers with the Georgia country row rather than renaming it.
- *
- * Returns the row count so the caller can report it — a zero means ICU supplied nothing, which is a different fact from
- * the pass not having run.
+ * @returns The number of rows staged.
  */
 export declare function stageCountryDisplayNames(ctx: {
     attrs: Map<number, PlaceAttrs>;

package/out/candidate/country-display-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"country-display-names.d.ts","sourceRoot":"","sources":["../../lib/candidate/country-display-names.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGlE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE;IAC7C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC9B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,QAAQ,CAAA;IAClB,EAAE,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAC/B,GAAG,MAAM,CA0CT"}
+{"version":3,"file":"country-display-names.d.ts","sourceRoot":"","sources":["../../lib/candidate/country-display-names.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAGlE;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE;IAC7C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC9B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,QAAQ,CAAA;IAClB,EAAE,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAC/B,GAAG,MAAM,CAsCT"}

package/out/candidate/country-display-names.js

@@ -2,31 +2,19 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 1b of the candidate build — fold ICU's country display names onto the country rows.
  */
 import { enumerateCountryDisplayNames } from "@mailwoman/codex/country";
 import { normalizeLocalityForKey } from "#street/normalize";
 /**
- * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).
+ * Stages each country name that `Intl.DisplayNames` renders in the codex display-name
+ * locales as a non-primary key on that country's candidate row.
  *
- * A bare `格鲁吉亚` (Georgia the country) resolved to NOTHING while `佐治亚州` (Georgia the US state) resolved correctly, and
- * the model gave both the same wrong `locality` tag — so the tag was never the variable. Measured 2026-08-15: 140 of
- * 237 country rows are synthetic and carry a canonical English name and nothing else; WOF holds no Chinese country
- * names at all; and the GeoNames alias fold filters through a Latin-script regex, so neither existing source could ever
- * supply them.
+ * The row's display name is unchanged, so a query such as `格鲁吉亚` resolves to the existing Georgia row.
+ * When several country rows share an ISO code, the most populous one receives the keys.
  *
- * `Intl.DisplayNames` already knows every one — ~280 regions, ~5,244 surfaces, from the same ICU the runtime uses for
- * every other locale-sensitive operation. No download, no vendored corpus, no snapshot to drift.
- *
- * `is_primary = 0`: these are NAMES THE WORLD USES, not the country's canonical name. The display `name` stays whatever
- * the gazetteer already had, so resolving `格鲁吉亚` answers with the Georgia country row rather than renaming it.
- *
- * Returns the row count so the caller can report it — a zero means ICU supplied nothing, which is a different fact from
- * the pass not having run.
+ * @returns The number of rows staged.
  */
 export function stageCountryDisplayNames(ctx) {
-    // One country row per ISO2. Where a code has several (historic rows surviving the is_current filter), the most
-    // populous wins — the same tiebreak the ranking uses everywhere else.
     const countryByISO2 = new Map();
     for (const [sid, a] of ctx.attrs) {
         if (a.ptid !== ctx.countryPtID)
@@ -35,7 +23,7 @@ export function stageCountryDisplayNames(ctx) {
         if (!iso2 || iso2 === "??")
             continue;
         const held = countryByISO2.get(iso2);
-        if (!held || a.pop > held.a.pop) {
+        if (!held || (a.pop ?? 0) > (held.a.pop ?? 0)) {
             countryByISO2.set(iso2, { sid, a });
         }
     }
@@ -46,8 +34,6 @@ export function stageCountryDisplayNames(ctx) {
         if (!target)
             continue;
         const k = normalizeLocalityForKey(name);
-        // The country's own key is already staged as its primary; INSERT OR IGNORE at materialization dedupes the
-        // rest, so this only skips the obvious self-alias.
         if (!k || k === target.a.pkey)
             continue;
         ctx.stageRow(k, target.a, target.sid, 0);

package/out/candidate/country-display-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"country-display-names.js","sourceRoot":"","sources":["../../lib/candidate/country-display-names.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAMxC;IACA,+GAA+G;IAC/G,sEAAsE;IACtE,MAAM,aAAa,GAAG,IAAI,GAAG,EAA0C,CAAA;IAEvE,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,WAAW;YAAE,SAAQ;QAExC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,SAAQ;QAEpC,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;YACjC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QACpC,CAAC;IACF,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEpB,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,4BAA4B,EAAE,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEtC,IAAI,CAAC,MAAM;YAAE,SAAQ;QAErB,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAEvC,0GAA0G;QAC1G,mDAAmD;QACnD,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;YAAE,SAAQ;QAEvC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAExC,MAAM,EAAE,CAAA;IACT,CAAC;IAED,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAErB,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"country-display-names.js","sourceRoot":"","sources":["../../lib/candidate/country-display-names.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAMxC;IACA,MAAM,aAAa,GAAG,IAAI,GAAG,EAA0C,CAAA;IAEvE,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,WAAW;YAAE,SAAQ;QAExC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,SAAQ;QAEpC,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEpC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC;YAC/C,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QACpC,CAAC;IACF,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEpB,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,4BAA4B,EAAE,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAEtC,IAAI,CAAC,MAAM;YAAE,SAAQ;QAErB,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;QAEvC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI;YAAE,SAAQ;QAEvC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAExC,MAAM,EAAE,CAAA;IACT,CAAC;IAED,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAErB,OAAO,MAAM,CAAA;AACd,CAAC"}

package/out/candidate/extract-fold.d.ts

@@ -2,34 +2,26 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
  */
 import { DatabaseClient } from "@mailwoman/sqlite/client";
-import type { CandidateDatabase } from "#candidate-schema";
+import type { PathBuilderLike } from "path-ts";
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs";
+import type { CandidateDatabase } from "#candidate/schema";
 /**
- * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
- * hanging off that same extract's `names` table.
+ * Stages one postcode or locality extract's located `spr` rows and their `names`
+ * aliases into the candidate table.
  *
- * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
- * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
- * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
- * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
+ * When `attrs` is given and the extract's `ancestors` table places a row in a known region,
+ * the row also gets that region's scope and the region's ancestor chain.
+ * The stored ancestors then agree with the row's scope.
  */
 export declare function foldExtract(ctx: {
-    /**
-     * The staging connection. The extract itself is opened read-only here and closed before returning.
-     */
     out: DatabaseClient<CandidateDatabase>;
-    extractPath: string;
+    extractPath: PathBuilderLike;
     extractPlacetype: "postalcode" | "locality";
     ccID: (code: string | null) => number;
     ptID: (pt: string | null) => number;
     stageRow: StageRow;
-    /**
-     * The admin places pass 1 staged — what an extract's region ancestry is resolved against. Absent, no extract row
-     * takes a region scope (the postcode extracts, which carry none).
-     */
     attrs?: Map<number, PlaceAttrs>;
     progress: (phase: string, message: string) => void;
 }): {

package/out/candidate/extract-fold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-fold.d.ts","sourceRoot":"","sources":["../../lib/candidate/extract-fold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAIzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAmClE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAChC;;OAEG;IACH,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,YAAY,GAAG,UAAU,CAAA;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACrC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACnC,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAClD,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAkJ/E"}
+{"version":3,"file":"extract-fold.d.ts","sourceRoot":"","sources":["../../lib/candidate/extract-fold.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AA0B1D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAChC,GAAG,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAA;IACtC,WAAW,EAAE,eAAe,CAAA;IAC5B,gBAAgB,EAAE,YAAY,GAAG,UAAU,CAAA;IAC3C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACrC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,CAAA;IACnC,QAAQ,EAAE,QAAQ,CAAA;IAElB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAClD,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAqH/E"}