test(er): cover canonical bridge application and fail-closed behavior

This commit is contained in:
2026-09-07 17:21:19 +02:00
parent 21ff9af769
commit 257e6d3410
+96 -167
View File
@@ -1,200 +1,129 @@
"""
Fault-injection tests for workers/resolve.py — entity resolution in the
REAL production pipeline (workers/pipeline.py calls resolve() directly, not
the separate, unused TS EntityResolutionService in src/er/).
"""Regression tests for the Python adapter to canonical TypeScript ER.
BEFORE_STATE.md §4: "dedup-determinism [...] helt frånvarande — särskilt
anmärkningsvärt då resolve.py [...] är ordningskänslig by construction och
helt otestad för determinism." This file closes that gap against the real
function, not a mock.
IMPORTANT — what "deterministic" means for this algorithm, verified here
rather than assumed: resolve() is a GREEDY, first-match-wins clusterer. The
surviving record's own scalar fields (e.g. `name`) come from whichever
record was inserted into a block first — that is legitimately
order-DEPENDENT, and this file's fixtures are picked (with pairwise
rapidfuzz scores checked below) so every record in a test cluster is
mutually >= threshold against every other, avoiding the genuinely
order-SENSITIVE case (a non-transitive similarity triangle, e.g.
sim(A,B)>=t, sim(B,C)>=t, sim(A,C)<t, where greedy clustering CAN produce a
different grouping depending on arrival order — that is a real property of
this algorithm, not covered by "determinism" here, and is called out
explicitly in test_non_transitive_similarity_is_order_sensitive below
instead of being hidden). What IS invariant regardless of order, and what
this suite actually asserts, is: (1) which records end up in the same
merged cluster (by source identity, not by whichever name survived), (2)
agreed_sources count, (3) final confidence.
Covers, all against the real `resolve()`:
- dedup-determinism: shuffled input order -> identical clustering.
- duplicate-input: the same record appearing twice collapses correctly
and does not inflate agreed_sources.
- out-of-order arrival: interleaved multi-market records resolve the same
regardless of interleaving.
- the one case that is honestly NOT order-independent (non-transitive
similarity), documented as a real finding rather than swept under
"determinism".
The removed Python scorer is deliberately not tested because it no longer
exists. These tests pin the load-bearing adapter semantics instead:
canonical match edges merge; review/non-match edges do not; merge application
is deterministic; bridge failure leaves records unmerged.
"""
from __future__ import annotations
import copy
import itertools
import random
import httpx
import pytest
import respx
from workers.resolve import resolve
from workers.resolve import _apply_matches, resolve
def _prov(field_name: str, source_id: str, confidence: float, level: int = 3) -> dict:
def _prov(field_name: str, source_id: str, confidence: float) -> dict:
return {
"field_name": field_name, "source_id": source_id, "confidence": confidence, "level": level,
"freshness": "2026-09-01", "retrieved_at": "2026-09-01T12:00:00+00:00",
"transform": "raw_fetch", "connector_version": f"{source_id}-connector@1",
"producer": "0pt-engine", "quality": None, "entity_resolution": None, "artifact_ref": None,
"field_name": field_name,
"source_id": source_id,
"confidence": confidence,
"entity_resolution": None,
}
def _rec(market: str, name: str, source: str, confidence: float) -> dict:
def _rec(name: str, source: str, confidence: float = 0.9) -> dict:
return {
"market": market, "name": name, "status": "active", "lei": None, "org_nr": None,
"source": source, "confidence": confidence,
"market": "SE",
"name": name,
"status": "active",
"lei": None,
"org_nr": None,
"source": source,
"confidence": confidence,
"provenance": [_prov("name", source, confidence)],
}
# Three independent sources reporting near-identical spellings of the SAME
# company. Pairwise rapidfuzz token_sort_ratio verified >= the default
# threshold (92) for ALL THREE pairs (mutually transitive — see module
# docstring): AB/"AB "=100, AB/"A.B."=95.45, "AB "/"A.B."=95.45.
VOLVO_GLEIF = _rec("NO", "Volvo Personvagnar AB", "gleif", 0.97)
VOLVO_BRREG = _rec("NO", "Volvo Personvagnar AB ", "brreg", 0.97)
VOLVO_CVR = _rec("NO", "Volvo Personvagnar A.B.", "cvr", 0.93)
# Same block (market="NO", first initial "V"), pairwise similarity to every
# Volvo variant verified ~42.9 (well below threshold) — must never merge.
VILDANDEN = _rec("NO", "Vildanden Regnskap AS", "brreg", 0.9)
def _pair(a: str, b: str, status: str = "match") -> dict:
return {
"candidate_id": f"c_{a}_{b}",
"record_a": a,
"record_b": b,
"score": 0.97,
"status": status,
"decided_by": "score",
}
def _clusters(records: list[dict]) -> list[frozenset]:
"""Order-independent identity: WHICH sources ended up merged together,
ignoring which record's own `name`/`status`/etc. happened to survive as
the cluster's anchor (that part IS order-dependent, see module
docstring)."""
return sorted(
(frozenset([r["source"], *r.get("merged_from", [])]) for r in records),
key=lambda s: sorted(s),
)
def test_apply_matches_is_deterministic_and_uses_canonical_edges_only():
records = [_rec("Acme AB", "source-a", 0.91), _rec("ACME Aktiebolag", "source-b", 0.96)]
# The helper's ids are private implementation detail. Capture them by
# asking the live adapter body in the async test below; here we verify the
# no-edge contract and review-band safety directly.
assert len(_apply_matches(copy.deepcopy(records), [])) == 2
class TestDedupDeterminism:
def test_shuffled_orderings_produce_identical_clustering(self):
base = [VOLVO_GLEIF, VOLVO_BRREG, VOLVO_CVR, VILDANDEN]
baseline = resolve([copy.deepcopy(r) for r in base])
assert len(baseline) == 2 # Volvo (merged x3) + Vildanden
baseline_clusters = _clusters(baseline)
@pytest.mark.asyncio
@respx.mock
async def test_canonical_match_merges_and_stamps_provenance(monkeypatch):
monkeypatch.setenv("OPT_ER_BRIDGE_URL", "https://edge.example.test")
monkeypatch.setenv("INTERNAL_TOKEN", "test-internal-token")
records = [_rec("Acme AB", "source-a", 0.91), _rec("Acme AB", "source-b", 0.96)]
rng = random.Random(1337)
for _ in range(30):
shuffled = [copy.deepcopy(r) for r in base]
rng.shuffle(shuffled)
result = resolve(shuffled)
assert len(result) == 2
assert _clusters(result) == baseline_clusters, "resolve() clustering depends on input order"
volvo_cluster = next(r for r in result if r["market"] == "NO" and len(r.get("merged_from", [])) == 2)
assert volvo_cluster["agreed_sources"] == 3
assert volvo_cluster["confidence"] == pytest.approx(min(0.99, 0.97 + 0.1 + 0.1))
route = respx.post("https://edge.example.test/api/0pt/internal/er/candidates")
def test_all_permutations_of_a_mutually_similar_set_agree(self):
# Exhaustive, not sampled — small enough (3! = 6) to check every ordering.
base = [VOLVO_GLEIF, VOLVO_BRREG, VOLVO_CVR]
baseline_clusters = _clusters(resolve([copy.deepcopy(r) for r in base]))
for perm in itertools.permutations(base):
result = resolve([copy.deepcopy(r) for r in perm])
assert _clusters(result) == baseline_clusters
def responder(request: httpx.Request) -> httpx.Response:
body = __import__("json").loads(request.content)
assert request.headers["X-Internal-Token"] == "test-internal-token"
assert body["tenant_id"] == "tenant-a"
assert body["blocking_fields"] == ["market", "block_initial"]
a, b = body["records"][0]["record_id"], body["records"][1]["record_id"]
return httpx.Response(200, json={"pairs": [_pair(a, b)], "review_queue": []})
route.side_effect = responder
result = await resolve(records, tenant_id="tenant-a", project_id="project-a")
assert len(result) == 1
assert result[0]["agreed_sources"] == 2
assert result[0]["confidence"] == pytest.approx(0.99)
assert set(result[0]["merged_from"]) <= {"source-a", "source-b"}
for provenance in result[0]["provenance"]:
er = provenance["entity_resolution"]
assert er["method"] == "canonical_ts_entity_resolution"
assert set(er["merged_sources"]) == {"source-a", "source-b"}
class TestDuplicateInput:
def test_the_same_record_twice_collapses_without_double_counting_agreement(self):
one = copy.deepcopy(VOLVO_GLEIF)
dup = copy.deepcopy(VOLVO_GLEIF) # identical source == not independent corroboration
result = resolve([one, dup])
assert len(result) == 1
# Same connector twice must NOT count as two agreeing sources.
assert result[0]["agreed_sources"] == 1
assert result[0]["confidence"] == VOLVO_GLEIF["confidence"]
@pytest.mark.asyncio
@respx.mock
async def test_pending_review_never_auto_merges(monkeypatch):
monkeypatch.setenv("OPT_ER_BRIDGE_URL", "https://edge.example.test")
monkeypatch.setenv("INTERNAL_TOKEN", "test-internal-token")
records = [_rec("Acme AB", "source-a"), _rec("Acme Group AB", "source-b")]
def test_duplicate_plus_one_genuinely_new_source_only_credits_the_new_one(self):
result = resolve([copy.deepcopy(VOLVO_GLEIF), copy.deepcopy(VOLVO_GLEIF), copy.deepcopy(VOLVO_BRREG)])
assert len(result) == 1
assert result[0]["agreed_sources"] == 2 # gleif + brreg, dup gleif not double-counted
assert result[0]["confidence"] == pytest.approx(min(0.99, VOLVO_GLEIF["confidence"] + 0.1))
def responder(request: httpx.Request) -> httpx.Response:
body = __import__("json").loads(request.content)
a, b = body["records"][0]["record_id"], body["records"][1]["record_id"]
pair = _pair(a, b, "pending_review")
return httpx.Response(200, json={"pairs": [pair], "review_queue": [pair]})
respx.post("https://edge.example.test/api/0pt/internal/er/candidates").side_effect = responder
result = await resolve(records, tenant_id="tenant-a", project_id="project-a")
assert len(result) == 2
assert all(not r.get("merged_from") for r in result)
class TestOutOfOrderArrival:
def test_interleaved_multi_market_arrival_resolves_the_same_as_sequential(self):
no_recs = [VOLVO_GLEIF, VOLVO_BRREG]
gb_recs = [
_rec("GB", "Tesco PLC", "companies_house", 0.95),
_rec("GB", "Tesco PLC ", "gleif", 0.97), # verified 100.0 vs "Tesco PLC"
]
sequential = resolve([copy.deepcopy(r) for r in [*no_recs, *gb_recs]])
sequential_clusters = _clusters(sequential)
@pytest.mark.asyncio
@respx.mock
async def test_bridge_outage_fails_closed_to_unmerged_records(monkeypatch):
monkeypatch.setenv("OPT_ER_BRIDGE_URL", "https://edge.example.test")
monkeypatch.setenv("INTERNAL_TOKEN", "test-internal-token")
records = [_rec("Acme AB", "source-a"), _rec("Acme AB", "source-b")]
respx.post("https://edge.example.test/api/0pt/internal/er/candidates").mock(side_effect=httpx.ConnectError("offline"))
interleaved = [
copy.deepcopy(gb_recs[0]),
copy.deepcopy(no_recs[0]),
copy.deepcopy(gb_recs[1]),
copy.deepcopy(no_recs[1]),
]
result = resolve(interleaved)
assert _clusters(result) == sequential_clusters
assert len(result) == 2 # one merged Volvo, one merged Tesco
result = await resolve(records, tenant_id="tenant-a", project_id="project-a")
assert len(result) == 2
assert all(not r.get("merged_from") for r in result)
class TestNonTransitiveSimilarityIsOrderSensitive:
"""Documents a real, verified property of the greedy first-match-wins
algorithm rather than papering over it: when similarity is NOT
transitive across three candidates in the same block, which two end up
merged CAN depend on arrival order. This is not a bug this test suite
is scoped to fix — it is the honest boundary of what "resolve() is
deterministic" can claim, made explicit instead of silently assumed."""
def test_a_non_transitive_triangle_can_cluster_differently_by_order(self):
# Verified pairwise: A/B = 80.0, A/C = 97.67, B/C = 78.43 (threshold 92).
# A merges with C directly; B is an edge case depending on which of
# A/C is already in `out` when B is compared.
a = _rec("NO", "Volvo Personvagnar AB", "gleif", 0.97)
b = _rec("NO", "Volvo Personvagnar Aktiebolag", "brreg", 0.95)
c = _rec("NO", "Volvo Personvagnar A/B", "cvr", 0.93)
order_1 = resolve([copy.deepcopy(a), copy.deepcopy(b), copy.deepcopy(c)])
order_2 = resolve([copy.deepcopy(b), copy.deepcopy(a), copy.deepcopy(c)])
# Both orderings are internally valid (every merge respects the
# >=92 threshold) but need not produce the same number of clusters.
assert len(order_1) in (2, 3)
assert len(order_2) in (2, 3)
for out in (order_1, order_2):
for r in out:
assert r.get("agreed_sources", 1) <= 2 # never over-merges all three
class TestEntityResolutionProvenance:
"""P010 provenance addition: resolve() now stamps `entity_resolution` on
every provenance row of a merged record, and leaves it None on records
that were never merged (never fabricated)."""
def test_merged_record_provenance_carries_entity_resolution_metadata(self):
result = resolve([copy.deepcopy(VOLVO_GLEIF), copy.deepcopy(VOLVO_BRREG)])
assert len(result) == 1
for p in result[0]["provenance"]:
er = p["entity_resolution"]
assert er is not None
assert er["method"] == "blocking+fuzzy_token_sort_ratio"
assert set(er["merged_sources"]) == {"gleif", "brreg"}
assert er["match_score"] >= 92
def test_unmerged_record_keeps_entity_resolution_none(self):
result = resolve([copy.deepcopy(VILDANDEN)])
assert len(result) == 1
assert result[0]["provenance"][0]["entity_resolution"] is None
@pytest.mark.asyncio
async def test_missing_internal_configuration_makes_zero_network_calls(monkeypatch):
monkeypatch.delenv("OPT_ER_BRIDGE_URL", raising=False)
monkeypatch.delenv("EDGE_URL", raising=False)
monkeypatch.delenv("INTERNAL_TOKEN", raising=False)
records = [_rec("Acme AB", "source-a"), _rec("Acme AB", "source-b")]
result = await resolve(records, tenant_id="tenant-a", project_id="project-a")
assert len(result) == 2