GoldenMatch

Highlights

TypeScript port catches up to Python v1.5.0's auto-config verification layer. Zero-config `dedupe(rows)` and `match(target, reference)` now ship runtime safety, score-distribution feedback, and offline-safe defaults.

What's new

Preflight — 6 checks before `autoConfigureRows` returns

1. Column resolution with domain auto-repair — fixes the Python-class crash where auto-config references domain-extracted columns without enabling `config.domain`.
2. Cardinality bounds — drops exact matchkeys on columns with cardinality ≥ 0.99 (always unique) or ≤ 0.01 (always same).
3. Block-size sanity — warns on mega-blocks (P99 > 5000) or hyper-selective blocking (median < 2).
4. Remote-asset demotion — `embedding`/`record_embedding`/`rerank` demoted unless `allowRemoteAssets: true`. Offline-safe by default.
5. Confidence-gated weight cap — low-confidence fields capped at weight 0.5.

Raises `ConfigValidationError` on unrepairable issues; attaches `PreflightReport` to the config.

Postflight — 4 signals after scoring, before clustering

• Score histogram + bimodality detection → optional threshold auto-nudge.
• Blocking recall — `"deferred"` sentinel (full brute-force impl reserved for iterative auto-config).
• Preliminary cluster sizes via union-find with bottleneck-pair diagnostics.
• Threshold-band overlap → advisory recommending LLM auto mode when ambiguous band > 20%.

`PostflightReport` attached to `DedupeResult` / `MatchResult`. Stable 8-key schema enforced by contract test.

New options

• `autoConfigureRows(..., { strict: true })` — suppresses postflight adjustments for deterministic parity runs.
• `autoConfigureRows(..., { allowRemoteAssets: true })` — opt-in to embedding / rerank scorers.

Classifier fixes (prerequisite Phase 0)

• Cardinality guard: unique-value columns → `id`, not `phone`/`zip`/`numeric`.
• Extended ID patterns: `voter_reg_num`, `account_no`, `guid_`, `uuid_`.
• New `year` col_type — routes to blocking, not scoring.
• New `multi_name` col_type for delimited author-style fields (token_sort, weight 1.0).
• Low-confidence weight cap at 0.3 for fields with profile confidence < 0.5.
• Added `ColumnProfile.confidence` field (0.9 / 0.7 / 0.3 semantics matching Python).

Edge-safe

Zero `node:*` imports in `src/core/autoconfigVerify.ts`. Runs in Vercel Edge / Cloudflare Workers / Bun / Deno.

Breaking changes

1. `ConfigValidationError` — `autoConfigureRows` may now throw on unrepairable preflight findings.
2. Unique-email / unique-phone columns no longer yield `exact_email` / `exact_phone` matchkeys — Check 2 drops them as `cardinality_high`. Preflight report surfaces every drop.
3. Remote-asset scorers demoted by default. Pass `allowRemoteAssets: true` to keep `embedding` / `record_embedding` / `rerank: true` in auto-generated configs.

Examples

• `examples/verificationInspection.ts` — end-to-end walkthrough of preflight findings + postflight signals.
• `examples/strictModeParity.ts` — deterministic parity runs with `strict: true`.

Verification

• 590 tests pass (up from 478 pre-change; +112 new).
• `tsc --noEmit` clean.
• `npm run build` (tsup) clean — 5 entrypoints.
• Parity harness vs Python: 4 fixtures, finding-key parity on 3 (1 documented divergence in `KNOWN_PARITY_GAPS`).
• 60+ property-based invariant assertions.
• Bundle size: `dist/index.js` = 284 KB.

Install

```bash
npm install goldenmatch@^0.3.0
```

Full changelog

Python v1.5.0 shipped the feature for PyPI in April 2026; v0.3.0 brings parity to the npm package after a short soak period. See PR #44 for the Python design and #48 for the TS port.