@mailwoman/corpus 2.0.0

package/out/src/adapters/wof-admin-json/adapter.js

@@ -0,0 +1,241 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin`: Who's On First admin GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** The original Phase 1.5 SQLite adapter (formerly at
+ *   `packages/corpus/src/adapters/wof-admin/`, removed in this same change) was replaced by this
+ *   one because the SQLite distribution path was unworkable for the real corpus build:
+ *
+ *   1. `dist.whosonfirst.org/sqlite/` is dead (NXDOMAIN); the Geocode-Earth mirror is the only one.
+ *   2. The Geocode-Earth-hosted postalcode DB tags every row `mz:is_current = -1` ("unknown but treated
+ *        as active"); the SQLite adapter's `is_current = 1` predicate emitted zero rows.
+ *   3. The `names` table in the SQLite distribution is empty — localized `name:*` variants live in a
+ *        separate distribution. The St. Petersburg / Mt. Vernon / Ft. Lauderdale alternation cases
+ *        (the original Phase 1.5.1 motivator) cannot be solved on the SQLite path even with a
+ *        patched `is_current` predicate.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-admin-<cc>` GitHub repos. Each
+ *   repo has `data/XXX/YYY/ZZZ/<wof-id>.geojson` files; `**\/*.geojson` walks the tree recursively.
+ *   Alternate-geometry siblings (`-alt-*`) are skipped — they're separate exports of the same
+ *   record, not new records.
+ *
+ *   Per record, the adapter emits one row per `(name-variant, hierarchy-variant)` pair:
+ *
+ *   - **Name variants**: the canonical `wof:name` (slot key `default`) plus every `name:*` localized
+ *       variant present on the feature (`name:eng_x_preferred`, `name:eng_x_colloquial`,
+ *       `name:rus_x_preferred`, ...). This is the Phase 1.5.1 fix for the St. Petersburg case:
+ *       `"Saint Petersburg"` (canonical) and `"St. Petersburg"` (eng_x_colloquial) both become
+ *       training rows for the same WOF id.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): locality → 3 variants, region → 2,
+ *       country → 1, county → 1.
+ *
+ *   `source_id` is `wof-admin-<wof_id>-<name-slot>-<hierarchy-variant>`. The previous SQLite adapter
+ *   used `wof-admin-<wof_id>-<hierarchy-variant>` (no name slot); the new format adds a name-slot
+ *   segment so the colloquial / preferred / per-locale variants survive dedup independently.
+ *
+ *   License: CC0. The adapter stamps every row with `CC0-1.0`.
+ */
+import { formatAddress, reconcileComponents } from "../../format.js";
+import { buildAncestryIndex, normalizeNameKey, walkFeatures } from "../../wof-json.js";
+/**
+ * Display name for the country, keyed by ISO 3166-1 alpha-2.
+ *
+ * Must be the **OpenCage-canonical** surface form: the `address-formatter` library expands some
+ * country names en route to its output (e.g. `"United States"` → `"United States of America"`). If
+ * `components.country` and the formatted `raw` disagree, alignment will fail downstream. Keying off
+ * the canonical form keeps the two in lockstep.
+ *
+ * Phase 1 US + FR only; extend as new locales come online. Missing countries fall back to the
+ * country row's `wof:name`, accepting the alignment risk for non-canonicalized names.
+ */
+const COUNTRY_DISPLAY_NAME = {
+    US: "United States of America",
+    FR: "France",
+};
+/** BCP-47 locale defaulting for the corpus row's `locale` field. Defaulted by country. */
+const LOCALE_BY_COUNTRY = {
+    US: "en-US",
+    FR: "fr-FR",
+};
+/** Map a WOF placetype to a Mailwoman `ComponentTag`, or `undefined` to skip. */
+function placetypeToTag(placetype) {
+    switch (placetype) {
+        case "country":
+        case "nation":
+            return "country";
+        case "macroregion":
+        case "region":
+            return "region";
+        case "macrocounty":
+        case "county":
+        case "localadmin":
+            return "subregion";
+        case "locality":
+            return "locality";
+        case "borough":
+        case "macrohood":
+        case "neighbourhood":
+        case "microhood":
+            return "dependent_locality";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Compute the hierarchy variants for a record given its ancestry chain and the chosen `selfName`.
+ *
+ * `selfName` is the surface form to use for the record's own component (locality / region / country
+ * / subregion). Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*`
+ * localized value for variant slots; ancestor names always come from the ancestor's canonical
+ * `wof:name`.
+ *
+ * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the OpenCage template
+ * produces the canonicalized form (`"United States of America"`), matching the legacy SQLite
+ * adapter's behavior.
+ */
+export function variantsFor(row, ancestry, selfName) {
+    const selfTag = placetypeToTag(row.placetype);
+    if (!selfTag)
+        return [];
+    const region = ancestry.find((a) => placetypeToTag(a.placetype) === "region");
+    const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country");
+    const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country;
+    const variants = [];
+    switch (selfTag) {
+        case "locality":
+        case "dependent_locality": {
+            variants.push({ suffix: "self", components: { [selfTag]: selfName } });
+            if (region) {
+                variants.push({
+                    suffix: "with-region",
+                    components: { [selfTag]: selfName, region: region.name },
+                });
+            }
+            if (region && country) {
+                variants.push({
+                    suffix: "with-region-country",
+                    components: { [selfTag]: selfName, region: region.name, country: countryDisplay },
+                });
+            }
+            else if (!region && country) {
+                variants.push({
+                    suffix: "with-country",
+                    components: { [selfTag]: selfName, country: countryDisplay },
+                });
+            }
+            return variants;
+        }
+        case "region": {
+            variants.push({ suffix: "self", components: { region: selfName } });
+            if (country) {
+                variants.push({
+                    suffix: "with-country",
+                    components: { region: selfName, country: countryDisplay },
+                });
+            }
+            return variants;
+        }
+        case "country": {
+            variants.push({ suffix: "self", components: { country: selfName } });
+            return variants;
+        }
+        case "subregion": {
+            variants.push({ suffix: "self", components: { subregion: selfName } });
+            return variants;
+        }
+        default:
+            return [];
+    }
+}
+/**
+ * Build the per-record name-slot list. The canonical `"default"` slot uses the OpenCage-canonical
+ * country form when the record is itself a country (matches SQLite-adapter behavior); every other
+ * placetype's default slot uses `wof:name` verbatim.
+ *
+ * Subsequent slots come from `name:*` variants, deduplicated against the default name so we don't
+ * emit a redundant `"default"`-equivalent row under a localized key.
+ */
+export function nameSlotsFor(rec) {
+    const selfTag = placetypeToTag(rec.placetype);
+    const canonicalSelfName = selfTag === "country" ? (COUNTRY_DISPLAY_NAME[rec.country] ?? rec.name) : rec.name;
+    const seen = new Set([canonicalSelfName]);
+    const slots = [{ key: "default", value: canonicalSelfName }];
+    for (const [rawKey, value] of rec.nameVariants) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        slots.push({ key: normalizeNameKey(rawKey), value });
+    }
+    return slots;
+}
+export const WOF_ADMIN_ADAPTER_ID = "wof-admin";
+/**
+ * Construct the wof-admin JSON-bundle adapter. The adapter is stateless across runs; calling this
+ * twice with the same input directory produces byte-identical `canonical.jsonl` (records are
+ * emitted in sorted `wof:id` order to be insensitive to filesystem walk ordering).
+ */
+export function createWofAdminAdapter() {
+    return {
+        id: WOF_ADMIN_ADAPTER_ID,
+        defaultLicense: "CC0-1.0",
+        description: "Who's On First admin GeoJSON bundles (countries, regions, counties, localities) — multi-name variants per record.",
+        async *rows(opts) {
+            // Pass 1: scan every GeoJSON file once, build the in-memory record index.
+            // We keep only records whose placetype maps to a ComponentTag — irrelevant placetypes
+            // (campus, county-region hybrids on which Mailwoman has no opinion) are dropped here so
+            // they don't inflate the ancestry index. Country-filtered runs prune to the matching
+            // country code too; the ancestors of a same-country record live in the same admin repo.
+            const byId = new Map();
+            for await (const rec of walkFeatures(opts.inputPath, { signal: opts.signal })) {
+                if (opts.signal?.aborted)
+                    return;
+                if (opts.country && rec.country !== opts.country)
+                    continue;
+                if (!placetypeToTag(rec.placetype))
+                    continue;
+                byId.set(rec.id, rec);
+            }
+            const ancestry = buildAncestryIndex(byId);
+            // Pass 2: emit rows in sorted-id order for deterministic JSONL.
+            const ids = [...byId.keys()].sort((a, b) => a - b);
+            let emitted = 0;
+            for (const id of ids) {
+                if (opts.signal?.aborted)
+                    return;
+                const rec = byId.get(id);
+                const chain = ancestry.get(id) ?? [];
+                const slots = nameSlotsFor(rec);
+                for (const slot of slots) {
+                    const variants = variantsFor(rec, chain, slot.value);
+                    for (const variant of variants) {
+                        if (opts.limit !== undefined && emitted >= opts.limit)
+                            return;
+                        const raw = formatAddress(variant.components, rec.country, { separator: ", " });
+                        if (!raw)
+                            continue;
+                        const aligned = reconcileComponents(variant.components, raw);
+                        if (Object.keys(aligned).length === 0)
+                            continue;
+                        yield {
+                            raw,
+                            components: aligned,
+                            country: rec.country,
+                            locale: LOCALE_BY_COUNTRY[rec.country],
+                            source: WOF_ADMIN_ADAPTER_ID,
+                            source_id: `${WOF_ADMIN_ADAPTER_ID}-${rec.id}-${slot.key}-${variant.suffix}`,
+                            corpus_version: "",
+                            license: "CC0-1.0",
+                        };
+                        emitted++;
+                    }
+                }
+            }
+        },
+    };
+}
+/** Single shared instance, suitable for `defaultAdapterRegistry`. */
+export const wofAdminAdapter = createWofAdminAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/src/adapters/wof-admin-json/adapter.js.map

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

package/out/src/adapters/wof-postalcode-json/adapter.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-postalcode`: Who's On First postalcode GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** Replaces the previous SpatiaLite-backed implementation (formerly at
+ *   `packages/corpus/src/adapters/wof-postalcode/`, removed in this same change). The rationale is
+ *   in `wof-admin-json/adapter.ts` and in `DECISIONS.md` — short version: the SQLite distribution
+ *   mirror is dead, the live distro tags every postcode row `mz:is_current = -1` which the old
+ *   `is_current = 1` predicate excluded, and localized `name:*` variants don't ship in the SQLite
+ *   export at all.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-postalcode-<cc>` repos plus
+ *   the relevant `whosonfirst-data-admin-<cc>` repos (postcode records reference admin ancestry by
+ *   `wof:parent_id`, so the locality / region / country records must be in the same walk for the
+ *   ancestry chain to resolve). The corpus pipeline clones all four repos under
+ *   `/data/corpus/sources/wof/repos/` and points the adapter at that root.
+ *
+ *   Per live postalcode record, the adapter emits one row per `(name-variant, hierarchy-variant)`
+ *   pair:
+ *
+ *   - **Name variants**: canonical `wof:name` (slot key `default`, typically the postcode digits
+ *       themselves) plus any `name:*` variants on the postcode feature. In practice WOF postcode
+ *       records rarely carry localized name variants, so this expansion is usually a no-op — but
+ *       the code path stays symmetric with the admin adapter for consistency.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): self, +locality, +locality+region,
+ *       +locality+region+country.
+ *
+ *   `source_id` is `wof-postalcode-<wof_id>-<name-slot>-<hierarchy-variant>`. Ancestor names always
+ *   come from the ancestor's canonical `wof:name`; this adapter does NOT iterate ancestor name
+ *   variants (e.g. it does not emit `"75008 Париж"` even when Paris has a `name:rus_x_preferred`).
+ *   That cross-product belongs to a future synthesis pass; emitting it here would multiply row
+ *   counts ~10× without a clear training-value story.
+ *
+ *   License: CC0.
+ */
+import type { ComponentTag } from "@mailwoman/core/types";
+import type { CorpusAdapter } from "../../types.js";
+import { type WofRecord } from "../../wof-json.js";
+interface VariantSpec {
+    suffix: string;
+    components: Partial<Record<ComponentTag, string>>;
+}
+/**
+ * Compute hierarchy variants for a postcode record. `selfName` is the postcode surface form
+ * (canonical `wof:name` for the `default` slot, a `name:*` localized variant otherwise).
+ */
+export declare function postcodeVariantsFor(row: WofRecord, ancestry: WofRecord[], selfName: string): VariantSpec[];
+/**
+ * Build the per-record name-slot list. The `default` slot uses `wof:name` verbatim (postcode
+ * digits); subsequent slots come from `name:*` variants dedup'd against the default.
+ */
+export declare function nameSlotsFor(rec: WofRecord): Array<{
+    key: string;
+    value: string;
+}>;
+export declare const WOF_POSTALCODE_ADAPTER_ID = "wof-postalcode";
+export declare function createWofPostalcodeAdapter(): CorpusAdapter;
+export declare const wofPostalcodeAdapter: CorpusAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/out/src/adapters/wof-postalcode-json/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/wof-postalcode-json/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACjF,OAAO,EAAsD,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAA;AA6BtG,UAAU,WAAW;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;CACjD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAmC1G;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CASlF;AAED,eAAO,MAAM,yBAAyB,mBAAmB,CAAA;AAEzD,wBAAgB,0BAA0B,IAAI,aAAa,CA2D1D;AAED,eAAO,MAAM,oBAAoB,eAA+B,CAAA"}

package/out/src/adapters/wof-postalcode-json/adapter.js

@@ -0,0 +1,178 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-postalcode`: Who's On First postalcode GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** Replaces the previous SpatiaLite-backed implementation (formerly at
+ *   `packages/corpus/src/adapters/wof-postalcode/`, removed in this same change). The rationale is
+ *   in `wof-admin-json/adapter.ts` and in `DECISIONS.md` — short version: the SQLite distribution
+ *   mirror is dead, the live distro tags every postcode row `mz:is_current = -1` which the old
+ *   `is_current = 1` predicate excluded, and localized `name:*` variants don't ship in the SQLite
+ *   export at all.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-postalcode-<cc>` repos plus
+ *   the relevant `whosonfirst-data-admin-<cc>` repos (postcode records reference admin ancestry by
+ *   `wof:parent_id`, so the locality / region / country records must be in the same walk for the
+ *   ancestry chain to resolve). The corpus pipeline clones all four repos under
+ *   `/data/corpus/sources/wof/repos/` and points the adapter at that root.
+ *
+ *   Per live postalcode record, the adapter emits one row per `(name-variant, hierarchy-variant)`
+ *   pair:
+ *
+ *   - **Name variants**: canonical `wof:name` (slot key `default`, typically the postcode digits
+ *       themselves) plus any `name:*` variants on the postcode feature. In practice WOF postcode
+ *       records rarely carry localized name variants, so this expansion is usually a no-op — but
+ *       the code path stays symmetric with the admin adapter for consistency.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): self, +locality, +locality+region,
+ *       +locality+region+country.
+ *
+ *   `source_id` is `wof-postalcode-<wof_id>-<name-slot>-<hierarchy-variant>`. Ancestor names always
+ *   come from the ancestor's canonical `wof:name`; this adapter does NOT iterate ancestor name
+ *   variants (e.g. it does not emit `"75008 Париж"` even when Paris has a `name:rus_x_preferred`).
+ *   That cross-product belongs to a future synthesis pass; emitting it here would multiply row
+ *   counts ~10× without a clear training-value story.
+ *
+ *   License: CC0.
+ */
+import { formatAddress, reconcileComponents } from "../../format.js";
+import { buildAncestryIndex, normalizeNameKey, walkFeatures } from "../../wof-json.js";
+const COUNTRY_DISPLAY_NAME = {
+    US: "United States of America",
+    FR: "France",
+};
+const LOCALE_BY_COUNTRY = {
+    US: "en-US",
+    FR: "fr-FR",
+};
+function placetypeToTag(placetype) {
+    switch (placetype) {
+        case "country":
+        case "nation":
+            return "country";
+        case "macroregion":
+        case "region":
+            return "region";
+        case "locality":
+            return "locality";
+        case "postalcode":
+            return "postcode";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Compute hierarchy variants for a postcode record. `selfName` is the postcode surface form
+ * (canonical `wof:name` for the `default` slot, a `name:*` localized variant otherwise).
+ */
+export function postcodeVariantsFor(row, ancestry, selfName) {
+    if (placetypeToTag(row.placetype) !== "postcode")
+        return [];
+    const locality = ancestry.find((a) => placetypeToTag(a.placetype) === "locality");
+    const region = ancestry.find((a) => placetypeToTag(a.placetype) === "region");
+    const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country");
+    const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country;
+    const variants = [{ suffix: "self", components: { postcode: selfName } }];
+    if (locality) {
+        variants.push({
+            suffix: "with-locality",
+            components: { postcode: selfName, locality: locality.name },
+        });
+    }
+    if (locality && region) {
+        variants.push({
+            suffix: "with-locality-region",
+            components: { postcode: selfName, locality: locality.name, region: region.name },
+        });
+    }
+    if (locality && region && country) {
+        variants.push({
+            suffix: "with-locality-region-country",
+            components: {
+                postcode: selfName,
+                locality: locality.name,
+                region: region.name,
+                country: countryDisplay,
+            },
+        });
+    }
+    return variants;
+}
+/**
+ * Build the per-record name-slot list. The `default` slot uses `wof:name` verbatim (postcode
+ * digits); subsequent slots come from `name:*` variants dedup'd against the default.
+ */
+export function nameSlotsFor(rec) {
+    const seen = new Set([rec.name]);
+    const slots = [{ key: "default", value: rec.name }];
+    for (const [rawKey, value] of rec.nameVariants) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        slots.push({ key: normalizeNameKey(rawKey), value });
+    }
+    return slots;
+}
+export const WOF_POSTALCODE_ADAPTER_ID = "wof-postalcode";
+export function createWofPostalcodeAdapter() {
+    return {
+        id: WOF_POSTALCODE_ADAPTER_ID,
+        defaultLicense: "CC0-1.0",
+        description: "Who's On First postalcode GeoJSON bundles (postcode → locality/region pairs). Ancestor names from sibling admin repos.",
+        async *rows(opts) {
+            // Pass 1: full walk. We keep every record whose placetype maps to a ComponentTag — the
+            // postcode adapter needs locality / region / country admin records in the index so it
+            // can resolve postcode ancestry, even though it only emits rows for postcode records.
+            const byId = new Map();
+            for await (const rec of walkFeatures(opts.inputPath, { signal: opts.signal })) {
+                if (opts.signal?.aborted)
+                    return;
+                if (opts.country && rec.country !== opts.country)
+                    continue;
+                if (!placetypeToTag(rec.placetype))
+                    continue;
+                byId.set(rec.id, rec);
+            }
+            const ancestry = buildAncestryIndex(byId);
+            // Pass 2: emit postcode rows only, sorted by id for determinism.
+            const ids = [...byId.keys()].sort((a, b) => a - b);
+            let emitted = 0;
+            for (const id of ids) {
+                if (opts.signal?.aborted)
+                    return;
+                const rec = byId.get(id);
+                if (placetypeToTag(rec.placetype) !== "postcode")
+                    continue;
+                const chain = ancestry.get(id) ?? [];
+                const slots = nameSlotsFor(rec);
+                for (const slot of slots) {
+                    const variants = postcodeVariantsFor(rec, chain, slot.value);
+                    for (const variant of variants) {
+                        if (opts.limit !== undefined && emitted >= opts.limit)
+                            return;
+                        const raw = formatAddress(variant.components, rec.country, { separator: ", " });
+                        if (!raw)
+                            continue;
+                        const aligned = reconcileComponents(variant.components, raw);
+                        if (Object.keys(aligned).length === 0)
+                            continue;
+                        yield {
+                            raw,
+                            components: aligned,
+                            country: rec.country,
+                            locale: LOCALE_BY_COUNTRY[rec.country],
+                            source: WOF_POSTALCODE_ADAPTER_ID,
+                            source_id: `${WOF_POSTALCODE_ADAPTER_ID}-${rec.id}-${slot.key}-${variant.suffix}`,
+                            corpus_version: "",
+                            license: "CC0-1.0",
+                        };
+                        emitted++;
+                    }
+                }
+            }
+        },
+    };
+}
+export const wofPostalcodeAdapter = createWofPostalcodeAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/src/adapters/wof-postalcode-json/adapter.js.map

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

package/out/src/align.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Alignment: turn a `CanonicalRow` (raw + components) into a `LabeledRow` (raw + tokens + BIO
+ *   labels) or a `QuarantinedRow` (raw + reason) per the Phase 1 plan.
+ *
+ *   Pipeline:
+ *
+ *   1. For each `(tag, value)` in `components`, find the value's character span in `raw`. First try a
+ *        verbatim substring match (case-insensitive, whitespace-collapsed). If that fails, fall
+ *        back to fuzzy match via `fastest-levenshtein`, with a tunable edit distance threshold.
+ *   2. If any component cannot be located, reject the row with a human-readable reason and send it to
+ *        the quarantine pile (`reason: "component-not-found:<tag>"` or
+ *        `"edit-distance-exceeded:<tag>:<dist>"`).
+ *   3. Tokenize `raw` with the supplied `Tokenizer` (defaults to the whitespace tokenizer).
+ *   4. For each token: walk the list of component spans, pick the one whose span contains the token's
+ *        character range. First token in a component span → `B-<tag>`; subsequent tokens →
+ *        `I-<tag>`; no overlap → `O`.
+ *
+ *   Two structural invariants the function preserves:
+ *
+ *   - `tokens.length === labels.length` always.
+ *   - Each component contributes at most one contiguous BIO run (no `B-tag … O … I-tag` gaps). This is
+ *       enforced by greedy first-match span assignment + ordered token iteration.
+ */
+import { type Tokenizer } from "./tokenize.js";
+import type { CanonicalRow, LabeledRow, QuarantinedRow } from "./types.js";
+/** Options for `alignRow`. */
+export interface AlignOptions {
+    /** Tokenizer to use. Defaults to `whitespaceTokenizer()`. */
+    tokenizer?: Tokenizer;
+    /**
+     * Max Levenshtein edit distance to accept when a verbatim substring match fails. Set `0` to
+     * require verbatim matches only. Default `2`.
+     *
+     * Distance is computed against same-length windows in `raw`, so the threshold scales naturally
+     * with the component value length.
+     */
+    maxEditDistance?: number;
+    /**
+     * Case-insensitive comparison for substring search. Default `true`. The retained span in `raw` is
+     * the original case; only matching is case-insensitive.
+     */
+    caseInsensitive?: boolean;
+}
+/** Either a successful labeled row or a quarantined one. */
+export type AlignmentResult = {
+    kind: "labeled";
+    row: LabeledRow;
+} | {
+    kind: "quarantined";
+    row: QuarantinedRow;
+};
+/** Align a single row. */
+export declare function alignRow(row: CanonicalRow, opts?: AlignOptions): AlignmentResult;
+//# sourceMappingURL=align.d.ts.map

package/out/src/align.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align.d.ts","sourceRoot":"","sources":["../../src/align.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE1E,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC5B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,SAAS,CAAA;IAErB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,cAAc,CAAA;CAAE,CAAA;AAQjH,0BAA0B;AAC1B,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,GAAE,YAAiB,GAAG,eAAe,CAyCpF"}