goldenmatch 0.1.0

package/tests/unit/streaming.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { StreamProcessor } from "../../src/core/streaming.js";
+import { makeMatchkeyConfig, makeMatchkeyField } from "../../src/core/types.js";
+import type { Row } from "../../src/core/types.js";
+
+function nameMk() {
+  return makeMatchkeyConfig({
+    name: "name_fuzzy",
+    type: "weighted",
+    fields: [
+      makeMatchkeyField({
+        field: "name",
+        scorer: "jaro_winkler",
+        transforms: ["lowercase"],
+      }),
+    ],
+  });
+}
+
+describe("StreamProcessor", () => {
+  it("first add with no existing cluster state creates a singleton", () => {
+    const sp = new StreamProcessor({ matchkey: nameMk(), threshold: 0.85 });
+    const result = sp.add({ __row_id__: 0, name: "Alice" });
+    expect(result.rowId).toBe(0);
+    expect(result.matchedIds).toEqual([]);
+    expect(result.clusterId).toBeGreaterThanOrEqual(0);
+    expect(sp.size).toBe(1);
+  });
+
+  it("matching record joins the existing cluster", () => {
+    const sp = new StreamProcessor({ matchkey: nameMk(), threshold: 0.85 });
+    const a = sp.add({ __row_id__: 0, name: "John Smith" });
+    const b = sp.add({ __row_id__: 1, name: "John Smith" });
+    expect(b.matchedIds).toContain(0);
+    expect(b.clusterId).toBe(a.clusterId);
+    expect(sp.size).toBe(2);
+  });
+
+  it("non-matching records get their own singleton clusters", () => {
+    const sp = new StreamProcessor({ matchkey: nameMk(), threshold: 0.95 });
+    const a = sp.add({ __row_id__: 0, name: "Alice Brown" });
+    const b = sp.add({ __row_id__: 1, name: "Zoltan Xiong" });
+    expect(b.matchedIds).toEqual([]);
+    expect(b.clusterId).not.toBe(a.clusterId);
+  });
+
+  it("size increments with each add", () => {
+    const sp = new StreamProcessor({ matchkey: nameMk(), threshold: 0.85 });
+    expect(sp.size).toBe(0);
+    sp.add({ __row_id__: 0, name: "A" });
+    expect(sp.size).toBe(1);
+    sp.add({ __row_id__: 1, name: "B" });
+    expect(sp.size).toBe(2);
+    sp.add({ __row_id__: 2, name: "C" });
+    expect(sp.size).toBe(3);
+  });
+
+  it("snapshot returns current clusters and rows", () => {
+    const sp = new StreamProcessor({ matchkey: nameMk(), threshold: 0.85 });
+    sp.add({ __row_id__: 0, name: "Alice" });
+    sp.add({ __row_id__: 1, name: "Bob" });
+    const snap = sp.snapshot();
+    expect(snap.rows.length).toBe(2);
+    expect(snap.clusters.size).toBeGreaterThan(0);
+    // Cluster members collectively cover all added row ids.
+    const allMembers = new Set<number>();
+    for (const info of snap.clusters.values()) {
+      for (const m of info.members) allMembers.add(m);
+    }
+    expect(allMembers.has(0)).toBe(true);
+    expect(allMembers.has(1)).toBe(true);
+  });
+
+  it("assigns __row_id__ automatically when absent on input row", () => {
+    const sp = new StreamProcessor({ matchkey: nameMk(), threshold: 0.85 });
+    const a = sp.add({ name: "X" });
+    const b = sp.add({ name: "Y" });
+    expect(a.rowId).toBe(0);
+    expect(b.rowId).toBe(1);
+    expect(sp.size).toBe(2);
+  });
+});

package/tests/unit/transforms.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect } from "vitest";
+import { applyTransform, applyTransforms, soundex, metaphone } from "../../src/core/index.js";
+import { sha256Hex, hmacSha256Hex } from "../../src/core/transforms.js";
+
+describe("applyTransform - basic transforms", () => {
+  it("lowercase", () => {
+    expect(applyTransform("HELLO", "lowercase")).toBe("hello");
+  });
+
+  it("uppercase", () => {
+    expect(applyTransform("hello", "uppercase")).toBe("HELLO");
+  });
+
+  it("strip", () => {
+    expect(applyTransform("  hello  ", "strip")).toBe("hello");
+  });
+
+  it("strip_all", () => {
+    expect(applyTransform("a b\tc\nd", "strip_all")).toBe("abcd");
+  });
+
+  it("digits_only", () => {
+    expect(applyTransform("abc123def", "digits_only")).toBe("123");
+  });
+
+  it("alpha_only", () => {
+    expect(applyTransform("abc123def!", "alpha_only")).toBe("abcdef");
+  });
+
+  it("normalize_whitespace", () => {
+    expect(applyTransform("  a   b\tc  ", "normalize_whitespace")).toBe("a b c");
+  });
+
+  it("token_sort", () => {
+    expect(applyTransform("Smith John", "token_sort")).toBe("John Smith");
+  });
+
+  it("first_token", () => {
+    expect(applyTransform("John Smith Doe", "first_token")).toBe("John");
+  });
+
+  it("last_token", () => {
+    expect(applyTransform("John Smith Doe", "last_token")).toBe("Doe");
+  });
+
+  it("returns null for null input", () => {
+    expect(applyTransform(null, "lowercase")).toBe(null);
+  });
+
+  it("unknown transform returns value unchanged", () => {
+    expect(applyTransform("hello", "nonexistent")).toBe("hello");
+  });
+});
+
+describe("applyTransform - parameterized", () => {
+  it("substring:0:3", () => {
+    expect(applyTransform("abcdef", "substring:0:3")).toBe("abc");
+  });
+
+  it("substring:2:5", () => {
+    expect(applyTransform("abcdef", "substring:2:5")).toBe("cde");
+  });
+
+  it("qgram:3 splits to 3-grams", () => {
+    const result = applyTransform("abcde", "qgram:3");
+    // 3-grams of "abcde": abc, bcd, cde (sorted)
+    expect(result).toBe("abc bcd cde");
+  });
+
+  it("qgram:2 splits to bigrams", () => {
+    const result = applyTransform("abc", "qgram:2");
+    // bigrams: ab, bc
+    expect(result).toBe("ab bc");
+  });
+});
+
+describe("soundex", () => {
+  it("Robert -> R163", () => {
+    expect(soundex("Robert")).toBe("R163");
+  });
+
+  it("Smith and Smyth have same code", () => {
+    expect(soundex("Smith")).toBe(soundex("Smyth"));
+  });
+
+  it("Rupert -> R163 (same as Robert)", () => {
+    expect(soundex("Rupert")).toBe("R163");
+  });
+
+  it("empty string -> 0000", () => {
+    expect(soundex("")).toBe("0000");
+  });
+
+  it("returns 4-character code", () => {
+    expect(soundex("Washington").length).toBe(4);
+  });
+});
+
+describe("metaphone", () => {
+  it("returns a string", () => {
+    expect(typeof metaphone("Thompson")).toBe("string");
+  });
+
+  it("empty string returns empty", () => {
+    expect(metaphone("")).toBe("");
+  });
+
+  it("code has at most 4 characters", () => {
+    expect(metaphone("Washington").length).toBeLessThanOrEqual(4);
+  });
+});
+
+describe("applyTransforms - chain", () => {
+  it("applies multiple in order", () => {
+    // lowercase then strip
+    expect(applyTransforms("  HELLO  ", ["lowercase", "strip"])).toBe("hello");
+  });
+
+  it("strip then digits_only", () => {
+    expect(applyTransforms("  abc123  ", ["strip", "digits_only"])).toBe("123");
+  });
+
+  it("empty chain returns value unchanged", () => {
+    expect(applyTransforms("hello", [])).toBe("hello");
+  });
+
+  it("propagates null through chain", () => {
+    expect(applyTransforms(null, ["lowercase", "strip"])).toBe(null);
+  });
+});
+
+describe("sha256Hex / hmacSha256Hex - Python parity", () => {
+  it("sha256 of empty string", () => {
+    expect(sha256Hex("")).toBe(
+      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    );
+  });
+
+  it("sha256 of 'abc' (FIPS 180-2 reference vector)", () => {
+    expect(sha256Hex("abc")).toBe(
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
+    );
+  });
+
+  it("sha256 handles UTF-8 multibyte input", () => {
+    // hashlib.sha256("héllo".encode()).hexdigest()
+    expect(sha256Hex("héllo")).toBe(
+      "3c48591d8d098a4538f5e013dfcf406e948eac4d3277b10bf614e295d6068179",
+    );
+  });
+
+  it("hmac-sha256 matches Python reference (empty key, empty msg)", () => {
+    // hmac.new(b"", b"", hashlib.sha256).hexdigest()
+    expect(hmacSha256Hex("", "")).toBe(
+      "b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad",
+    );
+  });
+
+  it("hmac-sha256 matches Python reference (RFC 4231 test case)", () => {
+    // hmac.new(b"key", b"The quick brown fox jumps over the lazy dog", hashlib.sha256).hexdigest()
+    expect(hmacSha256Hex("key", "The quick brown fox jumps over the lazy dog")).toBe(
+      "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8",
+    );
+  });
+});
+
+describe("bloom_filter - default size + hex length", () => {
+  it("default bloom_filter produces 256 hex chars (1024 bits)", () => {
+    const hex = applyTransform("hello", "bloom_filter");
+    expect(hex).not.toBe(null);
+    expect(hex!).toMatch(/^[0-9a-f]+$/);
+    expect(hex!.length).toBe(256); // 1024 bits / 4 bits per hex char
+  });
+
+  it("bloom_filter:standard produces 128 hex chars (512 bits)", () => {
+    const hex = applyTransform("hello", "bloom_filter:standard");
+    expect(hex!.length).toBe(128);
+  });
+
+  it("bloom_filter:high produces 256 hex chars (1024 bits)", () => {
+    const hex = applyTransform("hello", "bloom_filter:high");
+    expect(hex!.length).toBe(256);
+  });
+
+  it("bloom_filter:paranoid produces 512 hex chars (2048 bits)", () => {
+    const hex = applyTransform("hello", "bloom_filter:paranoid");
+    expect(hex!.length).toBe(512);
+  });
+
+  it("same input produces same output (deterministic)", () => {
+    expect(applyTransform("hello", "bloom_filter")).toBe(
+      applyTransform("hello", "bloom_filter"),
+    );
+  });
+
+  it("different inputs produce different outputs", () => {
+    const a = applyTransform("hello", "bloom_filter");
+    const b = applyTransform("world", "bloom_filter");
+    expect(a).not.toBe(b);
+  });
+
+  it("byte-for-byte Python parity for 'hello' default bloom_filter", () => {
+    // Reference generated by goldenmatch.utils.transforms.apply_transform("hello", "bloom_filter")
+    const expected =
+      "a008a1041000204000000400a000140000100048810004000008102010004000008400000000000080010100800000011014000000200000008002101000010002002100010000022000010020800000c00060000040000010010000000002400080000000800004008900200090000080800001000009000001000000100c20";
+    expect(applyTransform("hello", "bloom_filter")).toBe(expected);
+  });
+});

package/tests/unit/tui-widgets.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+
+describe("TUI widgets", () => {
+  it("exports widgets helper", async () => {
+    const mod = await import("../../src/node/tui/widgets.js");
+    expect(typeof mod.tryLoad).toBe("function");
+    expect(typeof mod.loadAddons).toBe("function");
+    expect(typeof mod.inkAddons).toBe("object");
+  });
+
+  it("tryLoad returns null for missing package", async () => {
+    const { tryLoad } = await import("../../src/node/tui/widgets.js");
+    expect(tryLoad("nonexistent-package-xyz")).toBeNull();
+  });
+
+  it("inkAddons getters return null for missing addons", async () => {
+    const { inkAddons } = await import("../../src/node/tui/widgets.js");
+    // In the test env none of the optional ink addons are installed.
+    // Each getter must return null rather than throwing.
+    expect(() => inkAddons.table).not.toThrow();
+    expect(() => inkAddons.selectInput).not.toThrow();
+    expect(() => inkAddons.textInput).not.toThrow();
+    expect(() => inkAddons.spinner).not.toThrow();
+    expect(() => inkAddons.gradient).not.toThrow();
+  });
+
+  it("loadAddons resolves to an object with all keys", async () => {
+    const { loadAddons } = await import("../../src/node/tui/widgets.js");
+    const addons = await loadAddons();
+    expect(addons).toHaveProperty("Table");
+    expect(addons).toHaveProperty("SelectInput");
+    expect(addons).toHaveProperty("TextInput");
+    expect(addons).toHaveProperty("Spinner");
+    expect(addons).toHaveProperty("Gradient");
+    // Each field is either null (missing package) or a loaded module/component.
+    for (const v of Object.values(addons)) {
+      expect(v === null || typeof v === "function" || typeof v === "object").toBe(
+        true,
+      );
+    }
+  });
+});

package/tests/unit/tui.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+
+describe("startTui", () => {
+  it("is exported as a function", async () => {
+    const { startTui } = await import("../../src/node/tui/app.js");
+    expect(typeof startTui).toBe("function");
+  });
+
+  it("throws helpful error when 'ink'/'react' not installed", async () => {
+    const { startTui } = await import("../../src/node/tui/app.js");
+    // ink/react are optional peer deps. In environments without them
+    // the loader inside startTui throws a helpful install message.
+    // If they happen to be installed, calling startTui would actually
+    // launch the TUI (which would block on stdin in tests) — so we
+    // only invoke when we expect the load to fail.
+    try {
+      await startTui({});
+      // If we get here, ink+react ARE installed. Just confirm no crash.
+      expect(true).toBe(true);
+    } catch (err) {
+      expect(String(err)).toMatch(/ink|react/i);
+    }
+  });
+});

package/tests/unit/validate.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi } from "vitest";
+import { validateRows, checkRule } from "../../src/core/validate.js";
+import type { ValidationRule } from "../../src/core/validate.js";
+import type { Row } from "../../src/core/types.js";
+
+describe("validateRows — not_null rule", () => {
+  it("quarantines rows that fail not_null when action is quarantine", () => {
+    const rows: Row[] = [
+      { email: "a@x.com" },
+      { email: null },
+      { email: "" },
+    ];
+    const rules: ValidationRule[] = [
+      {
+        column: "email",
+        ruleType: "not_null",
+        params: {},
+        action: "quarantine",
+      },
+    ];
+    const res = validateRows(rows, rules);
+    expect(res.valid.length).toBe(1);
+    expect(res.quarantine.length).toBe(2);
+    expect(res.report.quarantined).toBe(2);
+    expect(res.report.ruleViolations["email:not_null"]).toBe(2);
+  });
+
+  it("action='null' sets the failing cell to null but keeps the row", () => {
+    const rows: Row[] = [{ email: "" }];
+    const rules: ValidationRule[] = [
+      { column: "email", ruleType: "not_null", params: {}, action: "null" },
+    ];
+    const res = validateRows(rows, rules);
+    expect(res.valid.length).toBe(1);
+    expect(res.valid[0]!["email"]).toBeNull();
+    expect(res.quarantine.length).toBe(0);
+  });
+
+  it("action='flag' keeps the row and adds to __flags__ without quarantine", () => {
+    const rows: Row[] = [{ email: null }];
+    const rules: ValidationRule[] = [
+      { column: "email", ruleType: "not_null", params: {}, action: "flag" },
+    ];
+    const res = validateRows(rows, rules);
+    expect(res.valid.length).toBe(1);
+    const flags = res.valid[0]!["__flags__"] as string[];
+    expect(flags).toContain("email:not_null");
+    expect(res.report.flagged).toBe(1);
+  });
+});
+
+describe("validateRows — regex rule", () => {
+  it("valid values pass, invalid values trigger the action", () => {
+    const rows: Row[] = [
+      { email: "alice@example.com" },
+      { email: "not-an-email" },
+    ];
+    const rules: ValidationRule[] = [
+      {
+        column: "email",
+        ruleType: "regex",
+        params: { pattern: "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$" },
+        action: "quarantine",
+      },
+    ];
+    const res = validateRows(rows, rules);
+    expect(res.valid.length).toBe(1);
+    expect(res.quarantine.length).toBe(1);
+  });
+
+  it("invalid regex pattern does not crash; value is treated as failing", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const rows: Row[] = [{ email: "alice@example.com" }];
+    const rules: ValidationRule[] = [
+      {
+        column: "email",
+        ruleType: "regex",
+        params: { pattern: "([unclosed" },
+        action: "flag",
+      },
+    ];
+    // Must not throw.
+    expect(() => validateRows(rows, rules)).not.toThrow();
+    // Direct checkRule returns false for broken regex (via catch).
+    expect(
+      checkRule("a", {
+        column: "x",
+        ruleType: "regex",
+        params: { pattern: "([unclosed" },
+        action: "flag",
+      }),
+    ).toBe(false);
+    warn.mockRestore();
+  });
+});
+
+describe("checkRule — misc", () => {
+  it("min_length / max_length respect the `value` parameter", () => {
+    const minOk = checkRule("hello", {
+      column: "x",
+      ruleType: "min_length",
+      params: { value: 3 },
+      action: "flag",
+    });
+    const minFail = checkRule("hi", {
+      column: "x",
+      ruleType: "min_length",
+      params: { value: 3 },
+      action: "flag",
+    });
+    const maxOk = checkRule("hi", {
+      column: "x",
+      ruleType: "max_length",
+      params: { value: 3 },
+      action: "flag",
+    });
+    const maxFail = checkRule("toolong", {
+      column: "x",
+      ruleType: "max_length",
+      params: { value: 3 },
+      action: "flag",
+    });
+    expect(minOk).toBe(true);
+    expect(minFail).toBe(false);
+    expect(maxOk).toBe(true);
+    expect(maxFail).toBe(false);
+  });
+
+  it("in_set accepts allowed and rejects disallowed values", () => {
+    const allowed = checkRule("a", {
+      column: "x",
+      ruleType: "in_set",
+      params: { values: ["a", "b"] },
+      action: "flag",
+    });
+    const rejected = checkRule("z", {
+      column: "x",
+      ruleType: "in_set",
+      params: { values: ["a", "b"] },
+      action: "flag",
+    });
+    expect(allowed).toBe(true);
+    expect(rejected).toBe(false);
+  });
+});

package/tests/unit/workers-parallel.test.ts

@@ -0,0 +1,99 @@
+/**
+ * workers-parallel.test.ts -- Smoke tests for `scoreBlocksParallel`.
+ *
+ * piscina is an optional peer dep; these tests assert that the function
+ * degrades gracefully (fast-path / fallback) even when piscina isn't
+ * installed. When piscina IS installed, the worker path exercises true
+ * worker_threads, but we use block shapes that also work in the fallback.
+ */
+import { describe, it, expect } from "vitest";
+import { scoreBlocksParallel } from "../../src/node/backends/workers.js";
+import { pairKey } from "../../src/core/cluster.js";
+import type {
+  BlockResult,
+  MatchkeyConfig,
+  PairKey,
+  Row,
+} from "../../src/core/types.js";
+
+const mk: MatchkeyConfig = {
+  name: "name_match",
+  type: "weighted",
+  threshold: 0.5,
+  fields: [
+    { field: "name", transforms: [], scorer: "jaro_winkler", weight: 1 },
+  ],
+};
+
+function makeBlock(blockKey: string, rows: Row[]): BlockResult {
+  return { blockKey, rows, strategy: "static", depth: 0 };
+}
+
+describe("scoreBlocksParallel", () => {
+  it("returns empty for 0 blocks", async () => {
+    const result = await scoreBlocksParallel([], mk, new Set());
+    expect(result).toEqual([]);
+  });
+
+  it("uses sequential fast-path for <= 2 blocks", async () => {
+    const blocks = [
+      makeBlock("b0", [
+        { __row_id__: 1, name: "John" },
+        { __row_id__: 2, name: "Jon" },
+      ]),
+    ];
+    const result = await scoreBlocksParallel(blocks, mk, new Set());
+    expect(Array.isArray(result)).toBe(true);
+    // "John" vs "Jon" with jaro_winkler clears 0.5 threshold.
+    expect(result.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("falls back to concurrent path when piscina not installed", async () => {
+    // piscina is not installed in this dev env -- the dynamic import
+    // inside scoreBlocksParallel fails and we should land on the
+    // scoreBlocksConcurrent fallback, not throw.
+    const blocks: BlockResult[] = Array.from({ length: 5 }, (_, i) =>
+      makeBlock(`b${i}`, [
+        { __row_id__: i * 10 + 1, name: "John" },
+        { __row_id__: i * 10 + 2, name: "Jon" },
+      ]),
+    );
+    const result = await scoreBlocksParallel(blocks, mk, new Set());
+    expect(Array.isArray(result)).toBe(true);
+    // 5 blocks × at least 1 pair each clearing 0.5 threshold.
+    expect(result.length).toBeGreaterThanOrEqual(5);
+  });
+
+  it("mutates matchedPairs with newly discovered pairs", async () => {
+    const blocks: BlockResult[] = Array.from({ length: 4 }, (_, i) =>
+      makeBlock(`b${i}`, [
+        { __row_id__: i * 10 + 1, name: "Alice" },
+        { __row_id__: i * 10 + 2, name: "Alyce" },
+      ]),
+    );
+    const matched = new Set<PairKey>();
+    const result = await scoreBlocksParallel(blocks, mk, matched);
+    // Every newly returned pair must be in matchedPairs.
+    for (const p of result) {
+      const key = pairKey(p.idA, p.idB);
+      expect(matched.has(key)).toBe(true);
+    }
+  });
+
+  it("respects the exclude set (no duplicate pairs)", async () => {
+    const blocks: BlockResult[] = Array.from({ length: 3 }, (_, i) =>
+      makeBlock(`b${i}`, [
+        { __row_id__: i * 10 + 1, name: "Alice" },
+        { __row_id__: i * 10 + 2, name: "Alyce" },
+      ]),
+    );
+    const result = await scoreBlocksParallel(blocks, mk, new Set());
+    const keys = new Set<string>();
+    for (const p of result) {
+      const key =
+        p.idA < p.idB ? `${p.idA}:${p.idB}` : `${p.idB}:${p.idA}`;
+      expect(keys.has(key)).toBe(false);
+      keys.add(key);
+    }
+  });
+});

package/tests/unit/workers.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import { scoreBlocksConcurrent } from "../../src/node/backends/workers.js";
+import { scoreBlocksSequential } from "../../src/core/index.js";
+import type {
+  BlockResult,
+  MatchkeyConfig,
+  Row,
+} from "../../src/core/index.js";
+
+const mk: MatchkeyConfig = {
+  name: "name_match",
+  type: "weighted",
+  threshold: 0.5,
+  fields: [
+    { field: "name", transforms: [], scorer: "jaro_winkler", weight: 1 },
+  ],
+};
+
+function makeBlock(blockKey: string, rows: Row[]): BlockResult {
+  return { blockKey, rows, strategy: "static", depth: 0 };
+}
+
+describe("scoreBlocksConcurrent", () => {
+  it("0 blocks -> empty", async () => {
+    const out = await scoreBlocksConcurrent([], mk, new Set());
+    expect(out).toEqual([]);
+  });
+
+  it("small N (<=2 blocks) returns same pairs as sequential", async () => {
+    const block: Row[] = [
+      { __row_id__: 0, name: "Alice" },
+      { __row_id__: 1, name: "Alyce" },
+    ];
+    const blocks = [makeBlock("b0", block)];
+    const concurrent = await scoreBlocksConcurrent(blocks, mk, new Set());
+    const sequential = scoreBlocksSequential(blocks, mk, new Set());
+    expect(concurrent.length).toBe(sequential.length);
+    if (sequential.length > 0) {
+      expect(concurrent[0]!.idA).toBe(sequential[0]!.idA);
+      expect(concurrent[0]!.idB).toBe(sequential[0]!.idB);
+    }
+  });
+
+  it("many blocks (>2) batched concurrently returns same set as sequential", async () => {
+    const blocks: BlockResult[] = [];
+    for (let i = 0; i < 6; i++) {
+      const base = i * 10;
+      blocks.push(
+        makeBlock(`b${i}`, [
+          { __row_id__: base, name: "Alice" },
+          { __row_id__: base + 1, name: "Alyce" },
+        ]),
+      );
+    }
+    const concurrent = await scoreBlocksConcurrent(blocks, mk, new Set());
+    const sequential = scoreBlocksSequential(blocks, mk, new Set());
+    expect(concurrent.length).toBe(sequential.length);
+
+    const cKeys = new Set(concurrent.map((p) => `${p.idA}:${p.idB}`));
+    const sKeys = new Set(sequential.map((p) => `${p.idA}:${p.idB}`));
+    expect(cKeys).toEqual(sKeys);
+  });
+
+  it("handles empty/singleton blocks gracefully", async () => {
+    const blocks: BlockResult[] = [
+      makeBlock("empty", []),
+      makeBlock("singleton", [{ __row_id__: 0, name: "Alice" }]),
+      makeBlock("empty2", []),
+      makeBlock("singleton2", [{ __row_id__: 1, name: "Bob" }]),
+    ];
+    const out = await scoreBlocksConcurrent(blocks, mk, new Set());
+    expect(out).toEqual([]);
+  });
+});