@mailwoman/registry 4.8.1 → 4.11.0

package/README.md

@@ -0,0 +1,92 @@
+# @mailwoman/registry
+
+**Geocode-first record-matching application** — the high-level entry point that
+runs the full block → score → cluster pipeline over ingested records and returns
+canonical entities ready for export.
+
+This is the clinic-funding use case Mailwoman was built for, standing on a
+calibrated, label-free matcher.
+
+```ts
+import { resolveEntities, ingestRows, toGeoJSON } from "@mailwoman/registry";
+
+// 1. Ingest — CSV/array → normalized SourceRecords
+const records = ingestRows(rows, {
+  mapping: { name: "Provider Name", address: "Street Address", city: "City", ... },
+});
+
+// 2. Resolve — block → score → cluster with geo-first defaults
+const entities = resolveEntities(records, {
+  geocodeAddress: async (row) => ({ lat: 30.2672, lon: -97.7431 }),
+});
+
+// 3. Export — GeoJSON for QGIS
+const fc = toGeoJSON(entities);
+// → FeatureCollection with Point features + entity properties
+```
+
+## The full pipeline
+
+```
+CSV / SQLite → ingestRows → SourceRecord[] → resolveEntities → ResolvedEntity[]
+                                                                    ↓
+                                                               toGeoJSON()
+                                                                    ↓
+                                                            GeoJSON → QGIS
+```
+
+## API
+
+```ts
+// Ingest — parse CSV / map columns → normalized records
+import { ingestRows, parseCsv, inferMapping } from "@mailwoman/registry"
+// {
+//   ingestRows(rows, opts): SourceRecord[]
+//   parseCsv(csvText): string[][]
+//   inferMapping(headers): ColumnMapping
+// }
+
+// Resolve — run the full matcher pipeline
+import { resolveEntities } from "@mailwoman/registry"
+// resolveEntities(records, config): ResolvedEntity[]
+// Config: { geocodeAddress?, scorer?, blockingKeys?, threshold?, discriminators? }
+
+// Export — GeoJSON, MapLibre HTML, reconciliation reports
+import { toGeoJSON, toMapHTML, reconcile } from "@mailwoman/registry"
+
+// Learned scorer — pre-trained GBT for single-dataset dedup
+import { dedupGbtEnUs } from "@mailwoman/registry"
+```
+
+## Default configuration
+
+`resolveEntities` ships with sensible defaults:
+
+- **Blocking keys:** geo-cell (H3) + canonical address + phone + email
+- **Scoring model:** Fellegi-Sunter with label-free EM, term frequency adjustment
+- **Learned scorer:** optional GBT for single-dataset dedup (opt-in via `scorer`)
+- **Threshold:** 0.5 (configurable precision/recall knob)
+
+## CLI
+
+The `mailwoman` CLI exposes `registry` as a command:
+
+```bash
+# Multi-source entity resolution
+mailwoman registry --sources config.json --out entities.geojson
+
+# Cross-dataset reconciliation
+mailwoman registry --sources tx-nppes.json --reconcile tx-fcc.json
+```
+
+## Related
+
+- [`@mailwoman/match`](../match) — the low-level block/score/cluster primitives
+- [`@mailwoman/record`](../record) — `SourceRecord` schema and normalizers
+- [`@mailwoman/address-id`](../address-id) — exact-match join key
+- [Geocode-First Record Matching](https://mailwoman.sister.software/articles/concepts/geocode-first-record-matching/)
+- [Dedup Entity Truth](https://mailwoman.sister.software/articles/concepts/dedup-entity-truth/)
+
+## License
+
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html)

package/out/address-key.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The address-id consumer for the matcher (#259). Derives a stable {@link PostalAddressID} from a
+ *   resolved {@link SourceRecord} and exposes it as a blocking key — the deterministic,
+ *   exact-canonical-address complement to the fuzzy Fellegi-Sunter / GBT scoring. Two uses:
+ *
+ *   - **As a pre-dedup / join key:** `GROUP BY postalAddressId(record)` collapses records that resolve
+ *       to the same place AND share a canonical address with NO scoring at all — the cheap, certain
+ *       slice of dedup before the matcher does the fuzzy rest.
+ *   - **As a blocking key:** {@link addressIdBlockingKey} adds the address-id to the blocking union, so
+ *       records sharing one are guaranteed to be compared.
+ */
+import { type PostalAddressID } from "@mailwoman/address-id";
+import { type BlockingKey } from "@mailwoman/match";
+import type { SourceRecord } from "./types.js";
+/**
+ * The stable address primary key for a record, or null when it isn't geocoded (no coordinate → no
+ * locality cell) or carries no raw address to hash. Uses the resolved coordinate + the raw address;
+ * the state prefix is plucked from the address when present.
+ */
+export declare function postalAddressId(record: SourceRecord): PostalAddressID | null;
+/**
+ * A blocking key on the {@link postalAddressId} — records that resolve to the same place with the
+ * same canonical address block together. Add it to {@link defaultBlockingKeys}'s union when an exact
+ * address join should never be missed.
+ */
+export declare function addressIdBlockingKey(): BlockingKey<SourceRecord>;
+//# sourceMappingURL=address-key.d.ts.map

package/out/address-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-key.d.ts","sourceRoot":"","sources":["../address-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACnF,OAAO,EAAE,KAAK,WAAW,EAAY,MAAM,kBAAkB,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI,CAK5E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CAAC,YAAY,CAAC,CAEhE"}

package/out/address-key.js

@@ -0,0 +1,38 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The address-id consumer for the matcher (#259). Derives a stable {@link PostalAddressID} from a
+ *   resolved {@link SourceRecord} and exposes it as a blocking key — the deterministic,
+ *   exact-canonical-address complement to the fuzzy Fellegi-Sunter / GBT scoring. Two uses:
+ *
+ *   - **As a pre-dedup / join key:** `GROUP BY postalAddressId(record)` collapses records that resolve
+ *       to the same place AND share a canonical address with NO scoring at all — the cheap, certain
+ *       slice of dedup before the matcher does the fuzzy rest.
+ *   - **As a blocking key:** {@link addressIdBlockingKey} adds the address-id to the blocking union, so
+ *       records sharing one are guaranteed to be compared.
+ */
+import { createPostalAddressID } from "@mailwoman/address-id";
+import { exactKey } from "@mailwoman/match";
+/**
+ * The stable address primary key for a record, or null when it isn't geocoded (no coordinate → no
+ * locality cell) or carries no raw address to hash. Uses the resolved coordinate + the raw address;
+ * the state prefix is plucked from the address when present.
+ */
+export function postalAddressId(record) {
+    const coordinate = record.address?.geocode?.coordinate;
+    const address = record.address?.raw;
+    if (!coordinate || !address)
+        return null;
+    return createPostalAddressID({ coordinate, address });
+}
+/**
+ * A blocking key on the {@link postalAddressId} — records that resolve to the same place with the
+ * same canonical address block together. Add it to {@link defaultBlockingKeys}'s union when an exact
+ * address join should never be missed.
+ */
+export function addressIdBlockingKey() {
+    return exactKey((record) => postalAddressId(record));
+}
+//# sourceMappingURL=address-key.js.map

package/out/address-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-key.js","sourceRoot":"","sources":["../address-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,qBAAqB,EAAwB,MAAM,uBAAuB,CAAA;AACnF,OAAO,EAAoB,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAG7D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IACnD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAA;IACtD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,CAAA;IACnC,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IACxC,OAAO,qBAAqB,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAA;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IACnC,OAAO,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;AACrD,CAAC"}

package/out/geojson.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geojson.d.ts","sourceRoot":"","sources":["../geojson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAkB,wBAAwB,EAAE,cAAc,EAAgB,MAAM,YAAY,CAAA;AAmCxG;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,wBAAwB,CAKvF"}
+{"version":3,"file":"geojson.d.ts","sourceRoot":"","sources":["../geojson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAkB,wBAAwB,EAAE,cAAc,EAAgB,MAAM,YAAY,CAAA;AAqCxG;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,wBAAwB,CAKvF"}

package/out/geojson.js

@@ -34,6 +34,8 @@ function toFeature(entity) {
             recordCount: entity.records.length,
             cohesion: entity.cohesion,
             sourceIds: entity.records.map((r) => r.id),
+            // Distinct provenance labels the entity's records span — an entity with ≥2 is a cross-dataset link.
+            sources: [...new Set(entity.records.map((r) => r.source).filter((s) => !!s))].sort(),
             name: displayName(rep),
             organization: rep.organization?.canonical ?? null,
             address: rep.address?.formatted ?? null,

package/out/geojson.js.map

@@ -1 +1 @@
-{"version":3,"file":"geojson.js","sourceRoot":"","sources":["../geojson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,0EAA0E;AAC1E,SAAS,WAAW,CAAC,MAAoB;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAA;IACxB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;SAClG,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC;SACT,IAAI,EAAE,CAAA;IACR,OAAO,MAAM,IAAI,IAAI,CAAA;AACtB,CAAC;AAED,8CAA8C;AAC9C,SAAS,SAAS,CAAC,MAAsB;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAA;IACjC,OAAO;QACN,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE;YACT,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,CAAC,MAAM,CAAC,UAAW,CAAC,SAAS,EAAE,MAAM,CAAC,UAAW,CAAC,QAAQ,CAAC;SACxE;QACD,UAAU,EAAE;YACX,QAAQ,EAAE,MAAM,CAAC,EAAE;YACnB,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM;YAClC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1C,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC;YACtB,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,SAAS,IAAI,IAAI;YACjD,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,IAAI;YACvC,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI;SAC/C;KACD,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,QAAmC;IAC5D,OAAO;QACN,IAAI,EAAE,mBAAmB;QACzB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;KACvE,CAAA;AACF,CAAC"}
+{"version":3,"file":"geojson.js","sourceRoot":"","sources":["../geojson.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,0EAA0E;AAC1E,SAAS,WAAW,CAAC,MAAoB;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAA;IACxB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IACtB,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;SAClG,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC;SACT,IAAI,EAAE,CAAA;IACR,OAAO,MAAM,IAAI,IAAI,CAAA;AACtB,CAAC;AAED,8CAA8C;AAC9C,SAAS,SAAS,CAAC,MAAsB;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAA;IACjC,OAAO;QACN,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE;YACT,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,CAAC,MAAM,CAAC,UAAW,CAAC,SAAS,EAAE,MAAM,CAAC,UAAW,CAAC,QAAQ,CAAC;SACxE;QACD,UAAU,EAAE;YACX,QAAQ,EAAE,MAAM,CAAC,EAAE;YACnB,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM;YAClC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1C,oGAAoG;YACpG,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YACjG,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC;YACtB,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,SAAS,IAAI,IAAI;YACjD,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,IAAI;YACvC,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI;SAC/C;KACD,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,QAAmC;IAC5D,OAAO;QACN,IAAI,EAAE,mBAAmB;QACzB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;KACvE,CAAA;AACF,CAAC"}

package/out/index.d.ts

@@ -10,8 +10,13 @@
  *   {@link toGeoJSON} exports them for QGIS. This is the clinic-funding use case mailwoman was built
  *   for, finally standing on a calibrated, label-free matcher.
  */
+export * from "./address-key.js";
 export * from "./geojson.js";
 export * from "./ingest.js";
+export * from "./learned-scorer.js";
+export * from "./map-html.js";
+export * from "./models/dedup-gbt-en-us.js";
+export * from "./reconcile.js";
 export * from "./resolve.js";
 export * from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/out/index.js

@@ -10,8 +10,13 @@
  *   {@link toGeoJSON} exports them for QGIS. This is the clinic-funding use case mailwoman was built
  *   for, finally standing on a calibrated, label-free matcher.
  */
+export * from "./address-key.js";
 export * from "./geojson.js";
 export * from "./ingest.js";
+export * from "./learned-scorer.js";
+export * from "./map-html.js";
+export * from "./models/dedup-gbt-en-us.js";
+export * from "./reconcile.js";
 export * from "./resolve.js";
 export * from "./types.js";
 //# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,6BAA6B,CAAA;AAC3C,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/out/ingest.d.ts

@@ -26,8 +26,36 @@ import { toPostalAddress } from "@mailwoman/record";
 import type { SourceRecord } from "./types.js";
 /** Resolve a raw address string into a {@link PostalAddress}. The seam to mailwoman's geocoder. */
 export type GeocodeAddress = (raw: string) => Promise<PostalAddress | null> | PostalAddress | null;
-/** Maps dataset columns to record fields. A field may draw from several columns (joined with
-spaces). */
+/** Column delimiter of a delimited source. */
+export type Delimiter = "comma" | "tab";
+/** Infer the delimiter from a path's extension (`.tsv` → tab, else comma). */
+export declare function delimiterFor(path: string): Delimiter;
+/**
+ * Stream a delimited file's rows lazily as header-keyed objects — the same shape {@link parseCsv}
+ * returns, but **without loading the file into memory**. A multi-GB source (the NPPES registry is
+ * ~4.8 GB / 9.6M rows — too big for `readFileSync`, which throws `ERR_STRING_TOO_LONG`) streams
+ * line by line. Keys are the original header names so a {@link ColumnMapping} written against the
+ * source's headers matches. Filter/sample the stream before {@link ingestRows} to keep only the rows
+ * you geocode.
+ *
+ * We stream _lines_ with spliterator's `TextSpliterator` (pure-Node, the part that handles the huge
+ * file) and split each line into columns here with `String.prototype.split`. We deliberately do NOT
+ * use `CSVSpliterator`: its column tokenizer hard-codes `skipEmpty` (it builds the column
+ * spliterator as `{ delimiter }` with no `skipEmpty: false`), so consecutive delimiters collapse
+ * and EMPTY FIELDS ARE DROPPED — fatal for a fixed-width registry like NPPES where a row of 330
+ * columns full of empties would mis-parse to 40 and shift every value. (Upstream `spliterator` bug;
+ * revisit when it's fixed.)
+ *
+ * Assumes an unquoted delimited file (no fields containing the delimiter) — true for these
+ * government TSVs. For small, possibly-quoted CSVs use {@link parseCsv} (quote-aware, in-memory).
+ */
+export declare function streamRows(source: string, opts?: {
+    delimiter?: Delimiter;
+}): AsyncGenerator<Record<string, string>>;
+/**
+ * Maps dataset columns to record fields. A field may draw from several columns (joined with
+ * spaces).
+ */
 export interface ColumnMapping {
     /** Column holding a stable row id. Falls back to the row index. */
     id?: string;
@@ -38,16 +66,49 @@ export interface ColumnMapping {
     address?: string | string[];
     phone?: string;
     email?: string;
+    /**
+     * Extra secondary-identifier fields → the column(s) to draw each from (joined with spaces). Land
+     * on `SourceRecord.attributes` under the same key, for the matcher's `discriminators`
+     * (authorized-official name, taxonomy, license…).
+     */
+    attributes?: Record<string, string | string[]>;
 }
+/**
+ * Best-effort {@link ColumnMapping} inferred from a header row — the "point it at any CSV"
+ * convenience. Each column name is matched (case- and punctuation-insensitive, on whole tokens) to
+ * a field by keyword, in a precedence that resolves the common ambiguities: a dedicated id / phone
+ * / email column is claimed before the generic sweep, an org / facility column beats a person
+ * "name", and address columns (street / city / state / zip…) collect into one multi-column field.
+ * Imperfect on bespoke headers (an explicit mapping or the LLM-assisted inference #603 is the
+ * answer there), but it nails tidy and semi-tidy files with no hand-mapping. Unmatched columns are
+ * left out.
+ */
+export declare function inferMapping(header: readonly string[]): ColumnMapping;
 /** Options for {@link ingestRows}. */
 export interface IngestOptions {
     /** The geocoding seam. Without it, records carry name/org but no resolved address. */
     geocodeAddress?: GeocodeAddress;
+    /**
+     * Separator for joining a multi-column ADDRESS mapping (name/org always join with a space).
+     * Default `" "`. Pass `", "` to give the parser delimited input (`"214 Main St, Austin, TX
+     * 78701"`) instead of a concatenated run (`"214 Main St Austin TX 78701"`) — the latter strips
+     * the parser's segmentation boundaries and is partly OOD (it also breaks all-caps
+     * case-normalization; #694). **Default `", "` (#694 flip, validated).** Comma-join is the correct
+     * shape for an address built from separate columns, and #700 measured it at +15% cross-dataset
+     * rooftop (579→667) with no comma-less crater. The dedup GBT was trained on the old space-joined
+     * coords, so this flip is paired with a GBT re-validation (#694). Pass `" "` to restore the
+     * legacy space-join for a byte-stable A/B.
+     */
+    addressSeparator?: string;
 }
 /** Parse a CSV string (with a header row) into row objects keyed by column name. */
 export declare function parseCsv(text: string): Record<string, string>[];
-/** Normalize tabular rows into {@link SourceRecord}s under a {@link ColumnMapping}. */
-export declare function ingestRows(rows: Iterable<Record<string, string>>, mapping: ColumnMapping, opts?: IngestOptions): Promise<SourceRecord[]>;
+/**
+ * Normalize tabular rows into {@link SourceRecord}s under a {@link ColumnMapping}. Accepts a sync OR
+ * async iterable, so {@link parseCsv} (in-memory) and {@link streamRows} (lazy, for huge files) both
+ * thread straight through.
+ */
+export declare function ingestRows(rows: Iterable<Record<string, string>> | AsyncIterable<Record<string, string>>, mapping: ColumnMapping, opts?: IngestOptions): Promise<SourceRecord[]>;
 /**
  * The subset of mailwoman's `GeocodeResult` the adapter consumes — kept structural so this package
  * never imports the heavy geocoder, yet a real `GeocodeResult` maps straight in.

package/out/ingest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,EAAiD,eAAe,EAAe,MAAM,mBAAmB,CAAA;AAE/G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,mGAAmG;AACnG,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,aAAa,GAAG,IAAI,CAAA;AAElG;WACW;AACX,MAAM,WAAW,aAAa;IAC7B,mEAAmE;IACnE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC7B,sFAAsF;IACtF,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAE/D;AAcD,uFAAuF;AACvF,wBAAsB,UAAU,CAC/B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACtC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,aAAkB,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC,CA2BzB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IACvC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,SAAS,CAAC,EAAE,cAAc,CAAC,WAAW,CAAC,CAAA;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACvC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9G,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,UAAU,GAAG,IAAI,CAAA;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,cAAc,CAgBjB"}
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../ingest.ts"],"names":[],"mappings":"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"}

package/out/ingest.js

@@ -23,31 +23,139 @@
  */
 import { canonicalizeOrganizationName, parsePersonName, toPostalAddress, withGeocode } from "@mailwoman/record";
 import { parse as parseCsvSync } from "csv-parse/sync";
+import { open } from "node:fs/promises";
+import { Delimiters, TextSpliterator } from "spliterator";
+/** Infer the delimiter from a path's extension (`.tsv` → tab, else comma). */
+export function delimiterFor(path) {
+    return /\.tsv$/i.test(path) ? "tab" : "comma";
+}
+/**
+ * Stream a delimited file's rows lazily as header-keyed objects — the same shape {@link parseCsv}
+ * returns, but **without loading the file into memory**. A multi-GB source (the NPPES registry is
+ * ~4.8 GB / 9.6M rows — too big for `readFileSync`, which throws `ERR_STRING_TOO_LONG`) streams
+ * line by line. Keys are the original header names so a {@link ColumnMapping} written against the
+ * source's headers matches. Filter/sample the stream before {@link ingestRows} to keep only the rows
+ * you geocode.
+ *
+ * We stream _lines_ with spliterator's `TextSpliterator` (pure-Node, the part that handles the huge
+ * file) and split each line into columns here with `String.prototype.split`. We deliberately do NOT
+ * use `CSVSpliterator`: its column tokenizer hard-codes `skipEmpty` (it builds the column
+ * spliterator as `{ delimiter }` with no `skipEmpty: false`), so consecutive delimiters collapse
+ * and EMPTY FIELDS ARE DROPPED — fatal for a fixed-width registry like NPPES where a row of 330
+ * columns full of empties would mis-parse to 40 and shift every value. (Upstream `spliterator` bug;
+ * revisit when it's fixed.)
+ *
+ * Assumes an unquoted delimited file (no fields containing the delimiter) — true for these
+ * government TSVs. For small, possibly-quoted CSVs use {@link parseCsv} (quote-aware, in-memory).
+ */
+export async function* streamRows(source, opts = {}) {
+    const sep = (opts.delimiter ?? delimiterFor(source)) === "tab" ? "\t" : ",";
+    // Own the file handle so it's closed deterministically. spliterator's `autoDispose` only fires on
+    // natural completion, not on an early `break`/`.return()` — which then leaks the fd (a GC-time error
+    // in Node 24+). We open it, pass `autoDispose: false` so spliterator never touches our handle, and
+    // close it in `finally` (runs on completion AND when the consumer abandons the generator early).
+    const handle = await open(source, "r");
+    try {
+        let header = null;
+        for await (const line of TextSpliterator.fromAsync(handle, {
+            delimiter: Delimiters.LineFeed,
+            autoDispose: false,
+        })) {
+            if (line.length === 0)
+                continue; // blank line / trailing newline
+            const fields = line.replace(/\r$/, "").split(sep); // tolerate CRLF
+            if (header === null) {
+                header = fields;
+                continue;
+            }
+            const row = {};
+            for (let i = 0; i < header.length; i++)
+                row[header[i]] = fields[i] ?? "";
+            yield row;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Best-effort {@link ColumnMapping} inferred from a header row — the "point it at any CSV"
+ * convenience. Each column name is matched (case- and punctuation-insensitive, on whole tokens) to
+ * a field by keyword, in a precedence that resolves the common ambiguities: a dedicated id / phone
+ * / email column is claimed before the generic sweep, an org / facility column beats a person
+ * "name", and address columns (street / city / state / zip…) collect into one multi-column field.
+ * Imperfect on bespoke headers (an explicit mapping or the LLM-assisted inference #603 is the
+ * answer there), but it nails tidy and semi-tidy files with no hand-mapping. Unmatched columns are
+ * left out.
+ */
+export function inferMapping(header) {
+    // Pad to whole-token boundaries so "state" doesn't match inside "statement".
+    const tok = (h) => ` ${h
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim()} `;
+    const mapping = {};
+    const name = [];
+    const address = [];
+    for (const column of header) {
+        const h = tok(column);
+        const has = (...words) => words.some((w) => h.includes(` ${w} `));
+        if (!mapping.email && has("email", "e mail"))
+            mapping.email = column;
+        else if (!mapping.phone && has("phone", "telephone", "tel", "mobile", "cell"))
+            mapping.phone = column;
+        else if (!mapping.id && has("id", "npi", "ein", "frn", "spin", "uuid", "guid", "key"))
+            mapping.id = column;
+        else if (has("org", "organization", "organisation", "company", "business", "facility", "agency", "employer"))
+            mapping.organization ??= column;
+        else if (has("street", "address", "addr", "city", "town", "state", "province", "zip", "zipcode", "postal", "postcode", "county"))
+            address.push(column);
+        else if (has("name", "first", "last", "given", "family", "middle", "surname", "fullname", "contact"))
+            name.push(column);
+    }
+    if (name.length)
+        mapping.name = name.length === 1 ? name[0] : name;
+    if (address.length)
+        mapping.address = address;
+    return mapping;
+}
 /** Parse a CSV string (with a header row) into row objects keyed by column name. */
 export function parseCsv(text) {
     return parseCsvSync(text, { columns: true, skip_empty_lines: true, trim: true, relax_column_count: true });
 }
 /** Join the named column(s) of a row into a single trimmed string, or undefined if empty. */
-function pick(row, columns) {
+function pick(row, columns, separator = " ") {
     if (!columns)
         return undefined;
     const list = Array.isArray(columns) ? columns : [columns];
     const value = list
         .map((c) => row[c]?.trim())
         .filter(Boolean)
-        .join(" ")
+        .join(separator)
         .trim();
     return value || undefined;
 }
-/** Normalize tabular rows into {@link SourceRecord}s under a {@link ColumnMapping}. */
+/**
+ * Normalize tabular rows into {@link SourceRecord}s under a {@link ColumnMapping}. Accepts a sync OR
+ * async iterable, so {@link parseCsv} (in-memory) and {@link streamRows} (lazy, for huge files) both
+ * thread straight through.
+ */
 export async function ingestRows(rows, mapping, opts = {}) {
     const records = [];
     let index = 0;
-    for (const row of rows) {
+    for await (const row of rows) {
         const id = (mapping.id ? row[mapping.id]?.trim() : "") || String(index);
         const nameValue = pick(row, mapping.name);
         const orgValue = pick(row, mapping.organization);
-        const addressValue = pick(row, mapping.address);
+        const addressValue = pick(row, mapping.address, opts.addressSeparator ?? ", ");
+        let attributes;
+        if (mapping.attributes) {
+            for (const [key, columns] of Object.entries(mapping.attributes)) {
+                const value = pick(row, columns);
+                if (value)
+                    (attributes ??= {})[key] = value;
+            }
+        }
         const record = {
             id,
             source: mapping.source,
@@ -56,6 +164,7 @@ export async function ingestRows(rows, mapping, opts = {}) {
             phone: (mapping.phone && row[mapping.phone]?.trim()) || undefined,
             email: (mapping.email && row[mapping.email]?.trim()?.toLowerCase()) || undefined,
             address: addressValue && opts.geocodeAddress ? ((await opts.geocodeAddress(addressValue)) ?? undefined) : undefined,
+            attributes,
             raw: row,
         };
         records.push(record);

package/out/ingest.js.map

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

package/out/learned-scorer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The learned scorer (#603) — the production wiring for the gradient-boosted-tree model behind
+ *   {@link ResolveConfig.scorer}. Two pieces:
+ *
+ *   1. {@link createMatchFeaturizer} — the ONE feature extractor for a candidate pair, used identically
+ *        at train time (`scripts/record-matcher/train-gbt.ts`), eval time (the learned-scorer
+ *        evals), and inference time (here). A pair → one-hot of each comparison's agreement level +
+ *        the over-merge interaction terms (co-located × name/org disagreement) + address
+ *        crowdedness.
+ *   2. {@link createGbtScorer} — wraps a trained {@link GBT} + the featurizer into the `(a, b) => number`
+ *        the resolve pipeline's `scorer` hook expects (a logit, threshold-comparable with the
+ *        Fellegi-Sunter weight it replaces).
+ *
+ *   Both take the comparison set as INPUT (rather than importing {@link buildDefaultModel}) so this
+ *   module has no dependency cycle with `resolve.ts`. The contract that keeps train ≡ inference:
+ *   feed the comparisons from `buildDefaultModel({ collapseSpatial: true, addressFrequency })` —
+ *   the model's structure (and thus the feature layout) is fixed by that config; only the frequency
+ *   VALUES differ between the training corpus and the matched set, which is the point (the model
+ *   generalizes, as the cross-state eval showed).
+ */
+import { type Comparison, type GBT, type TermFrequencyTable } from "@mailwoman/match";
+import type { SourceRecord } from "./types.js";
+/** Inputs shared by the featurizer + the scorer factory. */
+export interface LearnedFeatureConfig {
+    /**
+     * The comparison set the features are built over — MUST be `buildDefaultModel({ collapseSpatial:
+     * true, addressFrequency }).comparisons` so the feature layout matches the trained model.
+     * (`usePhone` / `discriminators` are NOT part of the learned feature model — the GBT replaces the
+     * FS weight wholesale and owns its own feature vector.)
+     */
+    comparisons: Comparison<SourceRecord>[];
+    /**
+     * Address-frequency table for the crowdedness feature (a crowded shared address is weak
+     * identity).
+     */
+    addressFrequency: TermFrequencyTable;
+}
+/**
+ * Build the per-pair feature extractor. The vector is: one-hot of each comparison's agreement
+ * level, then the two over-merge interaction terms (spatial-exact × name-disagree, spatial-exact ×
+ * org-disagree — the "same place, different names" signature that drives co-located over-merges),
+ * then address crowdedness scaled into [0, 1]. Deterministic and EM-independent, so it is identical
+ * across train / eval / inference.
+ */
+export declare function createMatchFeaturizer(config: LearnedFeatureConfig): (a: SourceRecord, b: SourceRecord) => number[];
+/**
+ * Wrap a trained {@link GBT} into the `(a, b) => number` link scorer for
+ * {@link ResolveConfig.scorer}. The returned weight is the model's logit — same threshold-comparable
+ * units as the Fellegi-Sunter weight it replaces, so the pipeline's clustering + threshold
+ * semantics are unchanged.
+ */
+export declare function createGbtScorer(config: LearnedFeatureConfig & {
+    model: GBT;
+}): (a: SourceRecord, b: SourceRecord) => number;
+//# sourceMappingURL=learned-scorer.d.ts.map

package/out/learned-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learned-scorer.d.ts","sourceRoot":"","sources":["../learned-scorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAoB,KAAK,UAAU,EAAE,KAAK,GAAG,EAAY,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACjH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,WAAW,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,CAAA;IACvC;;;OAGG;IACH,gBAAgB,EAAE,kBAAkB,CAAA;CACpC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,KAAK,MAAM,EAAE,CAkClH;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,oBAAoB,GAAG;IAAE,KAAK,EAAE,GAAG,CAAA;CAAE,GAC3C,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,KAAK,MAAM,CAI9C"}