Add partner royalty settlement guard

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Revenue Infrastructure Slices
+
+- [Partner Royalty Settlement Guard](partner-royalty-settlement-guard/README.md) - audit-ready settlement checks for data-licensing and white-label analytics revenue shares.

partner-royalty-settlement-guard/README.md

@@ -0,0 +1,45 @@
+# Partner Royalty Settlement Guard
+
+Self-contained Revenue Infrastructure slice for issue #20. It focuses on a narrow gap that is different from the existing subscription, metering, tax, dispute, SLA, procurement, pricing experiment, renewal, margin, and privacy-gate modules: audit-ready settlement of data-licensing and white-label analytics revenue shares.
+
+The guard evaluates each license invoice before money is released to dataset contributors, reseller partners, and the platform.
+
+## What It Does
+
+- Calculates platform fees, reseller fees, contributor royalty pools, reserves, and payable lines.
+- Blocks duplicate invoices, expired agreements, unauthorized use cases, missing consent attestations, excessive reseller fees, and broken royalty split percentages.
+- Holds otherwise-valid settlements when anonymized subject counts are below the configured aggregation floor or payout lines are below the minimum payout threshold.
+- Produces a deterministic SHA-256 audit digest that finance can archive with the invoice packet.
+- Returns reviewer-ready actions for settlement, hold, and blocker states.
+
+## Files
+
+- `index.js` - dependency-free settlement evaluator.
+- `test.js` - Node assertions covering ready, held, blocked, duplicate, and validation paths.
+- `demo.js` - terminal demo over a synthetic license batch.
+- `requirements-map.md` - explicit mapping to issue #20 requirements.
+- `acceptance-notes.md` - verification notes and limitations.
+- `demo.svg` / `demo.mp4` - short visual demo artifacts for bounty review.
+
+## Run
+
+```bash
+node partner-royalty-settlement-guard/test.js
+node partner-royalty-settlement-guard/demo.js
+```
+
+## Example Output
+
+```text
+Partner Royalty Settlement Guard Demo
+=====================================
+settlements: 3
+ready: 1, held: 1, blocked: 1
+ready payouts: $925.00
+held payouts: $232.56
+blocked gross: $640.00
+```
+
+## Design Notes
+
+The module is synthetic-data-only and has no network, payment, Stripe, PayPal, bank, or credential integration. It is intended to be the policy and audit layer that would run before a real payout provider is called.

partner-royalty-settlement-guard/acceptance-notes.md

@@ -0,0 +1,23 @@
+# Acceptance Notes
+
+## Validation
+
+Run from the repository root:
+
+```bash
+node partner-royalty-settlement-guard/test.js
+node partner-royalty-settlement-guard/demo.js
+ffprobe -v error -show_entries format=duration,size -show_entries stream=codec_name,width,height -of default=noprint_wrappers=1 partner-royalty-settlement-guard/demo.mp4
+```
+
+## Expected Review Signals
+
+- Ready settlement releases payout lines and archives the digest.
+- Low anonymized subject count becomes a hold, not a blocker, so finance can aggregate more usage.
+- Duplicate invoice, expired agreement, missing consent, unauthorized use case, and split mismatch block release.
+- Audit digest remains stable for identical input.
+- All calculations use integer cents.
+
+## Scope Boundary
+
+This is an audit and policy module. It intentionally stops before live payout-provider integration so the demo remains credential-free and safe to run in CI or during review.

partner-royalty-settlement-guard/demo.js

@@ -0,0 +1,100 @@
+"use strict";
+
+const { evaluateSettlement, money } = require("./index");
+
+const sampleBatch = {
+  agreements: [
+    {
+      id: "agr-national-knowledge-graph",
+      datasetId: "dataset-citation-network-2026q2",
+      status: "active",
+      endsAt: "2027-03-31",
+      platformFeeRate: 0.18,
+      resellerFeeRate: 0.08,
+      allowedUseCases: ["policy-planning", "meta-research"],
+      contributorRoyaltySplits: [
+        { contributorId: "lab-north", share: 0.45 },
+        { contributorId: "lab-south", share: 0.35 },
+        { contributorId: "data-trust", share: 0.2 },
+      ],
+    },
+    {
+      id: "agr-white-label-pilot",
+      datasetId: "dataset-method-trends",
+      status: "active",
+      endsAt: "2026-09-30",
+      platformFeeRate: 0.2,
+      resellerFeeRate: 0.12,
+      allowedUseCases: ["white-label-dashboard"],
+      contributorRoyaltySplits: [
+        { contributorId: "methods-lab", share: 0.5 },
+        { contributorId: "instrument-core", share: 0.5 },
+      ],
+    },
+    {
+      id: "agr-expired-consortium",
+      datasetId: "dataset-private-notes",
+      status: "active",
+      endsAt: "2026-01-31",
+      allowedUseCases: ["market-intelligence"],
+      contributorRoyaltySplits: [{ contributorId: "legacy-lab", share: 1 }],
+    },
+  ],
+  licenseEvents: [
+    {
+      id: "lic-001",
+      invoiceId: "INV-2026-05-101",
+      agreementId: "agr-national-knowledge-graph",
+      customerId: "nih-policy-office",
+      datasetId: "dataset-citation-network-2026q2",
+      useCase: "policy-planning",
+      grossCents: 125000,
+      subjectCount: 480,
+      consentAttestation: true,
+    },
+    {
+      id: "lic-002",
+      invoiceId: "INV-2026-05-102",
+      agreementId: "agr-white-label-pilot",
+      customerId: "research-dashboard-reseller",
+      datasetId: "dataset-method-trends",
+      useCase: "white-label-dashboard",
+      grossCents: 36000,
+      subjectCount: 18,
+      consentAttestation: true,
+    },
+    {
+      id: "lic-003",
+      invoiceId: "INV-2026-05-101",
+      agreementId: "agr-expired-consortium",
+      customerId: "market-intel-firm",
+      datasetId: "dataset-private-notes",
+      useCase: "market-intelligence",
+      grossCents: 64000,
+      subjectCount: 72,
+      consentAttestation: false,
+    },
+  ],
+};
+
+const report = evaluateSettlement(sampleBatch);
+
+console.log("Partner Royalty Settlement Guard Demo");
+console.log("=====================================");
+console.log(`settlements: ${report.settlementCount}`);
+console.log(`ready: ${report.totals.readyCount}, held: ${report.totals.heldCount}, blocked: ${report.totals.blockedCount}`);
+console.log(`ready payouts: ${money(report.totals.readyPayoutCents)}`);
+console.log(`held payouts: ${money(report.totals.heldPayoutCents)}`);
+console.log(`blocked gross: ${money(report.totals.blockedGrossCents)}`);
+console.log(`audit digest: ${report.auditDigest.slice(0, 16)}...`);
+
+for (const settlement of report.settlements) {
+  console.log("");
+  console.log(`${settlement.eventId} ${settlement.status.toUpperCase()} ${money(settlement.grossCents)} ${settlement.invoiceId}`);
+  for (const finding of settlement.findings) {
+    console.log(`- ${finding.severity}: ${finding.code} - ${finding.message}`);
+  }
+  for (const action of settlement.recommendedActions) {
+    console.log(`  action: ${action}`);
+  }
+}