Add AI compute idempotency meter guard

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Revenue Infrastructure
+
+- [AI Compute Idempotency Meter Guard](./ai-compute-idempotency-meter-guard/README.md)

ai-compute-idempotency-meter-guard/README.md

@@ -0,0 +1,24 @@
+# AI Compute Idempotency Meter Guard
+
+This module is a self-contained Revenue Infrastructure slice for SCIBASE issue #20. It protects AI compute billing from retry double-billing, raw-count inflation, and ambiguous nondeterministic reproducibility rerun charges before finance posts revenue.
+
+The module uses synthetic data only and has no external dependencies.
+
+## What It Checks
+
+- Content-hash idempotency keys collapse retry rows even when `requestId` changes.
+- Orphaned tool calls are held until a matching terminal result or refund policy exists.
+- Raw event counts are compared with distinct account/source/day attribution counts.
+- Nondeterministic reproducibility reruns are held unless billing scope is explicit.
+- Account-level quota and prepaid top-up controls decide whether clean usage is covered, overage-billable, or held.
+- Finance receives deterministic meter rows, findings, account decisions, and an audit digest.
+
+## Run
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+Generated review artifacts are written to `reports/`, including the short H.264 demo video at `reports/demo.mp4`.

ai-compute-idempotency-meter-guard/acceptance-notes.md

@@ -0,0 +1,27 @@
+# Acceptance Notes
+
+## Scope
+
+The guard handles three concrete Revenue Infrastructure risks:
+
+1. Retry double-billing when an AI tool call is retried under a new request ID.
+2. Raw-count inflation when many cache hits or repeated events map to one distinct account/source/day attribution unit.
+3. Nondeterministic reproducibility reruns without an explicit policy for billing the run versus billing the verified output.
+4. Account-level invoice release decisions after included quota and prepaid top-up balances are applied.
+
+## Non-Goals
+
+- No live Stripe, PayPal, bank, wallet, or tax integration.
+- No private project content.
+- No external network calls.
+- No account identity or KYC handling.
+
+## Local Validation
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+The demo writes reviewer artifacts into `reports/`. The submitted review packet includes a short H.264 demo video at `reports/demo.mp4`.

ai-compute-idempotency-meter-guard/demo.js

@@ -0,0 +1,74 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { evaluateComputeBilling } from "./index.js"
+import { accountControls, computeEvents, policy } from "./sample-data.js"
+
+const report = evaluateComputeBilling(computeEvents, policy, accountControls)
+const reportsDir = new URL("./reports/", import.meta.url)
+mkdirSync(reportsDir, { recursive: true })
+
+const markdown = `# AI Compute Idempotency Meter Guard
+
+Status: ${report.status}
+
+## Totals
+- Raw events: ${report.totals.rawEvents}
+- Idempotency groups: ${report.totals.idempotencyGroups}
+- Collapsed retry rows: ${report.totals.collapsedRows}
+- Held rows: ${report.totals.heldRows}
+- Billable usage: ${report.totals.billableCents} cents
+- Avoided overbill: ${report.totals.avoidedOverbillCents} cents
+- Invoice overage: ${report.totals.invoiceCents} cents
+- Held invoice accounts: ${report.totals.heldInvoiceAccounts}
+- Audit digest: ${report.auditDigest}
+
+## Account Decisions
+${report.accountSummaries
+  .map(
+    (summary) =>
+      `- ${summary.accountId}: ${summary.billingDecision}, ${summary.plan}, ${summary.paymentRail}, billable ${summary.billableCents}c, invoice ${summary.invoiceCents}c, top-up applied ${summary.topUpAppliedCents}c, avoided ${summary.avoidedOverbillCents}c, critical findings ${summary.criticalFindings}`,
+  )
+  .join("\n")}
+
+## Highest-Risk Findings
+${report.findings
+  .filter((finding) => finding.severity !== "info")
+  .map((finding) => `- ${finding.severity}: ${finding.code} (${finding.accountId}) - ${finding.message}`)
+  .join("\n")}
+`
+
+const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720">
+  <rect width="1280" height="720" fill="#111827"/>
+  <rect x="56" y="54" width="1168" height="612" rx="22" fill="#f8fafc"/>
+  <text x="96" y="128" font-family="Arial, sans-serif" font-size="38" font-weight="700" fill="#111827">AI Compute Idempotency Meter Guard</text>
+  <text x="96" y="178" font-family="Arial, sans-serif" font-size="22" fill="#334155">Finance review status: ${report.status}</text>
+  <g font-family="Arial, sans-serif" font-size="24" fill="#111827">
+    <text x="96" y="260">Raw events: ${report.totals.rawEvents}</text>
+    <text x="96" y="305">Idempotency groups: ${report.totals.idempotencyGroups}</text>
+    <text x="96" y="350">Collapsed retry rows: ${report.totals.collapsedRows}</text>
+    <text x="96" y="395">Held rows: ${report.totals.heldRows}</text>
+    <text x="96" y="440">Avoided overbill: ${report.totals.avoidedOverbillCents} cents</text>
+    <text x="96" y="485">Invoice overage: ${report.totals.invoiceCents} cents</text>
+  </g>
+  <rect x="700" y="230" width="430" height="248" rx="14" fill="#e0f2fe" stroke="#0284c7" stroke-width="3"/>
+  <text x="732" y="286" font-family="Arial, sans-serif" font-size="26" font-weight="700" fill="#075985">Controls covered</text>
+  <text x="732" y="336" font-family="Arial, sans-serif" font-size="22" fill="#075985">Content-hash retry collapse</text>
+  <text x="732" y="378" font-family="Arial, sans-serif" font-size="22" fill="#075985">Raw vs attributed count guard</text>
+  <text x="732" y="420" font-family="Arial, sans-serif" font-size="22" fill="#075985">Rerun-scope billing hold</text>
+  <text x="96" y="590" font-family="Arial, sans-serif" font-size="18" fill="#475569">Audit digest: ${report.auditDigest.slice(0, 48)}...</text>
+</svg>
+`
+
+writeFileSync(join(reportsDir.pathname, "summary.json"), `${JSON.stringify(report, null, 2)}\n`)
+writeFileSync(join(reportsDir.pathname, "finance-review-packet.md"), markdown)
+writeFileSync(join(reportsDir.pathname, "summary.svg"), svg)
+
+console.log(`Status: ${report.status}`)
+console.log(`Raw events: ${report.totals.rawEvents}`)
+console.log(`Idempotency groups: ${report.totals.idempotencyGroups}`)
+console.log(`Collapsed retry rows: ${report.totals.collapsedRows}`)
+console.log(`Held rows: ${report.totals.heldRows}`)
+console.log(`Avoided overbill: ${report.totals.avoidedOverbillCents} cents`)
+console.log(`Invoice overage: ${report.totals.invoiceCents} cents`)
+console.log(`Held invoice accounts: ${report.totals.heldInvoiceAccounts}`)
+console.log(`Audit digest: ${report.auditDigest}`)