goldenmatch 0.1.0

package/dist/core/index.d.cts

@@ -0,0 +1,1972 @@
+import { R as Row, g as ColumnValue, e as ClusterInfo, P as PairKey, M as MatchkeyConfig, S as ScoredPair, B as BlockResult, o as MatchkeyField, b as BlockingConfig, c as BlockingKeyConfig, d as BudgetConfig, k as GoldenRulesConfig, f as ClusterProvenance, j as GoldenFieldRule, G as GoldenMatchConfig, D as DedupeResult, a as MatchResult, L as LLMScorerConfig, Q as QualityConfig, m as LearningConfig } from '../types-DhUdX5Rc.cjs';
+export { C as CanopyConfig, h as DedupeStats, i as DomainConfig, E as ExactMatchkey, F as FieldProvenance, I as InputConfig, l as InputFileConfig, n as MakeMatchkeyConfigInput, p as MemoryConfig, O as OutputConfig, q as ProbabilisticMatchkey, r as SortKeyField, s as StandardizationConfig, T as TransformConfig, V as VALID_SCORERS, t as VALID_STANDARDIZERS, u as VALID_STRATEGIES, v as VALID_TRANSFORMS, w as ValidationConfig, x as ValidationRuleConfig, W as WeightedMatchkey, y as getMatchkeys, z as makeBlockingConfig, A as makeConfig, H as makeGoldenRulesConfig, J as makeMatchkeyConfig, K as makeMatchkeyField, N as makeScoredPair } from '../types-DhUdX5Rc.cjs';
+
+/**
+ * data.ts — TabularData, edge-safe Polars replacement.
+ * Wraps readonly Row[] with column operations, joins, groupBy, sampling.
+ * No Node.js imports, no `process`.
+ */
+
+/** Returns true for null, undefined, NaN, and null-ish string sentinels. */
+declare function isNullish(v: unknown): v is null | undefined;
+/** Normalize an unknown value to ColumnValue (string | number | boolean | null). */
+declare function toColumnValue(v: unknown): ColumnValue;
+declare class TabularData {
+    private readonly _rows;
+    private _columnCache;
+    constructor(rows: readonly Row[]);
+    get rows(): readonly Row[];
+    get columns(): readonly string[];
+    get rowCount(): number;
+    /** Get column values with null coercion (N/A, NaN, etc. become null). */
+    column(name: string): readonly ColumnValue[];
+    /** Raw column access -- preserves original values without null coercion.
+     *  Use for profiling where "N/A" should remain a string, not become null. */
+    rawColumn(name: string): readonly ColumnValue[];
+    nullCount(col: string): number;
+    dropNulls(col: string): ColumnValue[];
+    nUnique(col: string): number;
+    valueCounts(col: string): Map<ColumnValue, number>;
+    /** MUST use loop -- Math.min(...array) crashes on >65K elements. */
+    min(col: string): number | null;
+    /** MUST use loop -- Math.max(...array) crashes on >65K elements. */
+    max(col: string): number | null;
+    mean(col: string): number | null;
+    std(col: string): number | null;
+    filter(predicate: (row: Row) => boolean): TabularData;
+    map(fn: (row: Row, index: number) => Row): TabularData;
+    slice(start: number, end?: number): TabularData;
+    /** Keep only the named columns. */
+    select(cols: readonly string[]): TabularData;
+    /** Drop the named columns. */
+    drop(cols: readonly string[]): TabularData;
+    /** Return a new TabularData with an added (or replaced) column. */
+    addColumn(name: string, values: readonly ColumnValue[]): TabularData;
+    /** Add a sequential row index column (like Polars with_row_index). */
+    withRowIndex(name?: string, offset?: number): TabularData;
+    /** Group rows by a column, returning Map<stringKey, TabularData>. */
+    groupBy(key: string): Map<string, TabularData>;
+    /**
+     * Inner join with another TabularData on a shared column.
+     * Columns from `other` get a suffix to avoid collisions.
+     */
+    join(other: TabularData, on: string, suffix?: string): TabularData;
+    /** Fisher-Yates partial shuffle with seedable PRNG. */
+    sample(n: number, seed?: number): TabularData;
+    /** Sort by a column (ascending). Nulls sort last. */
+    sortBy(col: string): TabularData;
+    /** Return rows with unique values in the given column (keeps first occurrence). */
+    unique(col: string): TabularData;
+    /** Return rows as plain dicts. */
+    toDicts(): Row[];
+    numericValues(col: string): number[];
+    stringValues(col: string): string[];
+    /** Create from an array of row dicts. */
+    static fromDicts(rows: readonly Row[]): TabularData;
+    /** Create from column-oriented data: {col: values[]}. */
+    static fromColumns(cols: Readonly<Record<string, readonly ColumnValue[]>>): TabularData;
+}
+
+/**
+ * transforms.ts — Pure field transform utilities.
+ * Edge-safe: no Node.js imports, no `process`.
+ *
+ * Ports goldenmatch/utils/transforms.py.
+ */
+/** Apply a single named transform to a value. Returns null if input is null. */
+declare function applyTransform(value: string | null, transform: string): string | null;
+/** Apply a chain of transforms in order. */
+declare function applyTransforms(value: string | null, transforms: readonly string[]): string | null;
+/**
+ * American Soundex (Robert Russell, 1918).
+ * 1. Keep first letter
+ * 2. Map consonants to digits (B/F/P/V->1, C/G/J/K/Q/S/X/Z->2, D/T->3, L->4, M/N->5, R->6)
+ * 3. Remove adjacent duplicates, vowels/H/W
+ * 4. Pad/truncate to 4 chars
+ *
+ * H and W are transparent — they do NOT reset the duplicate suppression.
+ * Vowels (A/E/I/O/U/Y) DO reset, so "Pfister" and "Jackson" work correctly.
+ */
+declare function soundex(value: string): string;
+/**
+ * Simplified Metaphone.
+ * Returns a phonetic code of up to 4 characters.
+ */
+declare function metaphone(value: string): string;
+
+/**
+ * cluster.ts — Union-Find clustering with MST splitting.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ */
+
+/** Canonicalize a pair key: always min:max. Sole producer of branded PairKey. */
+declare function pairKey(a: number, b: number): PairKey;
+/** Parse a pair key back into [idA, idB]. */
+declare function parsePairKey(key: PairKey): readonly [number, number];
+declare class UnionFind {
+    private parent;
+    private rank;
+    /** Add element as its own root. */
+    add(x: number): void;
+    /** Batch add multiple elements. */
+    addMany(ids: readonly number[]): void;
+    /** Find root with iterative path compression. */
+    find(x: number): number;
+    /** Union by rank. */
+    union(a: number, b: number): void;
+    /** Return all clusters as arrays of sets. */
+    getClusters(): Set<number>[];
+}
+/**
+ * Build a max-weight spanning tree using Kruskal's algorithm.
+ * Returns edges as [idA, idB, score] sorted by descending weight.
+ */
+declare function buildMst(members: readonly number[], pairScores: ReadonlyMap<PairKey, number>): [number, number, number][];
+interface ClusterConfidence {
+    readonly minEdge: number | null;
+    readonly avgEdge: number | null;
+    readonly connectivity: number;
+    readonly bottleneckPair: readonly [number, number] | null;
+    readonly confidence: number;
+}
+/**
+ * Compute confidence metrics for a cluster.
+ * confidence = 0.4 * minEdge + 0.3 * avgEdge + 0.3 * connectivity
+ */
+declare function computeClusterConfidence(pairScores: ReadonlyMap<PairKey, number>, size: number): ClusterConfidence;
+/** Internal mutable cluster info used during building. */
+interface MutableClusterInfo {
+    members: number[];
+    size: number;
+    oversized: boolean;
+    pairScores: Map<PairKey, number>;
+    confidence: number;
+    bottleneckPair: readonly [number, number] | null;
+    clusterQuality: "strong" | "weak" | "split";
+    _wasSplit?: boolean;
+}
+/**
+ * Split a cluster by removing the weakest MST edge.
+ * Returns sub-cluster infos.
+ */
+declare function splitOversizedCluster(members: readonly number[], pairScores: ReadonlyMap<PairKey, number>): MutableClusterInfo[];
+interface BuildClustersOptions {
+    readonly maxClusterSize?: number;
+    readonly weakClusterThreshold?: number;
+    readonly autoSplit?: boolean;
+}
+/**
+ * Build clusters from scored pairs using Union-Find.
+ *
+ * Auto-splits oversized clusters via MST (iterative, not recursive).
+ * Assigns cluster_quality: "strong", "weak" (avg-min > weakThreshold), or "split".
+ * Downgrades confidence by 0.7 for weak clusters.
+ */
+declare function buildClusters(pairs: readonly (readonly [number, number, number])[], allIds: readonly number[], options?: BuildClustersOptions): Map<number, ClusterInfo>;
+/**
+ * Add a new record to existing clusters based on matches.
+ *
+ * - No matches: new singleton cluster
+ * - Single cluster match: join that cluster
+ * - Multiple cluster match: merge all matched clusters
+ *
+ * Flags oversized but does NOT auto-split. Caller should call
+ * splitOversizedCluster() if desired.
+ */
+declare function addToCluster(recordId: number, matches: readonly (readonly [number, number])[], clusters: Map<number, ClusterInfo>, maxClusterSize?: number): Map<number, ClusterInfo>;
+/**
+ * Remove a record from its cluster and re-cluster remaining members.
+ * The removed record becomes a singleton.
+ */
+declare function unmergeRecord(recordId: number, clusters: Map<number, ClusterInfo>, threshold?: number): Map<number, ClusterInfo>;
+/**
+ * Shatter a cluster into individual singletons.
+ * All members become their own cluster. Pair scores are discarded.
+ */
+declare function unmergeCluster(clusterId: number, clusters: Map<number, ClusterInfo>): Map<number, ClusterInfo>;
+/**
+ * Get pair scores for a specific set of cluster members from all pairs.
+ * Call on-demand, not in hot path.
+ */
+declare function getClusterPairScores(members: readonly number[], allPairs: readonly (readonly [number, number, number])[]): Map<PairKey, number>;
+
+/**
+ * scorer.ts — Fuzzy scoring module for GoldenMatch.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/scorer.py. The Python version uses `rapidfuzz`
+ * for vectorized NxN scoring. Here we implement all algorithms in pure TS.
+ */
+
+/** Convert unknown value to string or null. */
+declare function asString(v: unknown): string | null;
+/**
+ * Jaro similarity between two strings.
+ *
+ * matchWindow = floor(max(lenA, lenB) / 2) - 1
+ * Count matches (chars within window) and transpositions.
+ * jaro = (m/lenA + m/lenB + (m - t/2) / m) / 3
+ */
+declare function jaro(a: string, b: string): number;
+/**
+ * Jaro-Winkler similarity.
+ * Adds a bonus for a common prefix of up to 4 characters, scaling factor 0.1.
+ */
+declare function jaroWinkler(a: string, b: string): number;
+/**
+ * Levenshtein edit distance (classic DP, 2-row optimization).
+ */
+declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Normalized Levenshtein similarity: 1 - distance / max(lenA, lenB).
+ */
+declare function levenshteinSimilarity(a: string, b: string): number;
+/**
+ * Indel (insertion+deletion) edit distance.
+ *
+ * Like Levenshtein but without substitutions — a substitution costs 2
+ * (one delete + one insert) instead of 1. This matches the distance
+ * metric used by rapidfuzz's Indel ratio, which underlies
+ * `rapidfuzz.fuzz.token_sort_ratio` in Python.
+ */
+declare function indelDistance(a: string, b: string): number;
+/**
+ * Indel normalized similarity: `1 - d_indel / (len_a + len_b)`.
+ * Matches rapidfuzz's `Indel.normalized_similarity`.
+ */
+declare function indelSimilarity(a: string, b: string): number;
+/**
+ * Token sort ratio, rapidfuzz-compatible.
+ *
+ * Matches `rapidfuzz.fuzz.token_sort_ratio`:
+ * 1. Lowercase both strings.
+ * 2. Strip non-alphanumeric characters (replace with whitespace).
+ * 3. Split on whitespace, drop empties, sort tokens, rejoin with single space.
+ * 4. Compare via Indel normalized similarity (NOT Levenshtein).
+ *
+ * Python reference: for ("John Smith", "Smith Johnson") returns ~0.8571.
+ */
+declare function tokenSortRatio(a: string, b: string): number;
+/**
+ * Soundex match: 1.0 if soundex codes equal, else 0.0.
+ */
+declare function soundexMatch(a: string, b: string): number;
+/**
+ * Dice coefficient on two hex-encoded bloom filters.
+ * 2 * intersection / (popcount_a + popcount_b)
+ */
+declare function diceCoefficient(a: string, b: string): number;
+/**
+ * Jaccard similarity on two hex-encoded bloom filters.
+ * intersection / union of bits
+ */
+declare function jaccardSimilarity(a: string, b: string): number;
+/**
+ * Ensemble scorer: combines jaro_winkler, token_sort, and soundex_match * 0.8.
+ * Takes element-wise max of all three.
+ */
+declare function ensembleScore(a: string, b: string): number;
+/**
+ * Score two field values using the specified scorer.
+ * Returns null if either value is null.
+ */
+declare function scoreField(valA: string | null, valB: string | null, scorer: string): number | null;
+/**
+ * Score a pair of rows across all fields using weighted aggregation.
+ * Fields that produce null scores are excluded. If all null -> 0.0.
+ */
+declare function scorePair(rowA: Row, rowB: Row, fields: readonly MatchkeyField[]): number;
+/**
+ * Build an NxN score matrix for a list of values using a scorer.
+ * Symmetric: matrix[i][j] === matrix[j][i]. Diagonal is 0.
+ */
+declare function scoreMatrix(values: (string | null)[], scorerName: string): number[][];
+/**
+ * Find exact matches by grouping rows on matchkey columns.
+ * Builds a composite key from all matchkey fields (with transforms applied),
+ * groups rows sharing the same key, and returns all pairs with score 1.0.
+ *
+ * Rows must have a `__row_id__` field.
+ */
+declare function findExactMatches(rows: readonly Row[], mk: MatchkeyConfig): ScoredPair[];
+/**
+ * Find fuzzy matches within a block of rows (NxN scoring).
+ *
+ * Implements early termination:
+ * - Score cheap fields (exact/soundex) first
+ * - Check if max possible score can reach threshold
+ * - Score expensive fuzzy fields only for promising pairs
+ *
+ * Rows must have a `__row_id__` field.
+ */
+declare function findFuzzyMatches(rows: readonly Row[], mk: MatchkeyConfig, excludePairs?: ReadonlySet<PairKey>, preScoredPairs?: readonly ScoredPair[]): ScoredPair[];
+interface ScoreBlocksOptions {
+    /** Filter to cross-source pairs only. */
+    readonly acrossFilesOnly?: boolean;
+    /** Row ID -> source name mapping (for acrossFilesOnly). */
+    readonly sourceLookup?: ReadonlyMap<number, string>;
+    /** Target IDs for match mode — filter to target/ref cross pairs. */
+    readonly targetIds?: ReadonlySet<number>;
+}
+/**
+ * Score all blocks sequentially.
+ *
+ * In JS there is no GIL, so we use sequential scoring as the default.
+ * For web workers or similar concurrency, the caller can partition blocks.
+ */
+declare function scoreBlocksSequential(blocks: readonly BlockResult[], mk: MatchkeyConfig, matchedPairs: Set<PairKey>, options?: ScoreBlocksOptions): ScoredPair[];
+
+/**
+ * matchkey.ts — Matchkey builder for GoldenMatch-JS.
+ * Edge-safe: no `node:` imports, pure TypeScript only.
+ *
+ * Ports matchkey building from goldenmatch/core/matchkey.py.
+ * In Python this uses Polars expressions; here we work with Row arrays.
+ */
+
+/**
+ * Build a composite matchkey value for a single row.
+ *
+ * For each field in the matchkey config:
+ * 1. Read the raw value from the row
+ * 2. Apply the field's transform chain
+ * 3. Concatenate all parts with "||" separator
+ *
+ * Returns `null` if any field value is null/undefined or transforms to null.
+ */
+declare function computeMatchkeyValue(row: Row, mk: MatchkeyConfig): string | null;
+/**
+ * Add matchkey columns to rows. For each matchkey `mk`, adds a column
+ * `__mk_{mk.name}__` with the computed matchkey value.
+ *
+ * Returns new row objects (does not mutate originals).
+ */
+declare function computeMatchkeys(rows: readonly Row[], matchkeys: readonly MatchkeyConfig[]): Row[];
+/**
+ * Add `__row_id__` column as sequential integers starting from `offset`.
+ *
+ * Returns new row objects (does not mutate originals).
+ */
+declare function addRowIds(rows: readonly Row[], offset?: number): Row[];
+/**
+ * Add `__source__` column with the given source name to every row.
+ *
+ * Returns new row objects (does not mutate originals).
+ */
+declare function addSourceColumn(rows: readonly Row[], sourceName: string): Row[];
+
+/**
+ * standardize.ts — Data standardization for GoldenMatch-JS.
+ * Edge-safe: no `node:` imports, pure TypeScript only.
+ *
+ * Ports standardization from goldenmatch/core/standardize.py.
+ * These are data cleaning transforms applied to columns before matching.
+ */
+
+/**
+ * Apply a named standardizer to a string value.
+ *
+ * @throws Error if the standardizer name is not recognized.
+ */
+declare function applyStandardizer(value: string, name: string): string;
+/**
+ * Apply standardization rules to rows.
+ *
+ * `rules` maps column names to arrays of standardizer names that are
+ * applied in sequence. For example:
+ *
+ * ```ts
+ * applyStandardization(rows, {
+ *   email: ["email"],
+ *   first_name: ["strip", "name_proper"],
+ *   phone: ["phone"],
+ * });
+ * ```
+ *
+ * Returns new row objects (does not mutate originals).
+ * Null/undefined column values are skipped (left as-is).
+ */
+declare function applyStandardization(rows: readonly Row[], rules: Readonly<Record<string, readonly string[]>>): Row[];
+
+/**
+ * blocker.ts — Groups records into blocks for pairwise comparison.
+ *
+ * Edge-safe: no Node.js imports. Pure TypeScript only.
+ *
+ * Ports `goldenmatch/core/blocker.py`.
+ */
+
+/**
+ * Group rows by blocking key. Skip blocks with fewer than 2 rows.
+ * Handle oversized blocks per `config.skipOversized`.
+ */
+declare function buildStaticBlocks(rows: readonly Row[], config: BlockingConfig): BlockResult[];
+/**
+ * Run multiple blocking passes using `config.passes`.
+ *
+ * Each pass uses a different `BlockingKeyConfig`. Blocks are deduplicated
+ * by block key so each unique key appears only once.
+ */
+declare function buildMultiPassBlocks(rows: readonly Row[], config: BlockingConfig): BlockResult[];
+/**
+ * Build static blocks first, then auto-split any oversized blocks
+ * using the highest-cardinality column.
+ *
+ * If `config.subBlockKeys` is configured, uses recursive sub-blocking
+ * instead of auto-split.
+ */
+declare function buildAdaptiveBlocks(rows: readonly Row[], config: BlockingConfig): BlockResult[];
+/**
+ * Evaluate candidate blocking keys and select the one with the smallest
+ * max group size while maintaining >= 50% coverage.
+ *
+ * Coverage = fraction of rows that produce a non-null block key.
+ * If only one key is provided, returns it directly.
+ */
+declare function selectBestBlockingKey(rows: readonly Row[], keys: readonly BlockingKeyConfig[], maxBlockSize?: number): BlockingKeyConfig;
+/**
+ * Build blocks from rows based on blocking configuration.
+ *
+ * Routes by `config.strategy`:
+ * - `"static"` -- hash-based grouping on blocking keys
+ * - `"multi_pass"` -- multiple passes with deduplication
+ * - `"sorted_neighborhood"` -- sliding window over sorted data
+ * - `"adaptive"` -- static + auto-split for oversized blocks
+ * - `"ann"`, `"ann_pairs"`, `"canopy"`, `"learned"` -- not yet implemented
+ *
+ * If `config.autoSelect` is true and multiple keys are configured,
+ * automatically selects the best key before blocking.
+ */
+declare function buildBlocks(rows: readonly Row[], config: BlockingConfig): BlockResult[];
+/**
+ * Async variant of `buildBlocks`. Required for `"ann"` and `"ann_pairs"`
+ * strategies which need to fetch embeddings via HTTP. All other strategies
+ * delegate to the synchronous `buildBlocks` path.
+ */
+declare function buildBlocksAsync(rows: readonly Row[], config: BlockingConfig): Promise<BlockResult[]>;
+
+/**
+ * embedder.ts — Embedding API client (OpenAI / Vertex AI / Voyage).
+ *
+ * Edge-safe: uses global `fetch()` only. No `node:` imports.
+ *
+ * Ports `goldenmatch/core/embedder.py` and `goldenmatch/core/vertex_embedder.py`,
+ * but replaces sentence-transformers / google-cloud-aiplatform with HTTP calls
+ * so the module runs in Edge / Workers / browser-like runtimes.
+ */
+type EmbedderProvider = "openai" | "vertex" | "voyage";
+interface EmbedderOptions {
+    readonly provider?: EmbedderProvider;
+    readonly model?: string;
+    readonly apiKey?: string;
+    /** Override the default endpoint URL. */
+    readonly endpoint?: string;
+    /** Batch size for API calls (default 64 for OpenAI, 50 for Vertex). */
+    readonly batchSize?: number;
+    /** Cache embeddings by text hash within an Embedder instance. */
+    readonly cache?: boolean;
+    /**
+     * For OpenAI text-embedding-3+ this requests a smaller embedding
+     * dimension (e.g. 512 instead of 1536).
+     */
+    readonly dimensions?: number;
+    /** GCP project ID (required for Vertex). */
+    readonly project?: string;
+    /** GCP region (Vertex). Default: us-central1. */
+    readonly location?: string;
+    /** Pre-fetched OAuth bearer token for Vertex. */
+    readonly bearerToken?: string;
+    /** Maximum HTTP retries for transient failures (default 3). */
+    readonly maxRetries?: number;
+}
+interface EmbeddingResult {
+    readonly embeddings: readonly Float32Array[];
+    readonly model: string;
+    readonly tokensUsed: number;
+}
+declare class EmbedderError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: string | undefined;
+    constructor(message: string, status?: number | undefined, body?: string | undefined);
+}
+declare class Embedder {
+    private readonly options;
+    private readonly cacheMap;
+    private readonly provider;
+    private readonly model;
+    private readonly batchSize;
+    private readonly maxRetries;
+    private readonly cacheEnabled;
+    constructor(options?: EmbedderOptions);
+    /** Embed a batch of texts in one or more API calls. */
+    embedBatch(texts: readonly string[]): Promise<EmbeddingResult>;
+    /** Embed a single text. */
+    embedOne(text: string): Promise<Float32Array>;
+    /**
+     * Embed a column of (possibly null) values. Null/empty get a zero vector.
+     * Identical text values are de-duplicated automatically.
+     */
+    embedColumn(values: readonly (string | null | undefined)[], _cacheKey?: string): Promise<readonly Float32Array[]>;
+    cosineSimilarity(a: Float32Array, b: Float32Array): number;
+    cosineSimilarityMatrix(embeddings: readonly Float32Array[]): number[][];
+    private firstDim;
+    private callProvider;
+    private callOpenAI;
+    private callVertex;
+    private callVoyage;
+}
+/**
+ * Return a cached Embedder instance keyed by provider+model.
+ * Pass a string to use a model name with default provider, or full options.
+ */
+declare function getEmbedder(modelOrOptions?: string | EmbedderOptions): Embedder;
+
+/**
+ * ann-blocker.ts — Approximate nearest neighbour blocking.
+ *
+ * Edge-safe: no `node:` imports, no FAISS. Implements a brute-force kNN
+ * (O(n^2)) which is appropriate for <= ~10K records. Embeddings are
+ * fetched via `getEmbedder()` which uses HTTP `fetch()`.
+ *
+ * Ports `goldenmatch/core/ann_blocker.py`.
+ */
+
+interface ANNBlockerOptions {
+    readonly topK?: number;
+    readonly metric?: "cosine" | "euclidean";
+}
+interface BuildANNOptions {
+    readonly topK?: number;
+    readonly model?: string;
+    readonly apiKey?: string;
+    readonly provider?: EmbedderOptions["provider"];
+    /** Row identifier column (default `__row_id__`). */
+    readonly idColumn?: string;
+    /** Maximum block size produced by Union-Find grouping. */
+    readonly maxBlockSize?: number;
+    /** Use hnswlib-node fast-path when available (falls back to brute-force). */
+    readonly useHNSW?: boolean;
+}
+/**
+ * Minimal shape of the `hnswlib-node` module that we rely on. The caller
+ * passes in the loaded module; we deliberately keep the surface tiny so we
+ * don't hard-depend on its types.
+ */
+interface HNSWModule {
+    readonly HierarchicalNSW: new (metric: string, dim: number) => HNSWIndexLike;
+}
+interface HNSWIndexLike {
+    initIndex(maxElements: number, M?: number, efConstruction?: number, randomSeed?: number): void;
+    setEf(ef: number): void;
+    addPoint(vector: number[] | Float32Array, labelId: number): void;
+    searchKnn(query: number[] | Float32Array, k: number): {
+        distances: number[];
+        neighbors: number[];
+    };
+}
+interface HNSWOptions {
+    readonly hnswModule: HNSWModule;
+    readonly topK?: number;
+    readonly metric?: "cosine" | "euclidean";
+    readonly maxElements?: number;
+    readonly M?: number;
+    readonly efConstruction?: number;
+    readonly efSearch?: number;
+}
+/** Shared interface so `ANNBlocker` and `HNSWANNBlocker` are interchangeable. */
+interface ANNBlockerBase {
+    buildIndex(embeddings: readonly Float32Array[]): void;
+    addToIndex(embedding: Float32Array): number;
+    query(queryEmbeddings: readonly Float32Array[]): Array<[number, number]>;
+    queryWithScores(queryEmbeddings: readonly Float32Array[]): Array<[number, number, number]>;
+    queryOne(queryEmbedding: Float32Array): Array<[number, number]>;
+    readonly indexSize: number;
+}
+declare function cosineSim(a: Float32Array, b: Float32Array): number;
+declare function euclideanDist(a: Float32Array, b: Float32Array): number;
+declare class ANNBlocker implements ANNBlockerBase {
+    private embeddings;
+    private readonly topK;
+    private readonly metric;
+    constructor(options?: ANNBlockerOptions);
+    /** Replace the index with a fresh set of embeddings. */
+    buildIndex(embeddings: readonly Float32Array[]): void;
+    /** Number of vectors currently in the index. */
+    get indexSize(): number;
+    /** Append a single embedding; returns its position. */
+    addToIndex(embedding: Float32Array): number;
+    /**
+     * For each query embedding, return up to topK (queryIdx, indexIdx) pairs.
+     * Self-matches (same index when queries == embeddings) are excluded only
+     * when the underlying object identity matches; otherwise the caller is
+     * responsible for filtering self-pairs.
+     *
+     * Pairs are canonicalised so the lower index is always first when querying
+     * against the same index population (queryIdx === indexIdx case removed).
+     */
+    query(queryEmbeddings: readonly Float32Array[]): Array<[number, number]>;
+    /** Same as `query` but also returns the similarity score for each pair. */
+    queryWithScores(queryEmbeddings: readonly Float32Array[]): Array<[number, number, number]>;
+    /** Top-K matches for a single query. Returns (neighborIdx, score). */
+    queryOne(queryEmbedding: Float32Array): Array<[number, number]>;
+    private topKFor;
+}
+declare class HNSWANNBlocker implements ANNBlockerBase {
+    private index;
+    private count;
+    private readonly opts;
+    private readonly topK;
+    private readonly metric;
+    constructor(opts: HNSWOptions);
+    get indexSize(): number;
+    buildIndex(embeddings: readonly Float32Array[]): void;
+    addToIndex(embedding: Float32Array): number;
+    query(queryEmbeddings: readonly Float32Array[]): Array<[number, number]>;
+    queryWithScores(queryEmbeddings: readonly Float32Array[]): Array<[number, number, number]>;
+    queryOne(queryEmbedding: Float32Array): Array<[number, number]>;
+}
+interface CreateANNBlockerOptions extends ANNBlockerOptions {
+    /** Attempt to use the hnswlib-node fast-path. */
+    readonly useHNSW?: boolean;
+    /** Pre-loaded hnswlib-node module (skips dynamic import). */
+    readonly hnswModule?: HNSWModule;
+    /** Additional HNSW tuning knobs. Ignored when falling back to brute-force. */
+    readonly maxElements?: number;
+    readonly M?: number;
+    readonly efConstruction?: number;
+    readonly efSearch?: number;
+    /**
+     * Override the warning sink when the fast-path is unavailable. Defaults to
+     * `console.warn`. Tests pass a spy here.
+     */
+    readonly onFallbackWarning?: (message: string) => void;
+}
+/**
+ * Build an ANN blocker, preferring the `hnswlib-node` fast-path when
+ * `useHNSW` is `true` and the module can be loaded. Falls back to the
+ * brute-force `ANNBlocker` when the module is missing (e.g. edge runtime,
+ * peer dep not installed) and emits a single warning.
+ */
+declare function createANNBlocker(options?: CreateANNBlockerOptions): Promise<ANNBlockerBase>;
+/**
+ * Embed one column, query top-K neighbours, and group connected pairs
+ * into micro-blocks via Union-Find.
+ */
+declare function buildANNBlocks(rows: readonly Row[], annColumn: string, options?: BuildANNOptions): Promise<BlockResult[]>;
+/**
+ * Variant that returns one BlockResult containing every row plus
+ * pre-scored pairs derived from ANN cosine similarity. Useful when the
+ * scorer should reuse the embedding-based scores instead of recomputing.
+ */
+declare function buildANNPairBlocks(rows: readonly Row[], annColumn: string, options?: BuildANNOptions): Promise<BlockResult[]>;
+
+/**
+ * cross-encoder.ts — LLM-based pair reranking ("cross-encoder lite").
+ *
+ * The Python port uses ONNX/sentence-transformers cross-encoders, which need
+ * native deps. This edge-safe variant performs zero-shot reranking by asking
+ * an LLM (OpenAI / Anthropic) for a 0..1 match score on borderline pairs.
+ *
+ * - Borderline pairs are identified by `band` around the matchkey threshold
+ *   and/or top-N highest fuzzy scores below the auto-accept cutoff.
+ * - The combined score is `0.5 * original + 0.5 * rerank` by default.
+ * - Budget tracking uses BudgetTracker; on any HTTP failure we degrade to
+ *   the original score for that pair.
+ *
+ * Edge-safe: uses global `fetch()` only.
+ */
+
+type CrossEncoderProvider = "openai" | "anthropic";
+type CrossEncoderReranker = "llm" | "cross-encoder";
+interface CrossEncoderModelOptions {
+    /** HuggingFace model id. Default "Xenova/ms-marco-MiniLM-L-6-v2". */
+    readonly model?: string;
+    /** Execution device. Default "cpu". */
+    readonly device?: "cpu" | "webgpu";
+    /** Use quantized weights (q8). Default true. */
+    readonly quantized?: boolean;
+}
+interface CrossEncoderOptions {
+    /**
+     * Reranker backend. `"llm"` (default) uses OpenAI/Anthropic.
+     * `"cross-encoder"` loads `@huggingface/transformers` and runs a real
+     * ONNX cross-encoder model locally; falls back to LLM on load/inference
+     * failure.
+     */
+    readonly reranker?: CrossEncoderReranker;
+    readonly provider?: CrossEncoderProvider;
+    readonly model?: string;
+    readonly apiKey?: string;
+    /** Device for cross-encoder model (when reranker="cross-encoder"). */
+    readonly device?: "cpu" | "webgpu";
+    /** Use quantized cross-encoder weights (q8). Default true. */
+    readonly quantized?: boolean;
+    /** Re-rank pairs scoring within `band` of `mk.threshold` (default 0.1). */
+    readonly band?: number;
+    /** Maximum number of pairs to rerank, ranked highest to lowest. */
+    readonly topN?: number;
+    /** Weight given to the LLM rerank vs the original score. Default 0.5. */
+    readonly rerankWeight?: number;
+    /** Budget cap shared with regular LLM scoring. */
+    readonly budget?: BudgetConfig;
+    /** Optional override for retry attempts. Default 2. */
+    readonly maxRetries?: number;
+}
+declare class CrossEncoderHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Optional local cross-encoder backed by @huggingface/transformers (ONNX).
+ *
+ * Kept optional so goldenmatch-js stays edge-safe / zero-deps by default.
+ * The peer dependency must be installed explicitly:
+ *   npm install @huggingface/transformers
+ *
+ * Typical usage is indirect: pass `reranker: "cross-encoder"` to
+ * `rerankPair` / `rerankTopPairs` and a shared model instance is cached.
+ */
+declare class CrossEncoderModel {
+    private readonly options;
+    private pipelineFn;
+    private loading;
+    constructor(options?: CrossEncoderModelOptions);
+    private ensureLoaded;
+    /** Score a single text pair. Returns a [0,1] relevance probability. */
+    score(textA: string, textB: string): Promise<number>;
+    /**
+     * Score a batch of text pairs. Currently calls `score` serially —
+     * transformers.js v3 batching APIs vary across versions, so we stay
+     * conservative. Still avoids any LLM HTTP round-trips.
+     */
+    scoreBatch(pairs: ReadonlyArray<readonly [string, string]>): Promise<number[]>;
+}
+/** Test hook: reset the cached model instance. */
+declare function _resetCrossEncoderModelCache(): void;
+/**
+ * Ask the LLM for a single 0..1 match score for two rows.
+ *
+ * Returns `NaN` when the call fails or the response is unparseable so
+ * callers can fall back to the original score.
+ */
+declare function rerankPair(rowA: Row, rowB: Row, fields: readonly string[], options?: CrossEncoderOptions): Promise<number>;
+/**
+ * Rerank borderline pairs via LLM. Pairs outside the borderline band are
+ * returned unchanged. Pairs the LLM can't score (HTTP error, parse fail,
+ * budget exhausted) keep their original score.
+ *
+ * Combine rule: `final = (1 - w) * original + w * rerank`, with `w = rerankWeight`.
+ *
+ * Pairs whose final score falls below `mk.threshold` are dropped from the
+ * result, matching the Python "rerank then re-filter" behaviour.
+ */
+declare function rerankTopPairs(pairs: readonly ScoredPair[], rows: readonly Row[], mk: MatchkeyConfig, options?: CrossEncoderOptions): Promise<readonly ScoredPair[]>;
+
+/**
+ * golden.ts — Golden record builder with per-field merge strategies.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ */
+
+interface MergeFieldResult {
+    readonly value: unknown;
+    readonly confidence: number;
+    readonly sourceIndex: number | null;
+}
+interface MergeFieldOptions {
+    readonly sources?: readonly string[];
+    readonly dates?: readonly unknown[];
+    readonly qualityWeights?: readonly number[];
+}
+/**
+ * Merge a list of values using the given strategy.
+ *
+ * Strategies:
+ * - most_complete: pick longest string value; tie-break by quality weight
+ * - majority_vote: pick most frequent value; weighted by quality if available
+ * - source_priority: pick first non-null from priority list
+ * - most_recent: pick value with most recent date
+ * - first_non_null: pick first non-null; prefer highest quality weight
+ */
+declare function mergeField(values: readonly unknown[], rule: GoldenFieldRule, options?: MergeFieldOptions): MergeFieldResult;
+interface GoldenRecord {
+    readonly fields: Readonly<Record<string, {
+        value: unknown;
+        confidence: number;
+    }>>;
+    readonly goldenConfidence: number;
+}
+/**
+ * Build a golden record from cluster rows.
+ *
+ * @param clusterRows - Array of row objects belonging to one cluster.
+ * @param rules - Golden rules config with default strategy and field rules.
+ * @param qualityScores - Optional map of `"rowId:column"` -> quality score.
+ */
+declare function buildGoldenRecord(clusterRows: readonly Row[], rules: GoldenRulesConfig, qualityScores?: ReadonlyMap<string, number>): GoldenRecord;
+interface GoldenRecordWithProvenanceResult {
+    readonly goldenRecords: readonly (Row & {
+        __cluster_id__: number;
+        __golden_confidence__: number;
+    })[];
+    readonly provenance: readonly ClusterProvenance[];
+}
+/**
+ * Build golden records with full field-level provenance tracking.
+ *
+ * @param allRows - All rows with `__cluster_id__` and `__row_id__` columns.
+ * @param rules - Golden rules config.
+ * @param clusters - Cluster map from buildClusters.
+ * @param qualityScores - Optional `"rowId:column"` -> quality score map.
+ */
+declare function buildGoldenRecordWithProvenance(allRows: readonly Row[], rules: GoldenRulesConfig, clusters: ReadonlyMap<number, ClusterInfo>, qualityScores?: ReadonlyMap<string, number>): GoldenRecordWithProvenanceResult;
+
+/**
+ * pipeline.ts — Core pipeline orchestrator for GoldenMatch-JS.
+ * Edge-safe: no `node:` imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/pipeline.py.
+ * Chains: standardize -> matchkeys -> block -> score -> cluster -> golden.
+ */
+
+interface DedupeOptions$1 {
+    readonly outputGolden?: boolean;
+    readonly outputReport?: boolean;
+    readonly acrossFilesOnly?: boolean;
+}
+/**
+ * Run the full deduplication pipeline.
+ *
+ * Steps:
+ * 1. Add __row_id__ and __source__ if not present
+ * 2. Apply standardization
+ * 3. Compute matchkeys
+ * 4. Phase 1: Exact matchkeys (hash-based grouping)
+ * 5. Phase 2: Fuzzy matchkeys (block + score)
+ * 6. Phase 3: Cluster (Union-Find with MST splitting)
+ * 7. Phase 4: Build golden records for multi-member clusters
+ * 8. Classify dupes vs unique
+ * 9. Compute stats
+ * 10. Return DedupeResult
+ */
+declare function runDedupePipeline(rows: readonly Row[], config: GoldenMatchConfig, options?: DedupeOptions$1): DedupeResult;
+/**
+ * Run the match pipeline: match target rows against reference rows.
+ *
+ * - Assigns __row_id__ with offset for reference rows
+ * - Assigns __source__ ("target" / "reference")
+ * - Runs same pipeline but filters to cross-source pairs only
+ */
+declare function runMatchPipeline(targetRows: readonly Row[], referenceRows: readonly Row[], config: GoldenMatchConfig): MatchResult;
+
+/**
+ * api.ts — High-level API functions wrapping the pipeline.
+ * Edge-safe: no `node:` imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/_api.py convenience functions.
+ */
+
+interface DedupeOptions {
+    /** Full config object -- takes precedence over shorthand options. */
+    readonly config?: GoldenMatchConfig;
+    /** Columns for exact matching (creates one exact matchkey per column). */
+    readonly exact?: readonly string[];
+    /** Columns for fuzzy matching with per-field thresholds. */
+    readonly fuzzy?: Readonly<Record<string, number>>;
+    /** Blocking key columns (lowercase transform applied). */
+    readonly blocking?: readonly string[];
+    /** Overall fuzzy threshold (default 0.85). */
+    readonly threshold?: number;
+    /** Enable LLM scorer for borderline pairs. Requires OPENAI_API_KEY or ANTHROPIC_API_KEY in env. */
+    readonly llmScorer?: boolean;
+}
+/**
+ * Deduplicate an array of row objects.
+ *
+ * Shorthand usage:
+ * ```ts
+ * const result = dedupe(rows, {
+ *   exact: ["email"],
+ *   fuzzy: { name: 0.85, address: 0.7 },
+ *   blocking: ["zip"],
+ *   threshold: 0.85,
+ * });
+ * ```
+ *
+ * Or provide a full config:
+ * ```ts
+ * const result = dedupe(rows, { config: myConfig });
+ * ```
+ */
+declare function dedupe(rows: readonly Row[], options?: DedupeOptions): DedupeResult;
+/**
+ * Match target rows against reference rows.
+ *
+ * Same options as `dedupe()`. Returns matched/unmatched target rows.
+ */
+declare function match(target: readonly Row[], reference: readonly Row[], options?: DedupeOptions): MatchResult;
+/**
+ * Score two strings using the specified scorer algorithm.
+ *
+ * @param a - First string.
+ * @param b - Second string.
+ * @param scorer - Scorer name (default: "jaro_winkler").
+ *   Valid scorers: exact, jaro_winkler, levenshtein, token_sort,
+ *   soundex_match, dice, jaccard, ensemble.
+ * @returns Similarity score between 0.0 and 1.0.
+ */
+declare function scoreStrings(a: string, b: string, scorer?: string): number;
+/**
+ * Score a pair of row objects across specified fields using weighted
+ * aggregation.
+ *
+ * @param rowA - First row.
+ * @param rowB - Second row.
+ * @param fields - Field configs specifying which fields to compare,
+ *   transforms to apply, scorer to use, and weight.
+ * @returns Weighted similarity score between 0.0 and 1.0.
+ */
+declare function scorePairRecord(rowA: Row, rowB: Row, fields: readonly MatchkeyField[]): number;
+
+/**
+ * config/loader.ts — Config loader that parses raw objects (from YAML/JSON)
+ * into typed GoldenMatchConfig.
+ *
+ * Edge-safe: no `node:` imports, no `require()`.
+ */
+
+/**
+ * Parse a raw JS object (already deserialized from YAML or JSON) into a
+ * validated GoldenMatchConfig.
+ *
+ * Handles:
+ * - Snake_case to camelCase key conversion
+ * - Normalization of `matchkeys` / `match_settings`
+ * - Parsing of all nested config objects
+ * - `default` -> `defaultStrategy` normalization in golden_rules
+ */
+declare function parseConfig(raw: unknown): GoldenMatchConfig;
+/**
+ * Parse a YAML string into a GoldenMatchConfig.
+ *
+ * Requires the caller to provide a YAML parse function (e.g. from the `yaml`
+ * npm package) to keep this module edge-safe with no dynamic imports.
+ *
+ * @param yamlStr - The YAML configuration string.
+ * @param yamlParseFn - A function that parses a YAML string into a JS object.
+ */
+declare function parseConfigYaml(yamlStr: string, yamlParseFn: (s: string) => unknown): GoldenMatchConfig;
+/**
+ * Convert a GoldenMatchConfig back to a plain JS object suitable for
+ * YAML or JSON serialization (snake_case keys).
+ *
+ * @param config - The typed config object.
+ * @param yamlStringifyFn - A function that serializes a JS object to YAML.
+ */
+declare function configToYaml(config: GoldenMatchConfig, yamlStringifyFn: (obj: unknown) => string): string;
+
+/**
+ * budget.ts — LLM budget tracking: cost accounting, model tiering,
+ * and graceful degradation. Ports `goldenmatch/core/llm_budget.py`.
+ *
+ * Edge-safe: no `node:` imports, no `process`.
+ */
+
+interface BudgetSnapshot {
+    readonly calls: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly costUsd: number;
+    readonly model: string;
+    readonly modelsUsed: Readonly<Record<string, number>>;
+    readonly remainingCalls: number | null;
+    readonly remainingUsd: number | null;
+    readonly pctUsed: number;
+    readonly exhausted: boolean;
+}
+/**
+ * Tracks LLM token usage, cost, and enforces budget limits.
+ *
+ * Mirrors `goldenmatch.core.llm_budget.BudgetTracker`. No thread lock
+ * is needed here — the edge runtime is single-threaded per request.
+ */
+declare class BudgetTracker {
+    private readonly config;
+    readonly model: string;
+    private _calls;
+    private _inputTokens;
+    private _outputTokens;
+    private _costUsd;
+    private _escalationCost;
+    private readonly _modelsUsed;
+    constructor(config?: BudgetConfig, model?: string);
+    /** Estimate the cost of a hypothetical call (USD). */
+    estimateCost(inputTokens: number, outputTokens: number, model?: string): number;
+    /** Record usage from a completed API call. */
+    record(inputTokens: number, outputTokens: number, model?: string): void;
+    /**
+     * Return true if another call can proceed without exceeding the budget.
+     * If `estimatedCost` is provided, checks whether the projected total stays
+     * under `maxCostUsd`.
+     */
+    canProceed(estimatedCost?: number): boolean;
+    /**
+     * Estimate whether a batch of a given token size can be sent.
+     * Mirrors Python's `can_send(estimated_tokens)`.
+     */
+    canSend(estimatedTokens: number): boolean;
+    /**
+     * Pick a model based on a pair score and escalation config.
+     * Returns `escalationModel` when the score is in the escalation band
+     * and the escalation sub-budget hasn't been exhausted.
+     */
+    selectModel(pairScore: number, defaultModel: string): string;
+    get costUsd(): number;
+    get calls(): number;
+    get inputTokens(): number;
+    get outputTokens(): number;
+    get exhausted(): boolean;
+    /** Return a snapshot of the current budget state. */
+    snapshot(): BudgetSnapshot;
+}
+/**
+ * Rough token count approximation.
+ * Rule of thumb: ~4 chars per token for English text.
+ */
+declare function countTokensApprox(text: string): number;
+
+/**
+ * scorer.ts — LLM scorer for borderline record pairs.
+ * Ports `goldenmatch/core/llm_scorer.py`.
+ *
+ * Three-tier decision:
+ *   score >= autoThreshold        -> auto-accept (promote to 1.0)
+ *   candidateLo <= score < hi     -> send to LLM
+ *   score < candidateLo           -> keep original score (never demoted)
+ *
+ * Edge-safe: uses `fetch()` (global on Node 20+/edge runtimes).
+ * No `node:` imports.
+ */
+
+interface LLMScoreResult {
+    readonly pairs: readonly ScoredPair[];
+    readonly budget: BudgetSnapshot | null;
+}
+/**
+ * Score borderline pairs with an LLM. Never demotes: pairs the LLM rejects
+ * keep their original fuzzy score. Pairs the LLM confirms are promoted to 1.0.
+ *
+ * When no `apiKey` is available, degrades gracefully and returns the input.
+ */
+declare function llmScorePairs(pairs: readonly ScoredPair[], rows: readonly Row[], config: LLMScorerConfig, apiKey?: string): Promise<LLMScoreResult>;
+/**
+ * Ask the LLM a single yes/no question about two strings. Returns 1.0
+ * for yes, 0.0 for no, and 0.0 on any error (graceful).
+ */
+declare function scoreStringsWithLlm(a: string, b: string, config: LLMScorerConfig, apiKey?: string): Promise<{
+    score: number;
+    budget: BudgetSnapshot;
+    error?: string;
+}>;
+
+/**
+ * cluster.ts — In-context LLM clustering: send blocks of borderline records
+ * to an LLM for direct cluster assignment. Ports `goldenmatch/core/llm_cluster.py`.
+ *
+ * Flow:
+ *   1. Pairs with candidateLo <= score < autoThreshold form the borderline band.
+ *   2. Build connected components over the borderline graph.
+ *   3. Oversized components split by dropping weakest edges first.
+ *   4. Each component (block) sent to LLM with a JSON cluster schema.
+ *   5. Pair scores synthesized from cluster membership + confidence.
+ *
+ * Degrades: cluster call fails -> pairwise fallback -> return input pairs.
+ * Edge-safe: fetch-only, no `node:` imports.
+ */
+
+declare function llmClusterPairs(pairs: readonly ScoredPair[], rows: readonly Row[], config: LLMScorerConfig, apiKey?: string): Promise<LLMScoreResult>;
+
+/**
+ * explain.ts — Natural language explanations for match decisions.
+ * Ports `goldenmatch/core/explain.py` (+ parts of `explainer.py`).
+ *
+ * Template-based, zero LLM cost. Produces human-readable summaries of why
+ * two records matched, plus cluster-level summaries.
+ *
+ * Edge-safe: no `node:` imports.
+ */
+
+interface FieldScoreDetail {
+    readonly field: string;
+    readonly scorer: string;
+    readonly valueA: string | null;
+    readonly valueB: string | null;
+    readonly score: number | null;
+    readonly weight: number;
+    readonly diffType: "identical" | "similar" | "different" | "missing" | "unknown";
+}
+interface PairExplanation {
+    readonly score: number;
+    readonly fieldScores: Readonly<Record<string, number | null>>;
+    readonly explanation: string;
+    readonly confidence: "high" | "medium" | "low";
+    readonly reasoning: readonly string[];
+    readonly details: readonly FieldScoreDetail[];
+}
+interface ClusterExplanation {
+    readonly clusterId: number;
+    readonly size: number;
+    readonly confidence: number;
+    readonly quality: string;
+    readonly summary: string;
+    readonly strongestField: string | null;
+    readonly weakestLink: readonly [number, number] | null;
+}
+/**
+ * Produce an NL explanation for why two rows match (or don't), using the
+ * scorers and weights defined by the matchkey config.
+ */
+declare function explainPair(rowA: Row, rowB: Row, mk: MatchkeyConfig): PairExplanation;
+/**
+ * Produce a template summary for a cluster: size, confidence, weakest link.
+ * Mirrors `explain_cluster_nl` in Python.
+ */
+declare function explainCluster(clusterId: number, cluster: ClusterInfo, rows: readonly Row[], mk: MatchkeyConfig): ClusterExplanation;
+
+/**
+ * probabilistic.ts — Fellegi-Sunter probabilistic matching with EM-trained
+ * parameters. Ports `goldenmatch/core/probabilistic.py` (discrete path).
+ *
+ * Implements:
+ * - Comparison vectors (2/3/N-level field agreements)
+ * - Splink-style EM: u estimated from random pairs (fixed), m trained via EM
+ * - Blocking fields get fixed neutral priors
+ * - Match weights as log2(m/u) log-likelihood ratios, normalized to [0,1]
+ *
+ * Edge-safe: no `node:` imports, no numpy. Uses typed arrays where helpful.
+ */
+
+interface EMOptions {
+    readonly maxIterations?: number;
+    readonly convergence?: number;
+    readonly blockingFields?: readonly string[];
+    readonly seed?: number;
+    readonly nSamplePairs?: number;
+}
+interface EMResult {
+    /** P(level | match) per field. */
+    readonly m: Readonly<Record<string, readonly number[]>>;
+    /** P(level | non-match) per field. */
+    readonly u: Readonly<Record<string, readonly number[]>>;
+    /** log2(m / u) per level per field. Score weights. */
+    readonly matchWeights: Readonly<Record<string, readonly number[]>>;
+    /** Estimated p(match) in the sampled population. */
+    readonly proportionMatched: number;
+    readonly iterations: number;
+    readonly converged: boolean;
+}
+/**
+ * Build a comparison vector: one integer level per field.
+ *   levels=2: 0=disagree, 1=agree
+ *   levels=3: 0=disagree, 1=partial, 2=agree (>= 0.95)
+ *   levels=N: evenly spaced thresholds k/N for k in 1..N-1
+ */
+declare function buildComparisonVector(rowA: Row, rowB: Row, fields: readonly MatchkeyField[]): readonly number[];
+/**
+ * Splink-style EM training:
+ *   1. Estimate u from random pairs (fixed throughout).
+ *   2. Train m via EM starting from exponential priors.
+ *   3. Blocking fields bypass EM and receive fixed neutral u + linear weights.
+ */
+declare function trainEM(rows: readonly Row[], mk: MatchkeyConfig, options?: EMOptions): EMResult;
+interface ProbScoreOptions {
+    readonly excludePairs?: ReadonlySet<string>;
+    readonly threshold?: number;
+}
+/**
+ * Score all pairs in a block using F-S match weights.
+ * Returns normalized scores in [0,1] (weight sum mapped to 0-1 via min/max).
+ * Pairs below threshold are filtered out.
+ */
+declare function scoreProbabilistic(rows: readonly Row[], mk: MatchkeyConfig, em: EMResult, options?: ProbScoreOptions): ScoredPair[];
+
+/**
+ * evaluate.ts — Precision/recall/F1 evaluation against ground truth.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/evaluate.py.
+ */
+
+interface EvalResult {
+    readonly precision: number;
+    readonly recall: number;
+    readonly f1: number;
+    readonly truePositives: number;
+    readonly falsePositives: number;
+    readonly falseNegatives: number;
+}
+/**
+ * Evaluate predicted pairs against ground-truth pairs.
+ *
+ * Pairs are treated as unordered (canonicalized to min:max).
+ */
+declare function evaluatePairs(predictedPairs: readonly ScoredPair[], groundTruthPairs: readonly (readonly [number, number])[]): EvalResult;
+/**
+ * Evaluate clusters against ground-truth pairs.
+ *
+ * Expands each cluster's members into the full set of intra-cluster pairs and
+ * compares that set to the ground truth.
+ */
+declare function evaluateClusters(clusters: ReadonlyMap<number, ClusterInfo>, groundTruthPairs: readonly (readonly [number, number])[], _allIds: readonly number[]): EvalResult;
+/**
+ * Extract ground truth pairs from a list of rows containing two id columns.
+ *
+ * Numeric strings are parsed to integers. Rows with missing/unparseable ids
+ * are skipped.
+ */
+declare function loadGroundTruthPairs(rows: readonly Row[], idColA: string, idColB: string): (readonly [number, number])[];
+
+/**
+ * streaming.ts — Incremental single-record match + cluster updates.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/streaming.py.
+ */
+
+interface StreamAddResult {
+    readonly rowId: number;
+    readonly matchedIds: readonly number[];
+    readonly clusterId: number;
+}
+interface StreamProcessorConfig {
+    readonly matchkey: MatchkeyConfig;
+    readonly threshold: number;
+    readonly maxClusterSize?: number;
+}
+interface StreamSnapshot {
+    readonly clusters: ReadonlyMap<number, ClusterInfo>;
+    readonly rows: readonly Row[];
+}
+/**
+ * Incremental record processor.
+ *
+ * On each `add()` the new row is matched against all previously seen rows
+ * using `matchOne`, then folded into the cluster map via `addToCluster`.
+ */
+declare class StreamProcessor {
+    private readonly config;
+    private readonly clusters;
+    private readonly rowsById;
+    private readonly order;
+    private nextId;
+    constructor(config: StreamProcessorConfig);
+    /** Add a new record and return match + cluster info. */
+    add(row: Row): StreamAddResult;
+    /** Number of records ingested. */
+    get size(): number;
+    /** Snapshot of current cluster state + rows. */
+    snapshot(): StreamSnapshot;
+}
+
+/**
+ * match-one.ts — Single-record matching primitive.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/match_one.py.
+ */
+
+interface MatchOneHit {
+    readonly rowId: number;
+    readonly score: number;
+}
+/**
+ * Match a single record against a dataset using a weighted matchkey.
+ *
+ * Threshold defaults to 0 (return everything). For exact matchkeys use
+ * {@link findExactMatchesOne}.
+ *
+ * Returns hits sorted by descending score. Rows are expected to carry
+ * `__row_id__`.
+ */
+declare function matchOne(record: Row, rows: readonly Row[], mk: MatchkeyConfig): readonly MatchOneHit[];
+/**
+ * Find exact matches for a single record against a dataset.
+ *
+ * Builds the composite matchkey for the probe record, then scans the rows
+ * and returns any that share the same composite key (score 1.0). Null
+ * transformed fields disqualify the comparison.
+ */
+declare function findExactMatchesOne(record: Row, rows: readonly Row[], mk: MatchkeyConfig): readonly MatchOneHit[];
+
+/**
+ * compare-clusters.ts — CCMS (Case Count Metric System) cluster comparison.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/compare_clusters.py.
+ * Reference: Talburt et al., Case Count Metric System, arXiv:2601.02824v1.
+ */
+
+type ClusterCase = "unchanged" | "merged" | "partitioned" | "overlapping";
+interface CCMSResult {
+    readonly unchanged: number;
+    readonly merged: number;
+    readonly partitioned: number;
+    readonly overlapping: number;
+    readonly twi: number;
+    readonly clusterClassifications: Readonly<Record<number, ClusterCase>>;
+    readonly cc1: number;
+    readonly cc2: number;
+    readonly rc: number;
+}
+/**
+ * Compare two clustering outcomes via the CCMS framework.
+ *
+ * Classifies each cluster in A as unchanged, merged, partitioned, or
+ * overlapping relative to B, and computes the Talburt-Wang Index:
+ *   TWI = sqrt(CC1 * CC2) / V
+ * where CC1/CC2 are cluster counts and V is the number of non-empty
+ * A-to-B cluster intersections.
+ *
+ * Throws if the two cluster dicts do not cover the same row IDs.
+ */
+declare function compareClusters(clustersA: ReadonlyMap<number, ClusterInfo>, clustersB: ReadonlyMap<number, ClusterInfo>): CCMSResult;
+
+/**
+ * sensitivity.ts — Parameter sweep engine for GoldenMatch.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/sensitivity.py.
+ */
+
+interface SweepParam {
+    /** Dot-path into the config, e.g. "threshold", "blocking.maxBlockSize". */
+    readonly path: string;
+    readonly values: readonly unknown[];
+}
+interface SweepPoint {
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly stats: Readonly<Record<string, number>>;
+    readonly twi?: number;
+    readonly error?: string;
+}
+interface SensitivityResult {
+    readonly baseline: SweepPoint;
+    readonly points: readonly SweepPoint[];
+    readonly stable: boolean;
+}
+/**
+ * Run a parameter sweep.
+ *
+ * Each point in the Cartesian product of `params` is applied to
+ * `baselineConfig`, the dedupe pipeline runs, and the resulting clusters are
+ * compared against the baseline via CCMS. A `stable` flag is set when every
+ * point's TWI is within 0.05 of 1.0.
+ *
+ * Per-point errors are caught and stored on the point so that partial
+ * results are preserved.
+ */
+declare function runSensitivity(rows: readonly Row[], baselineConfig: GoldenMatchConfig, params: readonly SweepParam[]): SensitivityResult;
+/** Render a human-readable stability report for a sensitivity result. */
+declare function stabilityReport(result: SensitivityResult): string;
+
+/**
+ * quality.ts — Lightweight quality scan stub.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports a subset of goldenmatch/core/quality.py. The Python version
+ * integrates with GoldenCheck; this port only provides the interface and a
+ * handful of basic heuristics that are safe to run client-side.
+ */
+
+type QualitySeverity = "info" | "warn" | "error";
+interface QualityFinding {
+    readonly column: string;
+    readonly issue: string;
+    readonly severity: QualitySeverity;
+    readonly affectedRows: number;
+    readonly sampleValues: readonly unknown[];
+}
+interface QualityRunResult {
+    readonly rows: readonly Row[];
+    readonly findings: readonly QualityFinding[];
+}
+/**
+ * Run a few cheap heuristics across the dataset: high null rate, low
+ * cardinality, inconsistent date format, obviously malformed emails.
+ */
+declare function scanQuality(rows: readonly Row[], _config?: QualityConfig): QualityFinding[];
+/**
+ * Pass-through runner: produce findings, echo rows unchanged.
+ *
+ * Mirrors `_scan_only` / `run_quality_check` from the Python module: no
+ * GoldenCheck, no row rewrites, just reportable findings.
+ */
+declare function runQualityCheck(rows: readonly Row[], config?: QualityConfig): QualityRunResult;
+
+/**
+ * autofix.ts — Lightweight row auto-fix utilities.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/autofix.py. Trims whitespace, nulls empty strings,
+ * and converts common "no value" tokens to null.
+ */
+
+interface AutoFixLog {
+    readonly fixType: string;
+    readonly column: string;
+    readonly affectedRows: number;
+}
+interface AutoFixResult {
+    readonly rows: Row[];
+    readonly log: AutoFixLog[];
+}
+/**
+ * Apply conservative fixes row-by-row:
+ * - trim string values
+ * - convert empty strings and common "no value" tokens to null
+ *
+ * Internal columns (prefix `__`) are preserved unchanged.
+ */
+declare function autoFixRows(rows: readonly Row[]): AutoFixResult;
+
+/**
+ * validate.ts — Column validation rules with quarantine/flag actions.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/validate.py.
+ */
+
+type ValidationAction = "null" | "quarantine" | "flag";
+type ValidationRuleType = "regex" | "min_length" | "max_length" | "not_null" | "in_set" | "format";
+interface ValidationRule {
+    readonly column: string;
+    readonly ruleType: ValidationRuleType;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly action: ValidationAction;
+}
+interface ValidationReport {
+    readonly totalRows: number;
+    readonly quarantined: number;
+    readonly flagged: number;
+    readonly ruleViolations: Readonly<Record<string, number>>;
+}
+interface ValidationResult {
+    readonly valid: Row[];
+    readonly quarantine: Row[];
+    readonly report: ValidationReport;
+}
+/**
+ * Validate rows against a list of rules.
+ *
+ * Actions:
+ * - "null":       replace the failing value with null, row stays valid
+ * - "quarantine": move row to quarantine bucket
+ * - "flag":       add __flags__ entry, row stays valid
+ */
+declare function validateRows(rows: readonly Row[], rules: readonly ValidationRule[]): ValidationResult;
+
+/**
+ * profiler.ts — Lightweight per-column data profiler.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports parts of goldenmatch/core/profiler.py that autoconfig relies on.
+ */
+
+type ColumnType = "email" | "phone" | "zip" | "date" | "name" | "geo" | "id" | "numeric" | "text";
+interface ColumnProfile {
+    readonly name: string;
+    readonly nullRate: number;
+    readonly nullCount: number;
+    readonly totalCount: number;
+    readonly distinctCount: number;
+    readonly cardinalityRatio: number;
+    readonly inferredType: ColumnType;
+    readonly avgLength: number;
+    readonly maxLength: number;
+    readonly sampleValues: readonly string[];
+}
+interface DatasetProfile {
+    readonly rowCount: number;
+    readonly columns: readonly ColumnProfile[];
+    readonly byName: Readonly<Record<string, ColumnProfile>>;
+}
+/** Profile all columns of a row array. */
+declare function profileRows(rows: readonly Row[]): DatasetProfile;
+
+/**
+ * ingest.ts — Edge-safe data-shape transforms for row arrays.
+ * Edge-safe: no `node:` imports, no file I/O.
+ *
+ * Ports goldenmatch/core/ingest.py minus file loading — callers are
+ * expected to bring already-parsed rows (JSON, fetched CSV, etc.).
+ */
+
+/**
+ * Rename columns according to a {oldName: newName} map.
+ *
+ * Keys missing from the map are passed through untouched. If a rename
+ * would collide with an existing column, the mapped column wins
+ * (mirroring Polars behavior).
+ */
+declare function applyColumnMap(rows: readonly Row[], columnMap: Readonly<Record<string, string>>): Row[];
+/**
+ * Ensure every required column exists on the first row of `rows`.
+ * No-ops on empty input.
+ */
+declare function validateColumns(rows: readonly Row[], required: readonly string[]): void;
+/**
+ * Concatenate several row arrays. Unioned schema: any column present in
+ * any input appears in the output; missing values become null.
+ */
+declare function concatRows(rowsArrays: readonly (readonly Row[])[]): Row[];
+
+/**
+ * review-queue.ts — Human-in-the-loop pair gating.
+ * Edge-safe: no Node.js imports, pure TypeScript only.
+ *
+ * Ports goldenmatch/core/review_queue.py. Default gates: >=0.95 auto-approve,
+ * <0.75 auto-reject, everything in between needs review.
+ */
+
+type ReviewStatus = "pending" | "approved" | "rejected";
+interface ReviewItem {
+    readonly pairId: string;
+    readonly idA: number;
+    readonly idB: number;
+    readonly score: number;
+    readonly status: ReviewStatus;
+    readonly createdAt: number;
+}
+interface GatedResult {
+    readonly autoApproved: readonly ScoredPair[];
+    readonly needsReview: readonly ReviewItem[];
+    readonly rejected: readonly ScoredPair[];
+}
+interface GateOptions {
+    readonly approveAbove?: number;
+    readonly rejectBelow?: number;
+}
+/**
+ * Split pairs into auto-approved, needs-review, and rejected buckets.
+ *
+ * Defaults: approveAbove=0.95, rejectBelow=0.75.
+ */
+declare function gatePairs(pairs: readonly ScoredPair[], options?: GateOptions): GatedResult;
+/**
+ * In-memory review queue for human adjudication of borderline pairs.
+ */
+declare class ReviewQueue {
+    private readonly items;
+    /** Add a pair as a pending review item (idempotent by canonical pair id). */
+    add(pair: ScoredPair): void;
+    /** Get an item by canonical pair id ("minId:maxId"). */
+    get(pairId: string): ReviewItem | undefined;
+    /** Mark a pair approved. No-op if unknown. */
+    approve(pairId: string): void;
+    /** Mark a pair rejected. No-op if unknown. */
+    reject(pairId: string): void;
+    /** All pending items. */
+    pending(): ReviewItem[];
+    /** All approved items. */
+    approved(): ReviewItem[];
+    /** All rejected items. */
+    rejected(): ReviewItem[];
+    /** Current queue size. */
+    size(): number;
+    /** Canonical pair id helper ("minId:maxId"). */
+    static pairIdFor(a: number, b: number): string;
+}
+
+/**
+ * autoconfig.ts — Auto-generate a GoldenMatch config from sample data.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/autoconfig.py. Profiles the rows, classifies
+ * columns, and builds exact/weighted matchkeys + blocking config.
+ */
+
+interface AutoconfigOptions {
+    readonly llmProvider?: string;
+    readonly llmAuto?: boolean;
+}
+/**
+ * Build a GoldenMatchConfig by profiling the provided rows.
+ *
+ * Mirrors goldenmatch.core.autoconfig.auto_configure_df. Does not apply
+ * standardization rules directly — callers can merge them onto the result.
+ */
+declare function autoConfigureRows(rows: readonly Row[], options?: AutoconfigOptions): GoldenMatchConfig;
+
+/**
+ * domain.ts — Domain detection & lightweight feature extraction.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/domain.py. Detects the subject area (product,
+ * person, bibliographic, company, generic) from column names and extracts
+ * per-row features (brand, model, version, etc.) as extra columns.
+ */
+
+interface DomainProfile {
+    readonly name: string;
+    readonly confidence: number;
+    readonly textColumns: readonly string[];
+    readonly featureColumns: readonly string[];
+}
+/**
+ * Detect the domain of a dataset based on its column names.
+ */
+declare function detectDomain(columns: readonly string[]): DomainProfile;
+/**
+ * Annotate rows with domain-specific extracted columns.
+ * Returns enriched rows plus indices with low extraction confidence.
+ */
+declare function extractFeatures(rows: readonly Row[], profile: DomainProfile, confidenceThreshold?: number): {
+    rows: Row[];
+    lowConfidenceIds: readonly number[];
+};
+
+/**
+ * lineage.ts — Provenance tracking for golden records.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/lineage.py. Records which source rows contributed
+ * each golden-record field, with the survivorship strategy and confidence.
+ */
+
+interface FieldProvenanceEntry {
+    readonly sourceRowId: number;
+    readonly strategy: string;
+    readonly confidence: number;
+}
+interface LineageEdge {
+    readonly clusterId: number;
+    readonly sourceRowIds: readonly number[];
+    readonly goldenRowId: number;
+    readonly fieldProvenance: Readonly<Record<string, FieldProvenanceEntry>>;
+    readonly timestamp: string;
+    /**
+     * Human-readable summary of this lineage edge. Only populated when
+     * `buildLineage` is called with `{ naturalLanguage: true }`.
+     */
+    readonly naturalLanguage?: string;
+}
+interface LineageBundle {
+    readonly edges: readonly LineageEdge[];
+    readonly timestamp: string;
+    readonly recordCount: number;
+}
+interface BuildLineageOptions {
+    /**
+     * When `true`, every emitted `LineageEdge` gets a human-readable
+     * `naturalLanguage` summary describing which rows were merged, how many
+     * fields carry provenance, and the strongest contributing field. Zero LLM
+     * cost — purely template-based.
+     */
+    readonly naturalLanguage?: boolean;
+    readonly defaultStrategy?: string;
+}
+/**
+ * Build a lineage bundle from a DedupeResult.
+ *
+ * The resulting bundle has one edge per golden record, with field-level
+ * provenance keyed by column name. Source row IDs include every member of
+ * the cluster the golden record came from.
+ *
+ * Pass `{ naturalLanguage: true }` to populate a human-readable summary on
+ * each edge (see {@link LineageEdge.naturalLanguage}).
+ */
+declare function buildLineage(result: DedupeResult, options?: BuildLineageOptions): LineageBundle;
+/** Serialize a lineage bundle to stable, human-readable JSON. */
+declare function lineageToJson(bundle: LineageBundle): string;
+/** Parse a lineage bundle from JSON. Does not validate schema. */
+declare function lineageFromJson(json: string): LineageBundle;
+
+/**
+ * learned-blocking.ts — Data-driven predicate selection for blocking.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/learned_blocking.py. Given a labelled set of
+ * matching pairs, greedy-select predicates (equal, soundex, prefix,
+ * qgram) that maximize recall while minimizing candidate pair count.
+ */
+
+interface LearnedPredicate {
+    readonly type: "equal" | "soundex" | "first_n_chars" | "qgram";
+    readonly field: string;
+    readonly n?: number;
+    readonly recall: number;
+    readonly reduction: number;
+}
+interface LearnedRules {
+    readonly predicates: readonly LearnedPredicate[];
+    readonly minRecall: number;
+    readonly minReduction: number;
+    readonly learnedAt: string;
+}
+interface LearnBlockingOptions {
+    readonly minRecall?: number;
+    readonly minReduction?: number;
+    readonly predicateDepth?: number;
+}
+/**
+ * Learn blocking rules from known-matching pairs.
+ *
+ * Evaluates candidate predicates for each column, then greedily selects
+ * predicates that add the most new recall per candidate pair introduced,
+ * stopping when minRecall is reached (or when options.predicateDepth is
+ * exceeded).
+ */
+declare function learnBlockingRules(rows: readonly Row[], knownPairs: readonly ScoredPair[], columns: readonly string[], options?: LearnBlockingOptions): LearnedRules;
+/**
+ * Apply learned rules to rows, returning one BlockResult per non-empty,
+ * non-oversized block. Each predicate is its own pass (OR'd together).
+ */
+declare function applyLearnedBlocks(rows: readonly Row[], rules: LearnedRules, maxBlockSize: number): BlockResult[];
+
+/**
+ * graph-er.ts — Multi-table entity resolution with evidence propagation.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/graph_er.py. Each table is deduped independently
+ * first, then cluster assignments propagate across foreign-key edges:
+ * if row A.fk points into B's cluster, rows of A whose FK shares a cluster
+ * get a similarity boost before re-clustering.
+ */
+
+interface TableSchema {
+    readonly name: string;
+    readonly rows: readonly Row[];
+    readonly idColumn: string;
+}
+interface Relationship {
+    readonly tableA: string;
+    readonly tableB: string;
+    readonly fkColumn: string;
+}
+interface GraphERResult {
+    readonly clustersByTable: ReadonlyMap<string, ReadonlyMap<number, ClusterInfo>>;
+    readonly converged: boolean;
+    readonly iterations: number;
+}
+/**
+ * A scorer for graph ER.
+ *
+ * **Contract:** Must return `ScoredPair.idA` / `.idB` as **0-based row indices
+ * into the input `rows` array**, NOT the `__row_id__` values (or any other
+ * external/stable row identifier) those rows may carry.
+ *
+ * Why: `runGraphER` seeds its Union-Find with `0..rows.length` and indexes
+ * foreign-key cluster lookups by row position. Returning external row IDs
+ * instead of 0-based indices causes the evidence-propagation boost to never
+ * apply (ids won't line up with the UF roots or the fk-index map) and can
+ * silently produce wrong clusters.
+ *
+ * If you have stable external row IDs, re-number your rows to 0-based
+ * positional indices before scoring, then map back afterward.
+ */
+interface GraphERScorer {
+    (rows: readonly Row[]): readonly ScoredPair[];
+}
+interface RunGraphEROptions {
+    readonly maxIterations?: number;
+    readonly convergenceThreshold?: number;
+    readonly similarityBoost?: number;
+    /** Per-table scorer: takes rows, returns scored pairs. Required. */
+    readonly scorerByTable: ReadonlyMap<string, GraphERScorer>;
+    /** Match threshold for building clusters. Default 0.85. */
+    readonly threshold?: number;
+}
+/**
+ * Run multi-table entity resolution with iterative evidence propagation.
+ *
+ * For each table, the caller provides a scorer that produces pair scores
+ * from a row array. The algorithm:
+ *   1. Score & cluster each table independently.
+ *   2. For every relationship A->B: find pairs in A whose fk resolves to
+ *      the same cluster in B. Boost those pair scores by `similarityBoost`.
+ *   3. Re-cluster every table. Repeat until clusters stabilize or
+ *      `maxIterations` is reached.
+ *
+ * **Scorer contract (important):** scorers in `options.scorerByTable` must
+ * return `ScoredPair.idA` / `.idB` as **0-based row indices** into the
+ * `rows` array they were handed (NOT the stable `__row_id__` values those
+ * rows may carry). The evidence-propagation step keys foreign-key cluster
+ * lookups by row position; using external row IDs will silently make the
+ * boost no-op and can produce wrong clusters. See {@link GraphERScorer}.
+ */
+declare function runGraphER(tables: readonly TableSchema[], relationships: readonly Relationship[], options: RunGraphEROptions): GraphERResult;
+
+/**
+ * memory/store.ts — Learning Memory store (in-memory backend).
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/memory/store.py. SQLite / Postgres backends are
+ * deferred (they require host-specific drivers); the in-memory backend
+ * keeps all corrections in a plain array with trust-based upsert.
+ */
+interface Correction {
+    readonly rowIdA: number;
+    readonly rowIdB: number;
+    readonly verdict: "match" | "no_match";
+    readonly feature: string;
+    readonly score: number;
+    readonly timestamp: number;
+    readonly trust: number;
+    readonly source: string;
+}
+interface MemoryStoreConfig {
+    readonly backend: "memory" | "sqlite" | "postgres";
+    readonly path?: string;
+    readonly trustDefault?: number;
+}
+declare class MemoryStore {
+    private readonly config;
+    private corrections;
+    constructor(config?: MemoryStoreConfig);
+    /** Append a correction unconditionally. */
+    add(correction: Correction): void;
+    /** Append many corrections unconditionally. */
+    addBatch(corrections: readonly Correction[]): void;
+    /** All corrections, in insertion order. */
+    list(): readonly Correction[];
+    /** Corrections whose verdict is "match". */
+    listMatches(): readonly Correction[];
+    /** Corrections whose verdict is "no_match". */
+    listNonMatches(): readonly Correction[];
+    count(): number;
+    clear(): void;
+    /**
+     * Trust-based upsert: if a correction for the same (pair, feature) already
+     * exists, keep whichever has higher trust. Ties break toward the more recent
+     * correction.
+     */
+    upsert(correction: Correction): void;
+    /** Return the effective config (for debugging). */
+    getConfig(): MemoryStoreConfig;
+}
+
+/**
+ * memory/corrections.ts — Apply stored corrections to scored pairs.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/memory/corrections.py. A correction is only
+ * applied if both rows still hash to the values seen when the correction
+ * was recorded (dual-hash staleness detection).
+ */
+
+/** Hash of a row across its non-internal fields (sorted, stringified). */
+declare function hashRow(row: Row): string;
+interface StoredRowHashes {
+    readonly rowIdAHash: string;
+    readonly rowIdBHash: string;
+}
+/**
+ * A caller can either provide a per-correction hash map (populated at
+ * collection time) or ask applyCorrections to compute current hashes alone
+ * — in which case staleness detection is a no-op (hashes always match).
+ */
+interface ApplyCorrectionsOptions {
+    readonly originalHashes?: ReadonlyMap<string, StoredRowHashes>;
+    /** When a correction matches, clamp pair score to this value. Default 1.0 for match, 0.0 for no_match. */
+    readonly matchScore?: number;
+    readonly noMatchScore?: number;
+}
+/**
+ * Apply user corrections stored in `store` to a list of scored pairs.
+ *
+ * For each correction:
+ *   - Find the pair (idA,idB) in the scored_pairs list.
+ *   - If caller supplied original hashes, compare them against a fresh
+ *     hash of the current row. Mismatch => stale, skip.
+ *   - Otherwise apply the verdict:
+ *       "match"    -> score clamped to matchScore (default 1.0)
+ *       "no_match" -> score clamped to noMatchScore (default 0.0)
+ *
+ * Returns the modified pairs plus counts of applied / stale corrections.
+ */
+declare function applyCorrections(pairs: readonly ScoredPair[], rows: readonly Row[], store: MemoryStore, options?: ApplyCorrectionsOptions): {
+    pairs: readonly ScoredPair[];
+    applied: number;
+    stale: number;
+};
+
+/**
+ * memory/learner.ts — Threshold tuning & weight learning from corrections.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/core/memory/learner.py. Given ≥10 corrections, sweep
+ * thresholds and pick the one maximizing F1 on the correction set. Given
+ * ≥50 corrections with per-field subscores, fit a simple logistic-
+ * regression-like weight update.
+ */
+
+interface LearnedParams {
+    readonly threshold?: number;
+    readonly fieldWeights?: Readonly<Record<string, number>>;
+    readonly correctionCount: number;
+}
+/**
+ * Per-correction subscores. When present, keys correspond to matchkey field
+ * names and values are in [0,1] representing each field's contribution.
+ * The learner uses these only when ≥ weightsMinCorrections samples include
+ * them.
+ */
+interface CorrectionSubscores {
+    readonly pairKey: string;
+    readonly subscores: Readonly<Record<string, number>>;
+}
+declare class MemoryLearner {
+    private readonly config;
+    constructor(config?: LearningConfig);
+    /**
+     * Tune threshold and (optionally) field weights from corrections.
+     *
+     * Threshold tuning: sweep 0.5..0.95 in 0.05 steps, compute F1 using each
+     * correction's stored `score` vs its verdict. Returns the threshold with
+     * the best F1 (ties break toward higher threshold for precision).
+     *
+     * Field weights: requires subscores. Fits a tiny gradient update that
+     * nudges weights toward better discrimination of match / no_match.
+     */
+    learn(corrections: readonly Correction[], baseline: MatchkeyConfig, subscores?: readonly CorrectionSubscores[]): LearnedParams;
+}
+
+/**
+ * pprl/protocol.ts — Privacy-preserving record linkage.
+ * Edge-safe: no `node:` imports.
+ *
+ * Ports goldenmatch/pprl/protocol.py. Encodes both datasets as bloom
+ * filters (CLKs) over the selected fields, then scores pairs via Dice or
+ * Jaccard similarity. Two protocol stubs are surfaced: trusted third
+ * party (no crypto beyond the bloom filter itself) and a simple SMC
+ * sketch that adds a salt per party before encoding.
+ */
+
+interface PPRLConfig {
+    readonly fields: readonly string[];
+    readonly securityLevel: "standard" | "high" | "paranoid";
+    readonly protocol: "trusted_third_party" | "smc";
+    readonly threshold: number;
+    /** Optional salt used with "high"/"paranoid" levels. */
+    readonly salt?: string;
+}
+interface PPRLMatch {
+    readonly idA: number;
+    readonly idB: number;
+    readonly score: number;
+}
+interface PPRLResult {
+    readonly matches: readonly PPRLMatch[];
+    readonly stats: Readonly<Record<string, unknown>>;
+}
+/**
+ * Encode both row sets as bloom filters and emit pair matches above the
+ * configured threshold.
+ */
+declare function runPPRL(rowsA: readonly Row[], rowsB: readonly Row[], config: PPRLConfig): PPRLResult;
+/**
+ * Auto-pick PPRL parameters for the given dataset pair. Penalizes
+ * near-unique fields (IDs), over-long fields, and high-null fields.
+ */
+declare function autoConfigurePPRL(rowsA: readonly Row[], rowsB: readonly Row[]): PPRLConfig;
+
+export { ANNBlocker, type ANNBlockerBase, type ANNBlockerOptions, type AutoFixLog, type AutoconfigOptions, BlockResult, BlockingConfig, BlockingKeyConfig, BudgetConfig, type BudgetSnapshot, BudgetTracker, type BuildANNOptions, type CCMSResult, type ClusterExplanation, ClusterInfo, ClusterProvenance, type ColumnProfile, ColumnValue, type Correction, type CreateANNBlockerOptions, CrossEncoderHttpError, CrossEncoderModel, type CrossEncoderModelOptions, type CrossEncoderOptions, type CrossEncoderProvider, type CrossEncoderReranker, type DatasetProfile, DedupeResult, type DomainProfile, type EMResult, Embedder, EmbedderError, type EmbedderOptions, type EmbedderProvider, type EmbeddingResult, type EvalResult, type GatedResult, GoldenFieldRule, GoldenMatchConfig, GoldenRulesConfig, type GraphERResult, HNSWANNBlocker, type HNSWIndexLike, type HNSWModule, type HNSWOptions, type LLMScoreResult, LLMScorerConfig, type LearnedParams, type LearnedPredicate, type LearnedRules, LearningConfig, type LineageBundle, type LineageEdge, MatchResult, MatchkeyConfig, MatchkeyField, MemoryLearner, MemoryStore, type MemoryStoreConfig, type PPRLConfig, type PPRLResult, type PairExplanation, PairKey, QualityConfig, type QualityFinding, type Relationship, type ReviewItem, ReviewQueue, Row, ScoredPair, type SensitivityResult, StreamProcessor, type SweepParam, type SweepPoint, type TableSchema, TabularData, UnionFind, type ValidationReport, type ValidationRule, _resetCrossEncoderModelCache, addRowIds, addSourceColumn, addToCluster, applyColumnMap, applyCorrections, applyLearnedBlocks, applyStandardization, applyStandardizer, applyTransform, applyTransforms, asString, autoConfigurePPRL, autoConfigureRows, autoFixRows, buildANNBlocks, buildANNPairBlocks, buildAdaptiveBlocks, buildBlocks, buildBlocksAsync, buildClusters, buildComparisonVector, buildGoldenRecord, buildGoldenRecordWithProvenance, buildLineage, buildMst, buildMultiPassBlocks, buildStaticBlocks, compareClusters, computeClusterConfidence, computeMatchkeyValue, computeMatchkeys, concatRows, configToYaml, cosineSim, countTokensApprox, createANNBlocker, dedupe, detectDomain, diceCoefficient, ensembleScore, euclideanDist, evaluateClusters, evaluatePairs, explainCluster, explainPair, extractFeatures, findExactMatches, findExactMatchesOne, findFuzzyMatches, gatePairs, getClusterPairScores, getEmbedder, hashRow, indelDistance, indelSimilarity, isNullish, jaccardSimilarity, jaro, jaroWinkler, learnBlockingRules, levenshteinDistance, levenshteinSimilarity, lineageFromJson, lineageToJson, llmClusterPairs, llmScorePairs, loadGroundTruthPairs, match, matchOne, mergeField, metaphone, pairKey, parseConfig, parseConfigYaml, parsePairKey, profileRows, rerankPair, rerankTopPairs, runDedupePipeline, runGraphER, runMatchPipeline, runPPRL, runQualityCheck, runSensitivity, scanQuality, scoreBlocksSequential, scoreField, scoreMatrix, scorePair, scorePairRecord, scoreProbabilistic, scoreStrings, scoreStringsWithLlm, selectBestBlockingKey, soundex, soundexMatch, splitOversizedCluster, stabilityReport, toColumnValue, tokenSortRatio, trainEM, unmergeCluster, unmergeRecord, validateColumns, validateRows };