Upload 15 files

src/Invoice Validation Functions/Bank validation.py

@@ -0,0 +1,438 @@
+import re
+from datetime import date, datetime
+from hashlib import sha256
+from unicodedata import normalize
+from decimal import Decimal
+
+from rapidfuzz import fuzz
+
+
+def run_bank_validation(
+    *,
+    document,
+    extracted_fields,
+    vendor_bank_accounts,
+    resolved_vendor_id,
+    platform_configs=None,
+    name_match_fn=None,
+):
+    """
+    Bank validation logic based on Cat 2 section 7.4.
+
+    Expected document fields:
+        document.id
+        document.tenant_id
+
+    Expected extracted_fields fields:
+        invoice_date
+        currency
+        bank_iban
+        bank_acc_no
+        bank_swift
+        bank_acc_name
+
+    Expected vendor_bank_accounts row fields:
+        tenant_id
+        vendor_id
+        iban_canonical
+        acc_no_canonical
+        swift_bic
+        bank_acc_name
+        currency_code
+        bank_country
+        is_primary
+        effective_from
+        effective_to
+        deleted_at
+
+    name_match_fn:
+        Optional function for bank account name comparison.
+        Should return something like:
+            {"decision": "matched" | "suggestion" | "unmatched"}
+    """
+
+    platform_configs = platform_configs or {}
+
+    iban_checksum_required = platform_configs.get(
+        "validation.iban_checksum_required",
+        True,
+    )
+
+    iban_accno_exempt_countries = set(
+        platform_configs.get(
+            "validation.iban_accno_substring_exempt_countries",
+            ["LC", "MT"],
+        )
+    )
+
+    high_threshold = Decimal(str(platform_configs.get("validation.rapidfuzz_high_threshold", "0.90")))
+    medium_threshold = Decimal(str(platform_configs.get("validation.rapidfuzz_medium_threshold", "0.75")))
+    suggestion_threshold = Decimal(str(platform_configs.get("validation.rapidfuzz_suggestion_threshold", "0.60")))
+
+    def hash_prefix(value, length=8):
+        if not value:
+            return None
+        return sha256(str(value).encode("utf-8")).hexdigest()[:length]
+
+    def canonicalize_text(value):
+        if value is None:
+            return None
+        value = normalize("NFKC", str(value))
+        value = value.strip().upper()
+        return value or None
+
+    def canonicalize_iban(value):
+        if value is None:
+            return None
+        value = normalize("NFKC", str(value))
+        value = re.sub(r"[\s\-\.,/\\:;_]+", "", value)
+        value = value.upper()
+        return value or None
+
+    def canonicalize_acc_no(value):
+        if value is None:
+            return None
+        value = normalize("NFKC", str(value))
+        value = re.sub(r"[\s\-\.,/\\:;_]+", "", value)
+        value = value.upper()
+        return value or None
+
+    def canonicalize_swift(value):
+        if value is None:
+            return None
+        value = normalize("NFKC", str(value))
+        value = re.sub(r"\s+", "", value)
+        value = value.upper()
+        return value or None
+
+    def iban_country(iban):
+        if not iban or len(iban) < 2:
+            return None
+        return iban[:2]
+
+    def iban_checksum_mod97_valid(iban):
+        """
+        Standard IBAN mod-97 validation.
+
+        Move first 4 chars to end.
+        Replace letters A=10 ... Z=35.
+        Result mod 97 must equal 1.
+        """
+        if not iban or len(iban) < 4:
+            return False
+
+        rearranged = iban[4:] + iban[:4]
+        numeric = ""
+
+        for char in rearranged:
+            if char.isdigit():
+                numeric += char
+            elif "A" <= char <= "Z":
+                numeric += str(ord(char) - ord("A") + 10)
+            else:
+                return False
+
+        remainder = 0
+        for digit in numeric:
+            remainder = (remainder * 10 + int(digit)) % 97
+
+        return remainder == 1
+
+    def iban_acc_no_consistent(iban, acc_no):
+        """
+        Basic consistency check:
+        remove country + check digits from IBAN,
+        then check whether account number appears inside BBAN.
+
+        Leading zeros are ignored for comparison.
+        """
+        if not iban or not acc_no:
+            return True
+
+        country = iban_country(iban)
+
+        if country in iban_accno_exempt_countries:
+            return True
+
+        bban = iban[4:]
+        stripped_acc_no = acc_no.lstrip("0") or acc_no
+
+        return stripped_acc_no in bban
+
+    def is_effective(row, invoice_date):
+        if getattr(row, "deleted_at", None):
+            return False
+
+        if invoice_date is None:
+            return True
+
+        effective_from = getattr(row, "effective_from", None)
+        effective_to = getattr(row, "effective_to", None)
+
+        if effective_from is not None and invoice_date < effective_from:
+            return False
+
+        if effective_to and invoice_date >= effective_to:
+            return False
+
+        return True
+
+    def default_name_match(invoice_name, master_name):
+        if not invoice_name or not master_name:
+            return {"decision": "unmatched"}
+
+        score = Decimal(str(fuzz.WRatio(invoice_name, master_name) / 100)).quantize(
+            Decimal("0.0001")
+        )
+
+        if score >= high_threshold:
+            return {"decision": "matched", "score_tier": "high"}
+        if score >= medium_threshold:
+            return {"decision": "matched", "score_tier": "medium"}
+        if score >= suggestion_threshold:
+            return {"decision": "suggestion", "score_tier": "low"}
+        return {"decision": "unmatched", "score_tier": "low"}
+
+    def bank_account_name_matches(invoice_name, master_name):
+        matcher = name_match_fn or default_name_match
+
+        result = matcher(
+            query_name=invoice_name,
+            candidate_pool=[master_name],
+            context={"purpose": "bank_acc_name_check"},
+        ) if name_match_fn else matcher(invoice_name, master_name)
+
+        return result.get("decision") == "matched"
+
+    def add_flag(code, *, field=None, weight=None, match_result="failed", invoice_value=None,
+                 master_value=None, currency_invoice=None, currency_master=None,
+                 primary_or_non_primary=None):
+        flag = {
+            "code": code,
+            "field": field,
+            "severity": "advisory",
+        }
+
+        if weight is not None:
+            flag["weight"] = weight
+
+        risk_flags.append(flag)
+
+        audit_entries.append(
+            {
+                "field": field,
+                "match_result": match_result,
+                "invoice_hash_prefix": hash_prefix(invoice_value),
+                "master_hash_prefix": hash_prefix(master_value),
+                "currency_invoice": currency_invoice,
+                "currency_master": currency_master,
+                "primary_or_non_primary": primary_or_non_primary,
+            }
+        )
+
+    risk_flags = []
+    skipped_steps = []
+    audit_entries = []
+
+    if resolved_vendor_id is None:
+        skipped_steps.append(
+            {
+                "step": "bank_validation",
+                "skip_reason": "vendor_unresolved",
+            }
+        )
+
+        return {
+            "risk_flags": risk_flags,
+            "skipped_steps": skipped_steps,
+            "audit_entries": audit_entries,
+            "match_result": "skipped",
+        }
+
+    invoice_date = getattr(extracted_fields, "invoice_date", None)
+
+    if isinstance(invoice_date, datetime):
+        invoice_date = invoice_date.date()
+
+
+    invoice_iban = canonicalize_iban(getattr(extracted_fields, "bank_iban", None))
+    invoice_acc_no = canonicalize_acc_no(getattr(extracted_fields, "bank_acc_no", None))
+    invoice_swift = canonicalize_swift(getattr(extracted_fields, "bank_swift", None))
+    invoice_bank_acc_name = getattr(extracted_fields, "bank_acc_name", None)
+    invoice_currency = canonicalize_text(getattr(extracted_fields, "currency", None))
+
+    # 1. Invoice-side pre-format checks.
+    if invoice_iban and iban_checksum_required:
+        if not iban_checksum_mod97_valid(invoice_iban):
+            add_flag(
+                "bank_iban_invalid_checksum",
+                field="bank_iban",
+                weight=Decimal("0.35"),
+                invoice_value=invoice_iban,
+            )
+
+    if invoice_iban and invoice_acc_no:
+        if not iban_acc_no_consistent(invoice_iban, invoice_acc_no):
+            add_flag(
+                "bank_iban_accno_inconsistent",
+                field="bank_iban/bank_acc_no",
+                weight=Decimal("0.35"),
+                invoice_value=f"{invoice_iban}|{invoice_acc_no}",
+            )
+
+    # 2. Build same-tenant, same-vendor, active candidate pool.
+    candidate_pool = [
+        row
+        for row in vendor_bank_accounts
+        if getattr(row, "tenant_id", None) == document.tenant_id
+        and getattr(row, "vendor_id", None) == resolved_vendor_id
+        and not getattr(row, "deleted_at", None)
+        and is_effective(row, invoice_date)
+    ]
+
+    candidate_pool.sort(
+        key=lambda row: (
+            bool(getattr(row, "is_primary", False)),
+            getattr(row, "effective_from", None) or date.max,
+        ),
+        reverse=True,
+    )
+
+    primary_rows = [
+        row for row in candidate_pool
+        if bool(getattr(row, "is_primary", False))
+    ]
+
+    non_primary_rows = [
+        row for row in candidate_pool
+        if not bool(getattr(row, "is_primary", False))
+    ]
+
+    primary = primary_rows[0] if primary_rows else None
+
+    invoice_has_any_bank_detail = any(
+        [
+            invoice_iban,
+            invoice_acc_no,
+            invoice_swift,
+            invoice_bank_acc_name,
+        ]
+    )
+
+    if invoice_has_any_bank_detail and not candidate_pool:
+        add_flag(
+            "new_bank_details_no_master",
+            field="bank_details",
+            invoice_value="bank_details_present",
+        )
+
+        return {
+            "risk_flags": risk_flags,
+            "skipped_steps": skipped_steps,
+            "audit_entries": audit_entries,
+            "match_result": "no_master_bank_details",
+        }
+
+    # 3. Compare against primary account.
+    if primary:
+        primary_match = True
+
+        master_iban = getattr(primary, "iban_canonical", None)
+        master_acc_no = getattr(primary, "acc_no_canonical", None)
+        master_swift = canonicalize_swift(getattr(primary, "swift_bic", None))
+        master_bank_acc_name = getattr(primary, "bank_acc_name", None)
+        master_currency = canonicalize_text(getattr(primary, "currency_code", None))
+
+        if invoice_iban:
+            if not master_iban:
+                primary_match = False
+                add_flag(
+                    "new_bank_field_type_no_master",
+                    field="bank_iban",
+                    invoice_value=invoice_iban,
+                    primary_or_non_primary="primary",
+                )
+            elif invoice_iban != master_iban:
+                primary_match = False
+                add_flag(
+                    "bank_iban_mismatch",
+                    field="bank_iban",
+                    invoice_value=invoice_iban,
+                    master_value=master_iban,
+                    primary_or_non_primary="primary",
+                )
+
+        if invoice_acc_no and master_acc_no and invoice_acc_no != master_acc_no:
+            primary_match = False
+            add_flag(
+                "bank_acc_no_mismatch",
+                field="bank_acc_no",
+                invoice_value=invoice_acc_no,
+                master_value=master_acc_no,
+                primary_or_non_primary="primary",
+            )
+
+        if invoice_swift and master_swift and invoice_swift != master_swift:
+            primary_match = False
+            add_flag(
+                "bank_swift_mismatch",
+                field="bank_swift",
+                invoice_value=invoice_swift,
+                master_value=master_swift,
+                primary_or_non_primary="primary",
+            )
+
+        if invoice_bank_acc_name and master_bank_acc_name:
+            if not bank_account_name_matches(invoice_bank_acc_name, master_bank_acc_name):
+                primary_match = False
+                add_flag(
+                    "bank_acc_name_mismatch",
+                    field="bank_acc_name",
+                    weight=Decimal("0.30"),
+                    invoice_value=invoice_bank_acc_name,
+                    master_value=master_bank_acc_name,
+                    primary_or_non_primary="primary",
+                )
+
+        if invoice_currency and master_currency and invoice_currency != master_currency:
+            primary_match = False
+            add_flag(
+                "bank_currency_mismatch",
+                field="currency",
+                weight=Decimal("0.20"),
+                currency_invoice=invoice_currency,
+                currency_master=master_currency,
+                primary_or_non_primary="primary",
+            )
+
+        match_result = "primary_match" if primary_match else "primary_mismatch"
+
+    else:
+        match_result = "no_primary_bank_account"
+
+        secondary_match = None
+        for row in non_primary_rows:
+            if invoice_iban and getattr(row, "iban_canonical", None) == invoice_iban:
+                secondary_match = row
+                break
+
+        if secondary_match:
+            add_flag(
+                "bank_non_primary_match",
+                field="bank_iban",
+                weight=Decimal("0.25"),
+                match_result="matched_non_primary",
+                invoice_value=invoice_iban,
+                master_value=getattr(secondary_match, "iban_canonical", None),
+                primary_or_non_primary="non_primary",
+            )
+
+    return {
+        "risk_flags": risk_flags,
+        "skipped_steps": skipped_steps,
+        "audit_entries": audit_entries,
+        "match_result": match_result,
+        "candidate_count": len(candidate_pool),
+        "primary_candidate_count": len(primary_rows),
+        "non_primary_candidate_count": len(non_primary_rows),
+    }

src/Invoice Validation Functions/Tax - ID validation.py

@@ -0,0 +1,556 @@
+import re
+from datetime import datetime, date, timezone
+from hashlib import sha256
+from unicodedata import normalize
+
+
+def _h_gb_vat_mod97(value, **_kw):
+    # UK VAT mod-97. Tries Method A then Method B (new-style) per HMRC spec.
+    # Value: 9 or 12 digits, GB prefix already stripped.
+    digits = re.sub(r"\D", "", value)
+    if len(digits) not in (9, 12):
+        return False
+    d = [int(c) for c in digits[:9]]
+    weights = [8, 7, 6, 5, 4, 3, 2]
+    s = sum(weights[i] * d[i] for i in range(7))
+    check = d[7] * 10 + d[8]
+    return (s - check) % 97 == 0 or (s + 55 - check) % 97 == 0
+
+
+def _h_de_vat_mod11(value, **_kw):
+    # German VAT recursive mod-11 check digit.
+    # Value: 9 digits, DE prefix already stripped.
+    digits = re.sub(r"\D", "", value)
+    if len(digits) != 9:
+        return False
+    product = 10
+    for c in digits[:8]:
+        s = (int(c) + product) % 10
+        if s == 0:
+            s = 10
+        product = (2 * s) % 11
+    check = 11 - product
+    if check == 10:
+        check = 0
+    return int(digits[8]) == check
+
+
+def _h_fr_vat_mod97(value, **_kw):
+    # French TVA key check.
+    # Value: 11 chars (FR prefix stripped): 2-char key + 9-digit SIREN.
+    # Numeric keys use the standard formula; alphanumeric keys use base-36 encoding.
+    if len(value) != 11:
+        return False
+    siren_str = value[2:]
+    if not siren_str.isdigit():
+        return False
+    siren = int(siren_str)
+    key = value[:2]
+    if key.isdigit():
+        return int(key) == (12 + 3 * (siren % 97)) % 97
+    def _char_val(c):
+        return int(c) if c.isdigit() else ord(c.upper()) - 55
+    k = _char_val(key[0]) * 36 + _char_val(key[1])
+    return k == (24 + 25 * (siren % 97)) % 97
+
+
+def _h_it_vat_luhn(value, **_kw):
+    # Italian Partita IVA Luhn-style check digit.
+    # Value: 11 digits, IT prefix already stripped.
+    digits = re.sub(r"\D", "", value)
+    if len(digits) != 11:
+        return False
+    odd_sum = sum(int(digits[i]) for i in range(0, 10, 2))
+    even_sum = 0
+    for i in range(1, 10, 2):
+        d = int(digits[i]) * 2
+        if d > 9:
+            d -= 9
+        even_sum += d
+    total = odd_sum + even_sum
+    return int(digits[10]) == (10 - total % 10) % 10
+
+
+def _h_es_nif(value, **_kw):
+    # Spanish NIF/CIF check character.
+    # Value: 9 chars (ES prefix stripped): [A-Z0-9][0-9]{7}[A-Z0-9].
+    if len(value) != 9:
+        return False
+    middle = value[1:8]
+    if not middle.isdigit():
+        return False
+    total = 0
+    for i, c in enumerate(middle):
+        d = int(c)
+        if i % 2 == 0:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    control = (10 - total % 10) % 10
+    check = value[8]
+    if check.isdigit():
+        return int(check) == control
+    return check.upper() == "JABCDEFGHI"[control]
+
+
+def _h_gstin_crc(value, **_kw):
+    # Indian GSTIN Luhn-mod36 check digit (official GSTN algorithm).
+    # Value: 15-char GSTIN (no prefix removed — GSTIN has no country prefix in its pattern).
+    if len(value) != 15:
+        return False
+    charset = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    total = 0
+    factor = 2
+    for c in value[:14]:
+        if c not in charset:
+            return False
+        pos = charset.index(c)
+        product = factor * pos
+        total += product // 36 + product % 36
+        factor = 3 - factor
+    check_pos = (36 - total % 36) % 36
+    return value[14] == charset[check_pos]
+
+
+def _h_abn_mod89(value, **_kw):
+    # Australian Business Number mod-89 weighted check.
+    # Value: 11 digits (no prefix removed).
+    digits = re.sub(r"\D", "", value)
+    if len(digits) != 11:
+        return False
+    weights = [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
+    d = [int(c) for c in digits]
+    d[0] -= 1
+    return sum(d[i] * weights[i] for i in range(11)) % 89 == 0
+
+
+def _h_bn_luhn(value, **_kw):
+    # Canadian Business Number Luhn check on the 9-digit registration number.
+    # The optional 6-char program account suffix (if present) is ignored.
+    nine = value[:9]
+    if len(nine) != 9 or not nine.isdigit():
+        return False
+    total = 0
+    for i in range(9):
+        d = int(nine[i])
+        if i % 2 == 1:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+    return total % 10 == 0
+
+
+def _h_sg_nric_fin(value, **_kw):
+    # Singapore NRIC/FIN check character.
+    # Value: 9 chars — [STFG][0-9]{7}[A-Z] (no prefix removed).
+    value = value.upper()
+    if len(value) != 9 or value[0] not in "STFG" or not value[1:8].isdigit():
+        return False
+    weights = [2, 7, 6, 5, 4, 3, 2]
+    total = sum(int(value[i + 1]) * weights[i] for i in range(7))
+    if value[0] in "TG":
+        total += 4
+    check_chars = "JZIHGFEDCBA" if value[0] in "ST" else "XWUTRQPNMLK"
+    return value[8] == check_chars[total % 11]
+
+
+_BUILTIN_CHECKSUM_HANDLERS = {
+    "gb_vat_mod97": _h_gb_vat_mod97,
+    "de_vat_mod11": _h_de_vat_mod11,
+    "fr_vat_mod97": _h_fr_vat_mod97,
+    "it_vat_luhn": _h_it_vat_luhn,
+    "es_nif": _h_es_nif,
+    "gstin_crc": _h_gstin_crc,
+    "abn_mod89": _h_abn_mod89,
+    "bn_luhn": _h_bn_luhn,
+    "sg_nric_fin": _h_sg_nric_fin,
+}
+
+
+def run_tax_id_validation(
+    *,
+    document,
+    extracted_fields,
+    vendor,
+    vendor_tax_ids,
+    resolved_vendor_id,
+    platform_configs=None,
+):
+    """
+    Runs Tax ID Validation after vendor resolution.
+
+    Expected document fields:
+        document.id
+        document.tenant_id
+
+    Expected extracted_fields fields:
+        sender_tax_id
+        invoice_date
+
+    Expected vendor fields:
+        vendor.id
+        vendor.billing_country
+        vendor.tax_registration_number
+
+    Expected vendor_tax_ids row fields:
+        tenant_id
+        vendor_id
+        tax_id_canonical
+        tax_id_type
+        verified_at
+        deleted_at
+        effective_from
+        effective_to
+    """
+
+    platform_configs = platform_configs or {}
+
+    tax_id_registry = platform_configs.get(
+        "validation.tax_id_family_registry",
+        {
+            "VAT-GB": {"pattern": r"^(GB)?[0-9]{9}([0-9]{3})?$", "checksum": "gb_vat_mod97"},
+            "VAT-DE": {"pattern": r"^(DE)?[0-9]{9}$", "checksum": "de_vat_mod11"},
+            "VAT-FR": {"pattern": r"^(FR)?[A-Z0-9]{2}[0-9]{9}$", "checksum": "fr_vat_mod97"},
+            "VAT-IT": {"pattern": r"^(IT)?[0-9]{11}$", "checksum": "it_vat_luhn"},
+            "VAT-ES": {"pattern": r"^(ES)?[A-Z0-9][0-9]{7}[A-Z0-9]$", "checksum": "es_nif"},
+            "VAT-NL": {"pattern": r"^(NL)?[0-9]{9}B[0-9]{2}$", "checksum": None},
+            "GSTIN-IN": {
+                "pattern": r"^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$",
+                "checksum": "gstin_crc",
+            },
+            "PAN-IN": {"pattern": r"^[A-Z]{5}[0-9]{4}[A-Z]$", "checksum": None},
+            "EIN-US": {"pattern": r"^[0-9]{2}-?[0-9]{7}$", "checksum": None},
+            "ABN-AU": {"pattern": r"^[0-9]{11}$", "checksum": "abn_mod89"},
+            "BN-CA": {"pattern": r"^[0-9]{9}([A-Z]{2}[0-9]{4})?$", "checksum": "bn_luhn"},
+            "TIN-SG": {"pattern": r"^(?:[STFG][0-9]{7}[A-Z]|[0-9]{9}[A-Z])$", "checksum": "sg_nric_fin"},
+        },
+    )
+
+    # Platform can override built-in handlers via validation.tax_id_checksum_handlers.
+    # Each handler: callable(value: str, tax_id_type: str | None, country_code: str | None) -> bool
+    checksum_handlers = platform_configs.get("validation.tax_id_checksum_handlers", _BUILTIN_CHECKSUM_HANDLERS)
+
+    def hash_prefix(value, length=8):
+        if not value:
+            return None
+        return sha256(str(value).encode("utf-8")).hexdigest()[:length]
+
+    def normalise_tax_id(value):
+        if value is None:
+            return None
+
+        value = normalize("NFKC", str(value))
+        value = re.sub(r"[\s\-\.,/\\:;_]+", "", value)
+        value = value.upper().strip()
+        return value or None
+
+    def country_from_tax_id_type(tax_id_type):
+        if not tax_id_type or "-" not in tax_id_type:
+            return None
+        return tax_id_type.split("-")[-1]
+
+    def registry_entries_for_country(country_code):
+        if not country_code:
+            return list(tax_id_registry.items())
+
+        country_code = str(country_code).upper()
+        return [
+            (tax_id_type, config)
+            for tax_id_type, config in tax_id_registry.items()
+            if country_from_tax_id_type(tax_id_type) == country_code
+        ]
+
+    def remove_country_prefix(value, tax_id_type):
+        country_code = country_from_tax_id_type(tax_id_type)
+        if country_code and value.startswith(country_code):
+            return value[len(country_code):]
+        return value
+
+    def checksum_valid(value, checksum_name, tax_id_type=None, country_code=None):
+        """
+        Real checksum gate:
+        - if checksum is not configured, treat as valid
+        - if a handler is provided by platform configs, use it
+        - otherwise fail closed (False) so invalid IDs do not silently pass
+        """
+        if checksum_name is None:
+            return True
+
+        handler = checksum_handlers.get(checksum_name)
+        if callable(handler):
+            return bool(handler(value, tax_id_type=tax_id_type, country_code=country_code))
+
+        return False
+
+    def canonicalise_tax_id(value, id_type=None, country_code=None):
+        stripped = normalise_tax_id(value)
+
+        if not stripped:
+            return {
+                "canonical": None,
+                "inferred_id_type": None,
+                "country_code": None,
+                "format_valid": None,
+                "checksum_valid": None,
+                "validation_passed": None,
+            }
+
+        resolved_id_type = None
+        registry_config = None
+
+        # Master path: direct lookup on (id_type, country_code).
+        if id_type:
+            resolved_id_type = id_type
+            registry_config = tax_id_registry.get(id_type)
+            # Cross-check: country embedded in id_type must match supplied country_code.
+            if registry_config and country_code:
+                embedded = country_from_tax_id_type(id_type)
+                if embedded and str(embedded).upper() != str(country_code).upper():
+                    registry_config = None
+
+        # Invoice path: infer by trying registry patterns for the supplied country.
+        else:
+            for candidate_id_type, candidate_config in registry_entries_for_country(country_code):
+                if re.match(candidate_config["pattern"], stripped):
+                    resolved_id_type = candidate_id_type
+                    registry_config = candidate_config
+                    break
+
+        # No registry entry matched: return stripped canonical value, no format/checksum enforcement.
+        if not registry_config:
+            return {
+                "canonical": stripped,
+                "inferred_id_type": None,
+                "country_code": None,
+                "format_valid": None,
+                "checksum_valid": None,
+                "validation_passed": None,
+            }
+
+        canonical = remove_country_prefix(stripped, resolved_id_type)
+        format_valid = bool(re.match(registry_config["pattern"], stripped))
+        checksum_ok = checksum_valid(
+            canonical,
+            registry_config.get("checksum"),
+            tax_id_type=resolved_id_type,
+            country_code=country_from_tax_id_type(resolved_id_type),
+        )
+
+        return {
+            "canonical": canonical,
+            "inferred_id_type": resolved_id_type,
+            "country_code": country_from_tax_id_type(resolved_id_type),
+            "format_valid": format_valid,
+            "checksum_valid": checksum_ok,
+            "validation_passed": bool(format_valid and checksum_ok),
+        }
+
+    def is_effective(row, invoice_date):
+        if getattr(row, "deleted_at", None) is not None:
+            return False
+
+        if invoice_date is None:
+            return False
+
+        effective_from = getattr(row, "effective_from", None)
+        effective_to = getattr(row, "effective_to", None)
+
+        if effective_from and invoice_date < effective_from:
+            return False
+
+        if effective_to and invoice_date >= effective_to:
+            return False
+
+        return True
+
+    risk_flags = []
+    advisory_flags = []
+    skipped_steps = []
+
+    if resolved_vendor_id is None:
+        skipped_steps.append(
+            {
+                "step": "tax_id_validation",
+                "skip_reason": "vendor_unresolved",
+            }
+        )
+        return {
+            "risk_flags": risk_flags,
+            "advisory_flags": advisory_flags,
+            "skipped_steps": skipped_steps,
+            "audit_payload": None,
+            "match_result": "skipped",
+        }
+
+    invoice_tax_id = getattr(extracted_fields, "sender_tax_id", None)
+    if not invoice_tax_id:
+        skipped_steps.append(
+            {
+                "step": "tax_id_validation",
+                "skip_reason": "no_invoice_tax_id",
+            }
+        )
+        return {
+            "risk_flags": risk_flags,
+            "advisory_flags": advisory_flags,
+            "skipped_steps": skipped_steps,
+            "audit_payload": None,
+            "match_result": "skipped",
+        }
+
+    invoice_date = getattr(extracted_fields, "invoice_date", None)
+    if isinstance(invoice_date, datetime):
+        invoice_date = invoice_date.date()
+    elif invoice_date is not None and not isinstance(invoice_date, date):
+        # Do not invent today's date; treat unknown types as unavailable.
+        invoice_date = None
+
+    vendor_country = getattr(vendor, "billing_country", None)
+
+    invoice_canonical_result = canonicalise_tax_id(
+        invoice_tax_id,
+        id_type=None,
+        country_code=vendor_country,
+    )
+
+    invoice_canonical = invoice_canonical_result["canonical"]
+    invoice_inferred_id_type = invoice_canonical_result["inferred_id_type"]
+    invoice_inferred_country = invoice_canonical_result["country_code"]
+
+    if not invoice_canonical:
+        skipped_steps.append({"step": "tax_id_validation", "skip_reason": "no_invoice_tax_id"})
+        return {
+            "risk_flags": risk_flags,
+            "advisory_flags": advisory_flags,
+            "skipped_steps": skipped_steps,
+            "audit_payload": None,
+            "match_result": "skipped",
+        }
+
+    candidate_rows_for_vendor = [
+        row
+        for row in vendor_tax_ids
+        if getattr(row, "tenant_id", None) == document.tenant_id
+        and getattr(row, "vendor_id", None) == resolved_vendor_id
+        and getattr(row, "deleted_at", None) is None
+    ]
+
+    effective_candidate_rows = [
+        row
+        for row in candidate_rows_for_vendor
+        if is_effective(row, invoice_date)
+    ]
+
+    matching_vendor_tax_row = None
+    for row in effective_candidate_rows:
+        if getattr(row, "tax_id_canonical", None) == invoice_canonical:
+            matching_vendor_tax_row = row
+            break
+
+    master_fallback_result = None
+    fallback_master_canonical = None
+
+    if not candidate_rows_for_vendor and getattr(vendor, "tax_registration_number", None):
+        master_fallback_result = canonicalise_tax_id(
+            vendor.tax_registration_number,
+            id_type=None,
+            country_code=vendor_country,
+        )
+        fallback_master_canonical = master_fallback_result["canonical"]
+
+    match_result = "unmatched"
+    master_hash_prefix = None
+    audit_id_type = invoice_inferred_id_type
+
+    if matching_vendor_tax_row:
+        match_result = "matched"
+        master_hash_prefix = hash_prefix(matching_vendor_tax_row.tax_id_canonical)
+        audit_id_type = getattr(matching_vendor_tax_row, "tax_id_type", None)
+
+        if getattr(matching_vendor_tax_row, "verified_at", None) is None:
+            advisory_flags.append(
+                {
+                    "code": "tax_id_unverified_master",
+                    "severity": "advisory",
+                    "vendor_id": resolved_vendor_id,
+                }
+            )
+
+        # Country mismatch only after a real successful match path.
+        if (
+            invoice_inferred_country
+            and vendor_country
+            and str(invoice_inferred_country).upper() != str(vendor_country).upper()
+        ):
+            risk_flags.append(
+                {
+                    "code": "tax_id_country_mismatch",
+                    "severity": "medium",
+                    "weight": 0.25,
+                    "invoice_country": invoice_inferred_country,
+                    "vendor_country": vendor_country,
+                }
+            )
+
+    elif not candidate_rows_for_vendor and fallback_master_canonical:
+        # Fallback only when there are no structured vendor_tax_ids rows at all.
+        master_hash_prefix = hash_prefix(fallback_master_canonical)
+
+        if invoice_canonical == fallback_master_canonical:
+            match_result = "matched_fallback"
+            if (
+                invoice_inferred_country
+                and vendor_country
+                and str(invoice_inferred_country).upper() != str(vendor_country).upper()
+            ):
+                risk_flags.append(
+                    {
+                        "code": "tax_id_country_mismatch",
+                        "severity": "medium",
+                        "weight": 0.25,
+                        "invoice_country": invoice_inferred_country,
+                        "vendor_country": vendor_country,
+                    }
+                )
+        else:
+            risk_flags.append(
+                {
+                    "code": "tax_id_mismatch",
+                    "severity": "high",
+                    "vendor_id": resolved_vendor_id,
+                }
+            )
+
+    else:
+        risk_flags.append(
+            {
+                "code": "tax_id_mismatch",
+                "severity": "high",
+                "vendor_id": resolved_vendor_id,
+            }
+        )
+
+    audit_payload = {
+        "document_id": document.id,
+        "vendor_id": resolved_vendor_id,
+        "match_result": match_result,
+        "invoice_hash_prefix": hash_prefix(invoice_canonical),
+        "master_hash_prefix": master_hash_prefix,
+        "id_type": audit_id_type,
+        "country_code": invoice_inferred_country or vendor_country,
+        "called_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    return {
+        "risk_flags": risk_flags,
+        "advisory_flags": advisory_flags,
+        "skipped_steps": skipped_steps,
+        "audit_payload": audit_payload,
+        "match_result": match_result,
+        "invoice_tax_id_canonical": invoice_canonical,
+        "invoice_tax_id_inferred_type": invoice_inferred_id_type,
+        "invoice_tax_id_format_valid": invoice_canonical_result.get("format_valid"),
+        "invoice_tax_id_checksum_valid": invoice_canonical_result.get("checksum_valid"),
+    }

src/Invoice Validation Functions/Vendor Validation.py

@@ -0,0 +1,385 @@
+from decimal import Decimal
+from hashlib import sha256
+from unicodedata import normalize
+from uuid import uuid4
+from datetime import datetime, timezone
+
+from rapidfuzz import fuzz, process
+
+
+def run_vendor_validation(
+    *,
+    document,
+    extracted_fields,
+    vendors,
+    platform_configs,
+    route_contexts=None,
+    actor_id=None,
+):
+    """
+    Runs Cat 2 vendor validation using RapidFuzz instead of the platform name-match algorithm.
+
+    Expected document fields:
+        document.id
+        document.tenant_id
+
+    Expected extracted_fields fields:
+        sender_name
+        sender_name_canonical
+        sender_tax_id_canonical
+        bank_iban_canonical
+
+    Expected vendor fields:
+        id
+        tenant_id
+        legal_name
+        vendor_name
+        legal_name_canonical
+        billing_country
+        billing_address
+        vendor_status
+        deleted_at
+
+    Returns a dict containing:
+        resolved_vendor_id
+        resolved_sender_name
+        resolved_sender_addr
+        risk_flags
+        advisory_flags
+        skipped_steps
+        audit_row
+        match_result
+    """
+
+    route_contexts = set(route_contexts or [])
+
+    require_high_tier_contexts = set(
+        platform_configs.get(
+            "validation.vendor_match_require_high_tier_contexts",
+            ["contract_match", "bank_validation", "approval_revalidation"],
+        )
+    )
+
+    algorithm_version = platform_configs.get(
+        "validation.name_match_algorithm_version",
+        "rapidfuzz.local.v1",
+    )
+
+    high_threshold = Decimal(str(platform_configs.get("validation.rapidfuzz_high_threshold", "0.90")))
+    medium_threshold = Decimal(str(platform_configs.get("validation.rapidfuzz_medium_threshold", "0.75")))
+    suggestion_threshold = Decimal(str(platform_configs.get("validation.rapidfuzz_suggestion_threshold", "0.60")))
+
+    def canonicalize(value):
+        if not value:
+            return ""
+        return normalize("NFKC", str(value)).lower().strip()
+
+    def hash_prefix(value, length=8):
+        if not value:
+            return None
+        return sha256(str(value).encode("utf-8")).hexdigest()[:length]
+
+    def get_vendor_names(vendor):
+        names = []
+
+        for name in (
+            getattr(vendor, "legal_name", None),
+            getattr(vendor, "vendor_name", None),
+        ):
+            canonical = canonicalize(name)
+            if canonical and canonical not in names:
+                names.append(canonical)
+
+        return names
+
+    def build_candidate_pool():
+        pool = []
+
+        for vendor in vendors:
+            if getattr(vendor, "tenant_id", None) != document.tenant_id:
+                continue
+
+            if getattr(vendor, "vendor_status", None) == "deleted":
+                continue
+
+            if getattr(vendor, "deleted_at", None) is not None:
+                continue
+
+            names = get_vendor_names(vendor)
+            if not names:
+                continue
+
+            pool.append(
+                {
+                    "record_id": vendor.id,
+                    "vendor": vendor,
+                    "names": names,
+                    "auxiliary": {
+                        "country": getattr(vendor, "billing_country", None),
+                        "tax_id_hash": hash_prefix(
+                            getattr(extracted_fields, "sender_tax_id_canonical", None)
+                        ),
+                        "iban_hash": hash_prefix(
+                            getattr(extracted_fields, "bank_iban_canonical", None)
+                        ),
+                    },
+                }
+            )
+
+        return pool
+
+    def rapidfuzz_name_match(query_name, candidate_pool):
+        choices = []
+
+        for candidate in candidate_pool:
+            for name in candidate["names"]:
+                choices.append(
+                    {
+                        "name": name,
+                        "record_id": candidate["record_id"],
+                        "vendor": candidate["vendor"],
+                    }
+                )
+
+        if not query_name or not choices:
+            return {
+                "decision": "unmatched",
+                "matched_record_id": None,
+                "matched_vendor": None,
+                "runner_up_record_id": None,
+                "runner_up_vendor": None,
+                "score": Decimal("0"),
+                "score_tier": "low",
+                "algorithm_version": algorithm_version,
+                "trace_id": str(uuid4()),
+            }
+
+        raw_matches = process.extract(
+            query_name,
+            [choice["name"] for choice in choices],
+            scorer=fuzz.WRatio,
+            limit=5,
+        )
+
+        ranked = []
+        seen_record_ids = set()
+
+        for matched_name, score, choice_index in raw_matches:
+            choice = choices[choice_index]
+            record_id = choice["record_id"]
+
+            if record_id in seen_record_ids:
+                continue
+
+            seen_record_ids.add(record_id)
+
+            ranked.append(
+                {
+                    "record_id": record_id,
+                    "vendor": choice["vendor"],
+                    "matched_name": matched_name,
+                    "score": Decimal(str(score / 100)).quantize(Decimal("0.0001")),
+                }
+            )
+
+        if not ranked:
+            best = None
+            runner_up = None
+            score = Decimal("0")
+        else:
+            best = ranked[0]
+            runner_up = ranked[1] if len(ranked) > 1 else None
+            score = best["score"]
+
+        if score >= high_threshold:
+            decision = "matched"
+            score_tier = "high"
+            matched_record_id = best["record_id"]
+            matched_vendor = best["vendor"]
+        elif score >= medium_threshold:
+            decision = "matched"
+            score_tier = "medium"
+            matched_record_id = best["record_id"]
+            matched_vendor = best["vendor"]
+        elif score >= suggestion_threshold:
+            decision = "suggestion"
+            score_tier = "low"
+            matched_record_id = None
+            matched_vendor = None
+        else:
+            decision = "unmatched"
+            score_tier = "low"
+            matched_record_id = None
+            matched_vendor = None
+
+        return {
+            "decision": decision,
+            "matched_record_id": matched_record_id,
+            "matched_vendor": matched_vendor,
+            "runner_up_record_id": runner_up["record_id"] if runner_up else (
+                best["record_id"] if decision == "suggestion" and best else None
+            ),
+            "runner_up_vendor": runner_up["vendor"] if runner_up else (
+                best["vendor"] if decision == "suggestion" and best else None
+            ),
+            "score": score,
+            "score_tier": score_tier,
+            "algorithm_version": algorithm_version,
+            "trace_id": str(uuid4()),
+        }
+
+    risk_flags = []
+    advisory_flags = []
+    skipped_steps = []
+
+    resolved_vendor_id = None
+    resolved_sender_name = None
+    resolved_sender_addr = None
+
+    query_name = canonicalize(
+        getattr(extracted_fields, "sender_name_canonical", None)
+        or getattr(extracted_fields, "sender_name", None)
+    )
+
+    candidate_pool = build_candidate_pool()
+
+    match_result = rapidfuzz_name_match(
+        query_name=query_name,
+        candidate_pool=candidate_pool,
+    )
+
+    decision = match_result["decision"]
+    score_tier = match_result["score_tier"]
+
+    control_context_requires_high = bool(route_contexts & require_high_tier_contexts)
+
+    if decision == "matched" and score_tier == "high":
+        resolved_vendor_id = match_result["matched_record_id"]
+
+    elif decision == "matched" and score_tier == "medium":
+        if control_context_requires_high:
+            match_result["decision"] = "suggestion"
+            advisory_flags.append(
+                {
+                    "code": "vendor_suggestion",
+                    "severity": "advisory",
+                    "record_id": match_result["matched_record_id"],
+                    "reason": "medium_tier_match_downgraded_for_control_context",
+                }
+            )
+            skipped_steps.extend(
+                [
+                    {"step": "vendor_tax_validation", "skip_reason": "vendor_unresolved"},
+                    {"step": "vendor_bank_validation", "skip_reason": "vendor_unresolved"},
+                    {"step": "vendor_status_validation", "skip_reason": "vendor_unresolved"},
+                ]
+            )
+        else:
+            resolved_vendor_id = match_result["matched_record_id"]
+            risk_flags.append(
+                {
+                    "code": "low_confidence_vendor_resolution",
+                    "severity": "medium",
+                    "record_id": resolved_vendor_id,
+                    "score_tier": score_tier,
+                }
+            )
+
+    elif decision == "suggestion":
+        advisory_flags.append(
+            {
+                "code": "vendor_suggestion",
+                "severity": "advisory",
+                "record_id": match_result["runner_up_record_id"],
+                "reason": "possible_vendor_match",
+            }
+        )
+        skipped_steps.extend(
+            [
+                {"step": "sender_field_override", "skip_reason": "vendor_unresolved"},
+                {"step": "vendor_tax_validation", "skip_reason": "vendor_unresolved"},
+                {"step": "vendor_bank_validation", "skip_reason": "vendor_unresolved"},
+                {"step": "vendor_status_validation", "skip_reason": "vendor_unresolved"},
+            ]
+        )
+
+    else:
+        risk_flags.append(
+            {
+                "code": "unknown_vendor",
+                "severity": "high",
+                "reason": "no_vendor_match_found",
+            }
+        )
+        skipped_steps.extend(
+            [
+                {"step": "sender_field_override", "skip_reason": "vendor_unresolved"},
+                {"step": "vendor_tax_validation", "skip_reason": "vendor_unresolved"},
+                {"step": "vendor_bank_validation", "skip_reason": "vendor_unresolved"},
+                {"step": "vendor_status_validation", "skip_reason": "vendor_unresolved"},
+            ]
+        )
+
+    blocked_vendor = None
+
+    if match_result["decision"] in ("matched", "suggestion"):
+        if match_result.get("matched_vendor") and match_result["matched_vendor"].vendor_status == "blocked":
+            blocked_vendor = match_result["matched_vendor"]
+
+        if match_result.get("runner_up_vendor") and match_result["runner_up_vendor"].vendor_status == "blocked":
+            blocked_vendor = match_result["runner_up_vendor"]
+
+    if blocked_vendor:
+        risk_flags.append(
+            {
+                "code": "vendor_blocked",
+                "severity": "high",
+                "record_id": blocked_vendor.id,
+                "reason": "matched_or_suggested_vendor_is_blocked",
+            }
+        )
+
+    if resolved_vendor_id:
+        resolved_vendor = match_result["matched_vendor"]
+
+        resolved_sender_name = (
+            getattr(resolved_vendor, "legal_name", None)
+            or getattr(resolved_vendor, "vendor_name", None)
+        )
+
+        billing_address = getattr(resolved_vendor, "billing_address", None)
+        if billing_address is not None:
+            resolved_sender_addr = billing_address
+
+    audit_row = {
+        "document_id": document.id,
+        "query_name_hash_prefix_8": hash_prefix(query_name, length=8),
+        "algorithm_version": algorithm_version,
+        "decision": match_result["decision"],
+        "matched_record_id": match_result["matched_record_id"],
+        "runner_up_record_id": match_result["runner_up_record_id"],
+        "score_tier": match_result["score_tier"],
+        "score": str(match_result["score"]),
+        "trace_id": match_result["trace_id"],
+        "called_at": datetime.now(timezone.utc),
+        "actor_id": actor_id,
+    }
+
+    return {
+        "resolved_vendor_id": resolved_vendor_id,
+        "resolved_sender_name": resolved_sender_name,
+        "resolved_sender_addr": resolved_sender_addr,
+        "risk_flags": risk_flags,
+        "advisory_flags": advisory_flags,
+        "skipped_steps": skipped_steps,
+        "audit_row": audit_row,
+        "match_result": {
+            "decision": match_result["decision"],
+            "matched_record_id": resolved_vendor_id,
+            "runner_up_record_id": match_result["runner_up_record_id"],
+            "score": match_result["score"],
+            "score_tier": match_result["score_tier"],
+            "algorithm_version": match_result["algorithm_version"],
+            "trace_id": match_result["trace_id"],
+        },
+    }

src/Invoice Validation Functions/completeness.py

@@ -0,0 +1,169 @@
+
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+
+
+def parse_date(value):
+    if value in (None, ""):
+        return None
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    try:
+        return datetime.strptime(str(value), "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+def parse_decimal(value):
+    if value in (None, ""):
+        return None
+    if isinstance(value, Decimal):
+        return value
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, ValueError):
+        return None
+
+
+def run_invoice_validation(*, document, extracted_fields, line_items, currency_seed_map, platform_configs=None):
+    """
+    Business validation logic for:
+      7.7.1 Required fields + due-date derivation path
+      7.7.2 Currency membership
+      7.7.3 Math cross-check with currency-aware tolerance
+    """
+    platform_configs = platform_configs or {}
+
+    cap_minor_units = int(
+        platform_configs.get("validation.solver_tolerance.cap_minor_units", 0)
+    )
+    base_per_minor_unit = int(
+        platform_configs.get("validation.solver_tolerance.base_per_minor_unit", 0)
+    )
+    per_line_minor_units = int(
+        platform_configs.get("validation.solver_tolerance.per_line_minor_units", 0)
+    )
+
+    risk_flags = []
+    skipped_steps = []
+
+    def add_flag(code, *, weight, detail=None):
+        risk_flags.append(
+            {
+                "code": code,
+                "severity": "advisory",
+                "weight": weight,
+                "detail": detail or {},
+            }
+        )
+
+    invoice_no = getattr(extracted_fields, "invoice_no", None)
+    invoice_date = parse_date(getattr(extracted_fields, "invoice_date", None))
+    total_amount = parse_decimal(getattr(extracted_fields, "total_amount", None))
+    subtotal = parse_decimal(getattr(extracted_fields, "subtotal", None))
+    sender_name = getattr(extracted_fields, "sender_name", None)
+    currency = getattr(extracted_fields, "currency", None)
+    due_date = parse_date(getattr(extracted_fields, "due_date", None))
+    payment_terms = getattr(extracted_fields, "payment_terms", None)
+
+    missing_fields = []
+
+    def mark_missing(field_name):
+        if field_name not in missing_fields:
+            missing_fields.append(field_name)
+
+    if not invoice_no:
+        mark_missing("invoice_no")
+    if invoice_date is None:
+        mark_missing("invoice_date")
+    if total_amount is None:
+        mark_missing("total_amount")
+    if not sender_name:
+        mark_missing("sender_name")
+    if not currency:
+        mark_missing("currency")
+
+    due_date_derivable = invoice_date is not None and payment_terms not in (None, "")
+    if due_date is None and not due_date_derivable:
+        mark_missing("due_date")
+        if invoice_date is None:
+            mark_missing("invoice_date")
+        if payment_terms in (None, ""):
+            mark_missing("payment_terms")
+
+    if missing_fields:
+        add_flag(
+            "incomplete_fields",
+            weight=0.25,
+            detail={"missing_fields": missing_fields},
+        )
+
+    currency_key = str(currency).strip().upper() if currency not in (None, "") else None
+    currency_row = currency_seed_map.get(currency_key) if currency_key else None
+
+    if currency_row is None:
+        add_flag(
+            "invalid_currency",
+            weight=0.20,
+            detail={
+                "currency": currency,
+                "reason": "currency_missing_or_not_in_iso_currencies_seed",
+            },
+        )
+
+    line_amounts = []
+    for li in line_items:
+        amount = parse_decimal(getattr(li, "amount", None))
+        if amount is not None:
+            line_amounts.append(amount)
+
+    num_line_items = len(line_amounts)
+    math_ran = False
+
+    if subtotal is not None and num_line_items > 0:
+        if currency_row is None:
+            skipped_steps.append(
+                {"step": "math_cross_check", "skip_reason": "currency_minor_unit_unknown"}
+            )
+        else:
+            minor_unit_value = parse_decimal(currency_row.get("minor_unit_value"))
+            if minor_unit_value is None:
+                skipped_steps.append(
+                    {"step": "math_cross_check", "skip_reason": "minor_unit_value_missing_in_seed"}
+                )
+            else:
+                math_ran = True
+                line_sum = sum(line_amounts, Decimal("0"))
+                tolerance_minor_units = min(
+                    cap_minor_units,
+                    base_per_minor_unit + per_line_minor_units * num_line_items,
+                )
+                tolerance_decimal = Decimal(tolerance_minor_units) * minor_unit_value
+                difference = abs(line_sum - subtotal)
+
+                if difference > tolerance_decimal:
+                    add_flag(
+                        "math_error_line_items",
+                        weight=0.20,
+                        detail={
+                            "subtotal": str(subtotal),
+                            "line_items_sum": str(line_sum),
+                            "difference": str(difference),
+                            "tolerance_minor_units": tolerance_minor_units,
+                            "tolerance_decimal": str(tolerance_decimal),
+                            "currency": currency_key,
+                            "minor_unit_value": str(minor_unit_value),
+                            "num_line_items": num_line_items,
+                        },
+                    )
+
+    return {
+        "risk_flags": risk_flags,
+        "skipped_steps": skipped_steps,
+        "result": "flagged" if risk_flags else "clean",
+        "missing_fields": missing_fields,
+        "currency_checked": currency_row is not None,
+        "math_checked": math_ran,
+    }

src/Invoice Validation Functions/date_sanity.py

@@ -0,0 +1,219 @@
+from datetime import date, datetime, timedelta
+from zoneinfo import ZoneInfo
+
+
+def run_date_sanity_checks(
+    *,
+    document,
+    extracted_fields,
+    platform_configs=None,
+):
+    """
+    Runs Date Sanity Checks after date normalisation.
+
+    Expected document fields:
+        document.id
+        document.tenant_id
+        Optional: document.tenant_timezone
+
+    Expected extracted_fields fields:
+        invoice_date
+        due_date
+        due_date_origin
+        payment_terms
+        service_start_date
+        service_end_date
+
+    Returns:
+        dict with advisory risk flags and audit-friendly result.
+    """
+
+    platform_configs = platform_configs or {}
+
+    default_timezone = platform_configs.get(
+        "validation.default_timezone",
+        getattr(document, "tenant_timezone", "UTC") or "UTC",
+    )
+
+    max_invoice_age_days = int(
+        platform_configs.get("validation.max_invoice_age_days", 365)
+    )
+
+    max_invoice_age_days = max(30, min(max_invoice_age_days, 1825))
+
+    service_end_grace_days = int(
+        platform_configs.get("validation.service_end_post_invoice_grace_days", 0)
+    )
+
+    def as_date(value):
+        if value is None or value == "":
+            return None
+
+        if isinstance(value, datetime):
+            return value.date()
+
+        if isinstance(value, date):
+            return value
+
+        return datetime.strptime(str(value), "%Y-%m-%d").date()
+
+    def as_int(value):
+        if value is None or value == "":
+            return None
+        try:
+            return int(value)
+        except (ValueError, TypeError):
+            return None
+
+    def tenant_current_date():
+        try:
+            return datetime.now(ZoneInfo(default_timezone)).date()
+        except Exception:
+            return datetime.now(ZoneInfo("UTC")).date()
+
+    def add_flag(code, *, weight, field, detail=None):
+        risk_flags.append(
+            {
+                "code": code,
+                "severity": "advisory",
+                "weight": weight,
+                "field": field,
+                "detail": detail or {},
+            }
+        )
+
+    risk_flags = []
+    skipped_steps = []
+
+    invoice_date = as_date(getattr(extracted_fields, "invoice_date", None))
+    due_date = as_date(getattr(extracted_fields, "due_date", None))
+    service_start_date = as_date(getattr(extracted_fields, "service_start_date", None))
+    service_end_date = as_date(getattr(extracted_fields, "service_end_date", None))
+    due_date_origin = getattr(extracted_fields, "due_date_origin", None)
+    payment_terms = as_int(getattr(extracted_fields, "payment_terms", None))
+
+    current_date = tenant_current_date()
+
+    # 1. Payment terms must be non-negative.
+    # Zero is allowed: due-on-receipt.
+    if payment_terms is not None and payment_terms < 0:
+        add_flag(
+            "date_anomaly_payment_terms_negative",
+            weight=0.20,
+            field="payment_terms",
+            detail={
+                "payment_terms": payment_terms,
+            },
+        )
+
+    # 2. Due date must be on or after invoice date.
+    if invoice_date is not None and due_date is not None:
+        if due_date < invoice_date:
+            add_flag(
+                "date_anomaly_due_before_invoice",
+                weight=0.20,
+                field="due_date",
+                detail={
+                    "invoice_date": str(invoice_date),
+                    "due_date": str(due_date),
+                },
+            )
+
+    if invoice_date is None:
+        skipped_steps.extend([
+            {"step": "date_anomaly_invoice_future_dated", "skip_reason": "no_invoice_date"},
+            {"step": "date_anomaly_invoice_too_old", "skip_reason": "no_invoice_date"},
+        ])
+
+    # 3. Invoice must not be future-dated.
+    if invoice_date is not None and invoice_date > current_date:
+        add_flag(
+            "date_anomaly_invoice_future_dated",
+            weight=0.20,
+            field="invoice_date",
+            detail={
+                "invoice_date": str(invoice_date),
+                "current_date": str(current_date),
+                "timezone": default_timezone,
+            },
+        )
+
+    # 4. Invoice must not be too old.
+    if invoice_date is not None:
+        oldest_allowed_date = current_date - timedelta(days=max_invoice_age_days)
+
+        if invoice_date < oldest_allowed_date:
+            add_flag(
+                "date_anomaly_invoice_too_old",
+                weight=0.15,
+                field="invoice_date",
+                detail={
+                    "invoice_date": str(invoice_date),
+                    "oldest_allowed_date": str(oldest_allowed_date),
+                    "max_invoice_age_days": max_invoice_age_days,
+                },
+            )
+
+    # 5. Service period must not be reversed.
+    if service_start_date is not None and service_end_date is not None:
+        if service_end_date < service_start_date:
+            add_flag(
+                "date_anomaly_service_period_reversed",
+                weight=0.15,
+                field="service_end_date",
+                detail={
+                    "service_start_date": str(service_start_date),
+                    "service_end_date": str(service_end_date),
+                },
+            )
+
+    # 6. Service end must not be too far after invoice date.
+    if service_end_date is not None:
+        if invoice_date is None:
+            skipped_steps.append(
+                {"step": "date_anomaly_service_end_after_invoice", "skip_reason": "no_invoice_date"}
+            )
+        else:
+            allowed_service_end = invoice_date + timedelta(days=service_end_grace_days)
+
+            if service_end_date > allowed_service_end:
+                add_flag(
+                    "date_anomaly_service_end_after_invoice",
+                    weight=0.15,
+                    field="service_end_date",
+                    detail={
+                        "invoice_date": str(invoice_date),
+                        "service_end_date": str(service_end_date),
+                        "allowed_service_end": str(allowed_service_end),
+                        "grace_days": service_end_grace_days,
+                    },
+                )
+
+    # 7. Due date could not be derived.
+    if due_date is None and due_date_origin == "unknown":
+        add_flag(
+            "due_date_not_derivable",
+            weight=0.10,
+            field="due_date",
+            detail={
+                "due_date_origin": due_date_origin,
+            },
+        )
+
+    return {
+        "risk_flags": risk_flags,
+        "skipped_steps": skipped_steps,
+        "flag_codes": [flag["code"] for flag in risk_flags],
+        "checked_fields": {
+            "invoice_date": str(invoice_date) if invoice_date else None,
+            "due_date": str(due_date) if due_date else None,
+            "due_date_origin": due_date_origin,
+            "payment_terms": payment_terms,
+            "service_start_date": str(service_start_date) if service_start_date else None,
+            "service_end_date": str(service_end_date) if service_end_date else None,
+            "current_date": str(current_date),
+            "timezone": default_timezone,
+            "max_invoice_age_days": max_invoice_age_days,
+            "service_end_post_invoice_grace_days": service_end_grace_days,
+        },
+    }

src/Invoice Validation Functions/orchestrator.py

@@ -0,0 +1,282 @@
+"""
+Invoice validation orchestrator.
+
+Loads platform_configs.json once, runs all seven validators in SDD order,
+wires outputs to downstream inputs, and returns a single consolidated result.
+
+No business logic lives here — all decisions remain inside the validator modules.
+"""
+
+import importlib.util
+import json
+import os
+
+
+# ---------------------------------------------------------------------------
+# Module loader — handles filenames that contain spaces or hyphens
+# ---------------------------------------------------------------------------
+
+def _load_fn(filename, fn_name):
+    """Import a function from a .py file by path."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    path = os.path.join(here, filename)
+    spec = importlib.util.spec_from_file_location(filename, path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return getattr(mod, fn_name)
+
+
+_run_vendor_validation        = _load_fn("Vendor Validation.py",         "run_vendor_validation")
+_run_tax_id_validation        = _load_fn("Tax - ID validation.py",        "run_tax_id_validation")
+_run_bank_validation          = _load_fn("Bank validation.py",            "run_bank_validation")
+_run_date_sanity_checks       = _load_fn("date_sanity.py",                "run_date_sanity_checks")
+_run_payment_terms_validation = _load_fn("payment terms valdiation.py",   "run_payment_terms_validation")
+_run_tax_amount_validation    = _load_fn("tax validation.py",             "run_tax_amount_validation")
+_run_completeness_validation  = _load_fn("completeness.py",               "run_invoice_validation")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+class _FieldProxy:
+    """
+    Overlays computed attributes onto an existing extracted_fields object so
+    downstream validators can read Tax-ID results via the normal
+    getattr(extracted_fields, ...) pattern without mutating the original object.
+
+    Only non-None values are overlaid; None values fall through to the base
+    object (and its getattr default), which preserves the lenient defaults each
+    validator defines for fields it cannot always receive.
+    """
+    __slots__ = ("_base", "_overlay")
+
+    def __init__(self, base, **overlay):
+        object.__setattr__(self, "_base", base)
+        object.__setattr__(self, "_overlay", {k: v for k, v in overlay.items() if v is not None})
+
+    def __getattr__(self, name):
+        overlay = object.__getattribute__(self, "_overlay")
+        if name in overlay:
+            return overlay[name]
+        return getattr(object.__getattribute__(self, "_base"), name)
+
+
+def _load_platform_configs(path=None):
+    if path is None:
+        here = os.path.dirname(os.path.abspath(__file__))
+        path = os.path.join(here, "platform_configs.json")
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _collect(result, key):
+    """Safely pull a list from a module result dict (returns [] if absent)."""
+    return result.get(key) or []
+
+
+# ---------------------------------------------------------------------------
+# Pipeline
+# ---------------------------------------------------------------------------
+
+def run_invoice_validation_pipeline(
+    *,
+    document,
+    extracted_fields,
+    vendors,
+    vendor_bank_accounts,
+    vendor_tax_ids,
+    entity,
+    line_items,
+    purchase_orders,
+    contracts,
+    tax_master_rows,
+    currency_seed_map,
+    platform_configs=None,
+    route_contexts=None,
+    actor_id=None,
+):
+    """
+    Run all seven validation modules in SDD order and return a consolidated result.
+
+    Parameters
+    ----------
+    document              : Invoice document object (needs .id, .tenant_id, .entity_id).
+    extracted_fields      : VLM-extracted fields object.
+    vendors               : Iterable of vendor records used for vendor matching.
+    vendor_bank_accounts  : Iterable of vendor bank account records.
+    vendor_tax_ids        : Iterable of vendor tax-ID records.
+    entity                : The routing entity object (needs .country_code, .vat_id, .region_code).
+    line_items            : Iterable of line-item records.
+    purchase_orders       : Iterable of purchase-order records.
+    contracts             : Iterable of contract records.
+    tax_master_rows       : Iterable of tax-master records.
+    currency_seed_map     : Dict mapping ISO currency code → row with minor_unit_value.
+    platform_configs      : Pre-loaded config dict; loaded from platform_configs.json when None.
+    route_contexts        : List of route-context strings forwarded to Vendor Validation.
+    actor_id              : Actor identifier forwarded to Vendor Validation for audit.
+
+    Returns
+    -------
+    {
+        "risk_flags":         [...],  # aggregated, in execution order
+        "advisory_flags":     [...],  # aggregated, in execution order
+        "skipped_steps":      [...],  # aggregated, in execution order
+        "ops_alerts":         [...],  # operational alerts (e.g. tax_master_unconfigured)
+        "resolved_vendor_id": ...,
+        "module_results":     {...},  # raw return dict from each module, keyed by name
+    }
+    """
+
+    if platform_configs is None:
+        platform_configs = _load_platform_configs()
+
+    risk_flags     = []
+    advisory_flags = []
+    skipped_steps  = []
+    ops_alerts     = []
+    module_results = {}
+
+    # ------------------------------------------------------------------
+    # Step 1 — Vendor Validation
+    # Runs first; produces resolved_vendor_id used by all downstream steps.
+    # ------------------------------------------------------------------
+    vendor_result = _run_vendor_validation(
+        document=document,
+        extracted_fields=extracted_fields,
+        vendors=vendors,
+        platform_configs=platform_configs,
+        route_contexts=route_contexts,
+        actor_id=actor_id,
+    )
+    module_results["vendor_validation"] = vendor_result
+    risk_flags.extend(_collect(vendor_result, "risk_flags"))
+    advisory_flags.extend(_collect(vendor_result, "advisory_flags"))
+    skipped_steps.extend(_collect(vendor_result, "skipped_steps"))
+
+    resolved_vendor_id = vendor_result.get("resolved_vendor_id")
+
+    # Resolve the vendor object so downstream modules receive it directly.
+    resolved_vendor = next(
+        (v for v in vendors if getattr(v, "id", None) == resolved_vendor_id),
+        None,
+    ) if resolved_vendor_id else None
+
+    # ------------------------------------------------------------------
+    # Step 2 — Tax ID Validation
+    # Depends on resolved_vendor_id and the resolved vendor object.
+    # ------------------------------------------------------------------
+    tax_id_result = _run_tax_id_validation(
+        document=document,
+        extracted_fields=extracted_fields,
+        vendor=resolved_vendor,
+        vendor_tax_ids=vendor_tax_ids,
+        resolved_vendor_id=resolved_vendor_id,
+        platform_configs=platform_configs,
+    )
+    module_results["tax_id_validation"] = tax_id_result
+    risk_flags.extend(_collect(tax_id_result, "risk_flags"))
+    advisory_flags.extend(_collect(tax_id_result, "advisory_flags"))
+    skipped_steps.extend(_collect(tax_id_result, "skipped_steps"))
+
+    # Enrich extracted_fields with Tax-ID results so Tax Validation can read
+    # sender_tax_id_inferred_family / _format_valid / _checksum_valid via its
+    # normal getattr(extracted_fields, ...) pattern.
+    enriched_fields = _FieldProxy(
+        extracted_fields,
+        sender_tax_id_inferred_family=tax_id_result.get("invoice_tax_id_inferred_type"),
+        sender_tax_id_format_valid=tax_id_result.get("invoice_tax_id_format_valid"),
+        sender_tax_id_checksum_valid=tax_id_result.get("invoice_tax_id_checksum_valid"),
+    )
+
+    # ------------------------------------------------------------------
+    # Step 3 — Bank Validation
+    # Depends on resolved_vendor_id.
+    # ------------------------------------------------------------------
+    bank_result = _run_bank_validation(
+        document=document,
+        extracted_fields=extracted_fields,
+        vendor_bank_accounts=vendor_bank_accounts,
+        resolved_vendor_id=resolved_vendor_id,
+        platform_configs=platform_configs,
+    )
+    module_results["bank_validation"] = bank_result
+    risk_flags.extend(_collect(bank_result, "risk_flags"))
+    advisory_flags.extend(_collect(bank_result, "advisory_flags"))
+    skipped_steps.extend(_collect(bank_result, "skipped_steps"))
+
+    # ------------------------------------------------------------------
+    # Step 4 — Date Sanity Checks
+    # Independent of vendor resolution.
+    # ------------------------------------------------------------------
+    date_result = _run_date_sanity_checks(
+        document=document,
+        extracted_fields=extracted_fields,
+        platform_configs=platform_configs,
+    )
+    module_results["date_sanity"] = date_result
+    risk_flags.extend(_collect(date_result, "risk_flags"))
+    advisory_flags.extend(_collect(date_result, "advisory_flags"))
+    skipped_steps.extend(_collect(date_result, "skipped_steps"))
+
+    # ------------------------------------------------------------------
+    # Step 5 — Payment Terms Validation
+    # Depends on resolved_vendor_id and the resolved vendor object.
+    # ------------------------------------------------------------------
+    payment_terms_result = _run_payment_terms_validation(
+        document=document,
+        extracted_fields=extracted_fields,
+        vendor=resolved_vendor,
+        purchase_orders=purchase_orders,
+        contracts=contracts,
+        resolved_vendor_id=resolved_vendor_id,
+        platform_configs=platform_configs,
+    )
+    module_results["payment_terms_validation"] = payment_terms_result
+    risk_flags.extend(_collect(payment_terms_result, "risk_flags"))
+    advisory_flags.extend(_collect(payment_terms_result, "advisory_flags"))
+    skipped_steps.extend(_collect(payment_terms_result, "skipped_steps"))
+
+    # ------------------------------------------------------------------
+    # Step 6 — Tax Amount Validation
+    # Depends on resolved vendor object and enriched_fields from Step 2.
+    # ------------------------------------------------------------------
+    tax_result = _run_tax_amount_validation(
+        document=document,
+        extracted_fields=enriched_fields,
+        line_items=line_items,
+        vendor=resolved_vendor,
+        entity=entity,
+        tax_master_rows=tax_master_rows,
+        platform_configs=platform_configs,
+    )
+    module_results["tax_validation"] = tax_result
+    risk_flags.extend(_collect(tax_result, "risk_flags"))
+    advisory_flags.extend(_collect(tax_result, "advisory_flags"))
+    skipped_steps.extend(_collect(tax_result, "skipped_checks"))   # tax validation uses "skipped_checks"
+    ops_alerts.extend(_collect(tax_result, "ops_alerts"))
+
+    # ------------------------------------------------------------------
+    # Step 7 — Completeness / Math Cross-check
+    # Independent of vendor resolution.
+    # ------------------------------------------------------------------
+    completeness_result = _run_completeness_validation(
+        document=document,
+        extracted_fields=extracted_fields,
+        line_items=line_items,
+        currency_seed_map=currency_seed_map,
+        platform_configs=platform_configs,
+    )
+    module_results["completeness"] = completeness_result
+    risk_flags.extend(_collect(completeness_result, "risk_flags"))
+    advisory_flags.extend(_collect(completeness_result, "advisory_flags"))
+    skipped_steps.extend(_collect(completeness_result, "skipped_steps"))
+
+    return {
+        "risk_flags": risk_flags,
+        "advisory_flags": advisory_flags,
+        "skipped_steps": skipped_steps,
+        "ops_alerts": ops_alerts,
+        "resolved_vendor_id": resolved_vendor_id,
+        "module_results": module_results,
+    }

src/Invoice Validation Functions/payment terms valdiation.py

@@ -0,0 +1,264 @@
+from datetime import date, datetime
+
+
+def run_payment_terms_validation(
+    *,
+    document,
+    extracted_fields,
+    vendor,
+    purchase_orders,
+    contracts,
+    resolved_vendor_id,
+    platform_configs=None,
+):
+    """
+    Payment Terms Validation.
+
+    Expected document fields:
+        document.id
+        document.tenant_id
+        document.entity_id
+
+    Expected extracted_fields fields:
+        payment_terms
+        po_number_canonical
+        invoice_date
+
+    Expected vendor fields:
+        vendor.id
+        vendor.payment_terms
+
+    Expected purchase_orders fields:
+        tenant_id
+        po_number_canonical
+        payment_terms
+        deleted_at
+
+    Expected contract fields:
+        tenant_id
+        vendor_id
+        entity_id
+        status
+        payment_terms
+        effective_from
+        effective_to
+        deleted_at
+
+    Returns:
+        dict with advisory flags, skipped status, and resolution detail.
+    """
+
+    platform_configs = platform_configs or {}
+
+    tolerance_days = int(
+        platform_configs.get("validation.payment_terms_tolerance_days", 0)
+    )
+
+    def as_int(value):
+        if value is None or value == "":
+            return None
+        try:
+            return int(value)
+        except (ValueError, TypeError):
+            return None
+
+    def as_date(value):
+        if value is None or value == "":
+            return None
+
+        if isinstance(value, datetime):
+            return value.date()
+
+        if isinstance(value, date):
+            return value
+
+        return datetime.strptime(str(value), "%Y-%m-%d").date()
+
+    def add_flag(code, *, weight, detail=None):
+        risk_flags.append(
+            {
+                "code": code,
+                "severity": "advisory",
+                "weight": weight,
+                "detail": detail or {},
+            }
+        )
+
+    def po_terms_tier():
+        po_number = getattr(extracted_fields, "po_number_canonical", None)
+
+        if not po_number:
+            return None
+
+        matching_pos = [
+            po
+            for po in purchase_orders
+            if po.tenant_id == document.tenant_id
+            and po.po_number_canonical == po_number
+            and getattr(po, "deleted_at", None) is None
+            and as_int(getattr(po, "payment_terms", None)) is not None
+        ]
+
+        if len(matching_pos) >= 1:
+            return {
+                "tier": "purchase_order",
+                "expected_payment_terms": as_int(matching_pos[0].payment_terms),
+                "source_id": getattr(matching_pos[0], "id", None),
+            }
+
+        return None
+
+    def contract_terms_tier():
+        invoice_date = as_date(getattr(extracted_fields, "invoice_date", None))
+
+        if not invoice_date:
+            skipped_steps.append(
+                {"step": "contract_payment_terms", "skip_reason": "no_invoice_date"}
+            )
+            return None
+
+        matching_contracts = []
+
+        for contract in contracts:
+            if contract.tenant_id != document.tenant_id:
+                continue
+
+            if contract.vendor_id != resolved_vendor_id:
+                continue
+
+            if contract.entity_id != document.entity_id:
+                continue
+
+            if getattr(contract, "status", None) != "active":
+                continue
+
+            if getattr(contract, "deleted_at", None) is not None:
+                continue
+
+            effective_from = as_date(getattr(contract, "effective_from", None))
+            effective_to = as_date(getattr(contract, "effective_to", None))
+
+            if effective_from is None or invoice_date < effective_from:
+                continue
+
+            if effective_to is not None and invoice_date > effective_to:
+                continue
+
+            matching_contracts.append(contract)
+
+        if len(matching_contracts) != 1:
+            return None
+
+        payment_terms = as_int(getattr(matching_contracts[0], "payment_terms", None))
+        if payment_terms is None:
+            return None
+
+        return {
+            "tier": "contract",
+            "expected_payment_terms": payment_terms,
+            "source_id": getattr(matching_contracts[0], "id", None),
+        }
+
+    def vendor_master_terms_tier():
+        payment_terms = as_int(getattr(vendor, "payment_terms", None))
+
+        if payment_terms is None:
+            return None
+
+        return {
+            "tier": "vendor_master",
+            "expected_payment_terms": payment_terms,
+            "source_id": getattr(vendor, "id", None),
+        }
+
+    risk_flags = []
+    skipped_steps = []
+
+    if resolved_vendor_id is None:
+        skipped_steps.append(
+            {
+                "step": "payment_terms_validation",
+                "skip_reason": "vendor_unresolved",
+            }
+        )
+        return {
+            "risk_flags": risk_flags,
+            "skipped_steps": skipped_steps,
+            "result": "skipped",
+            "expected_payment_terms": None,
+            "expected_source_tier": None,
+        }
+
+    invoice_payment_terms = as_int(getattr(extracted_fields, "payment_terms", None))
+
+    if invoice_payment_terms is None:
+        skipped_steps.append(
+            {
+                "step": "payment_terms_validation",
+                "skip_reason": "invoice_payment_terms_missing",
+            }
+        )
+
+        return {
+            "risk_flags": risk_flags,
+            "skipped_steps": skipped_steps,
+            "result": "skipped",
+            "expected_payment_terms": None,
+            "expected_source_tier": None,
+        }
+
+    resolved = (
+        po_terms_tier()
+        or contract_terms_tier()
+        or vendor_master_terms_tier()
+    )
+
+    if resolved is None:
+        add_flag(
+            "vendor_payment_terms_unconfigured",
+            weight=0.10,
+            detail={
+                "reason": "no_po_contract_or_vendor_payment_terms",
+            },
+        )
+
+        return {
+            "risk_flags": risk_flags,
+            "skipped_steps": skipped_steps,
+            "result": "unconfigured",
+            "expected_payment_terms": None,
+            "expected_source_tier": None,
+        }
+
+    expected_payment_terms = resolved["expected_payment_terms"]
+    expected_source_tier = resolved["tier"]
+
+    difference = abs(invoice_payment_terms - expected_payment_terms)
+
+    if difference > tolerance_days:
+        add_flag(
+            "payment_terms_mismatch",
+            weight=0.20,
+            detail={
+                "invoice_payment_terms": invoice_payment_terms,
+                "expected_payment_terms": expected_payment_terms,
+                "difference_days": difference,
+                "tolerance_days": tolerance_days,
+                "expected_source_tier": expected_source_tier,
+                "source_id": resolved.get("source_id"),
+            },
+        )
+
+        result = "mismatch"
+    else:
+        result = "matched"
+
+    return {
+        "risk_flags": risk_flags,
+        "skipped_steps": skipped_steps,
+        "result": result,
+        "invoice_payment_terms": invoice_payment_terms,
+        "expected_payment_terms": expected_payment_terms,
+        "expected_source_tier": expected_source_tier,
+        "tolerance_days": tolerance_days,
+    }

src/Invoice Validation Functions/platform_configs.json

@@ -0,0 +1,67 @@
+{
+    "_comment_vendor": "Vendor validation configs",
+
+    "validation.name_match_algorithm_version": "rapidfuzz.local.v1",
+
+    "validation.vendor_match_require_high_tier_contexts": [
+      "contract_match",
+      "bank_validation",
+      "approval_revalidation"
+    ],
+
+    "validation.rapidfuzz_high_threshold": 0.90,
+    "validation.rapidfuzz_medium_threshold": 0.75,
+    "validation.rapidfuzz_suggestion_threshold": 0.60,
+
+    "_comment_tax_id": "Tax ID validation configs",
+    "_comment_tax_id_handlers": "Built-in checksum handlers are implemented in Tax - ID validation.py (_BUILTIN_CHECKSUM_HANDLERS). They cover all families with a non-null checksum in the registry: gb_vat_mod97, de_vat_mod11, fr_vat_mod97, it_vat_luhn, es_nif, gstin_crc, abn_mod89, bn_luhn, sg_nric_fin. To override at runtime, supply a callable dict under validation.tax_id_checksum_handlers when building platform_configs.",
+
+    "validation.tax_id_family_registry": {
+        "VAT-GB":   {"pattern": "^(GB)?[0-9]{9}([0-9]{3})?$",                          "checksum": "gb_vat_mod97"},
+        "VAT-DE":   {"pattern": "^(DE)?[0-9]{9}$",                                      "checksum": "de_vat_mod11"},
+        "VAT-FR":   {"pattern": "^(FR)?[A-Z0-9]{2}[0-9]{9}$",                           "checksum": "fr_vat_mod97"},
+        "VAT-IT":   {"pattern": "^(IT)?[0-9]{11}$",                                     "checksum": "it_vat_luhn"},
+        "VAT-ES":   {"pattern": "^(ES)?[A-Z0-9][0-9]{7}[A-Z0-9]$",                     "checksum": "es_nif"},
+        "VAT-NL":   {"pattern": "^(NL)?[0-9]{9}B[0-9]{2}$",                            "checksum": null},
+        "GSTIN-IN": {"pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$",  "checksum": "gstin_crc"},
+        "PAN-IN":   {"pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$",                             "checksum": null},
+        "EIN-US":   {"pattern": "^[0-9]{2}-?[0-9]{7}$",                                "checksum": null},
+        "ABN-AU":   {"pattern": "^[0-9]{11}$",                                          "checksum": "abn_mod89"},
+        "BN-CA":    {"pattern": "^[0-9]{9}([A-Z]{2}[0-9]{4})?$",                       "checksum": "bn_luhn"},
+        "TIN-SG":   {"pattern": "^(?:[STFG][0-9]{7}[A-Z]|[0-9]{9}[A-Z])$",            "checksum": "sg_nric_fin"}
+    },
+
+    "_comment_bank": "Bank validation configs",
+
+    "validation.iban_checksum_required": true,
+    "validation.iban_accno_substring_exempt_countries": ["LC", "MT"],
+
+    "_comment_date": "Date sanity configs",
+    "validation.default_timezone": "Asia/Kolkata",
+    "validation.max_invoice_age_days": 365,
+    "validation.service_end_post_invoice_grace_days": 0,
+
+    "_comment_payment": "Payment terms configs",
+    "validation.payment_terms_tolerance_days": 2,
+
+    "_comment_tax": "Tax configs",
+    "validation.tax_rate_match_tolerance": "0.0001",
+    "iso_currencies.minor_unit_value": {
+        "USD": "0.01",
+        "GBP": "0.01",
+        "EUR": "0.01",
+        "INR": "0.01",
+        "JPY": "1",
+        "BHD": "0.001"
+    },
+    "validation.eu_member_states": [
+        "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR",
+        "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL",
+        "PL", "PT", "RO", "SK", "SI", "ES", "SE"
+    ],
+
+    "_comment_completeness": "Completeness configs",
+    "validation.solver_tolerance.cap_minor_units": 5,
+    "validation.solver_tolerance.base_per_minor_unit": 1,
+    "validation.solver_tolerance.per_line_minor_units": 1
+}

src/Invoice Validation Functions/tax validation.py

@@ -0,0 +1,587 @@
+from decimal import Decimal, ROUND_HALF_UP
+from datetime import date, datetime
+
+
+def run_tax_amount_validation(
+    *,
+    document,
+    extracted_fields,
+    line_items,
+    vendor,
+    entity,
+    tax_master_rows,
+    platform_configs=None,
+):
+    """
+    Tax percentage and tax amount validation.
+
+    Advisory checks:
+      - tax rate exists in tax_master
+      - tax amount matches taxable base
+      - cross-country routing
+      - US sales/use tax advisories
+      - UK VAT advisories
+      - India GST advisories
+      - EU reverse charge
+      - vendor withholding advisory
+      - vendor tax exemption handling
+    """
+
+    platform_configs = platform_configs or {}
+
+    tax_rate_tolerance = Decimal(
+        str(platform_configs.get("validation.tax_rate_match_tolerance", "0.0001"))
+    )
+
+    currency_minor_units = platform_configs.get(
+        "iso_currencies.minor_unit_value",
+        {
+            "USD": Decimal("0.01"),
+            "GBP": Decimal("0.01"),
+            "EUR": Decimal("0.01"),
+            "INR": Decimal("0.01"),
+            "JPY": Decimal("1"),
+            "BHD": Decimal("0.001"),
+        },
+    )
+
+    eu_member_states = set(
+        platform_configs.get(
+            "validation.eu_member_states",
+            [
+                "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR",
+                "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL",
+                "PL", "PT", "RO", "SK", "SI", "ES", "SE",
+            ],
+        )
+    )
+
+    def as_decimal(value):
+        if value is None or value == "":
+            return None
+        try:
+            return Decimal(str(value))
+        except Exception:
+            return None
+
+    def country(value):
+        if not value:
+            return None
+        return str(value).upper()
+
+    def is_zero(value):
+        value = as_decimal(value)
+        return value is not None and value == Decimal("0")
+
+    def is_non_zero(value):
+        value = as_decimal(value)
+        return value is not None and value != Decimal("0")
+
+    def invoice_date_value():
+        value = getattr(extracted_fields, "invoice_date", None)
+        if isinstance(value, datetime):
+            return value.date()
+        if isinstance(value, date):
+            return value
+        return None  # do not invent today's date
+
+    def currency_tolerance():
+        invoice_currency = country(getattr(extracted_fields, "currency", None))
+        raw = currency_minor_units.get(invoice_currency)
+        return Decimal(str(raw)) if raw is not None else None
+
+    def add_flag(code, *, weight=None, detail=None):
+        flag = {"code": code, "severity": "advisory"}
+        if weight is not None:
+            flag["weight"] = weight
+        if detail is not None:
+            flag["detail"] = detail
+        risk_flags.append(flag)
+
+    def add_advisory(code, *, detail=None):
+        advisory = {"code": code, "severity": "advisory"}
+        if detail is not None:
+            advisory["detail"] = detail
+        # avoid duplicates
+        if not any(a["code"] == code for a in advisory_flags):
+            advisory_flags.append(advisory)
+
+    def add_skip(check_name, reason):
+        skipped_checks.append({"check": check_name, "skip_reason": reason})
+
+    def effective_tax_master_rows():
+        invoice_date = invoice_date_value()
+        rows = []
+        for row in tax_master_rows:
+            if getattr(row, "tenant_id", None) != document.tenant_id:
+                continue
+            if not getattr(row, "is_active", True):
+                continue
+            if getattr(row, "deleted_at", None) is not None:
+                continue
+
+            # If invoice date is unavailable, do not invent one.
+            # Keep only active rows, but skip date-sensitive matching later if needed.
+            if invoice_date is not None:
+                effective_from = getattr(row, "effective_from", None)
+                effective_to = getattr(row, "effective_to", None)
+
+                if effective_from is not None and effective_from > invoice_date:
+                    continue
+                if effective_to is not None and invoice_date >= effective_to:
+                    continue
+
+            rows.append(row)
+        return rows
+
+    def rate_matches(master_rate, invoice_rate):
+        master_rate = as_decimal(master_rate)
+        invoice_rate = as_decimal(invoice_rate)
+        if master_rate is None or invoice_rate is None:
+            return False
+        return abs(master_rate - invoice_rate) <= tax_rate_tolerance
+
+    def row_region_matches(row_region, hint_region):
+        if row_region is None:
+            return True
+        return hint_region is not None and str(row_region).upper() == str(hint_region).upper()
+
+    def find_tax_master_rate(
+        *,
+        rate,
+        country_code,
+        region_code=None,
+        allowed_tax_types=None,
+        reduced_rate_allowed=False,
+    ):
+        country_code = country(country_code)
+        matches = []
+
+        for row in active_tax_master:
+            if country(getattr(row, "country_code", None)) != country_code:
+                continue
+
+            if not row_region_matches(getattr(row, "region_code", None), region_code):
+                continue
+
+            if allowed_tax_types is not None and getattr(row, "tax_type", None) not in allowed_tax_types:
+                continue
+
+            if rate_matches(getattr(row, "tax_rate", None), rate):
+                matches.append(row)
+                continue
+
+            elif reduced_rate_allowed:
+                tax_name = str(getattr(row, "tax_name", "") or "").lower()
+                if "reduced" in tax_name:
+                    matches.append(row)
+
+        return matches
+
+    def find_india_gst_aggregate_rate(rate, region_code, jurisdiction):
+        """
+        Match invoice aggregate GST rate against the sum of applicable component rates:
+          inter_state : IGST single-row match
+          intra_state : CGST + SGST pair whose rates sum to the invoice rate
+          None/unknown: try IGST, then CGST+SGST, then CGST+UTGST
+        """
+
+        def in_rows(tax_type, rgn=None):
+            return [
+                r for r in active_tax_master
+                if country(getattr(r, "country_code", None)) == "IN"
+                and getattr(r, "tax_type", None) == tax_type
+                and row_region_matches(getattr(r, "region_code", None), rgn)
+            ]
+
+        def sum_pair(type_a, type_b, rgn=None):
+            for a in in_rows(type_a, rgn):
+                a_rate = as_decimal(getattr(a, "tax_rate", None))
+                if a_rate is None:
+                    continue
+                for b in in_rows(type_b, rgn):
+                    b_rate = as_decimal(getattr(b, "tax_rate", None))
+                    if b_rate is None:
+                        continue
+                    if abs((a_rate + b_rate) - rate) <= tax_rate_tolerance:
+                        return [a, b]
+            return []
+
+        if jurisdiction == "inter_state":
+            for r in in_rows("IGST", region_code):
+                if rate_matches(getattr(r, "tax_rate", None), rate):
+                    return [r]
+            return []
+
+        if jurisdiction == "intra_state":
+            return sum_pair("CGST", "SGST", region_code)
+
+        # Unknown jurisdiction: try all applicable component combinations.
+        for r in in_rows("IGST"):
+            if rate_matches(getattr(r, "tax_rate", None), rate):
+                return [r]
+        result = sum_pair("CGST", "SGST")
+        if result:
+            return result
+        return sum_pair("CGST", "UTGST")
+
+    def all_line_rates_zero():
+        for line in line_items:
+            rate = as_decimal(getattr(line, "tax_rate_per_item", None))
+            if rate is None:
+                continue
+            if rate != Decimal("0"):
+                return False
+        return True
+
+    def all_line_tax_amounts_zero():
+        found_any = False
+        for line in line_items:
+            amount = as_decimal(getattr(line, "tax_amount_per_item", None))
+            if amount is None:
+                continue
+            found_any = True
+            if amount != Decimal("0"):
+                return False
+
+        summary_tax_amount = as_decimal(getattr(extracted_fields, "tax_amount", None))
+        if summary_tax_amount is not None:
+            found_any = True
+            if summary_tax_amount != Decimal("0"):
+                return False
+
+        return found_any
+
+    def sender_tax_family():
+        return getattr(extracted_fields, "sender_tax_id_inferred_family", None)
+
+    def sender_tax_valid_for_country(expected_family):
+        return (
+            getattr(extracted_fields, "sender_tax_id", None) is not None
+            and sender_tax_family() == expected_family
+            and bool(getattr(extracted_fields, "sender_tax_id_format_valid", True))
+            and bool(getattr(extracted_fields, "sender_tax_id_checksum_valid", True))
+        )
+
+    def supplier_and_recipient_are_eu():
+        return supplier_country in eu_member_states and recipient_country in eu_member_states
+
+    def eu_reverse_charge_conditions_met():
+        if not supplier_and_recipient_are_eu():
+            return False
+        if supplier_country == recipient_country:
+            return False
+
+        if vendor_exemption_status == "reverse_charge":
+            return True
+
+        supplier_family = f"VAT-{supplier_country}"
+        supplier_vat_valid = sender_tax_valid_for_country(supplier_family)
+        recipient_vat_present = bool(getattr(entity, "vat_id", None))
+
+        return (
+            supplier_vat_valid
+            and recipient_vat_present
+            and all_line_rates_zero()
+            and is_zero(getattr(extracted_fields, "tax_amount", None))
+        )
+
+    def india_jurisdiction():
+        supplier_state = getattr(vendor, "billing_state", None)
+        recipient_state = getattr(entity, "region_code", None)
+        if not supplier_state or not recipient_state:
+            return None
+        if str(supplier_state).upper() == str(recipient_state).upper():
+            return "intra_state"
+        return "inter_state"
+
+    risk_flags = []
+    advisory_flags = []
+    skipped_checks = []
+    ops_alerts = []
+    matched_tax_master_rows = {}
+
+    active_tax_master = effective_tax_master_rows()
+
+    supplier_country = country(getattr(vendor, "billing_country", None))
+    recipient_country = country(getattr(entity, "country_code", None))
+    invoice_currency = country(getattr(extracted_fields, "currency", None))
+    vendor_exemption_status = getattr(vendor, "exemption_status", None)
+    invoice_date = invoice_date_value()
+
+    if not active_tax_master:
+        ops_alerts.append(
+            {
+                "code": "alert.tax_master_unconfigured",
+                "tenant_id": document.tenant_id,
+            }
+        )
+        return {
+            "risk_flags": risk_flags,
+            "advisory_flags": advisory_flags,
+            "skipped_checks": [
+                {"check": "all_tax_checks", "skip_reason": "tax_master_unconfigured"}
+            ],
+            "ops_alerts": ops_alerts,
+            "matched_tax_master_rows": matched_tax_master_rows,
+        }
+
+    # Check 1 and Check 2 both skip if supplier country is missing.
+    if not supplier_country:
+        add_skip("rate_exists_in_master", "supplier_country_missing")
+        add_skip("tax_amount_matches_taxable_base", "supplier_country_missing")
+    else:
+        unique_rates = set()
+
+        # Gather unique non-null, non-zero line rates
+        for line in line_items:
+            rate = as_decimal(getattr(line, "tax_rate_per_item", None))
+            if rate is not None and rate != Decimal("0"):
+                unique_rates.add(
+                    (
+                        rate,
+                        getattr(line, "region_code_hint", None),
+                        getattr(line, "line_number", None),
+                    )
+                )
+
+        # Summary tax rate is checked separately
+        summary_rate = as_decimal(getattr(extracted_fields, "tax_rate", None))
+        if summary_rate is not None and summary_rate != Decimal("0"):
+            unique_rates.add((summary_rate, None, "summary"))
+
+        for rate, region_code, source in unique_rates:
+            # India aggregate rate matching is handled entirely in Check 6.
+            if supplier_country == "IN":
+                continue
+
+            # US state tax needs a region hint
+            if supplier_country == "US" and not region_code:
+                add_advisory("us_region_unresolved", detail={"source": source})
+                continue
+
+            allowed_tax_types = None
+            if supplier_country == "GB":
+                allowed_tax_types = {"VAT"}
+            if supplier_country == "IN":
+                allowed_tax_types = {"CGST", "SGST", "IGST", "UTGST"}
+            if supplier_country == "US":
+                allowed_tax_types = None
+
+            reduced_rate_allowed = vendor_exemption_status == "reduced_rate"
+
+            matches = find_tax_master_rate(
+                rate=rate,
+                country_code=supplier_country,
+                region_code=region_code,
+                allowed_tax_types=allowed_tax_types,
+                reduced_rate_allowed=reduced_rate_allowed,
+            )
+
+            if matches:
+                matched_tax_master_rows[source] = [getattr(row, "id", None) for row in matches]
+            else:
+                add_flag(
+                    "tax_rate_not_in_master",
+                    weight=Decimal("0.35"),
+                    detail={
+                        "rate": str(rate),
+                        "country": supplier_country,
+                        "region_code": region_code,
+                        "source": source,
+                    },
+                )
+
+
+    # Check 2: Amount matches taxable base.
+    if supplier_country:
+        tolerance = currency_tolerance()
+        if tolerance is None:
+            add_skip("tax_amount_matches_taxable_base", "currency_minor_unit_unknown")
+        else:
+            for line in line_items:
+                rate = as_decimal(getattr(line, "tax_rate_per_item", None))
+                amount = as_decimal(getattr(line, "amount", None))
+                actual_tax = as_decimal(getattr(line, "tax_amount_per_item", None))
+
+                if rate is None or amount is None or actual_tax is None:
+                    continue
+
+                discount = as_decimal(getattr(line, "discount_amount_per_item", None)) or Decimal("0")
+                taxable_base = amount - discount
+                expected_tax = taxable_base * (rate / Decimal("100"))
+
+                if abs(expected_tax - actual_tax) > tolerance:
+                    add_flag(
+                        "tax_amount_mismatch",
+                        weight=Decimal("0.35"),
+                        detail={
+                            "line_number": getattr(line, "line_number", None),
+                            "expected_tax": str(expected_tax.quantize(tolerance, rounding=ROUND_HALF_UP)),
+                            "actual_tax": str(actual_tax),
+                            "currency": invoice_currency,
+                        },
+                    )
+
+    # §8.9: vendor_tax_exempt advisory fires when all extracted line rates are zero.
+    if vendor_exemption_status == "exempt" and all_line_rates_zero():
+        add_advisory("vendor_tax_exempt")
+
+    # Check 3: Cross-country routing.
+    summary_tax_amount = as_decimal(getattr(extracted_fields, "tax_amount", None))
+
+    if supplier_country is None or summary_tax_amount is None or summary_tax_amount == Decimal("0"):
+        add_skip("cross_country_routing", "supplier_country_or_tax_amount_missing_or_zero")
+    elif recipient_country is None:
+        add_skip("cross_country_routing", "recipient_country_missing")
+    elif supplier_country != recipient_country:
+        add_flag(
+            "cross_country_tax",
+            weight=Decimal("0.30"),
+            detail={
+                "supplier_country": supplier_country,
+                "recipient_country": recipient_country,
+            },
+        )
+
+    # Check 4: United States.
+    if supplier_country == "US" or recipient_country == "US":
+        if supplier_country == "US" and summary_tax_amount is not None and summary_tax_amount != Decimal("0"):
+            add_flag(
+                "us_sales_tax",
+                weight=Decimal("0.20"),
+                detail={"tax_amount": str(summary_tax_amount)},
+            )
+
+        if (
+            recipient_country == "US"
+            and supplier_country != recipient_country
+            and all_line_rates_zero()
+        ):
+            add_flag(
+                "us_use_tax_possibly_owed",
+                weight=Decimal("0.15"),
+            )
+
+    # Check 5: United Kingdom.
+    if supplier_country == "GB" or recipient_country == "GB":
+        for line in line_items:
+            rate = as_decimal(getattr(line, "tax_rate_per_item", None))
+            tax_amount = as_decimal(getattr(line, "tax_amount_per_item", None))
+
+            if rate == Decimal("0"):
+                gb_matches = find_tax_master_rate(
+                    rate=rate,
+                    country_code="GB",
+                    region_code=getattr(line, "region_code_hint", None),
+                    allowed_tax_types={"zero_rated", "exempt", "VAT"},
+                    reduced_rate_allowed=False,
+                )
+
+                if any(getattr(row, "tax_type", None) == "zero_rated" for row in gb_matches):
+                    add_advisory("uk_zero_rated", detail={"line_number": getattr(line, "line_number", None)})
+                elif tax_amount == Decimal("0") and any(
+                    getattr(row, "tax_type", None) == "exempt" for row in gb_matches
+                ):
+                    add_advisory("uk_exempt", detail={"line_number": getattr(line, "line_number", None)})
+                elif not (
+                    vendor_exemption_status == "reverse_charge"
+                    and supplier_and_recipient_are_eu()
+                    and supplier_country != recipient_country
+                ) and not (
+                    vendor_exemption_status == "exempt"
+                    and all_line_rates_zero()
+                ):
+                    add_flag(
+                        "tax_rate_not_in_master",
+                        weight=Decimal("0.35"),
+                        detail={
+                            "rate": "0",
+                            "country": "GB",
+                            "source": getattr(line, "line_number", None),
+                        },
+                    )
+
+        if (
+            supplier_country == "GB"
+            and recipient_country == "GB"
+            and summary_tax_amount is not None
+            and summary_tax_amount != Decimal("0")
+            and not sender_tax_valid_for_country("VAT-GB")
+        ):
+            add_flag(
+                "missing_tax_id_for_local_tax",
+                weight=Decimal("0.25"),
+                detail={"expected_family": "VAT-GB"},
+            )
+
+    # Check 6: India GST.
+    if supplier_country == "IN" or recipient_country == "IN":
+        jurisdiction = india_jurisdiction()
+        if jurisdiction is None:
+            add_advisory("in_gst_jurisdiction_unresolved")
+        else:
+            add_advisory("in_gst_jurisdiction_inferred", detail={"jurisdiction": jurisdiction})
+
+        # Sender tax ID must look like GSTIN-IN or PAN-IN
+        if sender_tax_family() not in {"GSTIN-IN", "PAN-IN"}:
+            add_flag(
+                "missing_tax_id_for_local_tax",
+                weight=Decimal("0.25"),
+                detail={"expected_family": "GSTIN-IN or PAN-IN"},
+            )
+
+        for line in line_items:
+            rate = as_decimal(getattr(line, "tax_rate_per_item", None))
+            if rate is None or rate == Decimal("0"):
+                continue
+
+            region_code = None
+            if jurisdiction == "intra_state":
+                region_code = getattr(vendor, "billing_state", None) or getattr(entity, "region_code", None)
+
+            matches = find_india_gst_aggregate_rate(rate, region_code, jurisdiction)
+
+            if matches:
+                matched_tax_master_rows[getattr(line, "line_number", None)] = [
+                    getattr(r, "id", None) for r in matches
+                ]
+            else:
+                add_flag(
+                    "tax_rate_not_in_master",
+                    weight=Decimal("0.35"),
+                    detail={
+                        "rate": str(rate),
+                        "country": "IN",
+                        "region_code": region_code,
+                        "source": getattr(line, "line_number", None),
+                    },
+                )
+
+    # Check 7: EU reverse charge.
+    # If conditions are met, add advisory and retract cross_country_tax raised by Check 3.
+    if supplier_and_recipient_are_eu() and supplier_country != recipient_country:
+        if eu_reverse_charge_conditions_met():
+            add_advisory("eu_reverse_charge")
+            risk_flags[:] = [f for f in risk_flags if f["code"] != "cross_country_tax"]
+
+    # Check 8: Withholding tax advisory.
+    if vendor_exemption_status == "withholding_applicable":
+        add_advisory("vendor_withholding_applicable")
+
+    for line in line_items:
+        tax_master_id = getattr(line, "tax_master_id", None)
+        if not tax_master_id:
+            continue
+        for row in active_tax_master:
+            if getattr(row, "id", None) == tax_master_id and getattr(row, "tax_type", None) == "withholding":
+                add_advisory("vendor_withholding_applicable")
+                break
+
+    return {
+        "risk_flags": risk_flags,
+        "advisory_flags": advisory_flags,
+        "skipped_checks": skipped_checks,
+        "ops_alerts": ops_alerts,
+        "matched_tax_master_rows": matched_tax_master_rows,
+    }

src/Matching Functions/contract_match.py

@@ -0,0 +1,757 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal, ROUND_HALF_EVEN, getcontext
+from typing import Any, Callable, Optional
+
+import re
+import unicodedata
+
+from rapidfuzz import fuzz
+
+from two_way_match import MatchExceptionRecord, InvoiceLine, to_decimal
+
+# ============================================================
+# Decimal hygiene
+# ============================================================
+getcontext().prec = 28
+getcontext().rounding = ROUND_HALF_EVEN
+
+D0 = Decimal("0")
+D100 = Decimal("100")
+
+
+# ============================================================
+# Data models
+# ============================================================
+@dataclass(frozen=True)
+class RateCardItem:
+    id: int
+    description: Optional[str] = None
+    description_canonical: Optional[str] = None
+    unit_price: Optional[Decimal] = None
+    item_type: Optional[str] = None  # goods | services | None
+
+
+@dataclass(frozen=True)
+class ContractRecord:
+    id: int
+    tenant_id: int
+    vendor_id: int
+    entity_id: int
+    currency: str
+    status: str = "active"
+    deleted_at: Any = None
+    effective_from: Optional[date] = None
+    effective_to: Optional[date] = None
+    created_at: Optional[datetime] = None
+    total_value: Optional[Decimal] = None
+    cumulative_billed_amount: Optional[Decimal] = None
+    rate_card_items: Optional[list[RateCardItem]] = None
+
+
+@dataclass(frozen=True)
+class ContractInvoiceHeader:
+    id: int
+    tenant_id: int
+    entity_id: int
+    resolved_vendor_id: Optional[int]
+    currency: Optional[str]
+    invoice_date: Optional[date]
+    service_start_date: Optional[date] = None
+    service_end_date: Optional[date] = None
+    total_amount: Optional[Decimal] = None
+    advisory_flags: tuple[str, ...] = ()
+
+
+@dataclass
+class ContractLineResult:
+    invoice_line_id: int
+    rate_card_item_id: Optional[int]
+    line_status: str = "matched"   # matched | no_match | exception
+    line_zone: str = "green"       # green | amber | red
+    price_var_pct: Optional[Decimal] = None
+    allocated_inv_amount: Optional[Decimal] = None
+    allocated_rate_amount: Optional[Decimal] = None
+    exception_type: Optional[str] = None
+    exception_detail: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ContractMatchResult:
+    match_type: str = "contract"
+    overall_status: str = "exception"  # matched | partial_match | exception
+    match_zone: str = "red"            # green | amber | red | critical
+    documents_status: str = "pending_approval"
+
+    lines_total: int = 0
+    lines_matched: int = 0
+    lines_in_exception: int = 0
+
+    advisory_flags: list[str] = field(default_factory=list)
+    risk_flags: list[str] = field(default_factory=list)
+    skipped_steps: list[dict] = field(default_factory=list)
+    header_exceptions: list[MatchExceptionRecord] = field(default_factory=list)
+    match_exceptions: list[MatchExceptionRecord] = field(default_factory=list)
+    match_line_results: list[ContractLineResult] = field(default_factory=list)
+
+    selected_contract_id: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class ContractConfig:
+    # RapidFuzz thresholds for rate-card / tiebreaker matching
+    high_threshold: float = 90.0
+    medium_threshold: float = 80.0
+    score_cutoff: float = 80.0
+
+    # Price variance bands (same idea as 2-way; tune to your config table)
+    price_goods_green: Decimal = Decimal("5")
+    price_goods_amber: Decimal = Decimal("10")
+    price_services_green: Decimal = Decimal("10")
+    price_services_amber: Decimal = Decimal("15")
+
+    precision: int = 28
+
+
+# ============================================================
+# Helpers
+# ============================================================
+def canonicalise_identifier(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    value = unicodedata.normalize("NFKC", str(value)).upper()
+    value = re.sub(r"[^A-Z0-9]+", "", value)
+    return value or None
+
+
+def norm_currency(value: Optional[str]) -> Optional[str]:
+    return value.upper().strip() if value else None
+
+
+def price_variance_pct(inv_price: Optional[Decimal], ref_price: Optional[Decimal]) -> Optional[Decimal]:
+    if inv_price is None or ref_price is None or ref_price == 0:
+        return None
+    return (abs(inv_price - ref_price) / ref_price * D100).quantize(Decimal("0.0001"))
+
+
+def _bands(item_type: Optional[str], cfg: ContractConfig) -> tuple[Decimal, Decimal]:
+    item_type = (item_type or "services").lower()
+    if item_type == "goods":
+        return cfg.price_goods_green, cfg.price_goods_amber
+    return cfg.price_services_green, cfg.price_services_amber
+
+
+def _line_zone_from_price(price_pct: Optional[Decimal], item_type: Optional[str], cfg: ContractConfig) -> str:
+    if price_pct is None:
+        return "green"
+    green, amber = _bands(item_type, cfg)
+    if price_pct <= green:
+        return "green"
+    if price_pct <= amber:
+        return "amber"
+    return "red"
+
+
+def _is_service_window_contained(
+    contract: ContractRecord,
+    invoice_start: Optional[date],
+    invoice_end: Optional[date],
+) -> bool:
+    if invoice_start is None or invoice_end is None:
+        return False
+    if contract.effective_from is None:
+        return False
+    effective_to = contract.effective_to or date(9999, 12, 31)
+    return contract.effective_from <= invoice_start and invoice_end <= effective_to
+
+
+def _joined_invoice_descriptions(inv_lines: list[InvoiceLine]) -> str:
+    parts = []
+    for line in inv_lines:
+        if line.description_canonical:
+            parts.append(line.description_canonical)
+        elif line.description:
+            parts.append(canonicalise_identifier(line.description) or "")
+    return " ".join(p for p in parts if p).strip()
+
+
+def rapidfuzz_best_match(
+    query: str,
+    candidates: list[dict[str, Any]],
+    *,
+    high_threshold: float,
+    medium_threshold: float,
+    score_cutoff: float,
+) -> dict[str, Any]:
+    """
+    Simple local matcher.
+    Swap this out with your platform name-match algorithm later if required.
+    """
+    if not query or not candidates:
+        return {"decision": "unmatched", "score_tier": None, "score": 0.0, "record_id": None}
+
+    best_record_id = None
+    best_score = 0.0
+
+    for cand in candidates:
+        record_id = cand.get("record_id")
+        names = cand.get("names") or []
+        for name in names:
+            if not name:
+                continue
+            score = float(fuzz.WRatio(query, name, score_cutoff=score_cutoff))
+            if score > best_score:
+                best_score = score
+                best_record_id = record_id
+
+    if best_record_id is None or best_score < score_cutoff:
+        return {"decision": "unmatched", "score_tier": None, "score": 0.0, "record_id": None}
+
+    if best_score >= high_threshold:
+        tier = "high"
+    elif best_score >= medium_threshold:
+        tier = "medium"
+    else:
+        tier = "low"
+
+    return {
+        "decision": "matched" if tier in {"high", "medium"} else "suggestion",
+        "score_tier": tier,
+        "score": round(best_score, 2),
+        "record_id": best_record_id,
+    }
+
+
+def _contract_stub_result(
+    invoice: ContractInvoiceHeader,
+    inv_lines: list[InvoiceLine],
+    exception_type: str,
+    detail: dict[str, Any],
+) -> ContractMatchResult:
+    res = ContractMatchResult(
+        overall_status="exception",
+        match_zone="red",
+        documents_status="pending_approval",
+        lines_total=len(inv_lines),
+        lines_matched=0,
+        lines_in_exception=len(inv_lines),
+    )
+    res.header_exceptions.append(
+        MatchExceptionRecord(
+            exception_type=exception_type,
+            exception_detail=detail,
+        )
+    )
+    return res
+
+
+# ============================================================
+# Contract candidate selection
+# ============================================================
+def select_contract_candidate(
+    invoice: ContractInvoiceHeader,
+    inv_lines: list[InvoiceLine],
+    contracts: list[ContractRecord],
+    cfg: ContractConfig,
+) -> tuple[Optional[ContractRecord], Optional[MatchExceptionRecord]]:
+    """
+    Returns:
+      - selected contract
+      - or a MatchExceptionRecord for stub paths
+    """
+    inv_currency = norm_currency(invoice.currency)
+
+    initial_candidates: list[dict[str, Any]] = []
+    for c in contracts:
+        if c.deleted_at is not None:
+            continue
+        if c.status != "active":
+            continue
+        if c.tenant_id != invoice.tenant_id:
+            continue
+        if c.vendor_id != invoice.resolved_vendor_id:
+            continue
+        if c.entity_id != invoice.entity_id:
+            continue
+        if norm_currency(c.currency) != inv_currency:
+            continue
+        if invoice.invoice_date is None:
+            continue
+        if c.effective_from is None:
+            continue
+        effective_to = c.effective_to or date(9999, 12, 31)
+        if not (c.effective_from <= invoice.invoice_date < effective_to):
+            continue
+
+        initial_candidates.append(
+            {
+                "contract": c,
+                "elimination_reason": None,
+            }
+        )
+
+    if not initial_candidates:
+        return None, MatchExceptionRecord(
+            exception_type="contract_not_found",
+            exception_detail={
+                "reason": "initial_query_returned_zero_rows",
+                "tenant_id": invoice.tenant_id,
+                "vendor_id": invoice.resolved_vendor_id,
+                "entity_id": invoice.entity_id,
+                "currency": inv_currency,
+                "invoice_date": str(invoice.invoice_date) if invoice.invoice_date else None,
+            },
+        )
+
+    remaining = [x["contract"] for x in initial_candidates]
+
+    # Tiebreaker 1: service-period containment (only when both service dates are present)
+    if invoice.service_start_date is not None and invoice.service_end_date is not None:
+        contained = [c for c in remaining if _is_service_window_contained(c, invoice.service_start_date, invoice.service_end_date)]
+        if contained:
+            remaining = contained
+        else:
+            # Candidates existed, but all were filtered out by this rule
+            return None, MatchExceptionRecord(
+                exception_type="cannot_match_no_contract",
+                exception_detail={
+                    "reason": "all_candidates_filtered_out_by_service_period_containment",
+                    "invoice_service_start_date": str(invoice.service_start_date),
+                    "invoice_service_end_date": str(invoice.service_end_date),
+                    "considered_contract_ids": [c.id for c in remaining],
+                },
+            )
+
+    # Tiebreaker 2: rate-card best fit via RapidFuzz
+    # Query uses joined canonical invoice descriptions.
+    joined_desc = _joined_invoice_descriptions(inv_lines)
+    if joined_desc:
+        scored_candidates: list[dict[str, Any]] = []
+        for c in remaining:
+            if not c.rate_card_items:
+                continue
+            item_names = [
+                (item.description_canonical or canonicalise_identifier(item.description) or "")
+                for item in c.rate_card_items
+            ]
+            item_names = [n for n in item_names if n]
+            if not item_names:
+                continue
+            scored_candidates.append({"record_id": c.id, "names": item_names})
+
+        if scored_candidates:
+            # Contracts without rate card items cannot participate; exclude them now
+            # so they don't survive to tiebreaker 3 ahead of contracts that do.
+            scored_ids = {x["record_id"] for x in scored_candidates}
+            remaining = [c for c in remaining if c.id in scored_ids]
+
+            # Evaluate each contract individually: keep only those whose rate card
+            # descriptions yield decision='matched' against the joined invoice text.
+            matched_ids = {
+                x["record_id"]
+                for x in scored_candidates
+                if rapidfuzz_best_match(
+                    joined_desc,
+                    [x],
+                    high_threshold=cfg.high_threshold,
+                    medium_threshold=cfg.medium_threshold,
+                    score_cutoff=cfg.score_cutoff,
+                )["decision"] == "matched"
+            }
+            if matched_ids:
+                remaining = [c for c in remaining if c.id in matched_ids]
+            else:
+                return None, MatchExceptionRecord(
+                    exception_type="cannot_match_no_contract",
+                    exception_detail={
+                        "reason": "rate_card_best_fit_filtered_all_candidates",
+                        "joined_invoice_descriptions": joined_desc,
+                        "considered_contract_ids": [c.id for c in remaining],
+                    },
+                )
+
+    # Tiebreaker 3: newest created_at DESC, id DESC
+    remaining.sort(
+        key=lambda c: (
+            c.created_at or datetime.min,
+            c.id,
+        ),
+        reverse=True,
+    )
+
+    if len(remaining) == 1:
+        return remaining[0], None
+
+    if len(remaining) == 0:
+        return None, MatchExceptionRecord(
+            exception_type="cannot_match_no_contract",
+            exception_detail={
+                "reason": "all_candidates_removed_by_tiebreakers",
+            },
+        )
+
+    return None, MatchExceptionRecord(
+        exception_type="ambiguous_active_contract",
+        exception_detail={
+            "reason": "multiple_contracts_remain_after_tiebreakers",
+            "surviving_contract_ids": [c.id for c in remaining],
+        },
+    )
+
+
+# ============================================================
+# Config builder
+# ============================================================
+def _cfg_from_contract_dict(d: dict) -> ContractConfig:
+    def _d(key: str, default: str) -> Decimal:
+        return Decimal(str(d.get(key, default)))
+    def _f(key: str, default: float) -> float:
+        return float(d.get(key, default))
+    def _i(key: str, default: int) -> int:
+        return int(d.get(key, default))
+    return ContractConfig(
+        high_threshold=_f("contract_fuzzy_high_threshold", 90.0),
+        medium_threshold=_f("contract_fuzzy_medium_threshold", 80.0),
+        score_cutoff=_f("contract_fuzzy_score_cutoff", 80.0),
+        price_goods_green=_d("contract_price_goods_green", "5"),
+        price_goods_amber=_d("contract_price_goods_amber", "10"),
+        price_services_green=_d("contract_price_services_green", "10"),
+        price_services_amber=_d("contract_price_services_amber", "15"),
+        precision=_i("contract_precision", 28),
+    )
+
+
+# ============================================================
+# Main contract match core
+# ============================================================
+def run_contract_match_core(
+    invoice: ContractInvoiceHeader,
+    inv_lines: list[InvoiceLine],
+    contracts: list[ContractRecord],
+    *,
+    matching_configs: Optional[dict] = None,
+) -> ContractMatchResult:
+    """
+    Contract match used when po_number_canonical is NULL.
+
+    Returns:
+      - a stub exception result if no unique contract can be selected
+      - otherwise runs billing-period, rate-card, and budget checks
+
+    Note:
+      - cumulative_billed_amount is NOT incremented here
+      - this is matching-only, not approval
+    """
+    cfg = _cfg_from_contract_dict(matching_configs or {})
+    getcontext().prec = cfg.precision
+
+    result = ContractMatchResult(
+        lines_total=len(inv_lines),
+        documents_status="pending_approval",
+        match_type="contract",
+    )
+    result.advisory_flags = list(invoice.advisory_flags)
+
+    if invoice.resolved_vendor_id is None:
+        return _contract_stub_result(
+            invoice,
+            inv_lines,
+            "cannot_match_no_vendor",
+            {
+                "reason": "resolved_vendor_id_is_required",
+                "tenant_id": invoice.tenant_id,
+                "entity_id": invoice.entity_id,
+            },
+        )
+
+    selected_contract, stub_exc = select_contract_candidate(invoice, inv_lines, contracts, cfg)
+    if stub_exc is not None or selected_contract is None:
+        # contract_not_found / cannot_match_no_contract / ambiguous_active_contract
+        result.header_exceptions.append(stub_exc or MatchExceptionRecord(
+            exception_type="cannot_match_no_contract",
+            exception_detail={"reason": "no_selected_contract"},
+        ))
+        result.overall_status = "exception"
+        result.match_zone = "red"
+        result.lines_in_exception = len(inv_lines)
+        return result
+
+    result.selected_contract_id = selected_contract.id
+
+    # ---------------------------------------------------------
+    # Contract checks
+    # ---------------------------------------------------------
+    # 1) Billing period missing
+    if invoice.service_start_date is None or invoice.service_end_date is None:
+        result.match_exceptions.append(
+            MatchExceptionRecord(
+                exception_type="billing_period_unverified",
+                exception_detail={
+                    "reason": "service_start_date_or_service_end_date_missing",
+                    "service_start_date": str(invoice.service_start_date) if invoice.service_start_date else None,
+                    "service_end_date": str(invoice.service_end_date) if invoice.service_end_date else None,
+                },
+            )
+        )
+
+    # 2) Billing period outside contract
+    if invoice.service_start_date is not None and invoice.service_end_date is not None:
+        if not _is_service_window_contained(selected_contract, invoice.service_start_date, invoice.service_end_date):
+            result.match_exceptions.append(
+                MatchExceptionRecord(
+                    exception_type="billing_period_outside_contract",
+                    exception_detail={
+                        "reason": "invoice_service_window_not_contained_in_contract",
+                        "service_start_date": str(invoice.service_start_date),
+                        "service_end_date": str(invoice.service_end_date),
+                        "contract_effective_from": str(selected_contract.effective_from) if selected_contract.effective_from else None,
+                        "contract_effective_to": str(selected_contract.effective_to) if selected_contract.effective_to else None,
+                    },
+                )
+            )
+
+    # 3) Rate card exists
+    if not selected_contract.rate_card_items:
+        result.match_exceptions.append(
+            MatchExceptionRecord(
+                exception_type="no_rate_card_configured",
+                exception_detail={
+                    "reason": "contract_has_no_rate_card_items",
+                    "contract_id": selected_contract.id,
+                },
+            )
+        )
+        result.overall_status = "exception"
+        result.match_zone = "red"
+        result.lines_in_exception = len(inv_lines)
+        return result
+
+    # 4) Per-line rate check
+    rate_card_candidates = [
+        {
+            "record_id": item.id,
+            "names": [item.description_canonical or canonicalise_identifier(item.description) or ""],
+        }
+        for item in selected_contract.rate_card_items
+        if (item.description_canonical or item.description)
+    ]
+
+    line_matched_count = 0
+    line_exception_count = 0
+
+    for inv_line in inv_lines:
+        query = inv_line.description_canonical or canonicalise_identifier(inv_line.description) or ""
+        if not query:
+            result.match_exceptions.append(
+                MatchExceptionRecord(
+                    exception_type="no_rate_card_match",
+                    line_id=inv_line.id,
+                    exception_detail={
+                        "reason": "invoice_line_description_missing",
+                        "invoice_line_id": inv_line.id,
+                    },
+                )
+            )
+            line_exception_count += 1
+            continue
+
+        rf = rapidfuzz_best_match(
+            query=query,
+            candidates=rate_card_candidates,
+            high_threshold=cfg.high_threshold,
+            medium_threshold=cfg.medium_threshold,
+            score_cutoff=cfg.score_cutoff,
+        )
+
+        if rf["decision"] not in {"matched", "suggestion"} or rf["record_id"] is None:
+            result.match_exceptions.append(
+                MatchExceptionRecord(
+                    exception_type="no_rate_card_match",
+                    line_id=inv_line.id,
+                    exception_detail={
+                        "reason": "rate_card_name_match_failed",
+                        "invoice_line_id": inv_line.id,
+                        "query": query,
+                    },
+                )
+            )
+            line_exception_count += 1
+            continue
+
+        rate_item = next((x for x in selected_contract.rate_card_items if x.id == rf["record_id"]), None)
+        if rate_item is None:
+            result.match_exceptions.append(
+                MatchExceptionRecord(
+                    exception_type="no_rate_card_match",
+                    line_id=inv_line.id,
+                    exception_detail={
+                        "reason": "matched_rate_card_item_not_found",
+                        "invoice_line_id": inv_line.id,
+                        "matched_rate_card_item_id": rf["record_id"],
+                    },
+                )
+            )
+            line_exception_count += 1
+            continue
+
+        # Compare unit price if present
+        if inv_line.unit_price is None:
+            if "rate_card_match_no_price_compare" not in result.advisory_flags:
+                result.advisory_flags.append("rate_card_match_no_price_compare")
+            result.match_line_results.append(
+                ContractLineResult(
+                    invoice_line_id=inv_line.id,
+                    rate_card_item_id=rate_item.id,
+                    line_status="matched",
+                    line_zone="green",
+                    price_var_pct=None,
+                    allocated_inv_amount=inv_line.amount,
+                    allocated_rate_amount=rate_item.unit_price,
+                )
+            )
+            line_matched_count += 1
+            continue
+
+        if rate_item.unit_price is None:
+            # Name match succeeded; price comparison is impossible. Treat as an
+            # advisory (not a hard exception) because the match itself is valid.
+            if "rate_card_match_no_price_compare" not in result.advisory_flags:
+                result.advisory_flags.append("rate_card_match_no_price_compare")
+            result.match_line_results.append(
+                ContractLineResult(
+                    invoice_line_id=inv_line.id,
+                    rate_card_item_id=rate_item.id,
+                    line_status="matched",
+                    line_zone="green",
+                    price_var_pct=None,
+                    allocated_inv_amount=inv_line.amount,
+                    allocated_rate_amount=None,
+                )
+            )
+            line_matched_count += 1
+            continue
+
+        p_var = price_variance_pct(inv_line.unit_price, rate_item.unit_price)
+        zone = _line_zone_from_price(p_var, rate_item.item_type, cfg)
+
+        if zone == "red":
+            result.match_exceptions.append(
+                MatchExceptionRecord(
+                    exception_type="rate_card_price_mismatch",
+                    line_id=inv_line.id,
+                    po_line_id=rate_item.id,
+                    exception_detail={
+                        "reason": "price_outside_tolerance",
+                        "invoice_line_id": inv_line.id,
+                        "rate_card_item_id": rate_item.id,
+                        "invoice_unit_price": str(inv_line.unit_price),
+                        "rate_card_unit_price": str(rate_item.unit_price),
+                        "price_var_pct": str(p_var),
+                    },
+                )
+            )
+            result.match_line_results.append(
+                ContractLineResult(
+                    invoice_line_id=inv_line.id,
+                    rate_card_item_id=rate_item.id,
+                    line_status="exception",
+                    line_zone="red",
+                    price_var_pct=p_var,
+                    allocated_inv_amount=inv_line.amount,
+                    allocated_rate_amount=rate_item.unit_price,
+                    exception_type="rate_card_price_mismatch",
+                )
+            )
+            line_exception_count += 1
+            continue
+
+        result.match_line_results.append(
+            ContractLineResult(
+                invoice_line_id=inv_line.id,
+                rate_card_item_id=rate_item.id,
+                line_status="matched",
+                line_zone=zone,
+                price_var_pct=p_var,
+                allocated_inv_amount=inv_line.amount,
+                allocated_rate_amount=rate_item.unit_price,
+            )
+        )
+        line_matched_count += 1
+
+    result.lines_matched = line_matched_count
+    result.lines_in_exception = line_exception_count + (len(inv_lines) - line_matched_count - line_exception_count)
+
+    # ---------------------------------------------------------
+    # Budget ceiling
+    # ---------------------------------------------------------
+    inv_currency = norm_currency(invoice.currency)
+    contract_currency = norm_currency(selected_contract.currency)
+
+    if contract_currency != inv_currency:
+        result.match_exceptions.append(
+            MatchExceptionRecord(
+                exception_type="contract_currency_mismatch",
+                exception_detail={
+                    "reason": "contract_currency_changed_or_mismatch",
+                    "invoice_currency": inv_currency,
+                    "contract_currency": contract_currency,
+                    "contract_id": selected_contract.id,
+                },
+            )
+        )
+        result.overall_status = "exception"
+        result.match_zone = "red"
+        return result
+
+    if invoice.total_amount is not None:
+        cumulative = selected_contract.cumulative_billed_amount or D0
+        total_value = selected_contract.total_value
+        if total_value is not None and (cumulative + invoice.total_amount) > total_value:
+            result.match_exceptions.append(
+                MatchExceptionRecord(
+                    exception_type="contract_budget_exceeded",
+                    exception_detail={
+                        "reason": "budget_ceiling_breached",
+                        "contract_id": selected_contract.id,
+                        "invoice_total_amount": str(invoice.total_amount),
+                        "cumulative_billed_amount": str(cumulative),
+                        "contract_total_value": str(total_value),
+                    },
+                )
+            )
+            result.overall_status = "exception"
+            result.match_zone = "red"
+            return result
+
+    # ---------------------------------------------------------
+    # Overall status / zone
+    # ---------------------------------------------------------
+    if any(exc.exception_type in {
+        "billing_period_unverified",
+        "billing_period_outside_contract",
+        "no_rate_card_configured",
+        "no_rate_card_match",
+        "rate_card_price_mismatch",
+        "contract_budget_exceeded",
+        "contract_currency_mismatch",
+    } for exc in result.match_exceptions):
+        # If any hard contract exception exists, keep it red.
+        if result.lines_matched > 0 and result.lines_in_exception > 0:
+            result.overall_status = "partial_match"
+        else:
+            result.overall_status = "exception"
+        result.match_zone = "red"
+    else:
+        if result.lines_matched == result.lines_total and result.lines_in_exception == 0:
+            result.overall_status = "matched"
+            result.match_zone = "amber" if any(r.line_zone == "amber" for r in result.match_line_results) else "green"
+        elif result.lines_matched > 0:
+            result.overall_status = "partial_match"
+            result.match_zone = "amber" if any(r.line_zone == "amber" for r in result.match_line_results) else "green"
+        else:
+            result.overall_status = "exception"
+            result.match_zone = "red"
+
+    return result

src/Matching Functions/invoice_pipeline.py

@@ -0,0 +1,342 @@
+"""
+Top-level invoice processing pipeline.
+
+Flow: validation → routing → matching → final result.
+
+No business logic lives here. Each step delegates entirely to its own module:
+  - Validation  : Invoice Validation Functions/orchestrator.py
+  - Routing     : match_router.py
+  - 2-way match : two_way_match.py
+  - 3-way match : three_way_match.py (layers on top of 2-way result)
+  - Contract    : contract_match.py
+
+Caller responsibilities (not enforced here):
+  - Acquire the advisory lock before calling (SDD §3.1).
+  - Pre-fetch po, po_lines, gr_rows from the database.
+  - Construct matching_invoice (InvoiceHeader) and matching_inv_lines.
+  - Construct contract_invoice (ContractInvoiceHeader) when contract match is possible.
+  - Handle prior-match supersession in the database after this call returns (SDD §3.5).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+from typing import Any, Optional
+
+# ============================================================
+# Load validation orchestrator by path
+# (the directory name contains spaces, so importlib is required)
+# ============================================================
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_VALIDATION_DIR = os.path.normpath(os.path.join(_HERE, "..", "Invoice Validation Functions"))
+
+
+def _load_module_by_path(filepath: str, module_name: str):
+    spec = importlib.util.spec_from_file_location(module_name, filepath)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_val_orch = _load_module_by_path(
+    os.path.join(_VALIDATION_DIR, "orchestrator.py"),
+    "_validation_orchestrator",
+)
+_run_validation_pipeline = _val_orch.run_invoice_validation_pipeline
+
+
+# ============================================================
+# Matching layer imports
+# ============================================================
+
+from match_router import (
+    MatchPreconditionError,
+    RouteDecision,
+    RoutingDocument,
+    RoutingExtractedFields,
+    route_invoice,
+)
+from two_way_match import (
+    InvoiceHeader,
+    InvoiceLine,
+    MatchExceptionRecord,
+    POHeader,
+    POLine,
+    run_two_way_match_core,
+)
+from three_way_match import GRLineItem, run_three_way_match
+from contract_match import (
+    ContractInvoiceHeader,
+    ContractMatchResult,
+    run_contract_match_core,
+)
+
+
+# ============================================================
+# Config loader
+# ============================================================
+
+def _load_matching_configs(path: Optional[str] = None) -> dict:
+    if path is None:
+        path = os.path.join(_HERE, "matching_configs.json")
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+# ============================================================
+# Internal helpers
+# ============================================================
+
+def _stub_missing_contract_invoice(inv_lines: list[InvoiceLine]) -> ContractMatchResult:
+    """Returned when contract route is selected but contract_invoice was not provided."""
+    res = ContractMatchResult(
+        match_type="contract",
+        overall_status="exception",
+        match_zone="red",
+        documents_status="pending_approval",
+        lines_total=len(inv_lines),
+        lines_matched=0,
+        lines_in_exception=len(inv_lines),
+    )
+    res.header_exceptions.append(
+        MatchExceptionRecord(
+            exception_type="cannot_match_missing_contract_invoice",
+            exception_detail={"reason": "contract_invoice_not_provided_to_pipeline"},
+        )
+    )
+    return res
+
+
+def _collect_match_flags(match_result: Any) -> tuple[list, list, list]:
+    """Extract risk_flags, advisory_flags, skipped_steps from a match result."""
+    if match_result is None:
+        return [], [], []
+    return (
+        list(getattr(match_result, "risk_flags", None) or []),
+        list(getattr(match_result, "advisory_flags", None) or []),
+        list(getattr(match_result, "skipped_steps", None) or []),
+    )
+
+
+def _compute_final_status(validation_risk_flags: list, match_result: Any) -> str:
+    """
+    Derive a single final status from both validation and match outcomes.
+    Any validation risk flag is treated as an exception regardless of match result.
+    """
+    if validation_risk_flags:
+        return "exception"
+    if match_result is None:
+        return "exception"
+    return getattr(match_result, "overall_status", "exception")
+
+
+# ============================================================
+# Top-level pipeline
+# ============================================================
+
+def run_invoice_pipeline(
+    *,
+    # --- Validation inputs ---
+    document,
+    extracted_fields,
+    vendors,
+    vendor_bank_accounts,
+    vendor_tax_ids,
+    entity,
+    line_items,
+    purchase_orders,
+    contracts,
+    tax_master_rows,
+    currency_seed_map,
+    platform_configs: Optional[dict] = None,
+    route_contexts=None,
+    actor_id=None,
+    # --- Matching inputs ---
+    matching_invoice: InvoiceHeader,
+    matching_inv_lines: list[InvoiceLine],
+    contract_invoice: Optional[ContractInvoiceHeader] = None,
+    po: Optional[POHeader] = None,
+    po_lines: Optional[list[POLine]] = None,
+    gr_rows: Optional[list[GRLineItem]] = None,
+    matching_configs: Optional[dict] = None,
+) -> dict[str, Any]:
+    """
+    Run the full invoice processing pipeline and return a single combined result.
+
+    Parameters
+    ----------
+    document              : Invoice document object (.id, .tenant_id, .entity_id,
+                            .status, .doc_type required for routing).
+    extracted_fields      : VLM-extracted fields (.po_number_canonical used for routing).
+    vendors               : Vendor records for vendor validation.
+    vendor_bank_accounts  : Vendor bank account records.
+    vendor_tax_ids        : Vendor tax-ID records.
+    entity                : Routing entity (.country_code, .vat_id, .region_code).
+    line_items            : Invoice line-item records (for validation).
+    purchase_orders       : Purchase-order records (for payment-terms validation).
+    contracts             : Contract records (for payment-terms validation and contract match).
+    tax_master_rows       : Tax-master records.
+    currency_seed_map     : Dict mapping ISO currency code → minor-unit row.
+    platform_configs      : Validation config dict; loaded from platform_configs.json if None.
+    route_contexts        : Route-context strings forwarded to Vendor Validation.
+    actor_id              : Actor identifier forwarded to Vendor Validation for audit.
+    matching_invoice      : InvoiceHeader for 2-way / 3-way matching.
+    matching_inv_lines    : Invoice lines for all match types.
+    contract_invoice      : ContractInvoiceHeader for contract matching (optional).
+    po                    : Pre-fetched POHeader; None if no PO number on the invoice.
+    po_lines              : Pre-fetched PO lines; None if no PO.
+    gr_rows               : Pre-fetched GR rows; None or [] triggers 2-way instead of 3-way.
+    matching_configs      : Matching config dict; loaded from matching_configs.json if None.
+
+    Returns
+    -------
+    dict with keys:
+      validation_result  — raw dict from the validation pipeline
+      route              — 'two_way' | 'three_way' | 'contract' | 'credit_note' |
+                           'stub' | 'precondition_error'
+      match_result       — TwoWayMatchResult | ContractMatchResult | None
+      risk_flags         — combined validation + matching risk flags, in execution order
+      advisory_flags     — combined, in execution order
+      skipped_steps      — combined, in execution order
+      ops_alerts         — operational alerts from the validation layer
+      resolved_vendor_id — from vendor validation
+      final_status       — 'matched' | 'partial_match' | 'exception'
+    """
+
+    # ------------------------------------------------------------------
+    # Step 1 — Validation
+    # ------------------------------------------------------------------
+    validation_result = _run_validation_pipeline(
+        document=document,
+        extracted_fields=extracted_fields,
+        vendors=vendors,
+        vendor_bank_accounts=vendor_bank_accounts,
+        vendor_tax_ids=vendor_tax_ids,
+        entity=entity,
+        line_items=line_items,
+        purchase_orders=purchase_orders,
+        contracts=contracts,
+        tax_master_rows=tax_master_rows,
+        currency_seed_map=currency_seed_map,
+        platform_configs=platform_configs,
+        route_contexts=route_contexts,
+        actor_id=actor_id,
+    )
+
+    resolved_vendor_id = validation_result.get("resolved_vendor_id")
+    risk_flags: list    = list(validation_result.get("risk_flags")     or [])
+    advisory_flags: list = list(validation_result.get("advisory_flags") or [])
+    skipped_steps: list  = list(validation_result.get("skipped_steps")  or [])
+
+    # ------------------------------------------------------------------
+    # Step 2 — Routing
+    # ------------------------------------------------------------------
+    if matching_configs is None:
+        matching_configs = _load_matching_configs()
+
+    routing_doc = RoutingDocument(
+        id=getattr(document, "id", None),
+        tenant_id=getattr(document, "tenant_id", None),
+        entity_id=getattr(document, "entity_id", None),
+        status=getattr(document, "status", "validated"),
+        doc_type=getattr(document, "doc_type", "invoice"),
+    )
+    routing_ef = RoutingExtractedFields(
+        po_number_canonical=getattr(extracted_fields, "po_number_canonical", None),
+        resolved_vendor_id=resolved_vendor_id,
+    )
+
+    try:
+        decision: RouteDecision = route_invoice(
+            document=routing_doc,
+            ef=routing_ef,
+            inv_lines=matching_inv_lines,
+            po=po,
+            po_lines=po_lines,
+            gr_rows=gr_rows,
+        )
+    except MatchPreconditionError as exc:
+        return {
+            "validation_result": validation_result,
+            "route": "precondition_error",
+            "match_result": None,
+            "risk_flags": risk_flags,
+            "advisory_flags": advisory_flags,
+            "skipped_steps": skipped_steps,
+            "ops_alerts": list(validation_result.get("ops_alerts") or []),
+            "resolved_vendor_id": resolved_vendor_id,
+            "final_status": "exception",
+            "error": str(exc),
+        }
+
+    route = decision.route
+
+    # ------------------------------------------------------------------
+    # Step 3 — Matching
+    # ------------------------------------------------------------------
+    match_result: Any = None
+
+    if route == "stub":
+        match_result = decision.stub_result
+
+    elif route == "two_way":
+        match_result = run_two_way_match_core(
+            matching_invoice,
+            matching_inv_lines,
+            decision.po,
+            decision.po_lines or [],
+            matching_configs=matching_configs,
+        )
+
+    elif route == "three_way":
+        two_way_result = run_two_way_match_core(
+            matching_invoice,
+            matching_inv_lines,
+            decision.po,
+            decision.po_lines or [],
+            matching_configs=matching_configs,
+        )
+        match_result = run_three_way_match(
+            two_way_result,
+            matching_invoice,
+            matching_inv_lines,
+            decision.po_lines or [],
+            decision.gr_rows or [],
+            matching_configs=matching_configs,
+        )
+
+    elif route == "contract":
+        if contract_invoice is None:
+            match_result = _stub_missing_contract_invoice(matching_inv_lines)
+        else:
+            match_result = run_contract_match_core(
+                contract_invoice,
+                matching_inv_lines,
+                list(contracts),
+                matching_configs=matching_configs,
+            )
+
+    # ------------------------------------------------------------------
+    # Step 4 — Combine flags and return
+    # ------------------------------------------------------------------
+    m_risk, m_advisory, m_skipped = _collect_match_flags(match_result)
+    risk_flags.extend(m_risk)
+    advisory_flags.extend(m_advisory)
+    skipped_steps.extend(m_skipped)
+
+    return {
+        "validation_result": validation_result,
+        "route": route,
+        "match_result": match_result,
+        "risk_flags": risk_flags,
+        "advisory_flags": advisory_flags,
+        "skipped_steps": skipped_steps,
+        "ops_alerts": list(validation_result.get("ops_alerts") or []),
+        "resolved_vendor_id": resolved_vendor_id,
+        "final_status": _compute_final_status(
+            validation_result.get("risk_flags") or [], match_result
+        ),
+    }

src/Matching Functions/match_router.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional, Union
+
+from two_way_match import (
+    InvoiceLine,
+    MatchExceptionRecord,
+    POHeader,
+    POLine,
+    TwoWayMatchResult,
+)
+from three_way_match import GRLineItem
+from contract_match import ContractMatchResult
+
+
+# ============================================================
+# Precondition violation
+# ============================================================
+
+class MatchPreconditionError(Exception):
+    """Raised when document.status is not 'validated' or 'matching' (SDD §3.1)."""
+
+
+# ============================================================
+# Routing input models
+# ============================================================
+
+@dataclass(frozen=True)
+class RoutingDocument:
+    id: int
+    tenant_id: int
+    entity_id: int
+    status: str     # 'validated' | 'matching' — enforced by route_invoice
+    doc_type: str   # 'invoice' | 'credit_note' | ...
+
+
+@dataclass(frozen=True)
+class RoutingExtractedFields:
+    po_number_canonical: Optional[str]
+    resolved_vendor_id: Optional[int]
+
+
+# ============================================================
+# Routing decision
+# ============================================================
+
+MatchResult = Union[TwoWayMatchResult, ContractMatchResult]
+
+
+@dataclass
+class RouteDecision:
+    route: str                              # 'two_way' | 'three_way' | 'contract' | 'stub'
+    po: Optional[POHeader] = None          # populated for two_way / three_way
+    po_lines: Optional[list[POLine]] = None
+    gr_rows: Optional[list[GRLineItem]] = None  # populated for three_way
+    stub_result: Optional[MatchResult] = None   # populated when route='stub'
+
+
+# ============================================================
+# Stub builders (SDD §3.4)
+# ============================================================
+
+def _two_way_stub(
+    inv_lines: list[InvoiceLine],
+    exception_type: str,
+    exception_detail: dict[str, Any],
+) -> TwoWayMatchResult:
+    res = TwoWayMatchResult(
+        match_type="two_way",
+        overall_status="exception",
+        match_zone="red",
+        documents_status="pending_approval",
+        lines_total=len(inv_lines),
+        lines_matched=0,
+        lines_in_exception=len(inv_lines),
+    )
+    res.header_exceptions.append(
+        MatchExceptionRecord(
+            exception_type=exception_type,
+            exception_detail=exception_detail,
+        )
+    )
+    return res
+
+
+def _contract_stub(
+    inv_lines: list[InvoiceLine],
+    exception_type: str,
+    exception_detail: dict[str, Any],
+) -> ContractMatchResult:
+    res = ContractMatchResult(
+        match_type="contract",
+        overall_status="exception",
+        match_zone="red",
+        documents_status="pending_approval",
+        lines_total=len(inv_lines),
+        lines_matched=0,
+        lines_in_exception=len(inv_lines),
+    )
+    res.header_exceptions.append(
+        MatchExceptionRecord(
+            exception_type=exception_type,
+            exception_detail=exception_detail,
+        )
+    )
+    return res
+
+
+# ============================================================
+# Status sets
+# ============================================================
+
+_VALID_ENTRY_STATUSES = {"validated", "matching"}
+_PO_ACTIVE_STATUSES = {"open", "partial"}
+_PO_LINE_LIVE_STATUSES = {"open", "fully_invoiced"}
+_PO_LINE_DEAD_STATUSES = {"closed", "cancelled"}
+
+
+# ============================================================
+# Decision tree (SDD §3.3)
+# ============================================================
+
+def route_invoice(
+    document: RoutingDocument,
+    ef: RoutingExtractedFields,
+    inv_lines: list[InvoiceLine],
+    po: Optional[POHeader],
+    po_lines: Optional[list[POLine]],
+    gr_rows: Optional[list[GRLineItem]],
+) -> RouteDecision:
+    """
+    Deterministic match-type routing (SDD §3.3). First match wins.
+
+    Caller responsibilities:
+      - Acquire the advisory lock before calling (§3.1).
+      - Pre-fetch po / po_lines from the DB (pass None if po_number_canonical
+        is NULL or the PO row was not found).
+      - Pre-fetch gr_rows (pass empty list or None if no GR rows exist for the PO).
+      - After receiving RouteDecision, handle prior-match supersession (§3.5)
+        before dispatching to the match function.
+
+    Raises:
+      MatchPreconditionError — document.status not in {'validated', 'matching'} (§3.1).
+    """
+
+    # §3.1 — Entry precondition
+    if document.status not in _VALID_ENTRY_STATUSES:
+        raise MatchPreconditionError(
+            f"document {document.id} has status={document.status!r}; "
+            f"expected one of {sorted(_VALID_ENTRY_STATUSES)}"
+        )
+
+    # §3.3 rule 2 — PO-based routing
+    if ef.po_number_canonical is not None:
+        if po is None:
+            return RouteDecision(
+                route="stub",
+                stub_result=_two_way_stub(
+                    inv_lines,
+                    "po_not_found",
+                    {
+                        "reason": "no_purchase_order_matched_canonical",
+                        "tenant_id": document.tenant_id,
+                        "entity_id": document.entity_id,
+                        "po_number_canonical": ef.po_number_canonical,
+                    },
+                ),
+            )
+
+        if po.status == "cancelled":
+            return RouteDecision(
+                route="stub",
+                stub_result=_two_way_stub(
+                    inv_lines,
+                    "po_cancelled",
+                    {
+                        "reason": "purchase_order_is_cancelled",
+                        "po_id": po.id,
+                        "po_number_canonical": ef.po_number_canonical,
+                    },
+                ),
+            )
+
+        lines: list[POLine] = po_lines or []
+
+        if po.status == "closed" and all(
+            pl.status in _PO_LINE_DEAD_STATUSES for pl in lines
+        ):
+            return RouteDecision(
+                route="stub",
+                stub_result=_two_way_stub(
+                    inv_lines,
+                    "po_closed",
+                    {
+                        "reason": "purchase_order_closed_all_lines_dead",
+                        "po_id": po.id,
+                        "po_number_canonical": ef.po_number_canonical,
+                        "line_statuses": [pl.status for pl in lines],
+                    },
+                ),
+            )
+
+        # §3.3 table: open/partial + every line closed/cancelled → po_all_lines_closed
+        if po.status in _PO_ACTIVE_STATUSES and all(
+            pl.status in _PO_LINE_DEAD_STATUSES for pl in lines
+        ):
+            return RouteDecision(
+                route="stub",
+                stub_result=_two_way_stub(
+                    inv_lines,
+                    "po_all_lines_closed",
+                    {
+                        "reason": "all_po_lines_closed_or_cancelled",
+                        "po_id": po.id,
+                        "po_number_canonical": ef.po_number_canonical,
+                        "line_statuses": [pl.status for pl in lines],
+                    },
+                ),
+            )
+
+        # §3.3: at least one live line (open or fully_invoiced) must exist to proceed.
+        # fully_invoiced lines reach matching (not stub) so credit-note reversals and
+        # po_ceiling_exhausted can be raised correctly by §4 / §5.
+        has_live_line = any(pl.status in _PO_LINE_LIVE_STATUSES for pl in lines)
+        if not has_live_line:
+            return RouteDecision(
+                route="stub",
+                stub_result=_two_way_stub(
+                    inv_lines,
+                    "po_all_lines_closed",
+                    {
+                        "reason": "no_live_po_lines_found",
+                        "po_id": po.id,
+                        "po_number_canonical": ef.po_number_canonical,
+                        "line_statuses": [pl.status for pl in lines],
+                    },
+                ),
+            )
+
+        # §3.3: any GR row (any inspection_status) → three-way.
+        # §5 adjudicates no_accepted_gr / inspection_rejected / timing_fraud internally.
+        if gr_rows:
+            return RouteDecision(
+                route="three_way",
+                po=po,
+                po_lines=lines,
+                gr_rows=gr_rows,
+            )
+
+        return RouteDecision(
+            route="two_way",
+            po=po,
+            po_lines=lines,
+        )
+
+    # §3.3 rule 3 — No PO, no vendor anchor
+    if ef.resolved_vendor_id is None:
+        return RouteDecision(
+            route="stub",
+            stub_result=_contract_stub(
+                inv_lines,
+                "cannot_match_no_vendor",
+                {
+                    "reason": "resolved_vendor_id_is_null_and_no_po",
+                    "tenant_id": document.tenant_id,
+                    "entity_id": document.entity_id,
+                },
+            ),
+        )
+
+    # §3.3 rule 4 — No PO, vendor resolved → contract match
+    return RouteDecision(route="contract")

src/Matching Functions/matching_configs.json

@@ -0,0 +1,39 @@
+{
+    "_comment_two_way": "Two-way / three-way invoice-PO matching. All percentage thresholds are in % units (e.g. 5 means 5%).",
+
+    "tier3_price_variance_threshold": 0.10,
+
+    "price_goods_green": 5.0,
+    "price_goods_amber": 10.0,
+
+    "price_services_green": 10.0,
+    "price_services_amber": 15.0,
+
+    "qty_goods_green": 2.0,
+    "qty_goods_amber": 4.0,
+
+    "qty_services_green": 3.0,
+    "qty_services_amber": 6.0,
+
+    "tier4_gl_group_max_lines": 100,
+
+    "fuzzy_high_threshold": 90.0,
+    "fuzzy_medium_threshold": 80.0,
+    "fuzzy_score_cutoff": 80.0,
+
+    "precision": 28,
+
+    "_comment_contract": "Contract match configuration. Keys are prefixed 'contract_' to allow independent tuning from two-way bands.",
+
+    "contract_fuzzy_high_threshold": 90.0,
+    "contract_fuzzy_medium_threshold": 80.0,
+    "contract_fuzzy_score_cutoff": 80.0,
+
+    "contract_price_goods_green": 5.0,
+    "contract_price_goods_amber": 10.0,
+
+    "contract_price_services_green": 10.0,
+    "contract_price_services_amber": 15.0,
+
+    "contract_precision": 28
+}

src/Matching Functions/three_way_match.py

@@ -0,0 +1,416 @@
+from __future__ import annotations
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from typing import Any, Optional
+
+from two_way_match import (
+    InvoiceHeader,
+    InvoiceLine,
+    MatchExceptionRecord,
+    POLine,
+    TwoWayConfig,
+    TwoWayMatchResult,
+    _cfg_from_dict,
+    _qty_bands,
+    to_decimal,
+)
+
+D0 = Decimal("0")
+
+# ── New input dataclass ────────────────────────────────────────────────────────
+
+@dataclass
+class GRLineItem:
+    id:                 int
+    po_line_id:         Optional[int]
+    gr_date:            date             # DATE column, no timezone
+    inspection_status:  str              # 'accepted'|'partial_accept'|'rejected'|'pending'|'returned'
+    quantity_accepted:  Optional[Decimal]
+    quantity_received:  Optional[Decimal]
+    deleted_at:         Optional[Any] = None   # non-None → soft-deleted; excluded everywhere
+
+
+# ── Zone rank (adds 'critical' above 'red' for integrity signals) ──────────────
+
+_ZONE_RANK: dict[str, int] = {"green": 0, "amber": 1, "red": 2, "critical": 3}
+
+
+def _worse(a: Optional[str], b: str) -> str:
+    """Worst-wins comparator. critical > red > amber > green."""
+    return b if _ZONE_RANK.get(b, 0) > _ZONE_RANK.get(a or "green", 0) else (a or "green")
+
+
+def _push_zone(result: TwoWayMatchResult, inv_line_id: Optional[int], zone: str) -> None:
+    """Update a specific matched line's zone and the overall match_zone, worst-wins."""
+    if inv_line_id is not None:
+        for mlr in result.match_line_results:
+            if mlr.invoice_line_id == inv_line_id:
+                mlr.line_zone = _worse(mlr.line_zone, zone)
+    result.match_zone = _worse(result.match_zone, zone)
+
+
+# ── Private helpers ────────────────────────────────────────────────────────────
+
+def _uninvoiced_qty(
+    po_line: POLine,
+    accepted_by_po: dict[int, list[GRLineItem]],
+) -> Decimal:
+    """
+    SUM(quantity_accepted for accepted/partial_accept GRs on po_line) − po_line.invoiced_qty.
+    Raises RuntimeError on IDP17: quantity_accepted IS NULL on an accepted row.
+    Callers must NOT fall back to quantity_received — that would silently mask the violation.
+    """
+    rows = accepted_by_po.get(po_line.id, [])
+    for g in rows:
+        if g.quantity_accepted is None:
+            raise RuntimeError(
+                f"IDP17 violation: GR line id={g.id} inspection_status={g.inspection_status!r} "
+                "has quantity_accepted IS NULL."
+            )
+    total_accepted = sum((g.quantity_accepted for g in rows), D0)
+    return total_accepted - (to_decimal(po_line.invoiced_qty) or D0)
+
+
+def _band_verdict(
+    qty_over_pct: Decimal,
+    item_type: Optional[str],
+    cfg: TwoWayConfig,
+) -> Optional[str]:
+    """Return failing zone ('amber'|'red') if qty_over_pct exceeds tolerance, else None (pass)."""
+    qty_green, qty_amber = _qty_bands(item_type, cfg)   # reuses existing 2-way helper
+    if qty_over_pct == D0 or qty_over_pct <= qty_green:
+        return None
+    return "amber" if qty_over_pct <= qty_amber else "red"
+
+
+def _qty_check_single(
+    *,
+    inv_line: InvoiceLine,
+    po_line: POLine,
+    accepted_by_po: dict[int, list[GRLineItem]],
+    result: TwoWayMatchResult,
+    cfg: TwoWayConfig,
+) -> None:
+    """§5.3 quantity-over-received check for one Tier 1-3 (inv_line, po_line) direct match."""
+
+    # Pre-band guard 1: missing invoice qty — Cat 2 incomplete_fields already owns this flag
+    if inv_line.quantity is None:
+        result.skipped_steps.append({
+            "step": "qty_over_received",
+            "skip_reason": "inv_qty_null",
+            "line_id": inv_line.id,
+            "po_line_id": po_line.id,
+        })
+        return
+
+    uninvoiced = _uninvoiced_qty(po_line, accepted_by_po)
+
+    # Pre-band guard 2: negative uninvoiced → IDP17 forensic exception, zone red
+    if uninvoiced < D0:
+        result.match_exceptions.append(MatchExceptionRecord(
+            exception_type="qty_over_received",
+            line_id=inv_line.id,
+            po_line_id=po_line.id,
+            exception_detail={
+                "reason": "uninvoiced_accepted_qty_negative",
+                "uninvoiced_accepted_qty": str(uninvoiced),
+            },
+        ))
+        _push_zone(result, inv_line.id, "red")
+        result.overall_status = "exception"
+        return
+
+    inv_qty = inv_line.quantity
+
+    # Pre-band guard 3/4: uninvoiced == 0
+    if uninvoiced == D0:
+        if inv_qty > D0:
+            # All accepted GR qty already consumed by prior approved invoices
+            result.match_exceptions.append(MatchExceptionRecord(
+                exception_type="gr_fully_consumed",
+                line_id=inv_line.id,
+                po_line_id=po_line.id,
+                exception_detail={"reason": "gr_fully_consumed", "inv_qty": str(inv_qty)},
+            ))
+            _push_zone(result, inv_line.id, "red")
+            result.overall_status = "exception"
+        # inv_qty == 0 → noise line ($0 line), skip silently
+        return
+
+    # Band evaluation
+    qty_over_pct = max(D0, (inv_qty - uninvoiced) / uninvoiced * Decimal("100"))
+    zone = _band_verdict(qty_over_pct, po_line.item_type, cfg)
+    if zone:
+        result.match_exceptions.append(MatchExceptionRecord(
+            exception_type="qty_over_received",
+            line_id=inv_line.id,
+            po_line_id=po_line.id,
+            exception_detail={
+                "reason": "qty_over_received",
+                "qty_over_pct": str(qty_over_pct),
+                "inv_qty": str(inv_qty),
+                "uninvoiced_accepted_qty": str(uninvoiced),
+            },
+        ))
+        _push_zone(result, inv_line.id, zone)
+        result.overall_status = "exception"
+
+
+def _qty_check_tier4_group(
+    *,
+    gl_account: Optional[str],
+    group_inv_lines: list[InvoiceLine],
+    group_po_lines: list[POLine],
+    accepted_by_po: dict[int, list[GRLineItem]],
+    accepted_gr: list[GRLineItem],        # full accepted list — needed to detect no-GR vs consumed
+    result: TwoWayMatchResult,
+    cfg: TwoWayConfig,
+) -> None:
+    """
+    §5.6 aggregate GR quantity check for one Tier-4 GL group.
+    Partitions PO lines into goods / services subsets.
+    NULL-item-type PO lines are excluded from both (no GR obligation by default).
+    The quantity comparison is conservative: ALL inv-line qty (goods+services) vs
+    ONLY the goods-subset uninvoiced accepted qty.
+    """
+    po_goods    = [pl for pl in group_po_lines if pl.item_type == "goods"]
+    po_services = [pl for pl in group_po_lines if pl.item_type == "services"]
+
+    if not po_goods:
+        return      # 100 % services or all NULL item_type → no GR obligation for this group
+
+    goods_ids = {pl.id for pl in po_goods}
+
+    # IDP17 violations surface here via RuntimeError from _uninvoiced_qty
+    uninvoiced_goods = sum((_uninvoiced_qty(pl, accepted_by_po) for pl in po_goods), D0)
+
+    # Total invoice qty over the WHOLE group (conservative: includes services portion)
+    inv_qty_total = sum(
+        (il.quantity for il in group_inv_lines if il.quantity is not None), D0
+    )
+
+    inv_ids = [il.id for il in group_inv_lines]
+
+    base_detail: dict[str, Any] = {
+        "group_gl_account":              gl_account,
+        "po_lines_goods":                sorted(goods_ids),
+        "po_lines_services":             [pl.id for pl in po_services],
+        "uninvoiced_accepted_qty_goods": str(uninvoiced_goods),
+        "inv_qty_total":                 str(inv_qty_total),
+    }
+
+    # Pre-band guard: negative uninvoiced_goods → IDP17 forensic
+    if uninvoiced_goods < D0:
+        result.match_exceptions.append(MatchExceptionRecord(
+            exception_type="qty_over_received",
+            exception_detail={**base_detail, "reason": "uninvoiced_accepted_qty_negative"},
+        ))
+        for il_id in inv_ids:
+            _push_zone(result, il_id, "red")
+        result.overall_status = "exception"
+        return
+
+    # Pre-band guard: uninvoiced_goods == 0
+    if uninvoiced_goods == D0:
+        # Distinguish "no accepted GRs for goods lines yet" from "fully consumed"
+        has_accepted_gr_for_goods = any(g.po_line_id in goods_ids for g in accepted_gr)
+        exc_type = "gr_fully_consumed" if has_accepted_gr_for_goods else "no_accepted_gr"
+        if inv_qty_total > D0:
+            result.match_exceptions.append(MatchExceptionRecord(
+                exception_type=exc_type,
+                exception_detail={**base_detail, "reason": exc_type},
+            ))
+            for il_id in inv_ids:
+                _push_zone(result, il_id, "red")
+            result.overall_status = "exception"
+        # inv_qty_total == 0 → noise group, skip silently
+        return
+
+    # Band evaluation (always uses "goods" tolerance for mixed groups — §5.6 conservative choice)
+    qty_over_pct = max(D0, (inv_qty_total - uninvoiced_goods) / uninvoiced_goods * Decimal("100"))
+    zone = _band_verdict(qty_over_pct, "goods", cfg)
+    if zone:
+        result.match_exceptions.append(MatchExceptionRecord(
+            exception_type="qty_over_received",
+            exception_detail={
+                **base_detail,
+                "subset_breakdown": {"qty_over_pct": str(qty_over_pct)},
+            },
+        ))
+        for il_id in inv_ids:
+            _push_zone(result, il_id, zone)
+        result.overall_status = "exception"
+
+
+# ── Public entry point ─────────────────────────────────────────────────────────
+
+def run_three_way_match(
+    two_way_result: TwoWayMatchResult,
+    invoice: InvoiceHeader,           # must have invoice_date: Optional[date]
+    inv_lines: list[InvoiceLine],
+    po_lines: list[POLine],
+    gr_lines: list[GRLineItem],
+    *,
+    matching_configs: Optional[dict] = None,
+) -> TwoWayMatchResult:
+    """
+    Layers GR checks (§5.1–5.6) on top of an already-completed 2-way match result.
+    Always sets match_type='three_way'.
+
+    Check order (stop-on-fire for checks 1-3):
+        1. no_accepted_gr        — stop if no accepted/partial_accept GRs exist
+        2. invoice_before_gr     — stop if invoice pre-dates earliest accepted GR; zone→critical
+        3. gr_inspection_rejected — stop if any routed GR row has status='rejected'
+        4. qty_over_received     — per matched PO line (Tier 1-3) or GL group (Tier 4)
+
+    2-way line counts (lines_total / lines_matched / lines_in_exception) are never modified;
+    only match_zone, individual line_zone fields, match_exceptions, and overall_status change.
+    """
+    cfg = _cfg_from_dict(matching_configs or {})
+
+    result = two_way_result
+    result.match_type = "three_way"
+
+    inv_by_id: dict[int, InvoiceLine] = {il.id: il for il in inv_lines}
+    po_by_id:  dict[int, POLine]      = {pl.id: pl for pl in po_lines}
+
+    # Collect matched pairs from 2-way, split by tier
+    tier1_3: list[tuple[int, int]] = []
+    tier4:   list[tuple[int, int]] = []
+    for mlr in result.match_line_results:
+        if mlr.line_status != "matched":
+            continue
+        (tier4 if mlr.match_tier == 4 else tier1_3).append(
+            (mlr.invoice_line_id, mlr.po_line_id)
+        )
+
+    all_po_ids: set[int] = {po_id for _, po_id in tier1_3 + tier4}
+    if not all_po_ids:
+        return result   # nothing matched in 2-way; nothing to GR-check
+
+    # Route GR rows to matched PO lines.
+    # Exclude: soft-deleted rows, and 'returned' rows (those belong to credit-note matching §5.5).
+    routed = [
+        g for g in gr_lines
+        if g.po_line_id in all_po_ids
+        and g.deleted_at is None
+        and g.inspection_status != "returned"
+    ]
+
+    # ── Check 1: no accepted GR ────────────────────────────────────────────────
+    # Timing-fraud source set: accepted / partial_accept only (§5.1)
+    accepted = [g for g in routed if g.inspection_status in ("accepted", "partial_accept")]
+    if not accepted:
+        result.match_exceptions.append(MatchExceptionRecord(
+            exception_type="no_accepted_gr",
+            exception_detail={"reason": "no_accepted_gr",
+                              "matched_po_line_ids": sorted(all_po_ids)},
+        ))
+        result.overall_status = "exception"
+        return result
+
+    # ── Check 2: timing fraud ─────────────────────────────────────────────────
+    # Skip if invoice_date IS NULL (Cat 2 incomplete_fields already owns missing date).
+    if invoice.invoice_date is not None:
+        earliest_gr_date = min(g.gr_date for g in accepted)   # DATE-level comparison
+        if invoice.invoice_date < earliest_gr_date:
+            result.match_exceptions.append(MatchExceptionRecord(
+                exception_type="invoice_before_gr",
+                exception_detail={
+                    "reason":             "invoice_before_gr",
+                    "invoice_date":       str(invoice.invoice_date),
+                    "earliest_gr_date":   str(earliest_gr_date),
+                },
+            ))
+            result.risk_flags.append("invoice_before_gr")
+            result.match_zone     = "critical"    # §8.3 — integrity signal overrides normal zones
+            result.overall_status = "exception"
+            return result
+
+    # ── Check 3: inspection rejection ─────────────────────────────────────────
+    # Source set: ALL routed non-returned GR rows (§5.1) — rejected status fires regardless of
+    # whether the PO line also has accepted GRs.
+    rejected = [g for g in routed if g.inspection_status == "rejected"]
+    if rejected:
+        result.match_exceptions.append(MatchExceptionRecord(
+            exception_type="gr_inspection_rejected",
+            exception_detail={
+                "reason":           "gr_inspection_rejected",
+                "rejected_gr_ids":  sorted(g.id for g in rejected),
+            },
+        ))
+        result.overall_status = "exception"
+        return result
+
+    # ── Check 4: quantity over-received ────────────────────────────���──────────
+    # Build accepted-GR index per PO line, FIFO-ordered (gr_date ASC, id ASC).
+    # This ordering is analytical only — nothing is physically decremented (§5.4).
+    accepted_by_po: dict[int, list[GRLineItem]] = defaultdict(list)
+    for g in accepted:
+        if g.po_line_id is not None:
+            accepted_by_po[g.po_line_id].append(g)
+    for rows in accepted_by_po.values():
+        rows.sort(key=lambda g: (g.gr_date, g.id))
+
+    # Tier 1-3: one check per direct (inv_line, po_line) match
+    for inv_id, po_id in tier1_3:
+        il = inv_by_id.get(inv_id)
+        pl = po_by_id.get(po_id)
+        if il is None or pl is None:
+            continue
+        if pl.item_type in (None, "services"):
+            continue    # services and NULL-typed lines have no GR obligation
+        try:
+            _qty_check_single(
+                inv_line=il, po_line=pl,
+                accepted_by_po=accepted_by_po,
+                result=result, cfg=cfg,
+            )
+        except RuntimeError as exc:
+            result.match_exceptions.append(MatchExceptionRecord(
+                exception_type="data_integrity_violation",
+                line_id=inv_id,
+                po_line_id=po_id,
+                exception_detail={"reason": "idp17_quantity_accepted_null", "detail": str(exc)},
+            ))
+            _push_zone(result, inv_id, "red")
+            result.overall_status = "exception"
+
+    # Tier 4: aggregate check per GL group (§5.6)
+    if tier4:
+        # Reconstruct GL groups from inv_line.gl_account
+        gl_groups: dict[str, dict[str, set]] = defaultdict(
+            lambda: {"inv": set(), "po": set()}
+        )
+        for inv_id, po_id in tier4:
+            il = inv_by_id.get(inv_id)
+            if il is None:
+                continue
+            key = il.gl_account or "__null__"
+            gl_groups[key]["inv"].add(inv_id)
+            gl_groups[key]["po"].add(po_id)
+
+        for gl_key, ids in gl_groups.items():
+            try:
+                _qty_check_tier4_group(
+                    gl_account     = None if gl_key == "__null__" else gl_key,
+                    group_inv_lines= [inv_by_id[i] for i in ids["inv"] if i in inv_by_id],
+                    group_po_lines = [po_by_id[i]  for i in ids["po"]  if i in po_by_id],
+                    accepted_by_po = accepted_by_po,
+                    accepted_gr    = accepted,
+                    result=result, cfg=cfg,
+                )
+            except RuntimeError as exc:
+                result.match_exceptions.append(MatchExceptionRecord(
+                    exception_type="data_integrity_violation",
+                    exception_detail={
+                        "reason": "idp17_quantity_accepted_null",
+                        "gl_account": None if gl_key == "__null__" else gl_key,
+                        "detail": str(exc),
+                    },
+                ))
+                result.overall_status = "exception"
+
+    return result

src/Matching Functions/two_way_match.py

@@ -0,0 +1,1025 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal, ROUND_HALF_EVEN, getcontext
+from typing import Any, Callable, Optional
+import re
+import unicodedata
+
+from rapidfuzz import fuzz
+
+
+# ============================================================
+# Decimal / arithmetic hygiene
+# ============================================================
+getcontext().prec = 28
+getcontext().rounding = ROUND_HALF_EVEN
+
+D0 = Decimal("0")
+D100 = Decimal("100")
+
+
+# ============================================================
+# Data models
+# ============================================================
+@dataclass(frozen=True)
+class InvoiceLine:
+    id: int
+    description: Optional[str] = None
+    description_canonical: Optional[str] = None
+    sku: Optional[str] = None
+    sku_canonical: Optional[str] = None
+    gl_account: Optional[str] = None
+    quantity: Optional[Decimal] = None
+    unit_price: Optional[Decimal] = None
+    amount: Optional[Decimal] = None
+
+
+@dataclass(frozen=True)
+class POLine:
+    id: int
+    description: Optional[str] = None
+    description_canonical: Optional[str] = None
+    sku: Optional[str] = None
+    sku_canonical: Optional[str] = None
+    gl_account: Optional[str] = None
+    quantity: Optional[Decimal] = None
+    invoiced_qty: Optional[Decimal] = None
+    unit_price: Optional[Decimal] = None
+    item_type: Optional[str] = None  # 'goods' | 'services' | None
+    status: str = "open"             # 'open' | 'fully_invoiced' | 'closed' | 'cancelled'
+    deleted_at: Any = None
+
+
+@dataclass(frozen=True)
+class POHeader:
+    id: int
+    vendor_id: Optional[int] = None
+    currency: Optional[str] = None
+    status: str = "open"
+    deleted_at: Any = None
+
+
+@dataclass(frozen=True)
+class InvoiceHeader:
+    id: int
+    status: str
+    vendor_id: Optional[int] = None
+    currency: Optional[str] = None
+    total_amount: Optional[Decimal] = None
+    advisory_flags: tuple[str, ...] = ()
+    doc_type: str = "invoice"
+    tenant_id: Optional[int] = None
+    invoice_date: Optional[date] = None
+
+
+@dataclass
+class MatchExceptionRecord:
+    exception_type: str
+    line_id: Optional[int] = None
+    po_line_id: Optional[int] = None
+    exception_detail: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MatchLineResult:
+    invoice_line_id: int
+    po_line_id: Optional[int]
+    match_tier: int
+    allocated_inv_amount: Optional[Decimal] = None
+    allocated_po_amount: Optional[Decimal] = None
+    price_var_pct: Optional[Decimal] = None
+    qty_var_pct: Optional[Decimal] = None
+    line_zone: str = "green"   # green | amber | red
+    line_status: str = "matched"  # matched | no_match | exception
+    match_type: str = "two_way"
+
+
+@dataclass
+class TwoWayMatchResult:
+    match_type: str = "two_way"
+    overall_status: str = "exception"  # matched | partial_match | exception
+    match_zone: str = "green"          # green | amber | red
+    documents_status: str = "pending_approval"
+
+    lines_total: int = 0
+    lines_matched: int = 0
+    lines_in_exception: int = 0
+
+    risk_flags: list[str] = field(default_factory=list)
+    advisory_flags: list[str] = field(default_factory=list)
+    skipped_steps: list[dict] = field(default_factory=list)
+    header_exceptions: list[MatchExceptionRecord] = field(default_factory=list)
+    match_exceptions: list[MatchExceptionRecord] = field(default_factory=list)
+    match_line_results: list[MatchLineResult] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class TwoWayConfig:
+    tier3_price_variance_threshold: Decimal = Decimal("0.10")
+
+    price_goods_green: Decimal = Decimal("5")
+    price_goods_amber: Decimal = Decimal("10")
+    price_services_green: Decimal = Decimal("10")
+    price_services_amber: Decimal = Decimal("15")
+
+    qty_goods_green: Decimal = Decimal("2")
+    qty_goods_amber: Decimal = Decimal("4")
+    qty_services_green: Decimal = Decimal("3")
+    qty_services_amber: Decimal = Decimal("6")
+
+    tier4_gl_group_max_lines: int = 100
+
+    fuzzy_high_threshold: float = 90.0
+    fuzzy_medium_threshold: float = 80.0
+    fuzzy_score_cutoff: float = 80.0
+
+    precision: int = 28
+
+
+def _cfg_from_dict(d: dict) -> TwoWayConfig:
+    """Build TwoWayConfig from matching_configs dict. Falls back to dataclass defaults for missing keys."""
+    def _d(key: str, default: str) -> Decimal:
+        return Decimal(str(d.get(key, default)))
+
+    def _i(key: str, default: int) -> int:
+        return int(d.get(key, default))
+
+    def _f(key: str, default: float) -> float:
+        return float(d.get(key, default))
+
+    return TwoWayConfig(
+        tier3_price_variance_threshold=_d("tier3_price_variance_threshold", "0.10"),
+        price_goods_green=_d("price_goods_green", "5"),
+        price_goods_amber=_d("price_goods_amber", "10"),
+        price_services_green=_d("price_services_green", "10"),
+        price_services_amber=_d("price_services_amber", "15"),
+        qty_goods_green=_d("qty_goods_green", "2"),
+        qty_goods_amber=_d("qty_goods_amber", "4"),
+        qty_services_green=_d("qty_services_green", "3"),
+        qty_services_amber=_d("qty_services_amber", "6"),
+        tier4_gl_group_max_lines=_i("tier4_gl_group_max_lines", 100),
+        fuzzy_high_threshold=_f("fuzzy_high_threshold", 90.0),
+        fuzzy_medium_threshold=_f("fuzzy_medium_threshold", 80.0),
+        fuzzy_score_cutoff=_f("fuzzy_score_cutoff", 80.0),
+        precision=_i("precision", 28),
+    )
+
+
+# ============================================================
+# Helper functions
+# ============================================================
+def to_decimal(value: Any) -> Optional[Decimal]:
+    if value is None or value == "":
+        return None
+    if isinstance(value, Decimal):
+        return value
+    return Decimal(str(value))
+
+
+def canonicalise_identifier(value: Optional[str]) -> Optional[str]:
+    """
+    NFKC + uppercase + strip non-alphanumeric.
+    """
+    if value is None:
+        return None
+    value = unicodedata.normalize("NFKC", str(value)).upper()
+    value = re.sub(r"[^A-Z0-9]+", "", value)
+    return value or None
+
+
+def norm_currency(value: Optional[str]) -> Optional[str]:
+    return value.upper().strip() if value else None
+
+
+def price_variance_pct(inv_price: Optional[Decimal], po_price: Optional[Decimal]) -> Optional[Decimal]:
+    """
+    abs(inv - po) / po * 100
+    Skip if invoice price is NULL or po price is NULL or po price == 0.
+    """
+    if inv_price is None or po_price is None or po_price == 0:
+        return None
+    return (abs(inv_price - po_price) / po_price * D100).quantize(Decimal("0.0001"))
+
+
+def qty_over_pct(inv_qty: Optional[Decimal], available_qty: Optional[Decimal]) -> Optional[Decimal]:
+    """
+    max(0, (inv_qty - available_qty) / available_qty * 100)
+    Skip if inv_qty is NULL or available_qty is NULL/zero.
+    """
+    if inv_qty is None or available_qty is None or available_qty == 0:
+        return None
+    return (max(D0, (inv_qty - available_qty) / available_qty * D100)).quantize(Decimal("0.0001"))
+
+
+def available_qty(po_line: POLine) -> Decimal:
+    q = to_decimal(po_line.quantity) or D0
+    iq = to_decimal(po_line.invoiced_qty) or D0
+    return q - iq
+
+
+def remaining_po_value(po_lines: list[POLine]) -> Decimal:
+    total = D0
+    for line in po_lines:
+        if line.deleted_at is not None:
+            continue
+        if line.status != "open":
+            continue
+        q = to_decimal(line.quantity) or D0
+        iq = to_decimal(line.invoiced_qty) or D0
+        up = to_decimal(line.unit_price) or D0
+        total += (q - iq) * up
+    return total
+
+
+def same_vendor_merge_chain(
+    invoice_vendor_id: Optional[int],
+    po_vendor_id: Optional[int],
+    merge_chain_fn: Optional[Callable[[Optional[int], Optional[int]], bool]] = None,
+) -> bool:
+    if invoice_vendor_id is None or po_vendor_id is None:
+        return False
+    if merge_chain_fn is not None:
+        return bool(merge_chain_fn(invoice_vendor_id, po_vendor_id))
+    return invoice_vendor_id == po_vendor_id
+
+
+def zone_from_pct(
+    price_pct: Optional[Decimal],
+    qty_pct: Optional[Decimal],
+    item_type: Optional[str],
+    cfg: TwoWayConfig,
+) -> str:
+    """
+    Worst-wins among price and qty, ignoring NULL dimensions.
+    green -> amber -> red
+    """
+    item_type = (item_type or "services").lower()
+
+    if item_type == "goods":
+        price_green, price_amber = cfg.price_goods_green, cfg.price_goods_amber
+        qty_green, qty_amber = cfg.qty_goods_green, cfg.qty_goods_amber
+    else:
+        price_green, price_amber = cfg.price_services_green, cfg.price_services_amber
+        qty_green, qty_amber = cfg.qty_services_green, cfg.qty_services_amber
+
+    def single_zone(pct: Optional[Decimal], green: Decimal, amber: Decimal) -> Optional[str]:
+        if pct is None:
+            return None
+        if pct <= green:
+            return "green"
+        if pct <= amber:
+            return "amber"
+        return "red"
+
+    zones = [
+        single_zone(price_pct, price_green, price_amber),
+        single_zone(qty_pct, qty_green, qty_amber),
+    ]
+    zones = [z for z in zones if z is not None]
+
+    if not zones:
+        return "green"
+    if "red" in zones:
+        return "red"
+    if "amber" in zones:
+        return "amber"
+    return "green"
+
+
+def worse_zone(a: str, b: str) -> str:
+    rank = {"green": 0, "amber": 1, "red": 2}
+    return a if rank[a] >= rank[b] else b
+
+
+def _price_bands(item_type: Optional[str], cfg: TwoWayConfig) -> tuple[Decimal, Decimal]:
+    item_type = (item_type or "services").lower()
+    if item_type == "goods":
+        return cfg.price_goods_green, cfg.price_goods_amber
+    return cfg.price_services_green, cfg.price_services_amber
+
+
+def _qty_bands(item_type: Optional[str], cfg: TwoWayConfig) -> tuple[Decimal, Decimal]:
+    item_type = (item_type or "services").lower()
+    if item_type == "goods":
+        return cfg.qty_goods_green, cfg.qty_goods_amber
+    return cfg.qty_services_green, cfg.qty_services_amber
+
+
+def rapidfuzz_best_description_match(
+    query: str,
+    candidates: list[dict[str, Any]],
+    *,
+    high_threshold: float = 90.0,
+    medium_threshold: float = 80.0,
+    score_cutoff: float = 80.0,
+) -> dict[str, Any]:
+    """
+    Returns:
+    {
+        "decision": "matched" | "suggestion" | "unmatched",
+        "score_tier": "high" | "medium" | "low" | None,
+        "score": float,
+        "record_id": int | None
+    }
+    """
+    if not query or not candidates:
+        return {
+            "decision": "unmatched",
+            "score_tier": None,
+            "score": 0.0,
+            "record_id": None,
+        }
+
+    best_record_id = None
+    best_score = 0.0
+
+    for cand in candidates:
+        record_id = cand.get("record_id")
+        names = cand.get("names") or []
+        for cand_name in names:
+            if not cand_name:
+                continue
+            score = float(
+                fuzz.WRatio(
+                    query,
+                    cand_name,
+                    score_cutoff=score_cutoff,
+                )
+            )
+            if score > best_score:
+                best_score = score
+                best_record_id = record_id
+
+    if best_record_id is None or best_score < score_cutoff:
+        return {
+            "decision": "unmatched",
+            "score_tier": None,
+            "score": 0.0,
+            "record_id": None,
+        }
+
+    if best_score >= high_threshold:
+        score_tier = "high"
+    elif best_score >= medium_threshold:
+        score_tier = "medium"
+    else:
+        score_tier = "low"
+
+    decision = "matched" if score_tier in {"high", "medium"} else "suggestion"
+
+    return {
+        "decision": decision,
+        "score_tier": score_tier,
+        "score": round(best_score, 2),
+        "record_id": best_record_id,
+    }
+
+
+# ============================================================
+# Main 2-way matching function
+# ============================================================
+def run_two_way_match_core(
+    invoice: InvoiceHeader,
+    inv_lines: list[InvoiceLine],
+    po: POHeader,
+    po_lines: list[POLine],
+    *,
+    matching_configs: Optional[dict] = None,
+    merge_chain_fn: Optional[Callable[[Optional[int], Optional[int]], bool]] = None,
+    lock_candidate_po_lines_fn: Optional[Callable[[list[int]], None]] = None,
+) -> TwoWayMatchResult:
+    """
+    Core 2-way matching engine.
+
+    Implements:
+    - entry precondition on invoice.status
+    - header checks: currency, vendor merge-chain aware, PO value ceiling advisory
+    - Tier 1: SKU exact canonical match
+    - Tier 2: RapidFuzz description match
+    - Tier 3: GL exact + price tolerance
+    - Tier 4: aggregate GL matching over residue
+    - variance computation and zones
+    - exceptions and advisory flags
+    - analytical pool consumption only (no DB writes)
+    """
+
+    cfg = _cfg_from_dict(matching_configs or {})
+    getcontext().prec = cfg.precision
+
+    result = TwoWayMatchResult()
+    result.lines_total = len(inv_lines)
+    result.advisory_flags = list(invoice.advisory_flags)
+
+    invoice_currency = norm_currency(invoice.currency)
+    po_currency = norm_currency(po.currency)
+
+    # ---------------------------------------------------------
+    # Entry preconditions
+    # ---------------------------------------------------------
+    if invoice.status not in {"validated", "matching"}:
+        raise ValueError(
+            f"Precondition violation: invoice.status={invoice.status!r} "
+            f"must be in ('validated', 'matching')."
+        )
+
+    # ---------------------------------------------------------
+    # Header Check 1: Currency
+    # ---------------------------------------------------------
+    currency_ok = True
+    if invoice_currency is None:
+        currency_ok = False
+        result.skipped_steps.append({"step": "currency_check", "skip_reason": "ef_currency_null"})
+    elif po_currency is None or invoice_currency != po_currency:
+        currency_ok = False
+        result.header_exceptions.append(
+            MatchExceptionRecord(
+                exception_type="currency_mismatch",
+                exception_detail={
+                    "invoice_currency": invoice_currency,
+                    "po_currency": po_currency,
+                },
+            )
+        )
+
+    # ---------------------------------------------------------
+    # Header Check 2: Vendor (merge-chain aware)
+    # ---------------------------------------------------------
+    vendor_ok = same_vendor_merge_chain(invoice.vendor_id, po.vendor_id, merge_chain_fn)
+    if not vendor_ok:
+        result.header_exceptions.append(
+            MatchExceptionRecord(
+                exception_type="vendor_mismatch",
+                exception_detail={
+                    "invoice_vendor_id": invoice.vendor_id,
+                    "po_vendor_id": po.vendor_id,
+                    "merge_chain_aware": bool(merge_chain_fn is not None),
+                },
+            )
+        )
+
+    # ---------------------------------------------------------
+    # Header Check 3: PO value ceiling (advisory only)
+    # ---------------------------------------------------------
+    if not currency_ok:
+        result.skipped_steps.append({"step": "po_value_ceiling", "skip_reason": "currency_mismatch_or_null"})
+    elif invoice.total_amount is not None:
+        rem_value = remaining_po_value(po_lines)
+        if invoice.total_amount > rem_value:
+            result.advisory_flags.append("exceeds_remaining_po_value_at_match")
+
+    # ---------------------------------------------------------
+    # Build matching pool
+    # ---------------------------------------------------------
+    pool: list[POLine] = [
+        pl for pl in po_lines
+        if pl.deleted_at is None and pl.status in {"open", "fully_invoiced"}
+    ]
+
+    # Optional lock hook for caller-side DB advisory locks
+    if lock_candidate_po_lines_fn is not None:
+        lock_candidate_po_lines_fn([pl.id for pl in sorted(pool, key=lambda x: x.id)])
+
+    consumed_po_line_ids: set[int] = set()
+
+    def pool_remaining() -> list[POLine]:
+        return [pl for pl in pool if pl.id not in consumed_po_line_ids]
+
+    def consume_po_line(po_line_id: int) -> None:
+        consumed_po_line_ids.add(po_line_id)
+
+    # ---------------------------------------------------------
+    # Tier 1-3 per-line waterfall
+    # ---------------------------------------------------------
+    residue_lines: list[InvoiceLine] = []
+    line_exception_map: dict[int, list[MatchExceptionRecord]] = {}
+    item_type_unresolved_flagged = False
+
+    def add_line_exception(line_id: int, exc: MatchExceptionRecord) -> None:
+        line_exception_map.setdefault(line_id, []).append(exc)
+        result.match_exceptions.append(exc)
+
+    for inv_line in inv_lines:
+        inv_sku_canon = inv_line.sku_canonical or canonicalise_identifier(inv_line.sku)
+        inv_desc_canon = inv_line.description_canonical or canonicalise_identifier(inv_line.description)
+
+        matched_this_line = False
+
+        # -------------------------
+        # Tier 1: SKU exact match
+        # -------------------------
+        if inv_sku_canon:
+            candidates = [
+                pl for pl in pool_remaining()
+                if (pl.sku_canonical or canonicalise_identifier(pl.sku)) == inv_sku_canon
+            ]
+            candidates.sort(key=lambda x: x.id)
+
+            if candidates:
+                chosen = candidates[0]
+                if chosen.item_type is None and not item_type_unresolved_flagged:
+                    result.advisory_flags.append("item_type_unresolved")
+                    item_type_unresolved_flagged = True
+                matched, line_result = _finalize_tier1_3_line_match(
+                    inv_line=inv_line,
+                    po_line=chosen,
+                    tier=1,
+                    cfg=cfg,
+                )
+                if matched:
+                    result.match_line_results.append(line_result)
+                    consume_po_line(chosen.id)
+                    matched_this_line = True
+                else:
+                    add_line_exception(
+                        inv_line.id,
+                        MatchExceptionRecord(
+                            exception_type="po_ceiling_exhausted",
+                            line_id=inv_line.id,
+                            po_line_id=chosen.id,
+                            exception_detail={
+                                "reason": "available_qty_zero_or_negative",
+                                "po_line_id": chosen.id,
+                            },
+                        ),
+                    )
+                    matched_this_line = True
+
+        if matched_this_line:
+            continue
+
+        # -------------------------
+        # Tier 2: RapidFuzz description match
+        # -------------------------
+        pool_now = pool_remaining()
+        if inv_desc_canon and pool_now:
+            tier2_candidates = [
+                {
+                    "record_id": pl.id,
+                    "names": [
+                        pl.description_canonical
+                        or canonicalise_identifier(pl.description)
+                        or ""
+                    ],
+                }
+                for pl in pool_now
+            ]
+            tier2_candidates = [c for c in tier2_candidates if c["names"][0]]
+
+            if tier2_candidates:
+                rf_result = rapidfuzz_best_description_match(
+                    query=inv_desc_canon,
+                    candidates=tier2_candidates,
+                    high_threshold=cfg.fuzzy_high_threshold,
+                    medium_threshold=cfg.fuzzy_medium_threshold,
+                    score_cutoff=cfg.fuzzy_score_cutoff,
+                )
+
+                if rf_result["decision"] == "matched" and rf_result["record_id"] is not None:
+                    chosen = next((pl for pl in pool_now if pl.id == rf_result["record_id"]), None)
+                    if chosen is not None:
+                        if chosen.item_type is None and not item_type_unresolved_flagged:
+                            result.advisory_flags.append("item_type_unresolved")
+                            item_type_unresolved_flagged = True
+                        matched, line_result = _finalize_tier1_3_line_match(
+                            inv_line=inv_line,
+                            po_line=chosen,
+                            tier=2,
+                            cfg=cfg,
+                        )
+                        if matched:
+                            result.match_line_results.append(line_result)
+                            consume_po_line(chosen.id)
+                            matched_this_line = True
+                        else:
+                            add_line_exception(
+                                inv_line.id,
+                                MatchExceptionRecord(
+                                    exception_type="po_ceiling_exhausted",
+                                    line_id=inv_line.id,
+                                    po_line_id=chosen.id,
+                                    exception_detail={
+                                        "reason": "available_qty_zero_or_negative",
+                                        "po_line_id": chosen.id,
+                                    },
+                                ),
+                            )
+                            matched_this_line = True
+
+        if matched_this_line:
+            continue
+
+        # -------------------------
+        # Tier 3: GL exact + price tolerance
+        # -------------------------
+        tier3_candidates: list[POLine] = []
+        if inv_line.gl_account is not None:
+            for pl in pool_remaining():
+                if pl.gl_account is None:
+                    continue
+                if inv_line.gl_account != pl.gl_account:
+                    continue
+                if pl.unit_price is None or pl.unit_price == 0:
+                    continue
+                tier3_candidates.append(pl)
+
+        tier3_candidates.sort(key=lambda x: x.id)
+
+        for chosen in tier3_candidates:
+            p_var = price_variance_pct(to_decimal(inv_line.unit_price), to_decimal(chosen.unit_price))
+            if p_var is None:
+                continue
+
+            if p_var <= (cfg.tier3_price_variance_threshold * D100):
+                if chosen.item_type is None and not item_type_unresolved_flagged:
+                    result.advisory_flags.append("item_type_unresolved")
+                    item_type_unresolved_flagged = True
+                matched, line_result = _finalize_tier1_3_line_match(
+                    inv_line=inv_line,
+                    po_line=chosen,
+                    tier=3,
+                    cfg=cfg,
+                )
+                if matched:
+                    result.match_line_results.append(line_result)
+                    consume_po_line(chosen.id)
+                    matched_this_line = True
+                else:
+                    add_line_exception(
+                        inv_line.id,
+                        MatchExceptionRecord(
+                            exception_type="po_ceiling_exhausted",
+                            line_id=inv_line.id,
+                            po_line_id=chosen.id,
+                            exception_detail={
+                                "reason": "available_qty_zero_or_negative",
+                                "po_line_id": chosen.id,
+                            },
+                        ),
+                    )
+                    matched_this_line = True
+                break
+
+        if matched_this_line:
+            continue
+
+        # No Tier 1-3 hit
+        residue_lines.append(inv_line)
+
+    # ---------------------------------------------------------
+    # Tier 4: Aggregate GL match on residue
+    # ---------------------------------------------------------
+    residue_lines_by_gl: dict[str, list[InvoiceLine]] = {}
+    for line in residue_lines:
+        if line.gl_account is None:
+            add_line_exception(
+                line.id,
+                MatchExceptionRecord(
+                    exception_type="no_match",
+                    line_id=line.id,
+                    exception_detail={
+                        "reason": "gl_account_null_tier4_skip",
+                    },
+                ),
+            )
+            continue
+        residue_lines_by_gl.setdefault(line.gl_account, []).append(line)
+
+    residue_po_lines = pool_remaining()
+    po_lines_by_gl: dict[str, list[POLine]] = {}
+    for pl in residue_po_lines:
+        if pl.gl_account is None:
+            continue
+        po_lines_by_gl.setdefault(pl.gl_account, []).append(pl)
+
+    for gl, group_inv_lines in residue_lines_by_gl.items():
+        group_po_lines = po_lines_by_gl.get(gl, [])
+        if not group_po_lines:
+            for il in group_inv_lines:
+                add_line_exception(
+                    il.id,
+                    MatchExceptionRecord(
+                        exception_type="no_match",
+                        line_id=il.id,
+                        exception_detail={
+                            "reason": "no_po_lines_in_same_gl_group",
+                            "gl_account": gl,
+                        },
+                    ),
+                )
+            continue
+
+        group_inv_lines.sort(key=lambda x: x.id)
+        group_po_lines.sort(key=lambda x: x.id)
+
+        # Tier 4 group cap
+        if len(group_inv_lines) > cfg.tier4_gl_group_max_lines:
+            for il in group_inv_lines:
+                add_line_exception(
+                    il.id,
+                    MatchExceptionRecord(
+                        exception_type="no_match",
+                        line_id=il.id,
+                        exception_detail={
+                            "reason": "tier4_group_cap_exceeded",
+                            "group_gl_account": gl,
+                            "group_line_count": len(group_inv_lines),
+                            "cap": cfg.tier4_gl_group_max_lines,
+                        },
+                    ),
+                )
+            continue
+
+        # Invoice amount sum
+        if all(il.amount is None for il in group_inv_lines):
+            for il in group_inv_lines:
+                add_line_exception(
+                    il.id,
+                    MatchExceptionRecord(
+                        exception_type="no_match",
+                        line_id=il.id,
+                        exception_detail={
+                            "reason": "all_invoice_amounts_null",
+                            "group_gl_account": gl,
+                        },
+                    ),
+                )
+            continue
+
+        invoice_sum = sum((il.amount if il.amount is not None else D0 for il in group_inv_lines), D0)
+
+        # PO group sum — SDD §4.3: status='open' only.
+        # any_goods checks all lines (fully_invoiced included) because goods-first is a
+        # type-classification rule, not an availability rule.
+        open_group_po_lines = [pl for pl in group_po_lines if pl.status == "open"]
+        po_group_sum = D0
+        any_goods = False
+        for pl in group_po_lines:
+            if (pl.item_type or "").lower() == "goods":
+                any_goods = True
+        for pl in open_group_po_lines:
+            rem_qty = available_qty(pl)
+            up = to_decimal(pl.unit_price)
+            if up is None:
+                continue
+            po_group_sum += rem_qty * up
+
+        if any(pl.item_type is None for pl in group_po_lines) and not item_type_unresolved_flagged:
+            result.advisory_flags.append("item_type_unresolved")
+            item_type_unresolved_flagged = True
+
+        if po_group_sum == 0:
+            all_zero_price = (
+                bool(open_group_po_lines)
+                and all((to_decimal(pl.unit_price) or D0) == D0 for pl in open_group_po_lines)
+            )
+            exc_type = "zero_price_po_line_at_match" if all_zero_price else "no_match"
+            for il in group_inv_lines:
+                add_line_exception(
+                    il.id,
+                    MatchExceptionRecord(
+                        exception_type=exc_type,
+                        line_id=il.id,
+                        exception_detail={
+                            "reason": "po_group_sum_zero",
+                            "group_gl_account": gl,
+                            "po_line_ids": [pl.id for pl in group_po_lines],
+                        },
+                    ),
+                )
+            continue
+
+        group_variance_pct = (abs(invoice_sum - po_group_sum) / po_group_sum * D100).quantize(Decimal("0.0001"))
+        group_item_type = "goods" if any_goods else "services"
+
+        # Quantity sanity (before accepting Tier 4)
+        inv_qty_sum = sum((to_decimal(il.quantity) or D0 for il in group_inv_lines), D0)
+        po_available_qty_sum = sum((available_qty(pl) for pl in group_po_lines), D0)
+
+        if inv_qty_sum > 0 and po_available_qty_sum > 0:
+            qty_var = qty_over_pct(inv_qty_sum, po_available_qty_sum)
+            if qty_var is not None:
+                _, qty_amber = _qty_bands(group_item_type, cfg)
+                if qty_var > qty_amber:
+                    for il in group_inv_lines:
+                        add_line_exception(
+                            il.id,
+                            MatchExceptionRecord(
+                                exception_type="no_match",
+                                line_id=il.id,
+                                exception_detail={
+                                    "reason": "tier4_qty_sanity_failed",
+                                    "group_gl_account": gl,
+                                    "inv_qty_sum": str(inv_qty_sum),
+                                    "po_available_qty_sum": str(po_available_qty_sum),
+                                    "qty_over_pct": str(qty_var),
+                                },
+                            ),
+                        )
+                    continue
+
+        # Price tolerance for Tier 4
+        price_green, price_amber = _price_bands(group_item_type, cfg)
+        if group_variance_pct <= price_amber:
+            # Match the whole group and persist deterministic proportional allocations.
+            for il in group_inv_lines:
+                il_amount = il.amount if il.amount is not None else D0
+
+                raw_allocations: list[tuple[POLine, Decimal]] = []
+                for pl in open_group_po_lines:
+                    rem_qty = available_qty(pl)
+                    up = to_decimal(pl.unit_price) or D0
+                    allocated_po_amount = rem_qty * up
+                    raw_allocations.append((pl, allocated_po_amount))
+
+                po_sum = sum((amt for _, amt in raw_allocations), D0)
+                if po_sum == 0:
+                    add_line_exception(
+                        il.id,
+                        MatchExceptionRecord(
+                            exception_type="zero_price_po_line_at_match",
+                            line_id=il.id,
+                            exception_detail={
+                                "reason": "po_sum_zero_in_allocation",
+                                "group_gl_account": gl,
+                                "po_line_ids": [pl.id for pl, _ in raw_allocations],
+                            },
+                        ),
+                    )
+                    continue
+
+                quant = Decimal("0.01")
+                alloc_rows: list[tuple[POLine, Decimal, Decimal]] = []
+                for pl, allocated_po_amount in raw_allocations:
+                    allocated_inv_amount = (allocated_po_amount / po_sum * il_amount).quantize(quant)
+                    alloc_rows.append((pl, allocated_po_amount, allocated_inv_amount))
+
+                allocated_inv_total = sum((row[2] for row in alloc_rows), D0)
+                residue = (il_amount - allocated_inv_total).quantize(quant)
+
+                if residue != 0:
+                    # Largest allocated PO amount, tie-break by smallest po_line.id
+                    target_idx = min(
+                        range(len(alloc_rows)),
+                        key=lambda i: (-alloc_rows[i][1], alloc_rows[i][0].id),
+                    )
+                    pl, a_po, a_inv = alloc_rows[target_idx]
+                    alloc_rows[target_idx] = (pl, a_po, (a_inv + residue).quantize(quant))
+
+                group_line_zone = "green" if group_variance_pct <= price_green else ("amber" if group_variance_pct <= price_amber else "red")
+
+                for pl, allocated_po_amount, allocated_inv_amount in alloc_rows:
+                    result.match_line_results.append(
+                        MatchLineResult(
+                            invoice_line_id=il.id,
+                            po_line_id=pl.id,
+                            match_tier=4,
+                            allocated_inv_amount=allocated_inv_amount,
+                            allocated_po_amount=allocated_po_amount.quantize(Decimal("0.01")),
+                            price_var_pct=group_variance_pct,
+                            qty_var_pct=None,
+                            line_zone=group_line_zone,
+                            line_status="matched",
+                            match_type="two_way",
+                        )
+                    )
+
+                for pl in group_po_lines:
+                    consume_po_line(pl.id)
+
+            continue
+
+        # Outside tolerance -> no_match for every invoice line in the group
+        for il in group_inv_lines:
+            add_line_exception(
+                il.id,
+                MatchExceptionRecord(
+                    exception_type="no_match",
+                    line_id=il.id,
+                    exception_detail={
+                        "reason": "tier4_outside_tolerance",
+                        "group_gl_account": gl,
+                        "invoice_sum": str(invoice_sum),
+                        "po_sum": str(po_group_sum),
+                        "variance_pct": str(group_variance_pct),
+                        "po_line_ids": [pl.id for pl in group_po_lines],
+                    },
+                ),
+            )
+
+    # ---------------------------------------------------------
+    # Final summary
+    # ---------------------------------------------------------
+    matched_line_ids = {r.invoice_line_id for r in result.match_line_results if r.line_status == "matched"}
+    result.lines_matched = len(matched_line_ids)
+
+    exception_line_ids = set(line_exception_map.keys())
+
+    # Any invoice line not matched and not explicitly captured is a no_match exception
+    for line in inv_lines:
+        if line.id not in matched_line_ids and line.id not in exception_line_ids:
+            exception_line_ids.add(line.id)
+
+    result.lines_in_exception = len(exception_line_ids)
+
+    # Final overall status and zone
+    if result.header_exceptions:
+        result.overall_status = "exception"
+        result.match_zone = "red"
+    else:
+        any_amber = any(r.line_zone == "amber" for r in result.match_line_results)
+        any_red = any(r.line_zone == "red" for r in result.match_line_results)
+
+        if result.lines_matched == result.lines_total and result.lines_in_exception == 0:
+            result.overall_status = "matched"
+            result.match_zone = "red" if any_red else ("amber" if any_amber else "green")
+        elif result.lines_matched > 0:
+            result.overall_status = "partial_match"
+            if any_red or result.match_exceptions:
+                result.match_zone = "red"
+            elif any_amber:
+                result.match_zone = "amber"
+            else:
+                result.match_zone = "green"
+        else:
+            result.overall_status = "exception"
+            result.match_zone = "red"
+
+    # documents.status is always pending_approval after task_match
+    result.documents_status = "pending_approval"
+    result.match_type = "two_way"
+
+    return result
+
+
+# ============================================================
+# Internal helper for Tier 1-3 finalization
+# ============================================================
+def _finalize_tier1_3_line_match(
+    *,
+    inv_line: InvoiceLine,
+    po_line: POLine,
+    tier: int,
+    cfg: TwoWayConfig,
+) -> tuple[bool, MatchLineResult]:
+    """
+    Finalize a Tier 1-3 match candidate.
+
+    Returns:
+      (matched_successfully, result_row)
+
+    If available_qty == 0, the line is blocked with po_ceiling_exhausted.
+    """
+    inv_qty = to_decimal(inv_line.quantity)
+    inv_price = to_decimal(inv_line.unit_price)
+    po_price = to_decimal(po_line.unit_price)
+
+    avail_qty = available_qty(po_line)
+    if avail_qty < 0:
+        return False, MatchLineResult(
+            invoice_line_id=inv_line.id,
+            po_line_id=po_line.id,
+            match_tier=tier,
+            line_zone="red",
+            line_status="exception",
+            match_type="two_way",
+        )
+
+    if avail_qty == 0:
+        return False, MatchLineResult(
+            invoice_line_id=inv_line.id,
+            po_line_id=po_line.id,
+            match_tier=tier,
+            price_var_pct=price_variance_pct(inv_price, po_price),
+            qty_var_pct=None,
+            line_zone="red",
+            line_status="exception",
+            match_type="two_way",
+        )
+
+    p_var = price_variance_pct(inv_price, po_price)
+
+    if inv_qty is None:
+        q_var = None
+    else:
+        q_var = qty_over_pct(inv_qty, avail_qty)
+
+    item_type = (po_line.item_type or "services").lower()
+    line_zone = zone_from_pct(p_var, q_var, item_type, cfg)
+
+    allocated_inv_amount = inv_line.amount if inv_line.amount is not None else None
+    allocated_po_amount = ((to_decimal(po_line.quantity) or D0) - (to_decimal(po_line.invoiced_qty) or D0)) * (po_price or D0)
+
+    return True, MatchLineResult(
+        invoice_line_id=inv_line.id,
+        po_line_id=po_line.id,
+        match_tier=tier,
+        allocated_inv_amount=allocated_inv_amount,
+        allocated_po_amount=allocated_po_amount.quantize(Decimal("0.01")),
+        price_var_pct=p_var,
+        qty_var_pct=q_var,
+        line_zone=line_zone,
+        line_status="matched",
+        match_type="two_way",
+    )