Add compute meter replay guard

compute-meter-replay-guard/README.md

@@ -0,0 +1,76 @@
+# Compute Meter Replay Guard
+
+This module adds a deterministic guard for AI compute revenue metering before
+usage events are converted into invoice lines.
+
+It is scoped to synthetic billing telemetry only. It does not connect to Stripe,
+PayPal, bank accounts, wallets, customer systems, cloud meters, or private
+research data.
+
+## Why This Belongs In Revenue Infrastructure
+
+Usage-based AI billing depends on reliable metering. A replay job, duplicate
+event, missing idempotency key, stale correction, or unauthorized negative
+adjustment can overbill customers, underbill usage, or create finance disputes.
+This guard reviews a batch of synthetic meter events and decides whether the
+invoice run can proceed, needs repricing, or must be held.
+
+## Checks
+
+- Missing idempotency keys before billing.
+- Duplicate idempotency keys inside the replay window.
+- Reused invoice-line IDs across separate usage events.
+- Source sequence gaps that may indicate lost meter events.
+- Corrections older than the allowed correction window.
+- Negative adjustments without an authorized finance or meter role.
+- Plan and entitlement mismatches between event metadata and account state.
+- Event timestamp ordering problems.
+
+## Usage
+
+```bash
+node compute-meter-replay-guard/src/compute-meter-replay-guard.mjs \
+  compute-meter-replay-guard/fixtures/compute-meter-events.json \
+  --format markdown
+```
+
+JSON output:
+
+```bash
+node compute-meter-replay-guard/src/compute-meter-replay-guard.mjs \
+  compute-meter-replay-guard/fixtures/compute-meter-events.json \
+  --format json
+```
+
+## Validation
+
+```bash
+node compute-meter-replay-guard/test/run-tests.mjs
+```
+
+Expected result:
+
+```text
+compute meter replay guard tests passed
+```
+
+## Demo Artifacts
+
+- `demo/sample-report.md`
+- `demo/sample-report.json`
+- `demo/decision-flow.svg`
+- `demo/decision-flow.png`
+- `demo/compute-meter-replay-demo.mp4`
+
+## Scope Boundaries
+
+This assistant intentionally avoids:
+
+- live payment processors, banks, wallets, cards, or invoices;
+- real customer data;
+- external APIs or cloud billing systems;
+- tax, accounting, legal, or financial advice;
+- replacing human finance approval.
+
+It is a pre-invoice control that highlights billing evidence gaps and replay
+risks for review.

compute-meter-replay-guard/demo/sample-report.json

@@ -0,0 +1,96 @@
+{
+  "runId": "REV-METER-001",
+  "title": "June AI compute replay pre-invoice check",
+  "generatedAt": "2026-06-01T13:50:00Z",
+  "assistant": "compute-meter-replay-guard",
+  "decision": "hold",
+  "severityCounts": {
+    "critical": 3,
+    "high": 4,
+    "medium": 1,
+    "low": 0
+  },
+  "findings": [
+    {
+      "severity": "critical",
+      "eventIds": [
+        "E-001",
+        "E-002"
+      ],
+      "check": "duplicate-idempotency-key",
+      "evidence": "Idempotency key lab-pro:run-77:chunk-1 appears 2 times over 0.0 hours.",
+      "remediation": "Bill only the first accepted event and quarantine replay duplicates before invoice lines are generated."
+    },
+    {
+      "severity": "critical",
+      "eventIds": [
+        "E-007",
+        "E-008"
+      ],
+      "check": "duplicate-invoice-line",
+      "evidence": "Invoice line line-502 is referenced by 2 events.",
+      "remediation": "Hold the invoice run and regenerate invoice-line mapping from accepted meter events."
+    },
+    {
+      "severity": "critical",
+      "eventIds": [
+        "E-004"
+      ],
+      "check": "unauthorized-negative-adjustment",
+      "evidence": "E-004 applies -2400 cents with role support-agent.",
+      "remediation": "Require finance or meter-admin approval before applying a negative adjustment."
+    },
+    {
+      "severity": "high",
+      "eventIds": [
+        "E-005"
+      ],
+      "check": "entitlement-plan-mismatch",
+      "evidence": "E-005 was metered as individual-pro, but account acct-institution is on institution.",
+      "remediation": "Reprice the event under the account's active plan or hold invoice release."
+    },
+    {
+      "severity": "high",
+      "eventIds": [
+        "E-006"
+      ],
+      "check": "missing-idempotency-key",
+      "evidence": "E-006 has no idempotency key.",
+      "remediation": "Reject or enrich the event before it can create an invoice line."
+    },
+    {
+      "severity": "high",
+      "eventIds": [
+        "E-002",
+        "E-003"
+      ],
+      "check": "source-sequence-gap",
+      "evidence": "acct-lab-pro:usage-api jumps from sequence 101 to 104.",
+      "remediation": "Check replay source logs for missing usage before releasing invoice totals."
+    },
+    {
+      "severity": "high",
+      "eventIds": [
+        "E-004"
+      ],
+      "check": "stale-correction",
+      "evidence": "E-004 correction age is 167.1 hours.",
+      "remediation": "Route old corrections through a manual reprice or credit memo review."
+    },
+    {
+      "severity": "medium",
+      "eventIds": [
+        "E-006"
+      ],
+      "check": "timestamp-ordering",
+      "evidence": "E-006 was received before it occurred.",
+      "remediation": "Normalize source clocks or hold the event from invoice release."
+    }
+  ],
+  "financePrompts": [
+    "Which replay jobs can create duplicate invoice lines, and where should idempotency be enforced?",
+    "Which meter source logs prove whether missing sequence numbers represent lost usage or skipped test events?",
+    "Which correction approvals should route to credit memo review instead of automatic invoice repricing?",
+    "Which account plan snapshot should be used as the billable source of truth for this invoice run?"
+  ]
+}

compute-meter-replay-guard/demo/sample-report.md

@@ -0,0 +1,59 @@
+# Compute Meter Replay Guard - REV-METER-001
+
+Decision: HOLD
+
+## Severity Counts
+
+- Critical: 3
+- High: 4
+- Medium: 1
+- Low: 0
+
+## Findings
+
+### [CRITICAL] duplicate-idempotency-key
+- Events: E-001, E-002
+- Evidence: Idempotency key lab-pro:run-77:chunk-1 appears 2 times over 0.0 hours.
+- Remediation: Bill only the first accepted event and quarantine replay duplicates before invoice lines are generated.
+
+### [CRITICAL] duplicate-invoice-line
+- Events: E-007, E-008
+- Evidence: Invoice line line-502 is referenced by 2 events.
+- Remediation: Hold the invoice run and regenerate invoice-line mapping from accepted meter events.
+
+### [CRITICAL] unauthorized-negative-adjustment
+- Events: E-004
+- Evidence: E-004 applies -2400 cents with role support-agent.
+- Remediation: Require finance or meter-admin approval before applying a negative adjustment.
+
+### [HIGH] entitlement-plan-mismatch
+- Events: E-005
+- Evidence: E-005 was metered as individual-pro, but account acct-institution is on institution.
+- Remediation: Reprice the event under the account's active plan or hold invoice release.
+
+### [HIGH] missing-idempotency-key
+- Events: E-006
+- Evidence: E-006 has no idempotency key.
+- Remediation: Reject or enrich the event before it can create an invoice line.
+
+### [HIGH] source-sequence-gap
+- Events: E-002, E-003
+- Evidence: acct-lab-pro:usage-api jumps from sequence 101 to 104.
+- Remediation: Check replay source logs for missing usage before releasing invoice totals.
+
+### [HIGH] stale-correction
+- Events: E-004
+- Evidence: E-004 correction age is 167.1 hours.
+- Remediation: Route old corrections through a manual reprice or credit memo review.
+
+### [MEDIUM] timestamp-ordering
+- Events: E-006
+- Evidence: E-006 was received before it occurred.
+- Remediation: Normalize source clocks or hold the event from invoice release.
+
+## Finance Prompts
+
+- Which replay jobs can create duplicate invoice lines, and where should idempotency be enforced?
+- Which meter source logs prove whether missing sequence numbers represent lost usage or skipped test events?
+- Which correction approvals should route to credit memo review instead of automatic invoice repricing?
+- Which account plan snapshot should be used as the billable source of truth for this invoice run?