@mailwoman/corpus 9.4.0 → 10.1.0

package/out/adapters/osm/adapter.js

@@ -0,0 +1,260 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `osm`: OpenStreetMap address adapter for the countries no permissive source covers.
+ *
+ * Every row lists `ODbL-1.0`, whose recorded obligations include share-alike. A build run under
+ * `LicensePolicy.ShareAlikeFree` refuses these rows at ingest, so they reach only the open weights.
+ * That is why `defaultLicense` is not an option on this adapter.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address/format";
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { extractDelimited } from "@mailwoman/core/scripting/arguments";
+import { stripCombiningMarks } from "@mailwoman/normalize/fold";
+import { TextSpliterator } from "spliterator";
+import { stableSourceID } from "#adapters/source-id";
+import { SourceRegister } from "#registers";
+import { AddressRole, countDropped, SurfaceOrigin, } from "#types";
+/**
+ * Registry id for this adapter, stamped into every row it emits.
+ */
+export const OSM_ADAPTER_ID = "osm";
+/**
+ * OpenStreetMap's license.
+ *
+ * Its recorded obligations include share-alike, so a build run under
+ * `LicensePolicy.ShareAlikeFree` refuses every row carrying it.
+ */
+export const OSM_LICENSE = "ODbL-1.0";
+/**
+ * The URL of the ODbL license text.
+ */
+export const OSM_LICENSE_URL = "https://opendatacommons.org/licenses/odbl/1-0/";
+/**
+ * The attribution OSM requires in redistributed data and derived works.
+ *
+ * A database built from OSM embeds it, and a model card carries it when OSM-derived
+ * rows reached the checkpoint, which the effective training manifest records.
+ */
+export const OSM_ATTRIBUTION = "© OpenStreetMap contributors. Data licensed under the Open Database License (ODbL) 1.0 " +
+    `(${OSM_LICENSE_URL}); see https://www.openstreetmap.org/copyright.`;
+const MAX_STREET_WORDS = 8;
+/**
+ * Whether `addr:housenumber` holds a street designator — digits with an optional letter,
+ * fraction or dash suffix (`12`, `188a`, `14/E`, `1/1146`, `167-c`) or a one-
+ * or two-letter block prefix (`B-77`, `L58`, `R 948`) — rather than free text such
+ * as `House 34, Road 4, Sector 9`, `Plot #27` or a name.
+ */
+export function housenumberIsDesignator(value) {
+    const trimmed = value.trim();
+    return /^\d+[A-Za-z]?(?:[/-]\d*[A-Za-z]?)?$/u.test(trimmed) || /^[A-Za-z]{1,2}[-\s]?\d+[A-Za-z]?$/u.test(trimmed);
+}
+/**
+ * Whether `addr:street` matches the street-name shape.
+ *
+ * The value has no comma and contains at most {@link MAX_STREET_WORDS} words.
+ * Direction phrases such as `Near Cozy Water Park`, `Opposite Askari Towers` or `Behind …` return false.
+ */
+export function isStreetName(value) {
+    const trimmed = value.trim();
+    return (trimmed.length > 0 &&
+        !trimmed.includes(",") &&
+        trimmed.split(/\s+/u).length <= MAX_STREET_WORDS &&
+        !/^(?:near|opp(?:osite)?|behind|beside|next to|adjacent)\b/iu.test(trimmed));
+}
+/**
+ * Split an `addr:city` carrying a neighborhood ahead of the city (`Mirpur 10, Dhaka` →
+ * locality `Dhaka`, head `Mirpur 10`); a value without a comma is only the locality.
+ */
+export function splitCityValue(value) {
+    const parts = extractDelimited(value);
+    if (parts.length < 2) {
+        return { locality: value.trim(), head: null };
+    }
+    return { locality: parts.at(-1), head: parts.slice(0, -1).join(", ") };
+}
+const PLACEHOLDERS = new Set(["n/a", "na", "none", "-", "nil"]);
+function clean(value) {
+    const trimmed = value?.trim() ?? "";
+    return trimmed && !PLACEHOLDERS.has(trimmed.toLowerCase()) ? trimmed : null;
+}
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return null;
+    const parsed = tryParsingJSON(trimmed);
+    return parsed && typeof parsed === "object" ? parsed : null;
+}
+/**
+ * Maps one jsonl row onto the components the corpus asserts, or returns null when the row is refused.
+ *
+ * A row with a street-shaped `addr:street` is a street address.
+ * A row with no `addr:street` at all is admitted as a streetless premise when its house
+ * number is designator-shaped and a tag that maps to `locality` or `dependent_locality`
+ * (`addr:city`, `addr:place`, `addr:suburb`, `addr:subdistrict`, `addr:district`)
+ * carries the identity the street would have carried.
+ *
+ * That is OSM's documented scheme for addresses numbered within a named place
+ * rather than along a street, and it is the `streetless-premise-identity` shape.
+ * A row whose `addr:street` holds a line rather than a name stays refused:
+ * the mapper supplied a street, and the value is a line.
+ *
+ * Each refusal and each discarded component increments its reason in `dropped`.
+ */
+export function componentsForOSMRow(row, dropped) {
+    const tally = dropped ?? {};
+    const street = clean(row.street);
+    const number = clean(row.number);
+    const designator = number !== null && housenumberIsDesignator(number);
+    if (street && !isStreetName(street)) {
+        countDropped(tally, "row:street-not-a-name");
+        return null;
+    }
+    if (!street && !designator) {
+        countDropped(tally, number ? "row:streetless-house-number-not-designator" : "row:streetless-no-house-number");
+        return null;
+    }
+    const components = street ? { street } : {};
+    if (designator) {
+        components.house_number = number;
+    }
+    else if (number) {
+        countDropped(tally, "component:house_number:not-designator");
+    }
+    const unit = clean(row.unit);
+    if (unit) {
+        components.unit = unit;
+    }
+    const postcode = clean(row.postcode);
+    if (postcode && /^\d{4,6}$/u.test(postcode)) {
+        components.postcode = postcode;
+    }
+    else if (postcode) {
+        countDropped(tally, "component:postcode:not-4-to-6-digits");
+    }
+    const city = clean(row.city);
+    const split = city ? splitCityValue(city) : null;
+    if (split) {
+        components.locality = split.locality;
+    }
+    // Dependent-locality candidates in priority order (suburb, subdistrict, district, place, city head);
+    // `district` never becomes `region`, because Vietnam's country template
+    // renders it only when no city is present.
+    const dependent = [row.suburb, row.subdistrict, row.district, row.place, split?.head]
+        .map((value) => clean(value ?? undefined))
+        .find((value) => value !== null &&
+        !value.includes(",") &&
+        (street === null || !sameName(value, street)) &&
+        (split === null || !sameName(value, split.locality)));
+    if (dependent) {
+        components.dependent_locality = dependent;
+    }
+    const province = clean(row.province);
+    if (province && (split === null || !sameName(province, split.locality))) {
+        components.region = province;
+    }
+    // A streetless premise is a house number within a named place, so it needs a locality
+    // or a dependent locality, from any of the tags that map to them.
+    if (!street && !components.locality && !components.dependent_locality) {
+        countDropped(tally, "row:streetless-no-locality");
+        return null;
+    }
+    // An address row needs another component alongside the street or the streetless house number.
+    // Coarse adapters already teach bare names.
+    if (Object.keys(components).length === 1) {
+        countDropped(tally, street ? "row:street-only" : "row:house-number-only");
+        return null;
+    }
+    return components;
+}
+/**
+ * Vietnamese admin-generic prefixes stripped before name comparison, so a province that
+ * repeats the city with a prefix (`Thành phố Hà Nội`) is read as the repeat it is.
+ */
+const NAME_PREFIXES = /^(?:thanh pho|tinh|tp\.?|quan|phuong|huyen|thi xa)\s+/u;
+/**
+ * Whether two place names are the same name: case, whitespace, diacritics and a leading
+ * admin generic folded (`Bắc Ninh` = `Bac Ninh`; `Hà Nội` = `Thành phố Hà Nội`).
+ */
+export function sameName(a, b) {
+    const fold = (value) => stripCombiningMarks(value)
+        .replaceAll("đ", "d")
+        .replaceAll("Đ", "D")
+        .toLowerCase()
+        .replaceAll(/\s+/gu, " ")
+        .trim()
+        .replace(NAME_PREFIXES, "");
+    return fold(a) === fold(b);
+}
+export function createOSMAdapter() {
+    return {
+        id: OSM_ADAPTER_ID,
+        defaultLicense: OSM_LICENSE,
+        addressRole: AddressRole.Premise,
+        register: SourceRegister.OpenStreetMap,
+        surface: SurfaceOrigin.Rendered,
+        description: "OpenStreetMap addresses (ODbL, share-alike): per-country JSONL from a Geofabrik extract, for the countries no permissive source covers.",
+        async *rows(opts) {
+            if (!opts.country) {
+                throw new Error("osm adapter: --country is required (the JSONL is per-country and rows omit a country field)");
+            }
+            const country = opts.country;
+            let emitted = 0;
+            for await (const line of TextSpliterator.fromAsync(opts.inputPath)) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const row = parseLine(line);
+                if (!row) {
+                    if (line.trim() && !line.trim().startsWith("#")) {
+                        countDropped(opts, "row:unparseable-line");
+                    }
+                    continue;
+                }
+                // A Geofabrik extract's polygon extends past the border, so its records
+                // include addresses in the neighboring country.
+                // A record whose own `addr:country` names another country is refused.
+                // A record without the tag is kept and counted, so the size of the remaining
+                // uncertainty is in the manifest rather than assumed to be zero.
+                const tagged = clean(row.country)?.toUpperCase();
+                if (tagged && tagged !== country) {
+                    countDropped(opts, "row:country-tag-mismatch");
+                    continue;
+                }
+                if (!tagged) {
+                    countDropped(opts, "kept:country-untagged");
+                }
+                const components = componentsForOSMRow(row, opts);
+                if (!components)
+                    continue;
+                const rendered = formatAddressRow(components, country, { singleLine: true });
+                if (!rendered) {
+                    countDropped(opts, "row:render-failed");
+                    continue;
+                }
+                const { raw, components: aligned } = rendered;
+                for (const tag of rendered.unplaced) {
+                    countDropped(opts, `component:${tag}:not-rendered`);
+                }
+                yield {
+                    raw,
+                    components: aligned,
+                    country,
+                    source: OSM_ADAPTER_ID,
+                    source_id: stableSourceID(OSM_ADAPTER_ID, aligned),
+                    corpus_version: "",
+                    license: OSM_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const osmAdapter = createOSMAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/osm/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../lib/adapters/osm/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EACN,WAAW,EAIX,YAAY,EACZ,aAAa,GACb,MAAM,QAAQ,CAAA;AAEf;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAA;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,gDAAgD,CAAA;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAC3B,yFAAyF;IACzF,IAAI,eAAe,iDAAiD,CAAA;AAmBrE,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAE1B;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAE5B,OAAO,sCAAsC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,oCAAoC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAClH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAE5B,OAAO,CACN,OAAO,CAAC,MAAM,GAAG,CAAC;QAClB,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QACtB,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,gBAAgB;QAChD,CAAC,4DAA4D,CAAC,IAAI,CAAC,OAAO,CAAC,CAC3E,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC3C,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;IAErC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC9C,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AACxE,CAAC;AAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;AAE/D,SAAS,KAAK,CAAC,KAAyB;IACvC,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAEnC,OAAO,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA;AAC5E,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAE3B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAEpD,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAEtC,OAAO,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAuB,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAClC,GAAiB,EACjB,OAAyC;IAEzC,MAAM,KAAK,GAAG,OAAO,IAAI,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAChC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAChC,MAAM,UAAU,GAAG,MAAM,KAAK,IAAI,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAErE,IAAI,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,YAAY,CAAC,KAAK,EAAE,uBAAuB,CAAC,CAAA;QAE5C,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,IAAI,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAC5B,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAA;QAE7G,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,MAAM,UAAU,GAA+B,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAEvE,IAAI,UAAU,EAAE,CAAC;QAChB,UAAU,CAAC,YAAY,GAAG,MAAM,CAAA;IACjC,CAAC;SAAM,IAAI,MAAM,EAAE,CAAC;QACnB,YAAY,CAAC,KAAK,EAAE,uCAAuC,CAAC,CAAA;IAC7D,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAE5B,IAAI,IAAI,EAAE,CAAC;QACV,UAAU,CAAC,IAAI,GAAG,IAAI,CAAA;IACvB,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAEpC,IAAI,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7C,UAAU,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC/B,CAAC;SAAM,IAAI,QAAQ,EAAE,CAAC;QACrB,YAAY,CAAC,KAAK,EAAE,sCAAsC,CAAC,CAAA;IAC5D,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAEhD,IAAI,KAAK,EAAE,CAAC;QACX,UAAU,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAA;IACrC,CAAC;IAED,qGAAqG;IACrG,wEAAwE;IACxE,2CAA2C;IAC3C,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC;SACnF,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC;SACzC,IAAI,CACJ,CAAC,KAAK,EAAE,EAAE,CACT,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CACrD,CAAA;IAEF,IAAI,SAAS,EAAE,CAAC;QACf,UAAU,CAAC,kBAAkB,GAAG,SAAS,CAAA;IAC1C,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAEpC,IAAI,QAAQ,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACzE,UAAU,CAAC,MAAM,GAAG,QAAQ,CAAA;IAC7B,CAAC;IAED,sFAAsF;IACtF,kEAAkE;IAClE,IAAI,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC;QACvE,YAAY,CAAC,KAAK,EAAE,4BAA4B,CAAC,CAAA;QAEjD,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,8FAA8F;IAC9F,4CAA4C;IAC5C,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAA;QAEzE,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,OAAO,UAAU,CAAA;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,aAAa,GAAG,wDAAwD,CAAA;AAE9E;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,IAAI,GAAG,CAAC,KAAa,EAAU,EAAE,CACtC,mBAAmB,CAAC,KAAK,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,WAAW,EAAE;SACb,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC;SACxB,IAAI,EAAE;SACN,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;IAE7B,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAA;AAC3B,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC/B,OAAO;QACN,EAAE,EAAE,cAAc;QAClB,cAAc,EAAE,WAAW;QAC3B,WAAW,EAAE,WAAW,CAAC,OAAO;QAChC,QAAQ,EAAE,cAAc,CAAC,aAAa;QACtC,OAAO,EAAE,aAAa,CAAC,QAAQ;QAC/B,WAAW,EACV,yIAAyI;QAE1I,KAAK,CAAC,CAAC,IAAI,CAAC,IAAoB;YAC/B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CAAC,6FAA6F,CAAC,CAAA;YAC/G,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;YAC5B,IAAI,OAAO,GAAG,CAAC,CAAA;YAEf,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBACpE,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;oBAAE,MAAK;gBAE/B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,IAAI,CAAC,KAAK;oBAAE,MAAK;gBAE5D,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;gBAE3B,IAAI,CAAC,GAAG,EAAE,CAAC;oBACV,IAAI,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;wBACjD,YAAY,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAA;oBAC3C,CAAC;oBAED,SAAQ;gBACT,CAAC;gBAED,wEAAwE;gBACxE,gDAAgD;gBAChD,sEAAsE;gBACtE,6EAA6E;gBAC7E,iEAAiE;gBACjE,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,CAAA;gBAEhD,IAAI,MAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;oBAClC,YAAY,CAAC,IAAI,EAAE,0BAA0B,CAAC,CAAA;oBAE9C,SAAQ;gBACT,CAAC;gBAED,IAAI,CAAC,MAAM,EAAE,CAAC;oBACb,YAAY,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAA;gBAC5C,CAAC;gBAED,MAAM,UAAU,GAAG,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;gBAEjD,IAAI,CAAC,UAAU;oBAAE,SAAQ;gBAEzB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;gBAE5E,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACf,YAAY,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAA;oBAEvC,SAAQ;gBACT,CAAC;gBAED,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAA;gBAE7C,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;oBACrC,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAAC,CAAA;gBACpD,CAAC;gBAED,MAAM;oBACL,GAAG;oBACH,UAAU,EAAE,OAAO;oBACnB,OAAO;oBACP,MAAM,EAAE,cAAc;oBACtB,SAAS,EAAE,cAAc,CAAC,cAAc,EAAE,OAAO,CAAC;oBAClD,cAAc,EAAE,EAAE;oBAClB,OAAO,EAAE,WAAW;iBACpB,CAAA;gBAED,OAAO,EAAE,CAAA;YACV,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAA"}

package/out/adapters/overture/adapter.d.ts

@@ -3,43 +3,27 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `overture`: Overture Maps Addresses adapter (epic #470 — the conditional corpus adapter, realized
- *   2026-06-20). Overture's global Addresses theme is the single-schema, well-normalized address
- *   dataset that fixes OpenAddresses' per-country patchiness (OA dropped Spain; OA-DE omits the
- *   Bundesland) — it even re-hosts the OA Spain data the standalone OA bucket no longer serves.
- *
- *   This adapter consumes a per-country LINE-DELIMITED JSON dump of the corpus-relevant fields (`{
- *   street, number, unit, postcode, locality }`), produced by `scripts/ingest-overture-addresses.ts
- *   --corpus-jsonl` (which does the DuckDB / S3 heavy lifting and flattens `address_levels` → the
- *   municipality locality). The split keeps `@mailwoman/corpus` — a RUNTIME dep of the `mailwoman`
- *   CLI — free of the heavy native `@duckdb/node-api`; the adapter just streams JSONL line-by-line,
- *   exactly like `openaddresses`.
- *
- *   The `street` surface carries the locale's street keyword verbatim (`"CALLE JULAN"`, `"VIA
- *   ROMA"`). We map it to `street` whole and let the downstream affix-relabel split `street_prefix`
- *   — the same path every other source rides. This slice exists because the model was
- *   en-us/fr-trained and never saw non-en/fr street formats (the 2026-06-19 EU parse-blocker
- *   measured loc-correct ES 21% / IT 59% / NL 64% vs FR/US ~98%).
- *
- *   `--country` is REQUIRED (the JSONL is per-country and the rows omit a country field), matching
- *   `openaddresses`. License is Overture's CDLA-Permissive-2.0 (attribution; not share-alike).
- *
- *   | Field | ComponentTag | | --------- | ---------------------------------------------- | |
- *   `street` | `street` (keyword incl.; affix-relabel splits prefix) | | `number` | `house_number`
- *   (skipped when "S-N"/"S/N" = sin número) | | `unit` | `unit` (if non-empty) | | `postcode`|
- *   `postcode` | | `locality`| `locality` (Overture address_levels municipality, or postal_city) |
+ * `overture`: Overture Maps Addresses adapter. The `street` value keeps the locale's street keyword
+ * verbatim. The downstream affix-relabel step splits `street_prefix` from that value.
  */
-import type { CorpusAdapter } from "#types";
+import { type CorpusAdapter } from "#types";
 /**
- * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
- * it came from.
+ * Registry id stamped into every row this adapter emits, so a corpus record traces back to its dataset.
  */
 export declare const OVERTURE_ADAPTER_ID = "overture";
 /**
- * License carried by this source (CDLA-Permissive-2.0), attached to each row so downstream consumers inherit the terms
- * rather than having to look them up.
+ * License assigned by this source (`cdla-Permissive-2.0`, attribution-only
+ * rather than share-alike), attached to every row.
  */
 export declare const OVERTURE_DEFAULT_LICENSE = "CDLA-Permissive-2.0";
+/**
+ * Whether an Overture `unit` value is a secondary-unit designator
+ * (a digit or a single bare word) rather than a name.
+ *
+ * Overture-SG puts an estate name in this field on 91,818 of 142,210 rows and the literal
+ * `NIL` on 47,407 more, so a name taught as `unit` would teach a trailing proper name.
+ */
+export declare function unitFieldIsDesignator(value: string): boolean;
 export declare function createOvertureAdapter(): CorpusAdapter;
 /**
  * The configured adapter instance registered with the corpus builder.

package/out/adapters/overture/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/overture/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAC7C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAuB7D,wBAAgB,qBAAqB,IAAI,aAAa,CAqFrD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,eAA0B,CAAA"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/overture/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,EAAuD,KAAK,aAAa,EAAiB,MAAM,QAAQ,CAAA;AAE/G;;GAEG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAC7C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAiC7D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM5D;AAYD,wBAAgB,qBAAqB,IAAI,aAAa,CA8FrD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,eAA0B,CAAA"}

package/out/adapters/overture/adapter.js

@@ -3,46 +3,54 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `overture`: Overture Maps Addresses adapter (epic #470 — the conditional corpus adapter, realized
- *   2026-06-20). Overture's global Addresses theme is the single-schema, well-normalized address
- *   dataset that fixes OpenAddresses' per-country patchiness (OA dropped Spain; OA-DE omits the
- *   Bundesland) — it even re-hosts the OA Spain data the standalone OA bucket no longer serves.
- *
- *   This adapter consumes a per-country LINE-DELIMITED JSON dump of the corpus-relevant fields (`{
- *   street, number, unit, postcode, locality }`), produced by `scripts/ingest-overture-addresses.ts
- *   --corpus-jsonl` (which does the DuckDB / S3 heavy lifting and flattens `address_levels` → the
- *   municipality locality). The split keeps `@mailwoman/corpus` — a RUNTIME dep of the `mailwoman`
- *   CLI — free of the heavy native `@duckdb/node-api`; the adapter just streams JSONL line-by-line,
- *   exactly like `openaddresses`.
- *
- *   The `street` surface carries the locale's street keyword verbatim (`"CALLE JULAN"`, `"VIA
- *   ROMA"`). We map it to `street` whole and let the downstream affix-relabel split `street_prefix`
- *   — the same path every other source rides. This slice exists because the model was
- *   en-us/fr-trained and never saw non-en/fr street formats (the 2026-06-19 EU parse-blocker
- *   measured loc-correct ES 21% / IT 59% / NL 64% vs FR/US ~98%).
- *
- *   `--country` is REQUIRED (the JSONL is per-country and the rows omit a country field), matching
- *   `openaddresses`. License is Overture's CDLA-Permissive-2.0 (attribution; not share-alike).
- *
- *   | Field | ComponentTag | | --------- | ---------------------------------------------- | |
- *   `street` | `street` (keyword incl.; affix-relabel splits prefix) | | `number` | `house_number`
- *   (skipped when "S-N"/"S/N" = sin número) | | `unit` | `unit` (if non-empty) | | `postcode`|
- *   `postcode` | | `locality`| `locality` (Overture address_levels municipality, or postal_city) |
+ * `overture`: Overture Maps Addresses adapter. The `street` value keeps the locale's street keyword
+ * verbatim. The downstream affix-relabel step splits `street_prefix` from that value.
  */
+import { formatAddressRow } from "@mailwoman/codex/address/format";
+import { COUNTRY_SURFACE_FORMS } from "@mailwoman/codex/country";
 import { tryParsingJSON } from "@mailwoman/core/json";
-import { formatAddress, reconcileComponents } from "@mailwoman/formatter";
+import { sample } from "@mailwoman/core/random";
+import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils";
 import { TextSpliterator } from "spliterator";
-import { stableSourceID } from "#adapters/utils";
+import { stableSourceID } from "#adapters/source-id";
+import { SourceRegister } from "#registers";
+import { AddressRole, SurfaceOrigin } from "#types";
 /**
- * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
- * it came from.
+ * Registry id stamped into every row this adapter emits, so a corpus record traces back to its dataset.
  */
 export const OVERTURE_ADAPTER_ID = "overture";
 /**
- * License carried by this source (CDLA-Permissive-2.0), attached to each row so downstream consumers inherit the terms
- * rather than having to look them up.
+ * License assigned by this source (`cdla-Permissive-2.0`, attribution-only
+ * rather than share-alike), attached to every row.
  */
 export const OVERTURE_DEFAULT_LICENSE = "CDLA-Permissive-2.0";
+const DEFAULT_COUNTRY_SEED = 20_260_922;
+/**
+ * One attested written form of a country's name.
+ *
+ * Raises rather than returning empty when the codex has no entry, so a requested
+ * fraction cannot silently produce no country rows.
+ */
+function countrySurfaceForm(country, random) {
+    const forms = COUNTRY_SURFACE_FORMS[country];
+    if (!forms?.length) {
+        throw new Error(`No COUNTRY_SURFACE_FORMS entry for ${country} — add it to codex/country/country.ts before using --country-fraction`);
+    }
+    return sample(forms, random);
+}
+/**
+ * Whether an Overture `unit` value is a secondary-unit designator
+ * (a digit or a single bare word) rather than a name.
+ *
+ * Overture-SG puts an estate name in this field on 91,818 of 142,210 rows and the literal
+ * `NIL` on 47,407 more, so a name taught as `unit` would teach a trailing proper name.
+ */
+export function unitFieldIsDesignator(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.toUpperCase() === "NIL")
+        return false;
+    return /\d/u.test(trimmed) || !/\s/u.test(trimmed);
+}
 function parseLine(line) {
     const t = line.trim();
     if (!t || t.startsWith("#"))
@@ -54,15 +62,20 @@ export function createOvertureAdapter() {
     return {
         id: OVERTURE_ADAPTER_ID,
         defaultLicense: OVERTURE_DEFAULT_LICENSE,
+        addressRole: AddressRole.Premise,
+        // Overture rows include their own `sources[].dataset` and `sources[].license`,
+        // so this declares the aggregator rather than asserting a national grant.
+        register: SourceRegister.Overture,
+        surface: SurfaceOrigin.Rendered,
         description: "Overture Maps Addresses (global): per-country JSONL of street/number/postcode/locality.",
         async *rows(opts) {
             if (!opts.country) {
                 throw new Error("overture adapter: --country is required (the Overture JSONL is per-country and rows omit a country field)");
             }
             const country = opts.country;
-            // TextSpliterator streams string lines (parseLine keeps tolerating blank/`#`/malformed
-            // lines by returning null); the path string lets the lib own + dispose the file handle,
-            // including on an early `break`.
+            const countryFraction = opts.countryFraction ?? 0;
+            const random = makeMulberry32(opts.seed ?? DEFAULT_COUNTRY_SEED);
+            // The path string lets `TextSpliterator` own and dispose the file handle, including on an early `break`.
             const lines = TextSpliterator.fromAsync(opts.inputPath);
             let emitted = 0;
             for await (const line of lines) {
@@ -78,7 +91,7 @@ export function createOvertureAdapter() {
                 const unit = r.unit?.trim() ?? "";
                 const postcode = r.postcode?.trim() ?? "";
                 const locality = r.locality?.trim() ?? "";
-                // Only useful with a street + (postcode OR locality); point-only rows quarantine anyway.
+                // Only useful with a street + (postcode or locality); point-only rows quarantine anyway.
                 if (!street)
                     continue;
                 if (!postcode && !locality)
@@ -89,7 +102,7 @@ export function createOvertureAdapter() {
                     components.house_number = number;
                 }
                 components.street = street;
-                if (unit) {
+                if (unitFieldIsDesignator(unit)) {
                     components.unit = unit;
                 }
                 if (postcode) {
@@ -98,12 +111,15 @@ export function createOvertureAdapter() {
                 if (locality) {
                     components.locality = locality;
                 }
-                const raw = formatAddress(components, country, { separator: ", " });
-                if (!raw)
-                    continue;
-                const aligned = reconcileComponents(components, raw);
-                if (!Object.keys(aligned).length)
+                // Overture rows are country-implicit, so the surface form goes into `components`
+                // and each country's layout decides where the country lands in the rendered string.
+                if (countryFraction > 0 && random() < countryFraction) {
+                    components.country = countrySurfaceForm(country, random);
+                }
+                const rendered = formatAddressRow(components, country, { singleLine: true });
+                if (!rendered)
                     continue;
+                const { raw, components: aligned } = rendered;
                 yield {
                     raw,
                     components: aligned,

package/out/adapters/overture/adapter.js.map

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

package/out/adapters/po-box/adapter.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * PO box / PMB / Apartado / BP synthesizer adapter. It emits {@linkcode PO_BOX_ADAPTER_ID}.
+ *
+ * A PO box delivery line is mutually exclusive with a street line (USPS Pub 28 / DMM 508), so rows
+ * are generated fresh from a tuple rather than by mutating a street row.
+ */
+import { type PoBoxBaseTuple } from "#synthesizers/po-box";
+import { type CorpusAdapter } from "#types";
+/**
+ * Registry id stamped into every row this adapter emits, so a corpus record traces back to its dataset.
+ *
+ * The value comes from `RECIPE_SOURCES` because `recipes/po/box/index.ts` writes rows under the same id.
+ * Two producers of one id have to spell it the same way, or a rewrite of a corpus through that table
+ * moves the recipe's rows and leaves this adapter's behind under a name the table no longer answers for.
+ */
+export declare const PO_BOX_ADAPTER_ID: string;
+/**
+ * License for synthetic PO-box rows.
+ *
+ * They inherit the terms of the real tuples used to derive them.
+ *
+ * The value is stored in each row's `license` column and read by `licenseNamedIn`,
+ * so it stays byte-for-byte.
+ */
+export declare const PO_BOX_LICENSE = "Synthetic \u2014 derived from CC-BY / public-domain input tuples";
+export interface PoBoxInputRow extends PoBoxBaseTuple {
+    street?: string;
+    houseNumber?: string;
+}
+export interface PoBoxAdapterOptions {
+    /**
+     * How many PO box variants to emit per input tuple, each picking a different leader
+     * (and possibly a different number or noise level); default 1.
+     */
+    variantsPerInput?: number;
+    /**
+     * Probability (0..1) of emitting a PMB-with-street variant when the input has
+     * a street and the locale supports PMB.
+     * The default is 0.15.
+     */
+    pmbRatio?: number;
+    /**
+     * Deterministic seed for reproducible synthesis.
+     * The default is `Date.now()`.
+     */
+    seed?: number;
+    /**
+     * Probability (0..1) per input tuple of additionally emitting one self-contained US
+     * military/diplomatic PO-box row, so military volume scales with the input stream.
+     * The default is 0.
+     */
+    militaryRatio?: number;
+}
+export declare function createPoBoxAdapter(opts?: PoBoxAdapterOptions): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const poBoxAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/po-box/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/po-box/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,EAKN,KAAK,cAAc,EACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAuD,KAAK,aAAa,EAAiB,MAAM,QAAQ,CAAA;AAE/G;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAsC,CAAA;AACpE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,qEAAgE,CAAA;AAE3F,MAAM,WAAW,aAAc,SAAQ,cAAc;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,mBAAwB,GAAG,aAAa,CA0HhF;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,eAAuB,CAAA"}