Add revenue tax exemption controls

revenue-tax-exemption-controls/README.md

@@ -0,0 +1,24 @@
+# Revenue Tax Exemption Controls
+
+This module adds a focused Revenue Infrastructure slice for institutional tax exemption and grant billing compliance. It avoids live payment credentials and evaluates invoice readiness with deterministic local data.
+
+## What it checks
+
+- Expired or missing exemption certificates
+- Reverse-charge invoices without VAT ID evidence
+- Tax amount mismatch against configured jurisdictions
+- Unknown tax jurisdictions that require finance review
+- Grant budget overrun risk
+- Invoice line categories outside grant-approved spend
+- Payment settlement events that are missing or mismatched
+- Invoice-level recommended actions and an audit digest
+
+## Run locally
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+The sample data intentionally places two invoices on hold: one has an expired exemption certificate, grant-category drift, and settlement mismatch; the other has missing VAT ID evidence for reverse charge.

revenue-tax-exemption-controls/demo.js

@@ -0,0 +1,23 @@
+"use strict";
+
+const sampleBundle = require("./sample-data.json");
+const {
+  analyzeRevenueTaxControls,
+} = require("./src/revenue-tax-exemption-controls");
+
+const result = analyzeRevenueTaxControls(sampleBundle);
+
+console.log(`Decision: ${result.decision}`);
+console.log(`Audit digest: ${result.auditDigest}`);
+console.log("");
+console.log("Invoice summaries:");
+for (const summary of result.invoiceSummaries) {
+  console.log(`- ${summary.invoiceId}: ${summary.recommendedAction} (${summary.blockerCount} blocker, ${summary.warningCount} warning)`);
+}
+console.log("");
+console.log("Findings:");
+for (const finding of result.findings) {
+  console.log(`- [${finding.severity}] ${finding.invoiceId} ${finding.id}: ${finding.title}`);
+  console.log(`  detail: ${finding.detail}`);
+  console.log(`  remediation: ${finding.remediation}`);
+}

revenue-tax-exemption-controls/docs/requirement-map.md

@@ -0,0 +1,14 @@
+# Requirement Map
+
+| Revenue Infrastructure requirement | Implementation |
+| --- | --- |
+| Institutional billing | Customers include institutional tax profiles, jurisdictions, exemption certificates, and VAT/reverse-charge evidence. |
+| Invoice controls | Invoices include subscription/compute line items, tax jurisdictions, tax cents, grant budget IDs, and gross amount summaries. |
+| Grants and cost controls | Grant budgets enforce approved spend totals and allowed line-item categories. |
+| Payment/settlement evidence | Settlement events are reconciled against invoice gross amounts before revenue can be treated as cleanly billable. |
+| Compliance holds | Blockers produce `billing-hold`; warnings produce `finance-review`; clean invoices produce `billable`. |
+| Auditability | Results include invoice summaries, findings, recommended actions, and a deterministic `sha256` audit digest. |
+
+## Demo Video
+
+The PR includes `docs/tax-exemption-demo.mp4`, a real terminal walkthrough running the local check, test, and demo scripts.

revenue-tax-exemption-controls/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "revenue-tax-exemption-controls",
+  "version": "1.0.0",
+  "description": "Institutional tax exemption and grant billing compliance controls.",
+  "main": "src/revenue-tax-exemption-controls.js",
+  "scripts": {
+    "check": "node --check src/revenue-tax-exemption-controls.js && node --check test.js && node --check demo.js",
+    "test": "node test.js",
+    "demo": "node demo.js"
+  },
+  "license": "MIT"
+}

revenue-tax-exemption-controls/sample-data.json

@@ -0,0 +1,97 @@
+{
+  "now": "2026-05-15T00:00:00.000Z",
+  "customers": [
+    {
+      "id": "cust-university-lab",
+      "name": "Northbridge University Lab",
+      "taxProfile": {
+        "jurisdiction": "US-CA",
+        "exemptionStatus": "exempt",
+        "reverseCharge": false,
+        "vatId": null,
+        "exemptionCertificate": {
+          "id": "cert-2025-ca-221",
+          "status": "verified",
+          "expiresAt": "2026-04-01T00:00:00.000Z"
+        }
+      }
+    },
+    {
+      "id": "cust-eu-institute",
+      "name": "Helix EU Institute",
+      "taxProfile": {
+        "jurisdiction": "DE",
+        "exemptionStatus": "standard",
+        "reverseCharge": true,
+        "vatId": "",
+        "exemptionCertificate": null
+      }
+    }
+  ],
+  "grantBudgets": [
+    {
+      "id": "grant-nih-atlas-2026",
+      "approvedCents": 300000,
+      "usedCents": 252000,
+      "allowedCategories": ["subscription", "storage"]
+    },
+    {
+      "id": "grant-eu-knowledge-graph",
+      "approvedCents": 220000,
+      "usedCents": 80000,
+      "allowedCategories": ["subscription", "compute", "storage"]
+    }
+  ],
+  "invoices": [
+    {
+      "id": "inv-1007",
+      "customerId": "cust-university-lab",
+      "taxJurisdiction": "US-CA",
+      "grantBudgetId": "grant-nih-atlas-2026",
+      "taxCents": 0,
+      "lines": [
+        {
+          "description": "SCIBASE Enterprise workspace",
+          "category": "subscription",
+          "quantity": 1,
+          "unitCents": 42000
+        },
+        {
+          "description": "GPU compute overage",
+          "category": "compute",
+          "quantity": 1,
+          "unitCents": 12000
+        }
+      ]
+    },
+    {
+      "id": "inv-1008",
+      "customerId": "cust-eu-institute",
+      "taxJurisdiction": "DE",
+      "grantBudgetId": "grant-eu-knowledge-graph",
+      "taxCents": 0,
+      "lines": [
+        {
+          "description": "Knowledge graph API seats",
+          "category": "subscription",
+          "quantity": 2,
+          "unitCents": 18000
+        }
+      ]
+    }
+  ],
+  "settlementEvents": [
+    {
+      "invoiceId": "inv-1007",
+      "status": "settled",
+      "amountCents": 51000,
+      "processor": "stripe"
+    },
+    {
+      "invoiceId": "inv-1008",
+      "status": "settled",
+      "amountCents": 36000,
+      "processor": "stripe"
+    }
+  ]
+}