Add compute budget billing guard

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Revenue Infrastructure Guards
+
+- [Revenue Compute Budget Guard](./revenue-compute-budget-guard/) - validates AI compute spend thresholds, top-up coverage, customer notice freshness, and invoice release readiness.

revenue-compute-budget-guard/README.md

@@ -0,0 +1,51 @@
+# Revenue Compute Budget Guard
+
+This module adds an audit-ready guard for the AI compute billing stream in
+SCIBASE revenue infrastructure. It checks whether metered compute usage can be
+released to billing before customer budget notices, top-up coverage, and hard
+cap controls are satisfied.
+
+The guard is intentionally dependency-free and uses synthetic sample data only.
+It does not connect to payment processors, external APIs, customer accounts, or
+private billing data.
+
+## What It Covers
+
+- Account-level compute spend from billable usage events
+- Approved budget plus prepaid top-up balance
+- Warning and critical threshold decisions
+- Freshness of customer budget notices
+- Missing finance/account-owner notification recipients
+- Hard-cap billing hold enforcement
+- Draft invoice amount mismatches
+- Reviewer-ready JSON and Markdown evidence output
+
+## Decisions
+
+| Decision | Meaning |
+| --- | --- |
+| `CLEAR_TO_BILL` | Spend is within approved controls and invoice amount matches the ledger. |
+| `SEND_NOTICE_BEFORE_BILLING` | Billing can proceed only after warning/projection notice issues are remediated. |
+| `HOLD_COMPUTE_BILLING` | Critical overage, missing budget, or hard-cap control gaps block invoice release. |
+
+## Run Locally
+
+```bash
+node revenue-compute-budget-guard/test.js
+node revenue-compute-budget-guard/demo.js
+```
+
+The demo writes:
+
+- `revenue-compute-budget-guard/artifacts/demo-output.json`
+- `revenue-compute-budget-guard/artifacts/demo-report.md`
+
+## Requirement Map
+
+| Issue #20 revenue infrastructure requirement | Implementation |
+| --- | --- |
+| Usage-based pricing for heavy backend processing tasks | `usageEvents` are metered into billable compute spend. |
+| Transparent quotas and real-time usage meters | Budget, spend ratio, projected period-end spend, and allowed invoice amount are returned per account. |
+| Bundle tokens or allow top-ups | `topUpBalanceCents` is included in the approved spend limit and overage decision. |
+| Institutional billing governance | Draft invoice mismatch and hard-cap hold findings create reviewer-ready finance remediation evidence. |
+| No live payment or credential handling | The module is dependency-free and runs only on synthetic JSON sample data. |

revenue-compute-budget-guard/artifacts/demo-output.json

@@ -0,0 +1,122 @@
+{
+  "generatedAt": "2026-06-06T00:00:00Z",
+  "portfolioId": "revenue-infra-demo",
+  "accounts": [
+    {
+      "accountId": "lab-clear-001",
+      "plan": "Research Lab Pro",
+      "decision": "CLEAR_TO_BILL",
+      "spendCents": 78000,
+      "budgetCents": 700000,
+      "creditCents": 0,
+      "allowedInvoiceCents": 78000,
+      "spendRatio": 0.111,
+      "projectedSpendCents": 468000,
+      "projectedRatio": 0.669,
+      "findings": []
+    },
+    {
+      "accountId": "lab-warning-002",
+      "plan": "Institutional AI Compute",
+      "decision": "SEND_NOTICE_BEFORE_BILLING",
+      "spendCents": 79800,
+      "budgetCents": 100000,
+      "creditCents": 25000,
+      "allowedInvoiceCents": 79800,
+      "spendRatio": 0.798,
+      "projectedSpendCents": 478800,
+      "projectedRatio": 4.788,
+      "findings": [
+        {
+          "severity": "high",
+          "code": "BUDGET_THRESHOLD_NOTICE_STALE",
+          "message": "Budget threshold was crossed without a fresh customer notice.",
+          "remediation": "Send or refresh the budget threshold notice before billing the overage.",
+          "evidence": {
+            "threshold": 0.75,
+            "latestNoticeAt": "2026-06-02T09:00:00Z",
+            "noticeFreshnessHours": 48
+          }
+        }
+      ]
+    },
+    {
+      "accountId": "lab-hold-003",
+      "plan": "Enterprise Compute",
+      "decision": "HOLD_COMPUTE_BILLING",
+      "spendCents": 105500,
+      "budgetCents": 80000,
+      "creditCents": 10000,
+      "allowedInvoiceCents": 90000,
+      "spendRatio": 1.319,
+      "projectedSpendCents": 633000,
+      "projectedRatio": 7.912,
+      "findings": [
+        {
+          "severity": "high",
+          "code": "BUDGET_NOTICE_CONTACTS_MISSING",
+          "message": "Budget threshold was crossed, but the account does not have enough notice recipients.",
+          "remediation": "Add finance or account-owner recipients before releasing the compute invoice.",
+          "evidence": {
+            "contacts": [],
+            "minimumContacts": 1
+          }
+        },
+        {
+          "severity": "high",
+          "code": "BUDGET_THRESHOLD_NOTICE_STALE",
+          "message": "Budget threshold was crossed without a fresh customer notice.",
+          "remediation": "Send or refresh the budget threshold notice before billing the overage.",
+          "evidence": {
+            "threshold": 0.75,
+            "latestNoticeAt": null,
+            "noticeFreshnessHours": 48
+          }
+        },
+        {
+          "severity": "critical",
+          "code": "HARD_CAP_WITHOUT_BILLING_HOLD",
+          "message": "Compute usage reached the hard-cap threshold but billing hold controls are not enabled.",
+          "remediation": "Enable billing hold or record an explicit finance override before invoice release.",
+          "evidence": {
+            "spendCents": 105500,
+            "budgetCents": 80000,
+            "criticalThreshold": 1
+          }
+        },
+        {
+          "severity": "critical",
+          "code": "UNCOVERED_COMPUTE_OVERAGE",
+          "message": "Compute spend exceeds the approved budget plus prepaid top-up balance.",
+          "remediation": "Hold the invoice, request top-up authorization, or cap the billable amount to the approved limit.",
+          "evidence": {
+            "spendCents": 105500,
+            "approvedLimitCents": 90000,
+            "uncoveredCents": 15500
+          }
+        },
+        {
+          "severity": "high",
+          "code": "COMPUTE_INVOICE_AMOUNT_MISMATCH",
+          "message": "Draft compute invoice does not match the approved billable amount.",
+          "remediation": "Regenerate the invoice from the metered usage ledger and approved budget/top-up limit.",
+          "evidence": {
+            "invoiceId": "draft-hold-003",
+            "invoiceAmountCents": 105500,
+            "allowedInvoiceCents": 90000
+          }
+        }
+      ]
+    }
+  ],
+  "totals": {
+    "spendCents": 263300,
+    "approvedLimitCents": 915000,
+    "allowedInvoiceCents": 247800
+  },
+  "decisionCounts": {
+    "CLEAR_TO_BILL": 1,
+    "SEND_NOTICE_BEFORE_BILLING": 1,
+    "HOLD_COMPUTE_BILLING": 1
+  }
+}

revenue-compute-budget-guard/artifacts/demo-report.md

@@ -0,0 +1,53 @@
+# Compute Budget Guard Report
+
+Generated: 2026-06-06T00:00:00Z
+Portfolio: revenue-infra-demo
+
+## Totals
+
+- Metered compute spend: $2633.00
+- Approved budget plus top-ups: $9150.00
+- Approved invoiceable amount: $2478.00
+
+## Account Decisions
+
+### lab-clear-001
+
+- Decision: CLEAR_TO_BILL
+- Plan: Research Lab Pro
+- Spend: $780.00 of $7000.00 budget
+- Top-up credit: $0.00
+- Projected spend: $4680.00
+
+No findings.
+
+### lab-warning-002
+
+- Decision: SEND_NOTICE_BEFORE_BILLING
+- Plan: Institutional AI Compute
+- Spend: $798.00 of $1000.00 budget
+- Top-up credit: $250.00
+- Projected spend: $4788.00
+
+- [HIGH] BUDGET_THRESHOLD_NOTICE_STALE: Budget threshold was crossed without a fresh customer notice.
+  - Remediation: Send or refresh the budget threshold notice before billing the overage.
+
+### lab-hold-003
+
+- Decision: HOLD_COMPUTE_BILLING
+- Plan: Enterprise Compute
+- Spend: $1055.00 of $800.00 budget
+- Top-up credit: $100.00
+- Projected spend: $6330.00
+
+- [HIGH] BUDGET_NOTICE_CONTACTS_MISSING: Budget threshold was crossed, but the account does not have enough notice recipients.
+  - Remediation: Add finance or account-owner recipients before releasing the compute invoice.
+- [HIGH] BUDGET_THRESHOLD_NOTICE_STALE: Budget threshold was crossed without a fresh customer notice.
+  - Remediation: Send or refresh the budget threshold notice before billing the overage.
+- [CRITICAL] HARD_CAP_WITHOUT_BILLING_HOLD: Compute usage reached the hard-cap threshold but billing hold controls are not enabled.
+  - Remediation: Enable billing hold or record an explicit finance override before invoice release.
+- [CRITICAL] UNCOVERED_COMPUTE_OVERAGE: Compute spend exceeds the approved budget plus prepaid top-up balance.
+  - Remediation: Hold the invoice, request top-up authorization, or cap the billable amount to the approved limit.
+- [HIGH] COMPUTE_INVOICE_AMOUNT_MISMATCH: Draft compute invoice does not match the approved billable amount.
+  - Remediation: Regenerate the invoice from the metered usage ledger and approved budget/top-up limit.
+