[abrichr]

Stacked on #1513 (which is stacked on #1514). The base is measure/production-lifecycle, so the diff shows only this change.

In the production soak (#1513), the duplicate check was the largest operator cost after approvals. no_duplicate_candidate reads OpenEMR's on-screen match list and stops any new patient who shares a last name or a date of birth with an existing chart.

What changes

A check whose source is the record (runtime/checks/duplicate_record.py; the S5 seam in docs/design/DECOMPOSITION.md). It has three channels:

• FhirPatientSource: generic FHIR R4 Patient search;
• RestPatientSource: an OpenEMR adapter (/api/patient);
• SqlPatientSource: an OpenEMR adapter, the fallback (patient_data, MySQL %s parameters), wired by hand only.

It searches:

• by the date of birth (and with day and month swapped);
• by each part of the last and first name, and by first name;
• by MRN, phone and email.

It reads every page and decides:

Decision	Result
exact: same first name, last name and date of birth, or the same MRN	stop
close: the rules in docs/DUPLICATE_CHECK.md (name variants, nicknames, initials, prior names, near dates with a tie-breaker)	stop for a person; the halt names each record id and why
none	proceed
unreadable: see below	stop (fail closed)

The check is unreadable when:

• the channel is unreachable or refuses the credentials;
• the reply is not a result set, or a REST body carries any error field or no data list;
• a reported total doesn't match what was read;
• the search runs past 50 pages, or a REST page is full with no next link;
• a next-page link points to another host;
• a record has no id;
• the run's date of birth is missing or not ISO.

A record date that is only a year or a year and month counts as no date, so a name match is close.

One source for every path. Replayer resolves the source itself, from its own effect verifier and the program's pin (resolve_duplicate_source). So qualification (qualify/campaign.py), a run (build_replayer), and the lifecycle proof's run, execute and resume all use the same check:

• no path can pass another;
• a qualification replayer_kwargs hook that tries is refused;
• a verifier the resolution doesn't recognize, such as a test double without records_path, gives no source instead of an error.

There is no deployment-level switch any more, so nothing outside the program can make one path differ.

The program decides. The postcondition field candidate_source is part of the qualified program:

• record: FHIR or OpenEMR REST. A run without the channel fails closed, never the screen.
• screen: the on-screen list.
• unset: FHIR when the run has it, else the screen.

So REST is opt-in: only a program pinned to record uses it, and FHIR is the only automatic channel. The soak's OpenEMR program change pins record. candidate_record_fields maps a program's own parameter names; the default is OpenEMR's.

The stop reason reads failed: no_duplicate_candidate (record check via <channel>: <decision>, ...). unreadable is a program or channel problem, and exact and close are about the item; I've told #1517's author the exact form.

The exact numbers (offline)

A miss is a second chart for a patient who already has one.

Test set: the soak's seed-7 generator, 500 items with planted duplicates and extra charts. That makes 694 items, 440 new patients and 241 true duplicates: 47 from the generator, 194 planted.

	screen check	record check, first version	record check, now
missed, of 241	42	90	24
missed, of the 47 from the generator	0	0	0
false stops, of 440 new patients	252 (36.3 per 100 items)	2 (0.3)	2 (0.3)

Known limit: the record check's 24 misses, uncatchable without extra data:

• 12 are a new last name, new address, phone and email, and a mistyped day of birth (only the first name is shared);
• 12 are new first and last names and new contact details (only the date of birth is shared).

Catching them needs an MRN, an insurance id or a person.

The README (benchmark/dup_check/README.md) has every kind: how many were planted, the misses by check, and the rule that catches it. It also covers the two cases the review reproduced, a nickname plus a date typo and a last-name typo plus a date typo. Both now stop, and the screen misses the second. The planted kinds for rounds two to four were written alongside their rules, so only round one's held-out kinds were a blind test.

Limits

• Live OpenEMR 8.0.0.3 (benchmark/dup_check/live.py; raw output private, OpenAdaptAI/openadapt-corpus#18):
  • FHIR: decided 6 of 6 referrals with known answers right (exact, married name, nickname, swapped date, shared birth date only, namesake). OpenEMR's FHIR has no next link, and its Bundle.total equals the rows returned, so _count truncates silently. The check sends no _count, and OpenEMR returned all 120 of 120 rows. A larger set is untested.
  • REST: 6 of 6 at 500 rows a page. Paging works (_limit, links.next), but the links carry OpenEMR's configured site address. At 5 a page, the check refused the other-origin link and answered unreadable (fail closed). That's why REST stays opt-in.
  • Both match last names by prefix. FHIR doesn't expose a birth name, so prior names are searchable only through the SQL adapter.
• One seed.
• No change to the soak's operator-minute headline is claimed until the soak reruns with this on.
• StepResult.duplicate_check (exact, close, candidate, unreadable) is set on the halted step whenever the check fails, for problems_only switch policy: input problems leave it on, a person re-arms with one signed tap #1517's switch policy; omitted when unset.

Tests

• test_duplicate_record_check.py (52) and test_duplicate_source_paths.py (11).
• test_no_duplicate_candidate.py, and the deployment, approval, profile, run-gate, qualification and lifecycle tests that build a replayer.
• The launcher copy test (test_shipped_only_copy.py).
• ruff check, ruff format --check and both mypy gates report nothing in the changed files.
• The public artifact inventory is regenerated. It also registers Production configuration soak: verified items per operator-minute, before and after (evidence) #1513's soak results, which are in this PR's base.

🤖 Generated with Claude Code