Skip to main content
GoldenMatch ships as a Python toolkit and a TypeScript port that expose the same operations — the two are at surface parity. A tempting inference is that you can therefore run any pipeline phase in one language, hand the intermediate result to the other, and continue seamlessly.
Surface parity is not the same as artifact interoperability. “The same functions exist in both languages” does not imply “a phase’s output round-trips byte-for-byte.” Some boundaries genuinely do; others are numerically tolerance-bounded (a rounding difference can flip a match decision); a few can’t cross at all. This page tells you which is which, with the evidence.
The pipeline: ingest → standardize → matchkeys → block → score → cluster → golden → output.

​
Verdict table

Each verdict below is measured by a conformance test (or a documented architectural boundary), not assumed.

​
What this means in practice

Hand off at a durable-artifact boundary and it’s seamless. Score/cluster in either language, persist the identity graph or cluster JSON, and resume in the other — you get the same answer. Identity is the flagship: it doesn’t just round-trip, it cross-verifies cryptographically.
Handing off mid-numeric-pipeline is only as strong as the weakest link in the chain. If your hand-off point sits after standardize, after score (without the shared WASM scorer), or after an embedding step, the resumed pipeline can reach a different result than an all-one-language run. The failure modes are concrete:
  • a threshold decision flipping on a 4th-decimal score difference, or
  • a date / standardized value not reproducing across the parsers.

​
Guidance

  • Prefer the cluster or identity boundary for cross-language hand-off — both are byte-safe.
  • If you must hand off at the score boundary, enable the shared WASM scorer on the TypeScript side (byte-identical only for the byte-exact covered scorers: jaro_winkler / levenshtein / token_sort / exact) and avoid re-thresholding across the boundary. Note on Fellegi–Sunter: the batteries goldenmatch import now runs FS block scoring through the shared fs-wasm kernel by default (byte-aligned with Python-native — the #1854 fixed full-field operating point), so hand off at score from the bare goldenmatch entry for byte-safe FS. The lean goldenmatch/core entry keeps the pure-TS probabilistic.ts path (4-dp tolerance) unless you opt in with enableFsWasmScoring().
  • Do not split a pipeline across standardize / dates, embeddings, or the auto-config controller and expect bit-exact reproduction. Run those phases in a single language, then hand off the durable artifact.
  • The distributed / VLM / routing phases have no TS path — run them in Python.

​
How this is verified (the conformance harness)

These verdicts are backed by a runnable cross-language conformance harness (Python oracle → TypeScript parity test), so they stay honest as the code evolves:
  • Clustering boundary — a Python emitter produces scored-pair scenarios plus Python’s cluster partition; the TS test reruns each through buildClusters and asserts the identical partition. Scenarios include the divergence-prone oversized-cluster MST auto-split (unambiguous and tied-weakest-edge).
  • End-to-end split-run — Python runs a real pipeline (MatchEngine) and emits its scored pairs + clusters; the TS test (a) clusters Python’s real scored pairs and asserts it reproduces Python’s own clusters (hand-off fidelity), and (b) runs a full independent all-TS dedupe and asserts the same partition plus a bounded scored-pairs delta (no threshold flip). Blocking is neutralized so any divergence would be scoring/standardize, not a different candidate set.
  • Scoring tolerance — the scorer ground-truth parity test pins scores to 4 decimals across languages.
Known limit of the current evidence. The split-run’s clean agreement is dataset-specific — the scorers happened to agree closely and no pair sat exactly on the threshold. The 4-dp tolerance can still flip a cluster on adversarial data; the honest next step (tracked in the design note) is a split-run over a corrupted dataset engineered to sit pairs on the threshold, to find and quantify the flipping case. “Passed on a fair test” is not “can never flip.”

​
Reference

  • Design note + full verdict table: docs/design/2026-07-24-cross-language-phase-conformance.md
  • Harness: tests/parity/cluster-conformance.parity.test.ts, tests/parity/split-run.parity.test.ts, and their Python oracles under packages/python/goldenmatch/scripts/emit_*_conformance_fixture.py / emit_split_run_fixture.py.