Add trial promotion abuse guard

README.md

@@ -1,2 +1,8 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Revenue infrastructure controls
+
+- `trial-promotion-abuse-guard/` checks free-trial reuse, coupon stacking,
+  consortium discount eligibility, and trial-to-paid readiness before discount
+  leakage reaches invoice-facing revenue.

trial-promotion-abuse-guard/README.md

@@ -0,0 +1,43 @@
+# Trial Promotion Abuse Guard
+
+This module is a focused revenue-control slice for issue #20. It checks whether
+free trials, coupons, consortium discounts, and trial-to-paid conversions are
+safe to release into invoice-facing revenue.
+
+The guard is intentionally self-contained and uses only synthetic data. It does
+not call payment processors, billing providers, or customer systems.
+
+## What It Catches
+
+- Repeat free trials on the same institution domain.
+- Repeat trial attempts using the same payment fingerprint.
+- Disposable-domain trials.
+- Coupon stacking above policy.
+- Consortium discounts without an active roster entry.
+- Trial-to-paid conversion attempts without verified payment.
+- Discount leakage before invoice release.
+
+## Local Review
+
+```sh
+npm run check
+npm test
+npm run demo
+```
+
+The demo writes reviewer artifacts under `reports/`:
+
+- `promotion-abuse-packet.json`
+- `promotion-abuse-report.md`
+- `summary.svg`
+- `summary.png`
+- `demo.mp4`
+
+`demo.mp4` is a short H.264 reviewer preview generated from the checked-in
+summary frame.
+
+## Reviewer Outcome
+
+Finance gets a deterministic decision packet showing which promotions can be
+approved, which need a hold, which should be rejected, and how much discount
+leakage was prevented before the invoice is released.

trial-promotion-abuse-guard/acceptance-notes.md

@@ -0,0 +1,25 @@
+# Acceptance Notes
+
+## Included Checks
+
+- Duplicate free-trial attempts by institution domain and payment fingerprint.
+- Disposable-domain trial rejection.
+- Coupon stacking above the configured policy limit.
+- Discount cap enforcement with prevented-leakage cents.
+- Consortium discount hold when roster evidence is expired.
+- Trial-to-paid hold when payment verification is missing.
+- Clean discount approval path for a valid lab account.
+
+## Validation
+
+Run from this directory:
+
+```sh
+npm run check
+npm test
+npm run demo
+```
+
+The test suite verifies both blocking behavior and one clean approval path. The
+demo regenerates the finance review packet and visual summary from the checked-in
+sample data.

trial-promotion-abuse-guard/demo.js

@@ -0,0 +1,27 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const {buildMarkdownReport, buildSummarySvg, evaluatePromotionControls, money} = require("./index");
+const {sampleData} = require("./sample-data");
+
+const reportsDir = path.join(__dirname, "reports");
+fs.mkdirSync(reportsDir, {recursive: true});
+
+const result = evaluatePromotionControls(sampleData);
+const packetPath = path.join(reportsDir, "promotion-abuse-packet.json");
+const reportPath = path.join(reportsDir, "promotion-abuse-report.md");
+const svgPath = path.join(reportsDir, "summary.svg");
+
+fs.writeFileSync(packetPath, `${JSON.stringify(result, null, 2)}\n`);
+fs.writeFileSync(reportPath, buildMarkdownReport(result));
+fs.writeFileSync(svgPath, buildSummarySvg(result));
+
+console.log("Trial promotion abuse guard demo");
+console.log(`Digest: ${result.digest}`);
+console.log(`Events reviewed: ${result.metrics.totalEvents}`);
+console.log(`Approved: ${result.metrics.approvedEvents}`);
+console.log(`Held: ${result.metrics.heldEvents}`);
+console.log(`Rejected: ${result.metrics.rejectedEvents}`);
+console.log(`Discount leakage prevented: ${money(result.metrics.discountLeakagePreventedCents)}`);
+console.log(`Wrote ${path.relative(process.cwd(), packetPath)}`);
+console.log(`Wrote ${path.relative(process.cwd(), reportPath)}`);
+console.log(`Wrote ${path.relative(process.cwd(), svgPath)}`);