Add AI compute idempotency meter guard

[mjshanker]

/claim #20

Reviewer Path

• Start with ai-compute-idempotency-meter-guard/requirements-map.md for the acceptance coverage.
• Then inspect ai-compute-idempotency-meter-guard/index.js and ai-compute-idempotency-meter-guard/test.js for the implementation and regression checks.
• Use ai-compute-idempotency-meter-guard/reports/demo.mp4 and ai-compute-idempotency-meter-guard/reports/finance-review-packet.md for the short demo and finance-review evidence.

Sponsor Outcome

This PR gives the bounty poster a reviewable revenue-control slice for AI compute billing: retries and orphaned tool-call envelopes no longer inflate billable usage, raw usage remains auditable, uncertain reproducibility reruns are held out of invoice-facing revenue until policy is explicit, and clean usage is routed through included quota, prepaid top-ups, or overage invoicing. The sponsor-visible outcome is fewer accidental overcharges, clearer finance review evidence, and a deterministic path to verify the control from synthetic events through generated artifacts.

Summary

• Add a self-contained ai-compute-idempotency-meter-guard module for Revenue Infrastructure.
• Collapse retry/orphaned AI tool-call billing with content-hash idempotency keys that ignore changing request IDs.
• Separate billable-attributed usage from raw event counts so cache hits and repeated events do not inflate invoice usage.
• Hold nondeterministic reproducibility reruns until billing scope is explicit.
• Apply account-level included quota and prepaid top-up balances before releasing overage invoice cents.
• Emit deterministic finance review evidence, including invoice release decisions and recommended finance actions.
• Include synthetic sample data, local tests, JSON/Markdown/SVG reports, and short demo artifacts including H.264 MP4 video.

Acceptance Coverage

• Idempotency: repeated retry/orphaned tool-call events resolve to one billable usage unit.
• Attribution: raw observed events stay visible while only attributed billable units flow into the invoice-facing total.
• Reproducibility: nondeterministic reruns are held for finance review instead of being silently billed.
• Quota/top-up handling: clean usage is allocated to included compute quota, prepaid top-up balance, or invoice overage.
• Invoice readiness: each account gets a deterministic billing decision, invoice cents, and finance action.
• Auditability: generated reports show raw usage, attributed usage, held usage, and the reason each event landed in that bucket.
• Reviewability: the module is isolated, deterministic, and covered by a focused local test harness.

Scope Boundaries

This is not another generic billing engine, metering ledger, dispute guard, SLA credit calculator, royalty settlement module, forecast, FX reconciliation, procurement control, invoice acceptance gate, sanctions/export-control gate, payment rail failover, entitlement downgrade guard, usage anomaly credit memo, payment-webhook activation guard, trial/promotion abuse guard, storage overage billing guard, or institutional account transfer revenue guard.

This slice focuses specifically on AI compute retry idempotency, attribution correctness, and invoice-release safety before usage becomes billable revenue.

Risk And Regression Notes

• The change is isolated under ai-compute-idempotency-meter-guard/; it does not modify existing application runtime paths or existing billing code.
• Billing classification is deterministic and covered by local tests so event order, retry IDs, and duplicate tool-call envelopes do not inflate billable usage.
• Raw, attributed, held, quota-applied, top-up-applied, and overage invoice amounts are preserved in the finance-review packet so a reviewer can audit or override the classification without losing source evidence.
• The demo and generated reports are reproducible from the checked-in sample data, which keeps review focused on the revenue-control behavior rather than environment setup.

Validation

• cd ai-compute-idempotency-meter-guard && npm run check
• cd ai-compute-idempotency-meter-guard && npm test
• cd ai-compute-idempotency-meter-guard && npm run demo
• file ai-compute-idempotency-meter-guard/reports/demo.mp4 ai-compute-idempotency-meter-guard/reports/demo.gif ai-compute-idempotency-meter-guard/reports/summary.svg
• mdls -name kMDItemDurationSeconds -name kMDItemCodecs -name kMDItemPixelHeight -name kMDItemPixelWidth ai-compute-idempotency-meter-guard/reports/demo.mp4
• git diff --check

Demo Artifacts

• ai-compute-idempotency-meter-guard/reports/demo.mp4 - H.264, 960x540, 9.8 seconds
• ai-compute-idempotency-meter-guard/reports/demo.gif
• ai-compute-idempotency-meter-guard/reports/summary.svg
• ai-compute-idempotency-meter-guard/reports/summary.json
• ai-compute-idempotency-meter-guard/reports/finance-review-packet.md

Why This Submission Should Be Rewarded

Compared with competing revenue-infrastructure submissions, this one gives the bounty poster a self-contained decision packet for a concrete billing-control failure mode: synthetic usage events flow through regression tests into JSON, Markdown, SVG, and video artifacts that prove retries and orphaned tool-call envelopes do not inflate billable usage. The latest update also carries clean usage through included quota, prepaid top-up, and overage invoice decisions, so the reviewer can see the exact finance action for each account. The change is isolated from existing runtime paths, preserves raw audit data, and includes a finance-review packet, so the reviewer can verify the revenue-integrity outcome in minutes without external services or guessing at scope.

[mjshanker]

/claim #20