Add storage overage billing guard

README.md

@@ -1,2 +1,6 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+## Revenue Infrastructure Guardrails
+
+- `storage-overage-billing-guard/` reconciles private project storage, dataset snapshots, reproducibility artifacts, and licensed-export caches against institutional plan quotas so storage overage can be invoiced or held with clear finance evidence.

storage-overage-billing-guard/README.md

@@ -0,0 +1,36 @@
+# Storage Overage Billing Guard
+
+This self-contained revenue control reconciles institutional storage usage against contracted storage quotas before invoice release. It covers private project storage, dataset snapshots, reproducibility artifacts, and licensed-export caches using only synthetic data.
+
+## Why This Matters
+
+SCIBASE subscriptions can bundle storage with private projects, AI/reproducibility artifacts, and licensed analytics exports. If storage buckets are not reconciled before invoicing, the platform can miss recurring revenue, charge stale artifacts that should be purged, or delete data that is under legal hold.
+
+This guard produces a finance-ready decision packet:
+
+- `invoice_ready` when storage overage exceeds the contracted invoice minimum and has clean evidence.
+- `hold_for_ops_review` when usage is unmetered, stale, or blocked by a legal/deletion conflict.
+- `monitor` when usage stays within quota and no billing action is needed.
+
+## Run
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+## Outputs
+
+`npm run demo` writes reviewer artifacts to `reports/`:
+
+- `storage-overage-packet.json` with all decisions and charge math.
+- `storage-overage-report.md` with a finance-readable summary.
+- `summary.svg` with a compact visual dashboard.
+- `demo.mp4` with a short static demo video generated alongside the summary SVG.
+
+## Scope
+
+This module is intentionally narrow. It is not a generic billing ledger, seat or renewal true-up engine, payment webhook validator, payment failover module, dispute guard, SLA credit calculator, royalty settlement, revenue forecast, FX reconciliation, procurement control, invoice acceptance gate, sanctions/export-control gate, consortium pricing gate, trial/promotion abuse guard, plan-proration module, or AI compute idempotency meter.
+
+It focuses only on storage overage and retention evidence before storage-related revenue reaches the invoice.

storage-overage-billing-guard/acceptance-notes.md

@@ -0,0 +1,16 @@
+# Acceptance Notes
+
+## Reviewer Path
+
+1. Read `requirements-map.md` to confirm issue #20 coverage and scope boundaries.
+2. Inspect `index.js` for the charge and hold decision logic.
+3. Run `npm test` to verify quota math, unmetered leakage detection, legal-hold conflicts, and annualized run-rate calculations.
+4. Run `npm run demo` to regenerate the JSON, Markdown, SVG, and MP4 reviewer artifacts.
+
+## Synthetic Data Safety
+
+All accounts, institutions, rates, usage values, and artifacts in this module are synthetic. The module does not read environment variables, credentials, network resources, databases, or external APIs.
+
+## Distinctness
+
+This is not a renewal true-up, pricing experiment, payment webhook, payment failover, invoice acceptance, FX, tax, dispute, SLA, royalty, sanctions, promotion, plan migration, or AI compute idempotency module. It is scoped to storage quota reconciliation and retention evidence.

storage-overage-billing-guard/demo.js

@@ -0,0 +1,91 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const {execFileSync} = require('node:child_process');
+const {buildMarkdownReport, buildSummarySVG, evaluateStorageOverage} = require('./index');
+const {storageAccounts} = require('./sample-data');
+
+const reportDir = path.join(__dirname, 'reports');
+fs.mkdirSync(reportDir, {recursive: true});
+
+const evaluation = evaluateStorageOverage(storageAccounts);
+const packetPath = path.join(reportDir, 'storage-overage-packet.json');
+const markdownPath = path.join(reportDir, 'storage-overage-report.md');
+const svgPath = path.join(reportDir, 'summary.svg');
+const mp4Path = path.join(reportDir, 'demo.mp4');
+const framePath = path.join(reportDir, 'summary-frame.ppm');
+const videoNotePath = path.join(reportDir, 'demo-video-note.txt');
+
+function drawRect(buffer, width, x, y, rectWidth, rectHeight, color) {
+  for (let row = Math.max(0, y); row < Math.min(540, y + rectHeight); row += 1) {
+    for (let col = Math.max(0, x); col < Math.min(width, x + rectWidth); col += 1) {
+      const offset = (row * width + col) * 3;
+      buffer[offset] = color[0];
+      buffer[offset + 1] = color[1];
+      buffer[offset + 2] = color[2];
+    }
+  }
+}
+
+function writePPMFrame(evaluationResult, outputPath) {
+  const width = 960;
+  const height = 540;
+  const pixels = Buffer.alloc(width * height * 3, 248);
+  drawRect(pixels, width, 48, 42, 864, 456, [255, 255, 255]);
+  drawRect(pixels, width, 48, 42, 864, 3, [203, 213, 225]);
+  drawRect(pixels, width, 48, 495, 864, 3, [203, 213, 225]);
+  drawRect(pixels, width, 70, 82, 620, 18, [15, 23, 42]);
+  drawRect(pixels, width, 70, 122, Math.min(760, Math.round(evaluationResult.summary.monthlyRecoverableUSD * 3)), 18, [14, 116, 144]);
+  drawRect(pixels, width, 70, 150, Math.min(760, Math.round(evaluationResult.summary.unmeteredLeakageUSD * 20)), 18, [217, 119, 6]);
+
+  const maxCharge = Math.max(...evaluationResult.accounts.map((account) => account.chargesUSD.total), 1);
+  evaluationResult.accounts.forEach((account, index) => {
+    const y = 218 + index * 78;
+    const widthForCharge = Math.max(12, Math.round((account.chargesUSD.total / maxCharge) * 520));
+    const color = account.decision === 'hold_for_ops_review' ? [217, 119, 6] : account.decision === 'invoice_ready' ? [14, 116, 144] : [100, 116, 139];
+    drawRect(pixels, width, 70, y, 610, 2, [226, 232, 240]);
+    drawRect(pixels, width, 70, y + 18, widthForCharge, 28, color);
+  });
+
+  const header = Buffer.from(`P6\n${width} ${height}\n255\n`, 'ascii');
+  fs.writeFileSync(outputPath, Buffer.concat([header, pixels]));
+}
+
+fs.writeFileSync(packetPath, `${JSON.stringify(evaluation, null, 2)}\n`);
+fs.writeFileSync(markdownPath, buildMarkdownReport(evaluation));
+fs.writeFileSync(svgPath, buildSummarySVG(evaluation));
+writePPMFrame(evaluation, framePath);
+if (fs.existsSync(videoNotePath)) {
+  fs.unlinkSync(videoNotePath);
+}
+
+try {
+  execFileSync('ffmpeg', [
+    '-y',
+    '-loop',
+    '1',
+    '-t',
+    '6',
+    '-i',
+    framePath,
+    '-vf',
+    'scale=960:540:force_original_aspect_ratio=decrease,pad=960:540:(ow-iw)/2:(oh-ih)/2:color=white,format=yuv420p',
+    '-c:v',
+    'libx264',
+    '-movflags',
+    '+faststart',
+    mp4Path,
+  ], {stdio: 'ignore'});
+} catch (error) {
+  fs.writeFileSync(videoNotePath, `ffmpeg was not available or failed: ${error.message}\n`);
+} finally {
+  if (fs.existsSync(framePath)) {
+    fs.unlinkSync(framePath);
+  }
+}
+
+console.log(`Wrote ${packetPath}`);
+console.log(`Wrote ${markdownPath}`);
+console.log(`Wrote ${svgPath}`);
+if (fs.existsSync(mp4Path)) {
+  console.log(`Wrote ${mp4Path}`);
+}

storage-overage-billing-guard/index.js

@@ -0,0 +1,208 @@
+const DEFAULT_POLICY = {
+  staleArtifactReviewDays: 7,
+  annualizationFactor: 12,
+};
+
+function roundMoney(value) {
+  return Math.round((Number(value) + Number.EPSILON) * 100) / 100;
+}
+
+function sumBy(items, selector) {
+  return items.reduce((total, item) => total + selector(item), 0);
+}
+
+function artifactHasDeletionConflict(artifact, deletionRequests) {
+  return Boolean(artifact.legalHold && deletionRequests.some((request) => request.artifactID === artifact.id));
+}
+
+function evaluateAccount(account, policy = DEFAULT_POLICY) {
+  const privateMeteredGB = account.usage.privateProjectGB + account.usage.datasetSnapshotGB;
+  const privateBillableGB = privateMeteredGB + account.usage.unmeteredExternalBucketGB;
+  const privateOverageGB = Math.max(0, privateBillableGB - account.contract.privateProjectIncludedGB);
+  const artifactOverageGB = Math.max(0, account.usage.reproducibilityArtifactGB - account.contract.artifactIncludedGB);
+  const licensedCacheOverageGB = Math.max(0, account.usage.licensedExportCacheGB - account.contract.licensedCacheIncludedGB);
+
+  const privateChargeUSD = privateOverageGB * account.contract.privateOverageRateUSD;
+  const artifactChargeUSD = artifactOverageGB * account.contract.artifactOverageRateUSD;
+  const licensedCacheChargeUSD = licensedCacheOverageGB * account.contract.licensedCacheRateUSD;
+  const totalChargeUSD = roundMoney(privateChargeUSD + artifactChargeUSD + licensedCacheChargeUSD);
+  const unmeteredLeakageUSD = roundMoney(account.usage.unmeteredExternalBucketGB * account.contract.privateOverageRateUSD);
+
+  const staleArtifacts = account.artifacts.filter((artifact) => !artifact.legalHold && artifact.ageDays > artifact.retentionDays + policy.staleArtifactReviewDays);
+  const deletionHoldConflicts = account.artifacts.filter((artifact) => artifactHasDeletionConflict(artifact, account.deletionRequests));
+  const purgeCandidateGB = roundMoney(sumBy(staleArtifacts, (artifact) => artifact.gb));
+
+  const reasons = [];
+  if (privateOverageGB > 0) {
+    reasons.push(`${privateOverageGB} GB private storage over quota`);
+  }
+  if (artifactOverageGB > 0) {
+    reasons.push(`${artifactOverageGB} GB reproducibility artifact storage over quota`);
+  }
+  if (licensedCacheOverageGB > 0) {
+    reasons.push(`${licensedCacheOverageGB} GB licensed export cache over quota`);
+  }
+  if (account.usage.unmeteredExternalBucketGB > 0) {
+    reasons.push(`${account.usage.unmeteredExternalBucketGB} GB external bucket usage missing billable meter tags`);
+  }
+  if (staleArtifacts.length > 0) {
+    reasons.push(`${staleArtifacts.length} stale artifact(s) past retention grace`);
+  }
+  if (deletionHoldConflicts.length > 0) {
+    reasons.push(`${deletionHoldConflicts.length} deletion request(s) blocked by legal hold`);
+  }
+
+  let decision = 'monitor';
+  if (deletionHoldConflicts.length > 0 || account.usage.unmeteredExternalBucketGB > 0 || staleArtifacts.length > 0) {
+    decision = 'hold_for_ops_review';
+  } else if (totalChargeUSD >= account.contract.invoiceMinimumUSD) {
+    decision = 'invoice_ready';
+  }
+
+  const recommendedActions = [];
+  if (totalChargeUSD >= account.contract.invoiceMinimumUSD) {
+    recommendedActions.push(`prepare ${account.billingPeriod} storage overage line item for $${totalChargeUSD}`);
+  }
+  if (account.usage.unmeteredExternalBucketGB > 0) {
+    recommendedActions.push('attach meter tags to external bucket storage before invoice release');
+  }
+  if (staleArtifacts.length > 0) {
+    recommendedActions.push(`review or purge ${purgeCandidateGB} GB of stale artifacts`);
+  }
+  if (deletionHoldConflicts.length > 0) {
+    recommendedActions.push('route deletion-hold conflict to compliance owner before changing retention state');
+  }
+  if (recommendedActions.length === 0) {
+    recommendedActions.push('no billing action required this period');
+  }
+
+  return {
+    accountID: account.accountID,
+    institution: account.institution,
+    plan: account.plan,
+    billingPeriod: account.billingPeriod,
+    decision,
+    reasons,
+    usage: {
+      privateMeteredGB,
+      privateBillableGB,
+      artifactBillableGB: account.usage.reproducibilityArtifactGB,
+      licensedCacheBillableGB: account.usage.licensedExportCacheGB,
+      unmeteredExternalBucketGB: account.usage.unmeteredExternalBucketGB,
+    },
+    overage: {
+      privateOverageGB,
+      artifactOverageGB,
+      licensedCacheOverageGB,
+    },
+    chargesUSD: {
+      privateStorage: roundMoney(privateChargeUSD),
+      reproducibilityArtifacts: roundMoney(artifactChargeUSD),
+      licensedExportCache: roundMoney(licensedCacheChargeUSD),
+      total: totalChargeUSD,
+      annualizedRunRate: roundMoney(totalChargeUSD * policy.annualizationFactor),
+      unmeteredLeakage: unmeteredLeakageUSD,
+    },
+    controls: {
+      staleArtifacts: staleArtifacts.map((artifact) => artifact.id),
+      deletionHoldConflicts: deletionHoldConflicts.map((artifact) => artifact.id),
+      purgeCandidateGB,
+    },
+    recommendedActions,
+  };
+}
+
+function evaluateStorageOverage(accounts, policy = DEFAULT_POLICY) {
+  const accountResults = accounts.map((account) => evaluateAccount(account, policy));
+  const summary = {
+    accountsEvaluated: accountResults.length,
+    invoiceReadyCount: accountResults.filter((account) => account.decision === 'invoice_ready').length,
+    holdCount: accountResults.filter((account) => account.decision === 'hold_for_ops_review').length,
+    monitorCount: accountResults.filter((account) => account.decision === 'monitor').length,
+    monthlyRecoverableUSD: roundMoney(sumBy(accountResults, (account) => account.chargesUSD.total)),
+    annualizedRecoverableUSD: roundMoney(sumBy(accountResults, (account) => account.chargesUSD.annualizedRunRate)),
+    unmeteredLeakageUSD: roundMoney(sumBy(accountResults, (account) => account.chargesUSD.unmeteredLeakage)),
+    purgeCandidateGB: roundMoney(sumBy(accountResults, (account) => account.controls.purgeCandidateGB)),
+    deletionHoldConflicts: sumBy(accountResults, (account) => account.controls.deletionHoldConflicts.length),
+  };
+
+  return {
+    generatedAt: new Date().toISOString(),
+    summary,
+    accounts: accountResults,
+  };
+}
+
+function formatCurrency(value) {
+  return `$${roundMoney(value).toLocaleString('en-US', {minimumFractionDigits: 2, maximumFractionDigits: 2})}`;
+}
+
+function buildMarkdownReport(evaluation) {
+  const lines = [
+    '# Storage Overage Billing Guard Report',
+    '',
+    `Generated: ${evaluation.generatedAt}`,
+    '',
+    '## Summary',
+    '',
+    `- Accounts evaluated: ${evaluation.summary.accountsEvaluated}`,
+    `- Invoice-ready accounts: ${evaluation.summary.invoiceReadyCount}`,
+    `- Ops-review holds: ${evaluation.summary.holdCount}`,
+    `- Monthly recoverable storage revenue: ${formatCurrency(evaluation.summary.monthlyRecoverableUSD)}`,
+    `- Annualized run rate: ${formatCurrency(evaluation.summary.annualizedRecoverableUSD)}`,
+    `- Unmetered leakage caught: ${formatCurrency(evaluation.summary.unmeteredLeakageUSD)}`,
+    `- Purge candidates: ${evaluation.summary.purgeCandidateGB} GB`,
+    `- Deletion-hold conflicts: ${evaluation.summary.deletionHoldConflicts}`,
+    '',
+    '## Account Decisions',
+    '',
+    '| Institution | Decision | Charge | Overage | Actions |',
+    '| --- | --- | ---: | --- | --- |',
+  ];
+
+  evaluation.accounts.forEach((account) => {
+    const overage = [
+      `${account.overage.privateOverageGB} GB private`,
+      `${account.overage.artifactOverageGB} GB artifacts`,
+      `${account.overage.licensedCacheOverageGB} GB licensed cache`,
+    ].join('<br>');
+    lines.push(`| ${account.institution} | ${account.decision} | ${formatCurrency(account.chargesUSD.total)} | ${overage} | ${account.recommendedActions.join('<br>')} |`);
+  });
+
+  return `${lines.join('\n')}\n`;
+}
+
+function buildSummarySVG(evaluation) {
+  const maxCharge = Math.max(...evaluation.accounts.map((account) => account.chargesUSD.total), 1);
+  const bars = evaluation.accounts.map((account, index) => {
+    const width = Math.max(12, Math.round((account.chargesUSD.total / maxCharge) * 520));
+    const y = 185 + index * 76;
+    const color = account.decision === 'hold_for_ops_review' ? '#D97706' : account.decision === 'invoice_ready' ? '#0E7490' : '#64748B';
+    return [
+      `<text x="70" y="${y - 10}" font-size="18" font-family="Arial" fill="#111827">${account.institution}</text>`,
+      `<rect x="70" y="${y}" width="${width}" height="24" rx="6" fill="${color}" />`,
+      `<text x="${90 + width}" y="${y + 18}" font-size="16" font-family="Arial" fill="#111827">${formatCurrency(account.chargesUSD.total)} · ${account.decision}</text>`,
+    ].join('\n');
+  });
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg width="960" height="540" viewBox="0 0 960 540" xmlns="http://www.w3.org/2000/svg">
+  <rect width="960" height="540" fill="#F8FAFC"/>
+  <rect x="48" y="42" width="864" height="456" rx="20" fill="#FFFFFF" stroke="#CBD5E1"/>
+  <text x="70" y="92" font-size="30" font-family="Arial" font-weight="700" fill="#0F172A">Storage Overage Billing Guard</text>
+  <text x="70" y="126" font-size="18" font-family="Arial" fill="#475569">Monthly recoverable: ${formatCurrency(evaluation.summary.monthlyRecoverableUSD)} · Annualized: ${formatCurrency(evaluation.summary.annualizedRecoverableUSD)}</text>
+  <text x="70" y="152" font-size="16" font-family="Arial" fill="#475569">Holds: ${evaluation.summary.holdCount} · Unmetered leakage: ${formatCurrency(evaluation.summary.unmeteredLeakageUSD)} · Purge candidates: ${evaluation.summary.purgeCandidateGB} GB</text>
+  ${bars.join('\n')}
+</svg>
+`;
+}
+
+module.exports = {
+  DEFAULT_POLICY,
+  buildMarkdownReport,
+  buildSummarySVG,
+  evaluateAccount,
+  evaluateStorageOverage,
+  formatCurrency,
+  roundMoney,
+};

storage-overage-billing-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "storage-overage-billing-guard",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Synthetic storage overage billing guard for SCIBASE revenue infrastructure.",
+  "type": "commonjs",
+  "scripts": {
+    "check": "node --check index.js && node --check sample-data.js && node --check test.js && node --check demo.js",
+    "test": "node test.js",
+    "demo": "node demo.js"
+  }
+}