thumbgate 1.28.4 → 1.29.2

package/scripts/provider-payment-reconciler.js

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { runAudit: auditStripeLiveEvidence } = require('./external-customer-audit');
+const { auditPayPalLiveEvidence } = require('./provider-live-evidence');
+const { digestBuyerEmail } = require('./provider-revenue-evidence');
+const { OFFER_CATALOG } = require('./revenue-offer-system');
+const {
+  VERIFIED_PAYMENT_DIGEST_PATTERN,
+  VERIFIED_PAYMENT_SOURCE_PATTERN,
+  advanceSalesLead,
+  getSalesPipelinePath,
+  loadSalesLeads,
+} = require('./sales-pipeline');
+
+function normalizeRequiredText(value, label, maxLength = 1000) {
+  const text = String(value || '').trim().slice(0, maxLength);
+  if (!text) throw new Error(`${label} is required.`);
+  return text;
+}
+
+function parseArgs(argv = []) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) continue;
+    const eqIndex = arg.indexOf('=', 2);
+    const rawKey = eqIndex === -1 ? arg.slice(2) : arg.slice(2, eqIndex);
+    const key = rawKey.replaceAll(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (eqIndex !== -1) {
+      options[key] = arg.slice(eqIndex + 1);
+      continue;
+    }
+    const nextArg = argv[index + 1];
+    if (nextArg && !nextArg.startsWith('--')) {
+      options[key] = nextArg;
+      index += 1;
+      continue;
+    }
+    options[key] = true;
+  }
+  return options;
+}
+
+const SUPPORTED_PAYMENT_PROVIDERS = new Set(['paypal', 'stripe']);
+
+function offer(id, leadOffers = [id]) {
+  return Object.freeze([id, Object.freeze(leadOffers)]);
+}
+
+const OFFERS = Object.freeze({
+  [OFFER_CATALOG.workflow_hardening_diagnostic.priceCents]: offer(
+    'workflow_hardening_diagnostic', ['workflow_hardening_diagnostic', 'workflow_diagnostic']),
+  [OFFER_CATALOG.workflow_hardening_sprint.priceCents]: offer('workflow_hardening_sprint'),
+  [OFFER_CATALOG.workflow_hardening_sprint.priceCents
+    - OFFER_CATALOG.workflow_hardening_diagnostic.priceCents]: offer(
+    'workflow_hardening_sprint_diagnostic_credit_balance', ['workflow_hardening_sprint']),
+  [OFFER_CATALOG.pro.priceCents]: offer('pro_monthly', ['pro', 'pro_self_serve', 'pro_monthly']),
+  [OFFER_CATALOG.pro.annualPriceCents]: offer('pro_annual', ['pro', 'pro_self_serve', 'pro_annual']),
+  4900: offer('team_monthly_legacy', ['team', 'team_monthly_legacy']),
+  [OFFER_CATALOG.workflow_reliability_operations.priceCents]: offer('workflow_reliability_operations'),
+  [OFFER_CATALOG.enterprise_governance_pilot.priceCents]: offer('enterprise_governance_pilot'),
+  [OFFER_CATALOG.enterprise_reliability_operations.priceCents]: offer('enterprise_reliability_operations'),
+});
+
+function offerIdsFor(payment = {}) {
+  const attribution = payment.productAttribution || {};
+  const values = [
+    ...(Array.isArray(payment.offerIds) ? payment.offerIds : []),
+    payment.offerId,
+    ...(Array.isArray(attribution.offerIds) ? attribution.offerIds : []),
+    attribution.offerId,
+  ];
+  return [...new Set(values
+    .map((value) => String(value || '').trim().slice(0, 120))
+    .filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function matchPaymentOffer(payment = {}, lead = {}) {
+  const leadOffer = String(lead.offer || '').trim();
+  const identity = OFFERS[payment.grossCents];
+  if (!identity) {
+    throw new Error(`${payment.provider} payment ${payment.id} amount has no exact ThumbGate offer.`);
+  }
+  const [offerId, leadOffers] = identity;
+  const offerIds = Array.isArray(payment.offerIds) ? payment.offerIds : [];
+  if (payment.provider === 'stripe' && offerIds.length !== 1) {
+    throw new Error(`Stripe ${payment.id} requires one catalog offer ID.`);
+  }
+  if (payment.provider === 'paypal' && offerIds.length > 1) {
+    throw new Error(`PayPal ${payment.id} has multiple offer IDs.`);
+  }
+  if (offerIds.length === 1 && offerIds[0] !== offerId) {
+    throw new Error(`${payment.provider} payment ${payment.id} offer disagrees with amount.`);
+  }
+  if (!leadOffers.includes(leadOffer)) {
+    throw new Error(`${payment.provider} payment ${payment.id} is for ${offerId}, not ${leadOffer || '(missing)'}.`);
+  }
+  const buyerDigest = digestBuyerEmail(lead.contact?.email);
+  if (!buyerDigest) {
+    throw new Error(`Sales lead ${lead.leadId || '(missing)'} needs buyer email.`);
+  }
+  if (payment.buyerEmailDigest !== buyerDigest) {
+    throw new Error(`${payment.provider} payment ${payment.id} buyer does not match lead ${lead.leadId || '(missing)'}.`);
+  }
+  return {
+    paymentOfferId: offerId,
+    buyerEmailDigest: buyerDigest,
+  };
+}
+
+function validateVerifiedPayment(payment = {}, expectedId, expectedProvider = 'paypal', { auditedAt } = {}) {
+  const paymentId = String(payment.id || '').trim();
+  const provider = String(payment.provider || '').trim().toLowerCase();
+  const evidenceSource = String(payment.evidenceSource || '').trim();
+  const evidenceDigest = String(payment.evidenceDigest || '').trim().toLowerCase();
+  const status = String(payment.status || '').trim().toLowerCase();
+  const grossCents = payment.grossCents;
+  const refundedCents = payment.refundedCents;
+  const netCents = payment.netCents;
+  const currency = String(payment.currency || '').trim().toLowerCase();
+  const createdAt = new Date(String(payment.createdAt || ''));
+  const auditTime = new Date(String(auditedAt || ''));
+  const productAttribution = payment.productAttribution || {};
+  const invoiceId = String(payment.invoiceId || '').trim().slice(0, 127) || null;
+  const offerIds = offerIdsFor(payment);
+  const buyerEmailDigest = String(payment.buyerEmailDigest || '').trim().toLowerCase();
+
+  if (paymentId !== expectedId || provider !== expectedProvider ||
+      !SUPPORTED_PAYMENT_PROVIDERS.has(provider) || payment.evidenceVerified !== true
+      || !VERIFIED_PAYMENT_SOURCE_PATTERN.test(evidenceSource)
+      || !VERIFIED_PAYMENT_DIGEST_PATTERN.test(evidenceDigest)
+      || !Number.isSafeInteger(grossCents) || grossCents <= 0
+      || !Number.isSafeInteger(refundedCents) || refundedCents < 0 || refundedCents > grossCents
+      || !Number.isSafeInteger(netCents) || netCents < 0 || netCents !== grossCents - refundedCents
+      || currency !== 'usd'
+      || !/^sha256:[a-f0-9]{64}$/.test(buyerEmailDigest)
+      || (netCents === 0 ? status !== 'refunded' : !['completed', 'partially_refunded'].includes(status))
+      || Number.isNaN(createdAt.getTime())
+      || Number.isNaN(auditTime.getTime()) || createdAt.getTime() > auditTime.getTime() + 5 * 60 * 1000
+      || payment.customerClassification !== 'external' || payment.ownerTest !== false
+      || productAttribution.verified !== true
+      || String(productAttribution.product || '').trim().toLowerCase() !== 'thumbgate') {
+    throw new Error(`${expectedProvider} payment is malformed or lacks verified evidence.`);
+  }
+
+  return {
+    provider,
+    id: paymentId,
+    status,
+    grossCents,
+    refundedCents,
+    netCents,
+    currency,
+    createdAt: createdAt.toISOString(),
+    evidenceSource,
+    evidenceDigest,
+    invoiceId,
+    offerIds,
+    buyerEmailDigest,
+  };
+}
+
+function findPaymentUse(leads, payment) {
+  for (const lead of leads) {
+    for (const event of [...(lead.history || [])].reverse()) {
+      const evidence = event.evidence || {};
+      if (['provider_payment', 'provider_refund'].includes(evidence.kind)
+          && evidence.provider === payment.provider
+          && evidence.reference === payment.id
+          && evidence.verified === true) {
+        return { leadId: lead.leadId, event };
+      }
+    }
+  }
+  return null;
+}
+
+async function withPaymentReconciliationLock(statePath, operation, options = {}) {
+  const lockPath = `${statePath}.reconcile.lock`;
+  const retryDelayMs = options.retryDelayMs || 10;
+  const maxAttempts = options.maxAttempts || 400;
+  const staleAfterMs = options.staleAfterMs || 30_000;
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  let acquired = false;
+  for (let attempt = 0; attempt < maxAttempts && !acquired; attempt += 1) {
+    try {
+      fs.mkdirSync(lockPath);
+      acquired = true;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs > staleAfterMs) {
+          fs.rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (statError) {
+        if (statError?.code !== 'ENOENT') throw statError;
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+  }
+  if (!acquired) throw new Error('Sales payment reconciliation is busy; retry after the active reconciliation finishes.');
+  try {
+    return await operation();
+  } finally {
+    fs.rmSync(lockPath, { recursive: true, force: true });
+  }
+}
+
+async function reconcileProviderPayment(payload = {}, options = {}) {
+  const leadId = normalizeRequiredText(payload.leadId || payload.lead, 'leadId', 160);
+  const paymentId = normalizeRequiredText(payload.paymentId || payload.payment, 'paymentId', 1000);
+  const provider = String(payload.provider || 'paypal').trim().toLowerCase();
+  if (!SUPPORTED_PAYMENT_PROVIDERS.has(provider)) {
+    throw new Error(`provider must be one of: ${[...SUPPORTED_PAYMENT_PROVIDERS].join(', ')}.`);
+  }
+
+  const stateOptions = {
+    statePath: options.statePath || payload.statePath || null,
+    feedbackDir: options.feedbackDir || payload.feedbackDir || null,
+  };
+  const preflightLead = loadSalesLeads(stateOptions).find((entry) => entry.leadId === leadId);
+  if (!preflightLead) throw new Error(`Unknown sales lead: ${leadId}`);
+
+  const auditOptions = {
+    env: options.env || process.env,
+    now: options.now || payload.now,
+    timeZone: options.timeZone || payload.timeZone,
+  };
+  const audit = provider === 'paypal'
+    ? await (options.auditPayPalLiveEvidence || auditPayPalLiveEvidence)({
+      ...auditOptions,
+      fetchImpl: options.fetchImpl,
+    })
+    : await (options.auditStripeLiveEvidence || auditStripeLiveEvidence)({
+      ...auditOptions,
+      stripeClient: options.stripeClient,
+      stripeFactory: options.stripeFactory,
+      secretKey: options.stripeSecretKey,
+      secretPaths: options.secretPaths,
+    });
+  const auditedAt = new Date(String(audit?.generatedAt || options.now || payload.now || new Date().toISOString()));
+  const reconciliationAt = Number.isNaN(auditedAt.getTime())
+    ? new Date().toISOString()
+    : auditedAt.toISOString();
+  const stripeEvidence = audit?.productAttribution?.thumbgate || {};
+  const candidates = provider === 'stripe'
+    ? (Array.isArray(stripeEvidence.individualPaymentStates)
+      ? stripeEvidence.individualPaymentStates
+      : (Array.isArray(audit?.individualPaymentStates) ? audit.individualPaymentStates : []))
+    : (Array.isArray(audit?.individualPaymentStates)
+      ? audit.individualPaymentStates
+      : (Array.isArray(audit?.individualPayments) ? audit.individualPayments : []));
+  const candidate = candidates.find((payment) => String(payment?.id || '').trim() === paymentId);
+  if (!candidate) {
+    const gap = String(audit?.gap || '').trim();
+    throw new Error(gap
+      ? `Live ${provider} audit did not verify payment ${paymentId}: ${gap}`
+      : `Live ${provider} audit did not verify payment ${paymentId}.`);
+  }
+  const payment = validateVerifiedPayment(candidate, paymentId, provider, {
+    auditedAt: reconciliationAt,
+  });
+
+  return withPaymentReconciliationLock(getSalesPipelinePath(stateOptions), () => {
+  const leads = loadSalesLeads(stateOptions);
+  const lead = leads.find((entry) => entry.leadId === leadId);
+  if (!lead) throw new Error(`Unknown sales lead: ${leadId}`);
+  const offerMatch = matchPaymentOffer(payment, lead);
+  const existingUse = findPaymentUse(leads, payment);
+  if (existingUse && existingUse.leadId !== leadId) {
+    throw new Error(`${provider} payment ${paymentId} is already attributed to another sales lead.`);
+  }
+  if (payment.netCents === 0) {
+    if (!existingUse || existingUse.leadId !== leadId || !['paid', 'lost'].includes(lead.stage)) {
+      throw new Error(`Fully refunded ${provider} payment ${paymentId} cannot create a new paid pipeline record.`);
+    }
+    if (lead.stage === 'lost' && existingUse.event.evidence.kind === 'provider_refund') {
+      return {
+        provider: payment.provider,
+        paymentId: payment.id,
+        leadId,
+        stage: lead.stage,
+        amountCents: lead.revenue.amountCents,
+        currency: lead.revenue.currency,
+        offerId: offerMatch.paymentOfferId,
+        evidenceDigest: existingUse.event.evidence.digest,
+        reverifiedEvidenceDigest: payment.evidenceDigest,
+        unchanged: true,
+        statePath: getSalesPipelinePath(stateOptions),
+      };
+    }
+    if (lead.stage !== 'paid') {
+      throw new Error(`Sales lead ${leadId} cannot apply a full refund from stage ${lead.stage}.`);
+    }
+    const refunded = advanceSalesLead({
+      leadId,
+      stage: 'lost',
+      amountCents: 0,
+      currency: 'usd',
+      timestamp: reconciliationAt,
+      evidenceKind: 'provider_refund',
+      evidenceProvider: payment.provider,
+      evidenceSource: payment.evidenceSource,
+      evidenceRef: payment.id,
+      evidenceVerified: true,
+      evidenceDigest: payment.evidenceDigest,
+      evidenceInvoiceId: payment.invoiceId,
+      evidenceOfferId: offerMatch.paymentOfferId,
+      evidenceBuyerDigest: offerMatch.buyerEmailDigest,
+      actor: 'provider-reconciliation',
+      note: `Paid status retired after authenticated live ${provider} evidence verified a full refund.`,
+    }, stateOptions);
+    return {
+      provider: payment.provider,
+      paymentId: payment.id,
+      leadId,
+      stage: refunded.lead.stage,
+      amountCents: refunded.lead.revenue.amountCents,
+      currency: refunded.lead.revenue.currency,
+      offerId: offerMatch.paymentOfferId,
+      evidenceDigest: payment.evidenceDigest,
+      unchanged: refunded.unchanged,
+      statePath: getSalesPipelinePath(stateOptions),
+    };
+  }
+  const existingBindingMatches = existingUse?.event?.evidence?.offerId === offerMatch.paymentOfferId
+    && existingUse?.event?.evidence?.buyerDigest === offerMatch.buyerEmailDigest;
+  if (existingUse && existingUse.leadId === leadId && lead.stage === 'paid'
+      && lead.revenue.amountCents === payment.netCents && existingBindingMatches) {
+    return {
+      provider: payment.provider,
+      paymentId: payment.id,
+      leadId,
+      stage: lead.stage,
+      amountCents: lead.revenue.amountCents,
+      currency: lead.revenue.currency,
+      offerId: offerMatch.paymentOfferId,
+      evidenceDigest: existingUse.event.evidence.digest,
+      reverifiedEvidenceDigest: payment.evidenceDigest,
+      unchanged: true,
+      statePath: getSalesPipelinePath(stateOptions),
+    };
+  }
+  if (existingUse && existingUse.leadId === leadId && lead.stage !== 'paid') {
+    throw new Error(`Sales lead ${leadId} cannot restore paid revenue from stage ${lead.stage}.`);
+  }
+  if (lead.stage === 'paid') {
+    if (!existingUse) throw new Error(`Sales lead ${leadId} is already paid with different evidence.`);
+  }
+
+  const upgradesLegacyBinding = Boolean(existingUse
+    && lead.revenue.amountCents === payment.netCents
+    && !existingBindingMatches);
+
+  const result = advanceSalesLead({
+    leadId,
+    stage: 'paid',
+    amountCents: payment.netCents,
+    currency: 'usd',
+    timestamp: existingUse ? reconciliationAt : payment.createdAt,
+    evidenceKind: 'provider_payment',
+    evidenceProvider: payment.provider,
+    evidenceSource: payment.evidenceSource,
+    evidenceRef: payment.id,
+    evidenceVerified: true,
+    evidenceDigest: payment.evidenceDigest,
+    evidenceInvoiceId: payment.invoiceId,
+    evidenceOfferId: offerMatch.paymentOfferId,
+    evidenceBuyerDigest: offerMatch.buyerEmailDigest,
+    actor: 'provider-reconciliation',
+    note: existingUse
+      ? (upgradesLegacyBinding
+        ? `Live ${provider} buyer and offer binding added.`
+        : `Paid amount updated from authenticated live ${provider} refund-adjusted evidence.`)
+      : `Paid status reconciled from authenticated live ${provider} evidence.`,
+    force: payload.force === true,
+  }, stateOptions);
+
+  return {
+    provider: payment.provider,
+    paymentId: payment.id,
+    leadId,
+    stage: result.lead.stage,
+    amountCents: result.lead.revenue.amountCents,
+    currency: result.lead.revenue.currency,
+    offerId: offerMatch.paymentOfferId,
+    evidenceDigest: payment.evidenceDigest,
+    unchanged: result.unchanged,
+    statePath: getSalesPipelinePath(stateOptions),
+  };
+  });
+}
+
+async function runCli(argv = process.argv.slice(2), options = {}) {
+  const args = parseArgs(argv);
+  return reconcileProviderPayment({
+    leadId: args.lead || args.leadId,
+    paymentId: args.payment || args.paymentId,
+    provider: args.provider,
+    force: args.force === true,
+    now: args.now,
+    timeZone: args.timeZone,
+  }, {
+    ...options,
+    statePath: args.state || options.statePath,
+    feedbackDir: args.feedbackDir || options.feedbackDir,
+  });
+}
+
+function isCliInvocation(argv = process.argv) {
+  const invokedPath = argv[1];
+  if (!invokedPath) return false;
+  try {
+    return fs.realpathSync(path.resolve(invokedPath)) === fs.realpathSync(__filename);
+  } catch {
+    return path.resolve(invokedPath) === path.resolve(__filename);
+  }
+}
+
+if (isCliInvocation()) {
+  runCli()
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((error) => {
+      console.error(error?.message || error);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = {
+  findPaymentUse,
+  isCliInvocation,
+  parseArgs,
+  reconcileProviderPayment,
+  runCli,
+  validateVerifiedPayment,
+  withPaymentReconciliationLock,
+};

package/scripts/provider-revenue-evidence.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+
+const { formatLocalDate, resolveAnalyticsWindow } = require('./analytics-window');
+
+const SCHEMA_VERSION = 1;
+const MAX_SNAPSHOT_AGE_MS = 24 * 60 * 60 * 1000;
+const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const PROVIDERS = Object.freeze(['paypal', 'merchantOfRecord', 'githubMarketplace']);
+const SOURCE_KINDS = Object.freeze({
+  paypal: new Set(['provider_api_export', 'provider_api_live']),
+  merchantOfRecord: new Set(['provider_api_export', 'provider_api_live']),
+  githubMarketplace: new Set(['provider_api_export']),
+});
+const COUNTED_STATUSES = new Set(['paid', 'settled', 'completed', 'partially_refunded', 'refunded']);
+const ALLOWED_STATUSES = new Set([...COUNTED_STATUSES, 'cancelled', 'canceled', 'failed']);
+
+function normalizeBuyerEmail(value) {
+  const email = String(value || '').trim().toLowerCase();
+  return email && email.length <= 320 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ? email : null;
+}
+
+function digestBuyerEmail(value) {
+  const email = normalizeBuyerEmail(value);
+  return email ? `sha256:${crypto.createHash('sha256').update(`thumbgate-buyer-email-v1:${email}`).digest('hex')}` : null;
+}
+
+function localDateRange(startLocalDate, endLocalDate) {
+  const dates = [];
+  const end = Date.parse(`${endLocalDate}T00:00:00.000Z`);
+  for (let cursor = Date.parse(`${startLocalDate}T00:00:00.000Z`); cursor <= end; cursor += 86400000) {
+    dates.push(new Date(cursor).toISOString().slice(0, 10));
+  }
+  return dates;
+}
+
+function canonicalProvider(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[^a-z0-9]/g, '');
+  if (normalized === 'paypal') return 'paypal';
+  if (normalized === 'merchantofrecord' || normalized === 'mor') return 'merchantOfRecord';
+  if (normalized === 'githubmarketplace' || normalized === 'github') return 'githubMarketplace';
+  return null;
+}
+
+function integer(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function parseTimestamp(value) {
+  const parsed = new Date(String(value || ''));
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+function fail(provider, gap, extra = {}) {
+  return {
+    provider,
+    audited: false,
+    status: 'audit_incomplete',
+    evidenceVerified: false,
+    evidenceSource: null,
+    evidenceDigest: extra.evidenceDigest || null,
+    revenue: null,
+    gap,
+  };
+}
+
+function auditProviderSnapshot(snapshot, {
+  expectedProvider,
+  now,
+  timeZone = 'UTC',
+  evidenceDigest = null,
+  evidencePath = null,
+} = {}) {
+  const provider = canonicalProvider(expectedProvider || snapshot?.provider);
+  if (!provider || !PROVIDERS.includes(provider)) return fail(provider || expectedProvider || null, 'Unsupported revenue provider.');
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) return fail(provider, 'Evidence must be one JSON object.');
+  if (snapshot.schemaVersion !== SCHEMA_VERSION) return fail(provider, `schemaVersion must equal ${SCHEMA_VERSION}.`);
+  if (canonicalProvider(snapshot.provider) !== provider) return fail(provider, 'Snapshot provider does not match the requested provider.');
+
+  const nowDate = parseTimestamp(now || new Date().toISOString());
+  const generatedAt = parseTimestamp(snapshot.generatedAt);
+  if (!nowDate || !generatedAt) return fail(provider, 'now and generatedAt must be valid ISO timestamps.', { evidenceDigest });
+  if (generatedAt.getTime() > nowDate.getTime() + MAX_FUTURE_SKEW_MS) return fail(provider, 'Snapshot generatedAt is implausibly in the future.', { evidenceDigest });
+  if (nowDate.getTime() - generatedAt.getTime() > MAX_SNAPSHOT_AGE_MS) return fail(provider, 'Snapshot is stale; provider evidence must be refreshed within 24 hours.', { evidenceDigest });
+
+  const sourceKind = String(snapshot.source?.kind || '').trim();
+  const sourceReference = String(snapshot.source?.reference || '').trim();
+  if (!SOURCE_KINDS[provider].has(sourceKind) || !sourceReference) {
+    return fail(provider, 'A supported provider-origin source.kind and non-empty source.reference are required.', { evidenceDigest });
+  }
+  if (String(snapshot.currency || '').trim().toLowerCase() !== 'usd') return fail(provider, 'Only an explicit USD snapshot can enter the USD target control.', { evidenceDigest });
+
+  let window;
+  try {
+    window = resolveAnalyticsWindow({ window: '30d', now: nowDate.toISOString(), timeZone });
+  } catch (error) {
+    return fail(provider, `Invalid audit window: ${error.message}`, { evidenceDigest });
+  }
+  const scope = snapshot.scope || {};
+  const scopeDatePattern = /^\d{4}-\d{2}-\d{2}$/;
+  if (!scopeDatePattern.test(String(scope.startLocalDate || '')) ||
+      !scopeDatePattern.test(String(scope.endLocalDate || '')) ||
+      scope.completeness !== 'all_transactions' || scope.timeZone !== window.timeZone ||
+      String(scope.startLocalDate || '') > window.startLocalDate ||
+      String(scope.endLocalDate || '') !== window.endLocalDate) {
+    return fail(provider, 'Snapshot scope must attest all transactions and cover the exact trailing 30-day local-date window.', { evidenceDigest });
+  }
+
+  if (!Array.isArray(snapshot.transactions) || !Array.isArray(snapshot.subscriptions)) {
+    return fail(provider, 'transactions and subscriptions must both be arrays, including for audited zero.', { evidenceDigest });
+  }
+  const subscriptionsComplete = scope.subscriptionsCompleteness !== 'not_audited';
+  if (!subscriptionsComplete && snapshot.subscriptions.length > 0) {
+    return fail(provider, 'A snapshot cannot include subscriptions while declaring subscription state not audited.', { evidenceDigest });
+  }
+
+  const dates = localDateRange(window.startLocalDate, window.endLocalDate);
+  const dailyGrossRevenueCents = Object.fromEntries(dates.map((date) => [date, 0]));
+  const dailyNetRevenueCents = Object.fromEntries(dates.map((date) => [date, 0]));
+  const transactionIds = new Set();
+  const payingCustomers = new Set();
+  let transactionCount = 0;
+
+  for (const [index, transaction] of snapshot.transactions.entries()) {
+    const id = String(transaction?.id || '').trim();
+    const status = String(transaction?.status || '').trim().toLowerCase();
+    const createdAt = parseTimestamp(transaction?.createdAt);
+    const grossCents = integer(transaction?.grossCents);
+    const refundedCents = integer(transaction?.refundedCents);
+    const customerId = String(transaction?.customerId || '').trim();
+    const attributed = transaction?.productAttribution?.verified === true &&
+      String(transaction?.productAttribution?.product || '').trim().toLowerCase() === 'thumbgate';
+    const external = transaction?.customerClassification === 'external' && transaction?.ownerTest === false;
+    if (!id || transactionIds.has(id)) return fail(provider, `Transaction ${index} has a missing or duplicate provider ID.`, { evidenceDigest });
+    transactionIds.add(id);
+    if (!ALLOWED_STATUSES.has(status)) return fail(provider, `Transaction ${id} has an unsupported status.`, { evidenceDigest });
+    if (!createdAt || createdAt.getTime() > nowDate.getTime() + MAX_FUTURE_SKEW_MS) return fail(provider, `Transaction ${id} has an invalid or future createdAt.`, { evidenceDigest });
+    if (grossCents === null || refundedCents === null || refundedCents > grossCents) return fail(provider, `Transaction ${id} has invalid gross/refund cents.`, { evidenceDigest });
+    if (status === 'refunded' && refundedCents !== grossCents) return fail(provider, `Transaction ${id} is marked refunded but is not fully refunded.`, { evidenceDigest });
+    if (status === 'partially_refunded' && (refundedCents === 0 || refundedCents === grossCents)) return fail(provider, `Transaction ${id} has an inconsistent partial-refund status.`, { evidenceDigest });
+    if (!customerId || !attributed || !external) return fail(provider, `Transaction ${id} lacks verified ThumbGate attribution or external-customer evidence.`, { evidenceDigest });
+    if (!COUNTED_STATUSES.has(status)) continue;
+    const localDate = formatLocalDate(createdAt, window.timeZone);
+    if (!(localDate in dailyGrossRevenueCents)) continue;
+    const netCents = grossCents - refundedCents;
+    dailyGrossRevenueCents[localDate] += grossCents;
+    dailyNetRevenueCents[localDate] += netCents;
+    transactionCount += 1;
+    if (netCents > 0) payingCustomers.add(customerId);
+  }
+
+  const subscriptionIds = new Set();
+  const activeSubscriptionCustomers = new Set();
+  let activeSubscriptionCount = 0;
+  let mrrCents = 0;
+  for (const [index, subscription] of snapshot.subscriptions.entries()) {
+    const id = String(subscription?.id || '').trim();
+    const status = String(subscription?.status || '').trim().toLowerCase();
+    const customerId = String(subscription?.customerId || '').trim();
+    const monthlyCents = integer(subscription?.mrrCents);
+    const attributed = subscription?.productAttribution?.verified === true &&
+      String(subscription?.productAttribution?.product || '').trim().toLowerCase() === 'thumbgate';
+    const external = subscription?.customerClassification === 'external' && subscription?.ownerTest === false;
+    if (!id || subscriptionIds.has(id)) return fail(provider, `Subscription ${index} has a missing or duplicate provider ID.`, { evidenceDigest });
+    subscriptionIds.add(id);
+    if (!['active', 'trialing', 'cancelled', 'canceled', 'past_due'].includes(status)) return fail(provider, `Subscription ${id} has an unsupported status.`, { evidenceDigest });
+    if (monthlyCents === null || !customerId || !attributed || !external) return fail(provider, `Subscription ${id} lacks valid MRR, attribution, or external-customer evidence.`, { evidenceDigest });
+    if (status !== 'active') continue;
+    activeSubscriptionCount += 1;
+    mrrCents += monthlyCents;
+    activeSubscriptionCustomers.add(customerId);
+  }
+
+  const todayGrossRevenueCents = dailyGrossRevenueCents[window.endLocalDate];
+  const todayNetRevenueCents = dailyNetRevenueCents[window.endLocalDate];
+  const trailing30DayGrossRevenueCents = Object.values(dailyGrossRevenueCents).reduce((sum, value) => sum + value, 0);
+  const trailing30DayNetRevenueCents = Object.values(dailyNetRevenueCents).reduce((sum, value) => sum + value, 0);
+  for (const customerId of activeSubscriptionCustomers) payingCustomers.add(customerId);
+
+  return {
+    provider,
+    audited: true,
+    status: 'provider_snapshot_audited',
+    evidenceVerified: true,
+    evidenceSource: `${sourceKind}:${sourceReference}`,
+    evidenceDigest,
+    evidencePath,
+    gap: null,
+    revenue: {
+      verified: true,
+      currency: 'usd',
+      basis: 'provider-origin all-transactions snapshot; refunds assigned to original transaction cohort',
+      timeZone: window.timeZone,
+      todayLocalDate: window.endLocalDate,
+      trailing30DayStartLocalDate: window.startLocalDate,
+      todayGrossRevenueCents,
+      todayNetRevenueCents,
+      trailing30DayGrossRevenueCents,
+      trailing30DayNetRevenueCents,
+      dailyGrossRevenueCents,
+      dailyNetRevenueCents,
+      externalMrrCents: subscriptionsComplete ? mrrCents : null,
+      activeExternalSubscriptions: subscriptionsComplete ? activeSubscriptionCount : null,
+      externalPayingCustomerIdentities: payingCustomers.size,
+      countedTransactionCount: transactionCount,
+    },
+  };
+}
+
+function auditProviderSnapshotFile(filePath, options = {}) {
+  const provider = canonicalProvider(options.expectedProvider);
+  if (!filePath) return fail(provider, `${provider} evidence path was not provided.`);
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath);
+  } catch (error) {
+    return fail(provider, `Could not read provider evidence: ${error.message}`);
+  }
+  const evidenceDigest = `sha256:${crypto.createHash('sha256').update(raw).digest('hex')}`;
+  let snapshot;
+  try {
+    snapshot = JSON.parse(raw.toString('utf8'));
+  } catch (error) {
+    return fail(provider, `Provider evidence is not valid JSON: ${error.message}`, { evidenceDigest });
+  }
+  return auditProviderSnapshot(snapshot, { ...options, evidenceDigest, evidencePath: filePath });
+}
+
+function auditProviderEvidenceFiles({ paths = {}, now, timeZone } = {}) {
+  return Object.fromEntries(PROVIDERS.map((provider) => [
+    provider,
+    auditProviderSnapshotFile(paths[provider], { expectedProvider: provider, now, timeZone }),
+  ]));
+}
+
+module.exports = {
+  MAX_SNAPSHOT_AGE_MS,
+  PROVIDERS,
+  SCHEMA_VERSION,
+  auditProviderEvidenceFiles,
+  auditProviderSnapshot,
+  auditProviderSnapshotFile,
+  canonicalProvider,
+  digestBuyerEmail,
+  normalizeBuyerEmail,
+};