Decision rules — how a screen resolves to Pass / Review / Fail

This is the one authoritative page for the rules that turn a set of real watchlist matches into a final Pass / Review / Fail decision: the decision priority ladder, the full decision matrix, the named rules DM-1 / DM-2 / DM-3, the floors and policy modifiers layered on top, the Enhanced Due Diligence escalation, and every tenant knob. Nothing here is a black box — each rule is drawn straight from the decision engine. For the companion 0–100 risk score that bands a result, and a worked example you can reproduce with two curl calls, see Score & decision. Deeper engineering notes live in docs/decision-matrix.md, docs/decision-priority.md and docs/decision-criteria.md, which this page consolidates.

1 · Where a decision comes from — four layers

A decision is assembled in four ordered layers. The matrix owns only the base per-match decision; the aggregate, the floors, and the priority ladder sit on top of it.

2 · The decision priority ladder

When a subject matches several categories at once (say sanctions and PEP), the ladder decides which match is the primary (decisive) one — the headline "this is why". It never changes the outcome (that stays the strongest decision); it only names the primary factor. The shipped default order (highest → lowest), straight from the DecisionPriority enum:

• Per-tenant reorderable. A tenant may supply its own order via RiskProfile.DecisionPriorityOrderJson. A partial order is completed automatically — the tenant's listed priorities first (in the order given, duplicates ignored), then every omitted priority in default order — so the ranking is always total and gap-free.
• Outcome-neutral by construction. The priority resolver reads the same per-factor decision the aggregate used, so the named primary can never disagree with the decision.

3 · The decision matrix

Each real, enabled match gets a base decision from an explicit matrix addressed by three axes — category × evidence tier × multiplicity (single vs 2+ real matches).

What admits a match to the "exact" rows (Q5)

The bar for a name to count as exact is 100% identical to the watchlist name after normalisation — FuzzyNameScorer.ExactNameSimilarity = 1.00, per-tenant via RiskProfile.ExactNameSimilarity. Anything below that bar, however close, is an algorithmic variation and may not auto-block; it is routed to a human.

The five evidence tiers combine that name bar with the date-of-birth signal:

The shipped default grid

P is the tenant's unconfirmed-hit posture SanctionsUnconfirmedDecision — Review by default, Fail for a strict tenant. The grid is seeded identically for Single and Multiple:

‡ sanctions ExactName-no-DoB follows the posture P — it was Fail under DM-1 (Q4, §4). † criminal ExactName-no-DoB is Fail (ENG-2, unchanged: a 100%-identical name to a terror entry is confirmed even without a DoB). ◆ the DoB near-match column is resolved before any category ladder, so no category can auto-Fail on a date of birth that is close but not identical (Q6). ★ adverse-media ExactName+DoB is Review — it was Fail under DM-2 (Q7, §4).

Three structural invariants (un-overridable)

The matrix enforces these regardless of any tenant override — a misconfiguration cannot breach them:

What invariant 3 covers — the four producers of a Fail

There are exactly four things in the whole engine that can produce a Fail. The invariant binds three of them. Read the table as the answer to the only question that matters here — "can this configuration auto-block a name that is not 100% identical?": for every row but the first, the answer is no.

4 · The named rules — DM-1, DM-2, DM-3, and the 2026-08-23 answers

Several cells depart from a naive "confirmed = name + DoB" reading. Each is an owner decision, and each has a rationale and a worked example. Two of the three original DM rules were superseded on 2026-08-23 — they are kept here, not deleted, because a client integrated against the older behaviour needs to see exactly what moved and why.

Q4 — a sanctions hit with an exact name and no DoB is a Review (supersedes DM-1)

sanctions × ExactNameNoDob → P — the unconfirmed posture; Review by default, Fail for a strict tenant.

• What DM-1 said (2026-08-07). A sanctions entry that carries no DoB — common on OFAC — can never reach the ExactNameExactDob tier, so following the posture would let the commonest sanctions shape clear to Review. DM-1 therefore Failed it on the name alone.
• Why it changed (2026-08-23). The missing DoB is precisely what leaves the identity unconfirmed, and an unconfirmed identity is not a basis for a machine to reject a customer with no human in the loop — particularly for common names. The recall argument survives intact: Review is not Pass. The hit is surfaced, the unconfirmed-watchlist floor (§5) stops any band policy quietly downgrading it, and the structural invariant means the cell can never be configured to Pass.
• A tenant can have DM-1 back, two ways and without a code change: set SanctionsUnconfirmedDecision = Fail (strict posture), or override this one cell to Fail via PUT …/decision-matrix.
• Example. Screen Bashar al-Assad with no DoB. The name is identical to the OFAC / EU / UK sanctions entries, which carry no DoB. Tier ExactNameNoDob → sanctions cell Review — a mandatory analyst decision, not an automatic rejection.

Q6 — a DoB that is close but not identical is a Review, in every category

* × ExactNameDobNearMatch → Review, resolved ahead of every category ladder.

• Rationale. Two full dates of birth that are present on both sides and differ — but by less than the tenant's DobYearTolerance — are neither a corroboration nor a rule-out. Previously such a pair was absorbed into the corroborated tier and could carry a category to an automatic Fail. It now has a tier of its own, and that tier is Review everywhere: no category auto-Fails on a date of birth that is close but not identical.
• Example. A subject born 1980-01-01 matches a sanctions entry reading 1980-11-02. Same year, inside a ±1-year tolerance, but not the same date → ExactNameDobNearMatch → Review, where the old behaviour reached the confirmed tier and Failed.
• Beyond the tolerance the pair is a mismatch, not a near-match, and DM-3 below applies.

Q7 — an adverse-media hit with exact name + exact DoB is a Review (supersedes DM-2)

adverse_media × ExactNameExactDob → Review; every adverse-media tier is now Review.

• What DM-2 said (2026-08-07). A name and a corroborated full DoB agreeing inside an adverse-media record is strong enough to block rather than merely review.
• Why it changed (2026-08-23). Adverse media is an allegation reported by a publisher, not an adjudicated blocking event, and it is not a list a regulator obliges you to act on. Confirming which person the article is about does not make the article a finding — so the confirmation raises the quality of the review, not the severity of the outcome. GDPR Art. 10 (#108) continues to govern adverse media on natural persons.
• A tenant that wants the old posture overrides the single cell to Fail; no code change.
• Example. An adverse-media record names Jane Q. Public, DoB 1970-03-04; the subject supplies the same name and the same DoB → tier ExactNameExactDob → adverse-media cell Review, with the corroborated DoB visible in the factor so the analyst knows the identification is solid.

Unchanged — criminal / terror

criminal × ExactNameExactDob → Fail and criminal × ExactNameNoDob → Fail (ENG-2) both stand as cells: terror and criminal categories were not in scope of the 2026-08-23 answers. What tightened for them is the Q5 name bar — the auto-Fail now requires a 100%-identical name, where a 0.98 near-exact name previously qualified. Two shapes changed outcome, and they are not the same case:

• No DoB, near-exact name (e.g. a one-character typo of a terror name). Falls to WeakOrPartialName and follows the tenant posture — and, being non-identical, cannot be lifted above Review even by the strict posture.
• Corroborating DoB, non-identical name. The tier is still ExactNameExactDob and the cell still reads Fail, but the third invariant clamps it to Review. This is the single most consequential change in the wave: an agreeing date of birth no longer substitutes for the name. Andreas routes algorithmic name variations to an analyst precisely "to verify dates of birth, nationalities, or secondary identifiers", so a DoB that agrees is the analyst's evidence rather than a reason to bypass them. The case file carries NAME_NOT_EXACT and a rule string naming the clamp, so the downgrade is never silent.

DM-3 — an exact name with a wrong DoB is surfaced for review, not silently cleared

*.ExactNameDobMismatch is a real cell (default Review for PEP / adverse-media, posture P for sanctions / criminal) instead of being dropped as a false positive.

• Rationale. An exact name whose full DoB is present on both sides but differs beyond the DobYearTolerance (default ±1 year) used to be classified FalsePositive and dropped — it Passed by absence. DM-3 surfaces it as a PotentialMatch so the tenant matrix decides it. A merely partial name with a differing DoB is still ruled out as a different person.
• Example. A subject with a token-exact name to a watchlist entry supplies DoB 1980-01-01; the entry says 1955-06-30. Beyond ±1 year → tier ExactNameDobMismatch → surfaced as a PotentialMatch → decided by the matrix (Review), not dropped.

5 · Floors and policy modifiers

These are applied to the aggregate decision. They never lower a Fail; they exist to stop a risky match quietly clearing.

6 · Enhanced Due Diligence (EDD) — a graduated ladder across all four PEP classes

A separate post-screening check (EddEscalationCheck, OPR-4b/5), run after the base decision — not part of the matrix. When EDD is on for the screen (the per-screen toggle, else the tenant default EnhancedDueDiligenceDefault, default false), every §5.5 PEP class attracts enhanced due diligence. What varies is the intensity:

• The ceiling is a tenant knob. EddEscalationMaxClass (default class 1, National) is the least-sensitive class that still escalates; every class at or above it in sensitivity Fails under EDD. Set it to LocalGovernmentAndAssociates and the whole ladder blocks; set it to Unknown and nothing escalates while the notes are still recorded.
• 🔴 This inverted on 2026-08-23 (Q3). The check previously escalated class 4 only — so a tenant that switched EDD on blocked on a mayor's cousin and let a sitting head of government through at Review. The owner's rule is a ladder: "all four classes need EDD, graduated — class 1 maximum, class 4 calibrated", so escalation now runs from the most sensitive class down to the ceiling.
• A non-escalating class is never silent. It emits a Note finding on the match ("EDD — <class>: enhanced due diligence applies at graduated intensity; reviewable, not escalated"), so an analyst can tell "EDD assessed this and calibrated it" apart from "EDD never looked at this match".

Only pep-tagged matches are in scope. A tenant opts out of the check entirely by adding its key (edd_escalation) to DisabledPostScreeningChecks. When EDD raises an otherwise-Review PEP to Fail, that escalation — not the category — is named as the headline reason (EDD_ESCALATION).

7 · What's tenant-configurable

Every rule above is per-tenant configuration, not a fixed constant:

8 · How a decision is reached — the full flow

1. Retrieve & classify. Candidates are classified on the name × DoB axis into TruePositive / PotentialMatch / FalsePositive. Only the first two are real and carry forward; a different name is dropped.
2. Drop disabled types. A warning type the tenant has switched off is removed before decisioning, as if the hit never happened.
3. Assign an evidence tier. Each real match lands in one of the five tiers from its name strength (against the 100%-identical ExactNameSimilarity bar) and its DoB signal — agrees / differs within DobYearTolerance / differs beyond it / absent.
4. Resolve the base decision. Each match is resolved through its matrix cell (category × tier × multiplicity), or its per-warning-type override. Either way the result passes through invariant 3: a Fail on a name that does not clear the ExactNameSimilarity bar is clamped to Review, and NAME_NOT_EXACT is recorded on the case file. The named rules of §4 live here.
5. Aggregate. Take the strongest base decision across all matches (Fail > Review > Pass).
6. Apply floors & policy. Fail stands. A Review runs EscalateHighToFail — which can only reach Fail when the screen has a carrier, a counted match that is itself name-identical, blocking-capable and High-band on its own contribution (invariant 3, §3), and otherwise holds at Review — or AllowLowBandPass, then the unconfirmed-watchlist floor; any path to Pass runs the confirmed-PEP floor.
7. EDD escalation. If EDD is on, a PEP match at or above the tenant's EddEscalationMaxClass (default class 1) escalates the decision to Fail; a less-sensitive class records a transparency note.
8. Name the primary. The priority ladder names the decisive match — presentation only, never changing the outcome.
9. Return. The response carries decision, riskScore, riskBand, reasonCodes, and the contributing factors[] — the full audit trail.