[codex] Add revenue dispute evidence guard

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Revenue infrastructure additions
+
+- `revenue-dispute-evidence-guard`: chargeback and failed-payment evidence guard for revenue recovery, entitlement holds, and payment-rail dispute packets.

revenue-dispute-evidence-guard/README.md

@@ -0,0 +1,25 @@
+# Revenue Dispute Evidence Guard
+
+Revenue infrastructure needs controls for the moments after billing succeeds or fails: card disputes, invoice short-payments, failed top-ups, and license access that should pause until finance has enough evidence to recover revenue. This module adds a deterministic chargeback and payment-dispute evidence guard for institutional revenue operations.
+
+The guard is self-contained and credential-free. It consumes synthetic customer, invoice, payment, entitlement, and usage records, then emits:
+
+- dispute and failed-payment findings with severity and recovery deadlines
+- entitlement hold/release decisions for subscriptions, compute top-ups, and data licenses
+- payment-rail evidence packets for Stripe, PayPal, and institutional invoice workflows
+- finance actions prioritized by revenue at risk and due date
+- deterministic audit digests for reviewer-ready validation
+
+## Run
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+The demo reads `data/sample-revenue-input.json`. Visual review artifacts are in `docs/demo.svg` and `docs/demo.gif`.
+
+## Fit For Issue #20
+
+This targets the Revenue Infrastructure requirements for secure payment integrations, institutional invoicing, subscription billing, AI compute usage, top-ups, and licensing API revenue. It is distinct from prior billing, metering, entitlement, procurement, licensing, tax, margin, renewal, and revenue-recognition slices because it focuses on payment reversals, evidence readiness, dispute deadlines, and entitlement holds after payment risk appears.

revenue-dispute-evidence-guard/data/sample-revenue-input.json

@@ -0,0 +1,140 @@
+{
+  "generatedAt": "2026-05-16T14:45:00Z",
+  "organization": "Northbridge Research Cloud",
+  "customers": [
+    {
+      "id": "cust-lab-a",
+      "name": "Atlas Organoid Lab",
+      "tier": "lab",
+      "accountOwner": "Maya Patel",
+      "billingEmail": "billing+atlas@example.edu"
+    },
+    {
+      "id": "cust-institute-b",
+      "name": "Helix Institute Consortium",
+      "tier": "institution",
+      "accountOwner": "Evan Brooks",
+      "billingEmail": "ap+helix@example.org"
+    },
+    {
+      "id": "cust-analyst-c",
+      "name": "Quanta Policy Analytics",
+      "tier": "licensing",
+      "accountOwner": "Lena Ross",
+      "billingEmail": "finance+quanta@example.net"
+    }
+  ],
+  "invoices": [
+    {
+      "id": "inv-1001",
+      "customerId": "cust-lab-a",
+      "amountUsd": 2400,
+      "issuedAt": "2026-04-28",
+      "dueAt": "2026-05-12",
+      "status": "paid",
+      "lineItems": ["lab_subscription", "ai_compute_topup"]
+    },
+    {
+      "id": "inv-1002",
+      "customerId": "cust-institute-b",
+      "amountUsd": 9800,
+      "issuedAt": "2026-04-20",
+      "dueAt": "2026-05-10",
+      "status": "short_paid",
+      "lineItems": ["institution_license", "priority_support"]
+    },
+    {
+      "id": "inv-1003",
+      "customerId": "cust-analyst-c",
+      "amountUsd": 5200,
+      "issuedAt": "2026-05-01",
+      "dueAt": "2026-05-15",
+      "status": "open",
+      "lineItems": ["analytics_api_license"]
+    }
+  ],
+  "payments": [
+    {
+      "id": "pay-778",
+      "invoiceId": "inv-1001",
+      "rail": "stripe",
+      "amountUsd": 2400,
+      "status": "disputed",
+      "disputeReason": "fraudulent",
+      "disputeDueAt": "2026-05-18",
+      "evidence": ["signed_order_form", "seat_login_history", "compute_usage_log", "receipt_email"],
+      "requiredEvidence": ["signed_order_form", "service_acceptance", "seat_login_history", "compute_usage_log", "receipt_email"]
+    },
+    {
+      "id": "pay-812",
+      "invoiceId": "inv-1002",
+      "rail": "institutional_invoice",
+      "amountUsd": 7600,
+      "status": "short_paid",
+      "disputeReason": "missing_purchase_order",
+      "disputeDueAt": "2026-05-17",
+      "evidence": ["signed_order_form", "usage_report"],
+      "requiredEvidence": ["signed_order_form", "purchase_order", "usage_report", "invoice_pdf"]
+    },
+    {
+      "id": "pay-845",
+      "invoiceId": "inv-1003",
+      "rail": "paypal",
+      "amountUsd": 0,
+      "status": "failed",
+      "disputeReason": "funding_source_declined",
+      "disputeDueAt": "2026-05-20",
+      "evidence": ["invoice_pdf"],
+      "requiredEvidence": ["invoice_pdf", "license_delivery_log", "api_access_log"]
+    }
+  ],
+  "entitlements": [
+    {
+      "id": "ent-lab-a-compute",
+      "customerId": "cust-lab-a",
+      "invoiceId": "inv-1001",
+      "kind": "ai_compute_topup",
+      "monthlyValueUsd": 900,
+      "status": "active"
+    },
+    {
+      "id": "ent-institute-b-license",
+      "customerId": "cust-institute-b",
+      "invoiceId": "inv-1002",
+      "kind": "institution_license",
+      "monthlyValueUsd": 6200,
+      "status": "active"
+    },
+    {
+      "id": "ent-analyst-c-api",
+      "customerId": "cust-analyst-c",
+      "invoiceId": "inv-1003",
+      "kind": "analytics_api_license",
+      "monthlyValueUsd": 5200,
+      "status": "provisioning"
+    }
+  ],
+  "usageEvents": [
+    {
+      "customerId": "cust-lab-a",
+      "invoiceId": "inv-1001",
+      "kind": "ai_inference_hours",
+      "quantity": 330,
+      "recordedAt": "2026-05-11"
+    },
+    {
+      "customerId": "cust-institute-b",
+      "invoiceId": "inv-1002",
+      "kind": "institution_active_seats",
+      "quantity": 180,
+      "recordedAt": "2026-05-12"
+    },
+    {
+      "customerId": "cust-analyst-c",
+      "invoiceId": "inv-1003",
+      "kind": "analytics_api_queries",
+      "quantity": 24000,
+      "recordedAt": "2026-05-13"
+    }
+  ]
+}

revenue-dispute-evidence-guard/docs/requirement-map.md

@@ -0,0 +1,14 @@
+# Requirement Map
+
+| Issue #20 capability | Implementation evidence |
+| --- | --- |
+| Secure payment integrations | Stripe, PayPal, and institutional invoice rails are modeled in `data/sample-revenue-input.json` and packetized by `evidencePackets()` |
+| Subscription billing | customer tiers, invoice line items, and active entitlements are connected to payment risk |
+| AI compute billing and top-ups | `ai_compute_topup` entitlement and compute usage events are included in entitlement hold decisions |
+| Institutional invoicing | short-paid institutional invoice flow requires purchase order and invoice PDF evidence |
+| Licensing APIs and analytics | analytics API license entitlement is paused when PayPal funding fails |
+| Revenue sustainability | `revenueAtRiskUsd`, finance actions, due dates, and deterministic digests prioritize recovery work |
+
+## Distinctness
+
+This module is not another billing ledger, metering engine, entitlement calculator, procurement control, privacy-safe licensing gate, tax exemption checker, margin guard, renewal true-up, or revenue-recognition close. It focuses on post-billing payment risk: disputes, short-payments, failed payments, evidence packets, and entitlement holds.

revenue-dispute-evidence-guard/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "revenue-dispute-evidence-guard",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "check": "node --check src/dispute-evidence-guard.js && node --check scripts/demo.js && node --check test/dispute-evidence-guard.test.js",
+    "test": "node --test test/dispute-evidence-guard.test.js",
+    "demo": "node scripts/demo.js"
+  }
+}

revenue-dispute-evidence-guard/scripts/demo.js

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { analyzeRevenueDisputes } from "../src/dispute-evidence-guard.js";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const input = JSON.parse(readFileSync(join(root, "data", "sample-revenue-input.json"), "utf8"));
+const report = analyzeRevenueDisputes(input);
+
+console.log(`${report.organization} dispute evidence guard`);
+console.log(`Evidence digest: ${report.evidenceDigest}`);
+console.log(`Revenue at risk: $${report.summary.revenueAtRiskUsd}`);
+console.log(`Findings: ${report.summary.paymentsAtRisk} (${report.summary.criticalFindings} critical, ${report.summary.highFindings} high)`);
+console.log(`Entitlements: ${report.summary.heldEntitlements} held, ${report.summary.limitedEntitlements} limited`);
+console.log("Top finance actions:");
+for (const action of report.financeActions.slice(0, 5)) {
+  console.log(`- [${action.severity}] ${action.action}: ${action.paymentId} missing ${action.missingEvidence.join(", ") || "none"}`);
+}