SCIBASE-AI · goodgoodclaw · May 31, 2026
diff --git a/institutional-invoice-delivery-assurance-guard/README.md b/institutional-invoice-delivery-assurance-guard/README.md
@@ -0,0 +1,38 @@
+# Institutional Invoice Delivery Assurance Guard
+
+This module adds a dependency-free guard for institutional invoice delivery
+evidence in the Revenue Infrastructure flow. It runs after an invoice is
+generated and before AR aging, dunning, collections, or entitlement holds begin.
+
+## Scope
+
+The guard validates whether an invoice has truly reached the customer's
+accounts-payable route:
+
+- Billing email delivery, hard bounces, and retry windows.
+- Customer portal upload receipts.
+- Purchase-order attachment state for PO-required accounts.
+- Invoice payload hash versus delivered PDF hash parity.
+- Issue date and due date ordering.
+- Fresh AP contact verification.
+- Finance owner escalation for failed delivery packets.
+
+This is separate from quote approval, billing receipt privacy, institutional
+invoice collections, dunning entitlement holds, payment rail failover, revenue
+recognition, and procurement controls.
+
+## Run
+
+```bash
+python3 institutional-invoice-delivery-assurance-guard/invoice_delivery_assurance_guard.py \
+  --sample \
+  --json institutional-invoice-delivery-assurance-guard/demo/report.json \
+  --markdown institutional-invoice-delivery-assurance-guard/demo/summary.md \
+  --svg institutional-invoice-delivery-assurance-guard/demo/graph.svg
+```
+
+## Test
+
+```bash
+python3 -m unittest institutional-invoice-delivery-assurance-guard/test_invoice_delivery_assurance_guard.py
+```
diff --git a/institutional-invoice-delivery-assurance-guard/demo/graph.svg b/institutional-invoice-delivery-assurance-guard/demo/graph.svg
diff --git a/institutional-invoice-delivery-assurance-guard/demo/report.json b/institutional-invoice-delivery-assurance-guard/demo/report.json
@@ -0,0 +1,195 @@
+{
+  "guard": "institutional-invoice-delivery-assurance-guard",
+  "invoices": [
+    {
+      "accepted_routes": [
+        {
+          "evidence": "ap@astro-university.edu",
+          "status": "accepted",
+          "type": "email"
+        },
+        {
+          "evidence": "COUPA-RECEIPT-9912",
+          "status": "uploaded",
+          "type": "portal"
+        }
+      ],
+      "account_id": "ACCT-UNIV-ASTRO",
+      "actions": [
+        {
+          "action": "release-invoice-to-ar-aging",
+          "owner": "finance-owner-astro",
+          "reason": "accepted delivery evidence present"
+        }
+      ],
+      "ar_status": "start_ar_aging",
+      "decision": "release_to_ar",
+      "findings": [],
+      "invoice_id": "INV-DELIV-001"
+    },
+    {
+      "accepted_routes": [],
+      "account_id": "ACCT-NATIONAL-LAB",
+      "actions": [
+        {
+          "action": "pause-ar-aging-and-dunning",
+          "owner": "finance-owner-lab",
+          "reason": "delivery evidence is incomplete or unsafe"
+        },
+        {
+          "action": "refresh-ap-route-and-redeliver",
+          "owner": "finance-owner-lab",
+          "reason": "invoice did not reach a verified AP route"
+        },
+        {
+          "action": "reverify-ap-contact",
+          "owner": "finance-owner-lab",
+          "reason": "AP route verification is stale or absent"
+        }
+      ],
+      "ar_status": "do_not_age_or_dun",
+      "decision": "hold_for_finance",
+      "findings": [
+        {
+          "code": "STALE_AP_CONTACT",
+          "field": "ap_contact_verified_at",
+          "message": "AP contact verification is older than 180 days.",
+          "severity": "review"
+        },
+        {
+          "code": "HARD_DELIVERY_BOUNCE",
+          "field": "delivery_channels[0].status",
+          "message": "Invoice route produced a hard delivery bounce.",
+          "severity": "block"
+        },
+        {
+          "code": "NO_ACCEPTED_DELIVERY_ROUTE",
+          "field": "delivery_channels",
+          "message": "Invoice has no accepted email or portal delivery evidence.",
+          "severity": "block"
+        }
+      ],
+      "invoice_id": "INV-BOUNCE-002"
+    },
+    {
+      "accepted_routes": [
+        {
+          "evidence": "ap@eu-consortium.example",
+          "status": "accepted",
+          "type": "email"
+        }
+      ],
+      "account_id": "ACCT-EU-CONSORTIUM",
+      "actions": [
+        {
+          "action": "pause-ar-aging-and-dunning",
+          "owner": "finance-owner-eu",
+          "reason": "delivery evidence is incomplete or unsafe"
+        },
+        {
+          "action": "upload-to-customer-portal",
+          "owner": "finance-owner-eu",
+          "reason": "portal receipt is required"
+        }
+      ],
+      "ar_status": "pause_ar_aging_until_delivery_evidence",
+      "decision": "retry_delivery",
+      "findings": [
+        {
+          "code": "DELIVERY_RETRY_PENDING",
+          "field": "delivery_channels[1].status",
+          "message": "Invoice route is still pending retry evidence.",
+          "severity": "review"
+        },
+        {
+          "code": "MISSING_PORTAL_RECEIPT",
+          "field": "delivery_channels",
+          "message": "Customer requires a portal receipt before invoice can enter AR aging.",
+          "severity": "review"
+        }
+      ],
+      "invoice_id": "INV-PORTAL-003"
+    },
+    {
+      "accepted_routes": [
+        {
+          "evidence": "ap@med-school.example",
+          "status": "accepted",
+          "type": "email"
+        }
+      ],
+      "account_id": "ACCT-MED-SCHOOL",
+      "actions": [
+        {
+          "action": "pause-ar-aging-and-dunning",
+          "owner": "finance-owner-med",
+          "reason": "delivery evidence is incomplete or unsafe"
+        },
+        {
+          "action": "attach-po-evidence-before-redelivery",
+          "owner": "finance-owner-med",
+          "reason": "PO-required account lacks auditable evidence"
+        }
+      ],
+      "ar_status": "do_not_age_or_dun",
+      "decision": "hold_for_finance",
+      "findings": [
+        {
+          "code": "MISSING_PO_ATTACHMENT",
+          "field": "po_attachment_hash",
+          "message": "PO-required account has no auditable PO attachment hash.",
+          "severity": "block"
+        }
+      ],
+      "invoice_id": "INV-PO-004"
+    },
+    {
+      "accepted_routes": [
+        {
+          "evidence": "ap@cloud-lab.example",
+          "status": "accepted",
+          "type": "email"
+        }
+      ],
+      "account_id": "ACCT-CLOUD-LAB",
+      "actions": [
+        {
+          "action": "pause-ar-aging-and-dunning",
+          "owner": "finance-ops",
+          "reason": "delivery evidence is incomplete or unsafe"
+        },
+        {
+          "action": "regenerate-and-redeliver-approved-pdf",
+          "owner": "finance-ops",
+          "reason": "delivered PDF does not match approved invoice"
+        }
+      ],
+      "ar_status": "do_not_age_or_dun",
+      "decision": "hold_for_finance",
+      "findings": [
+        {
+          "code": "DELIVERED_PDF_HASH_MISMATCH",
+          "field": "delivered_pdf_hash",
+          "message": "Delivered PDF hash does not match the approved invoice payload.",
+          "severity": "block"
+        },
+        {
+          "code": "MISSING_FINANCE_OWNER",
+          "field": "finance_owner",
+          "message": "Failed delivery packets need an accountable finance owner.",
+          "severity": "review"
+        }
+      ],
+      "invoice_id": "INV-HASH-005"
+    }
+  ],
+  "review_as_of": "2026-05-31",
+  "summary": {
+    "accepted_route_count": 5,
+    "action_count": 10,
+    "hold_for_finance": 3,
+    "release_to_ar": 1,
+    "retry_delivery": 1,
+    "total": 5
+  }
+}
diff --git a/institutional-invoice-delivery-assurance-guard/demo/summary.md b/institutional-invoice-delivery-assurance-guard/demo/summary.md
@@ -0,0 +1,16 @@
+# Institutional Invoice Delivery Assurance Summary
+
+- Total invoices: 5
+- Release to AR: 1
+- Retry delivery: 1
+- Hold for finance: 3
+- Accepted routes: 5
+- Required actions: 10
+
+| Invoice | Decision | AR status | Findings | Actions |
+| --- | --- | --- | --- | --- |
+| INV-DELIV-001 | release_to_ar | start_ar_aging | none | release-invoice-to-ar-aging |
+| INV-BOUNCE-002 | hold_for_finance | do_not_age_or_dun | STALE_AP_CONTACT, HARD_DELIVERY_BOUNCE, NO_ACCEPTED_DELIVERY_ROUTE | pause-ar-aging-and-dunning, refresh-ap-route-and-redeliver, reverify-ap-contact |
+| INV-PORTAL-003 | retry_delivery | pause_ar_aging_until_delivery_evidence | DELIVERY_RETRY_PENDING, MISSING_PORTAL_RECEIPT | pause-ar-aging-and-dunning, upload-to-customer-portal |
+| INV-PO-004 | hold_for_finance | do_not_age_or_dun | MISSING_PO_ATTACHMENT | pause-ar-aging-and-dunning, attach-po-evidence-before-redelivery |
+| INV-HASH-005 | hold_for_finance | do_not_age_or_dun | DELIVERED_PDF_HASH_MISMATCH, MISSING_FINANCE_OWNER | pause-ar-aging-and-dunning, regenerate-and-redeliver-approved-pdf |