Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

33.5 KB
Raw Blame
// api/_lib/x402/ring-reconciliation.js
//
// Ring Reconciliation — closes the reconciliation blind spot over the closed-loop
// x402 ring economy. The daily revenue reconciler (revenue-reconciliation.js)
// proves x402_autonomous_log and agent_payment_intents against the chain, but the
// ring's own books — x402_self_facilitator_log (every settle our self-hosted
// facilitator broadcast) and x402_ring_ledger (treasury→payer sweeps) — were
// never verified. A settlement that exists only in the facilitator log is a
// claim, not a fact; this module makes it a fact or a paged discrepancy.
//
// WHY A SIBLING MODULE, NOT AN EXTENSION OF revenue-reconciliation.js
// -------------------------------------------------------------------
// Three reasons. (1) Cadence: the ring ticks per-minute, so its silence alarm
// (the zero-volume tripwire) needs a 30-minute cycle — the revenue reconciler is
// daily and must stay daily. (2) Different verification depth: ring checks parse
// transactions to prove amount + receiver, not just signature existence. (3) The
// hard constraint that the existing reconciler's behavior for non-ring scopes
// stays byte-identical — a separate module makes that trivially true. Both
// modules share the same payment_reconciliation verdict table, upsert shape, and
// UNIQUE(source, source_ref) convention, so the ops financial-integrity board
// reads ring findings alongside everything else, separated by source.
//
// THE FIVE CHECKS (every 30 min, 72h rolling window, read-only on chain)
// ----------------------------------------------------------------------
//   1. SETTLE INTEGRITY — every ok settle in x402_self_facilitator_log must have
//      a tx signature that exists and succeeded on-chain (batched
//      getSignatureStatuses). Missing → x402_ring_settle_missing; reverted →
//      x402_ring_settle_failed. Both CRITICAL: the facilitator said "settled"
//      and the chain disagrees.
//   2. AMOUNT FIDELITY — for a sampled subset of confirmed settles (bounded by
//      the shared 50-parsed-tx budget), parse the transaction and prove the
//      recipient (pay_to) gained EXACTLY amount_atomic of the logged mint, from
//      pre/postTokenBalances. Divergence → x402_ring_amount_mismatch (CRITICAL:
//      the log's dollar figure is fiction).
//   3. SWEEP INTEGRITY — every x402_ring_ledger kind='sweep' row: signature must
//      exist + succeed, and (parsed, budget-first priority) the USDC must have
//      moved from_wallet → to_wallet in the exact ledger amount, with
//      from_wallet equal to the configured treasury. Wrong direction, wrong
//      amount, or a non-treasury source → x402_ring_sweep_mismatch (CRITICAL).
//   4. CROSS-LOG COHERENCE — a ring tick lands in BOTH books: the buyer side in
//      x402_autonomous_log and the settlement side in x402_self_facilitator_log,
//      joined on signature. A settlement with no buyer record is value leaving
//      through our own facilitator with no spender we know of; a ring-settle
//      buyer row with no settlement record means the facilitator log is losing
//      rows. Either orphan → x402_ring_log_orphan (WARN, daily-throttled alert;
//      rows younger than the grace window are skipped so an in-flight tick is
//      never a false positive).
//   5. FEE COHERENCE — yesterday's summed fee_lamports from the facilitator log
//      vs the fee-audit rollup's number for the same day (x402_fee_audit,
//      written by the fee-minimization pipeline). >20% divergence → WARN,
//      daily-throttled. If the fee-audit table has not landed in this
//      environment yet the check reports itself skipped rather than inventing a
//      comparison.
//
// ZERO-VOLUME TRIPWIRE — if the ring is enabled (self-facilitator on + treasury
// configured; ctx.ringEnabled overrides for callers that already validated
// config) and the facilitator log shows zero ok settles in the last 30 minutes,
// alert "ring enabled but silent". This is the alarm for "it was working and
// then it wasn't" — the failure mode that previously went unnoticed. The verdict
// row flips back to reconciled the moment volume returns, so the board self-heals.
//
// BOUNDS — read-only against the chain; getSignatureStatuses batched at 256; at
// most MAX_PARSED_TX_PER_RUN (50) getParsedTransaction calls per run, sweeps
// funded from that budget first (they are rare and each one moves the whole
// float). Never mutates the logs it audits — verdicts in payment_reconciliation
// and one x402_autonomous_log summary row are the only writes.
//
// Wiring: run()-style entry (`ring-reconciliation`) in autonomous-registry.js,
// cooldown 1800 s. Downstream: the ops financial-integrity board reads
// payment_reconciliation WHERE NOT reconciled; ring findings carry sources
// ring_facilitator_settle / ring_ledger_sweep / ring_log_coherence /
// ring_fee_coherence / ring_tripwire.

import { randomUUID } from 'node:crypto';

import { sql as defaultSql } from '../db.js';
import { env } from '../env.js';
import { logger } from '../usage.js';
import { sendOpsAlert } from '../alerts.js';
import { cacheGet, cacheSet } from '../cache.js';
import { solanaConnection } from '../solana/connection.js';
import { USDC_MINT, SOLANA_RPC } from './pay.js';

const log = logger('x402-ring-reconciliation');

const ASSET = USDC_MINT || 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';

// 72h rolling window on a 30-min cadence: every settle is re-verified ~144 times
// before it ages out, so a transient RPC miss self-heals instead of latching.
const LOOKBACK_HOURS = 72;
// Per-minute ring cadence ⇒ ~4,320 settles per 72h window. The row cap sits above
// that so normal volume is never silently truncated; if it ever is, the summary
// says so (settle_rows_truncated).
const MAX_SETTLE_ROWS = 5000;
const MAX_SWEEP_ROWS = 500;
// getSignatureStatuses accepts up to 256 signatures per call.
const STATUS_BATCH = 256;
// Shared parsed-transaction budget per run (the expensive RPC). Sweeps draw
// first; settle amount-sampling gets the remainder.
export const MAX_PARSED_TX_PER_RUN = 50;
// A tick is two writes from two processes; give the slower book this long before
// calling its counterpart an orphan.
export const ORPHAN_GRACE_MINUTES = 15;
// Tripwire window: the ring pays per-minute, so 30 silent minutes is ~30 missed
// ticks — unambiguously stalled, not merely slow.
export const TRIPWIRE_WINDOW_MINUTES = 30;
// Fee coherence tolerance — the audit rollup and the raw log measure the same
// burn; anything past this is one of them lying.
export const FEE_DIVERGENCE_THRESHOLD = 0.2;

// WARN-class findings (coherence, fee drift) throttle to one alert per day so a
// stable low-grade discrepancy cannot flood the ops channel.
const WARN_THROTTLE_SECONDS = 86_400;

// Same DDL as revenue-reconciliation.js — idempotent, shared verdict sink.
async function ensureSchema(db) {
	await db`
		CREATE TABLE IF NOT EXISTS payment_reconciliation (
			id            bigserial   PRIMARY KEY,
			source        text        NOT NULL,
			source_ref    text        NOT NULL,
			tx_signature  text,
			network       text,
			amount_atomic bigint,
			db_status     text        NOT NULL,
			chain_status  text        NOT NULL,
			reconciled    boolean     NOT NULL,
			discrepancy   text,
			detail        jsonb,
			run_id        uuid,
			first_seen_at timestamptz NOT NULL DEFAULT now(),
			checked_at    timestamptz NOT NULL DEFAULT now(),
			UNIQUE (source, source_ref)
		)
	`;
	await db`CREATE INDEX IF NOT EXISTS payment_reconciliation_open_idx
		ON payment_reconciliation (checked_at DESC) WHERE reconciled = false`;
	await db`ALTER TABLE x402_autonomous_log ADD COLUMN IF NOT EXISTS value_extracted jsonb`;
}

async function upsertVerdict(db, runId, { source, sourceRef, txSig, amountAtomic, dbStatus, chainStatus, reconciled, discrepancy, detail }) {
	try {
		await db`
			INSERT INTO payment_reconciliation
				(source, source_ref, tx_signature, network, amount_atomic,
				 db_status, chain_status, reconciled, discrepancy, detail, run_id, checked_at)
			VALUES
				(${source}, ${sourceRef}, ${txSig || null}, ${'solana:mainnet'}, ${amountAtomic ?? null},
				 ${dbStatus}, ${chainStatus}, ${reconciled}, ${discrepancy || null},
				 ${detail ? JSON.stringify(detail) : null}, ${runId}, now())
			ON CONFLICT (source, source_ref) DO UPDATE SET
				tx_signature  = EXCLUDED.tx_signature,
				network       = EXCLUDED.network,
				amount_atomic = EXCLUDED.amount_atomic,
				db_status     = EXCLUDED.db_status,
				chain_status  = EXCLUDED.chain_status,
				reconciled    = EXCLUDED.reconciled,
				discrepancy   = EXCLUDED.discrepancy,
				detail        = EXCLUDED.detail,
				run_id        = EXCLUDED.run_id,
				checked_at    = now()
		`;
	} catch (err) {
		log.warn('ring_reconcile_upsert_failed', { ref: `${source}:${sourceRef}`, message: err?.message });
	}
}

// ── Book loaders — tables may not exist in a fresh env; that is "no book", not
//    an error (mirrors loadInboundRecords in the sibling reconciler).

async function loadSettleRows(db) {
	try {
		return await db`
			SELECT id, ts, payer, pay_to, mint, amount_atomic, tx_sig
			FROM x402_self_facilitator_log
			WHERE action = 'settle' AND ok = true
			  AND ts > now() - (${LOOKBACK_HOURS} || ' hours')::interval
			ORDER BY ts DESC
			LIMIT ${MAX_SETTLE_ROWS}
		`;
	} catch (err) {
		if (!err?.message?.includes('does not exist')) {
			log.warn('ring_reconcile_settle_load_failed', { message: err?.message });
		}
		return [];
	}
}

async function loadSweepRows(db) {
	try {
		return await db`
			SELECT id, ts, kind, from_wallet, to_wallet, mint, amount_atomic, tx_sig
			FROM x402_ring_ledger
			WHERE kind IN ('sweep', 'revshare')
			  AND ts > now() - (${LOOKBACK_HOURS} || ' hours')::interval
			ORDER BY ts DESC
			LIMIT ${MAX_SWEEP_ROWS}
		`;
	} catch (err) {
		if (!err?.message?.includes('does not exist')) {
			log.warn('ring_reconcile_sweep_load_failed', { message: err?.message });
		}
		return [];
	}
}

// Per-tx totals across ALL legs of every sweep signature, aggregated in SQL so
// the MAX_SWEEP_ROWS page can never truncate one leg of a split sweep (payer +
// revshare share a tx_sig) and hand verifySweepMovement a partial sum, which
// would raise a false-positive critical mismatch. No LIMIT: the aggregate runs
// over the same lookback window and both legs of a tx always share one ts.
async function loadSweepTxTotals(db) {
	const totals = new Map();
	try {
		const rows = await db`
			SELECT tx_sig, SUM(amount_atomic)::bigint AS total
			FROM x402_ring_ledger
			WHERE kind IN ('sweep', 'revshare') AND tx_sig IS NOT NULL
			  AND ts > now() - (${LOOKBACK_HOURS} || ' hours')::interval
			GROUP BY tx_sig
		`;
		for (const r of rows) totals.set(r.tx_sig, BigInt(r.total ?? 0));
	} catch (err) {
		if (!err?.message?.includes('does not exist')) {
			log.warn('ring_reconcile_sweep_totals_failed', { message: err?.message });
		}
	}
	return totals;
}

// Buyer-side rows for cross-log coherence: every successful autonomous payment
// with a signature (any endpoint — a settle matched by ANY buyer row is
// coherent), plus the endpoint so ring-settle buyer rows can be isolated for the
// reverse direction.
async function loadBuyerRows(db) {
	try {
		return await db`
			SELECT id, ts, tx_signature, endpoint_url
			FROM x402_autonomous_log
			WHERE success = true AND tx_signature IS NOT NULL
			  AND ts > now() - (${LOOKBACK_HOURS} || ' hours')::interval
			ORDER BY ts DESC
			LIMIT ${MAX_SETTLE_ROWS}
		`;
	} catch (err) {
		if (!err?.message?.includes('does not exist')) {
			log.warn('ring_reconcile_buyer_load_failed', { message: err?.message });
		}
		return [];
	}
}

// ── Chain helpers

// signature → { found, err } | absent on RPC failure (callers treat a missing
// entry as unknown, never a discrepancy).
async function fetchOnChainStatuses(conn, signatures) {
	const out = new Map();
	for (let i = 0; i < signatures.length; i += STATUS_BATCH) {
		const batch = signatures.slice(i, i + STATUS_BATCH);
		try {
			const { value } = await conn.getSignatureStatuses(batch, { searchTransactionHistory: true });
			batch.forEach((sig, j) => {
				const st = value?.[j];
				out.set(sig, st ? { found: true, err: st.err ?? null } : { found: false, err: null });
			});
		} catch (err) {
			log.warn('ring_reconcile_status_batch_failed', { from: i, message: err?.message });
		}
	}
	return out;
}

// Net token movement per owner for one mint, from a parsed transaction's
// pre/postTokenBalances. Sums across ATAs so an owner with several accounts
// still nets correctly. Pure; exported for tests.
export function tokenDeltasByOwner(parsedTx, mint) {
	const deltas = new Map();
	const meta = parsedTx?.meta;
	if (!meta || !Array.isArray(meta.preTokenBalances) || !Array.isArray(meta.postTokenBalances)) {
		return null;
	}
	const add = (owner, amount) => {
		if (!owner) return;
		deltas.set(owner, (deltas.get(owner) ?? 0n) + amount);
	};
	for (const b of meta.postTokenBalances) {
		if (b?.mint === mint) add(b.owner, BigInt(b.uiTokenAmount?.amount || 0));
	}
	for (const b of meta.preTokenBalances) {
		if (b?.mint === mint) add(b.owner, -BigInt(b.uiTokenAmount?.amount || 0));
	}
	return deltas;
}

// Prove one confirmed settle's parsed tx pays EXACTLY amount_atomic of mint to
// pay_to. Pure; exported for tests. Returns { ok } | { ok:false, reason }.
export function verifySettleAmount(row, parsedTx) {
	const mint = row.mint || ASSET;
	const deltas = tokenDeltasByOwner(parsedTx, mint);
	if (deltas === null) return { ok: false, reason: 'tx_unparseable', soft: true };
	const received = deltas.get(row.pay_to) ?? 0n;
	if (received !== BigInt(row.amount_atomic ?? 0)) {
		return { ok: false, reason: `receiver_got_${received}_logged_${row.amount_atomic}` };
	}
	return { ok: true };
}

// Prove one confirmed sweep moved amount_atomic of mint from_wallet → to_wallet,
// and that the source is the configured treasury (treasury→payer and
// treasury→master revshare are the only legal directions). A single sweep tx
// may carry MULTIPLE ledger legs (payer sweep + master revshare), so the
// treasury's total on-chain delta is checked against `txTotalAtomic`: the sum
// of every ledger row sharing this tx_sig (defaults to the row's own amount for
// the single-leg case). The recipient check stays per-row. Pure; exported for
// tests.
export function verifySweepMovement(row, parsedTx, treasuryAddress, txTotalAtomic = null) {
	const mint = row.mint || ASSET;
	if (treasuryAddress && row.from_wallet !== treasuryAddress) {
		return { ok: false, reason: `sweep_source_not_treasury:${row.from_wallet}` };
	}
	const deltas = tokenDeltasByOwner(parsedTx, mint);
	if (deltas === null) return { ok: false, reason: 'tx_unparseable', soft: true };
	const amount = BigInt(row.amount_atomic ?? 0);
	const txTotal = BigInt(txTotalAtomic ?? row.amount_atomic ?? 0);
	const sent = deltas.get(row.from_wallet) ?? 0n;
	const received = deltas.get(row.to_wallet) ?? 0n;
	if (sent !== -txTotal) return { ok: false, reason: `treasury_delta_${sent}_expected_${-txTotal}` };
	if (received !== amount) return { ok: false, reason: `payer_delta_${received}_expected_${amount}` };
	return { ok: true };
}

// Fee divergence between the raw facilitator log and the fee-audit rollup for
// one day. Pure; exported for tests. null = not comparable (no audit figure).
export function feeDivergence(loggedLamports, auditLamports) {
	if (auditLamports == null || !Number.isFinite(Number(auditLamports))) return null;
	const logged = Number(loggedLamports || 0);
	const audited = Number(auditLamports);
	if (logged === 0 && audited === 0) return 0;
	const base = Math.max(logged, audited);
	return Math.abs(logged - audited) / base;
}

// Is the ring supposed to be producing volume? Local config read: the
// self-hosted facilitator flag plus a configured treasury are the two settings
// without which nothing can settle. Callers that already ran a fuller config
// validation pass the answer in via ctx.ringEnabled instead.
function ringEnabledLocal() {
	const on = String(process.env.X402_SELF_FACILITATOR_ENABLED || '').toLowerCase() === 'true';
	return on && Boolean(env.X402_PAY_TO_SOLANA || process.env.X402_PAY_TO_SOLANA);
}

async function recordLogRow(db, runId, { durationMs, success, errorMsg, summary }) {
	try {
		await db`
			INSERT INTO x402_autonomous_log
				(run_id, endpoint_type, service_name, endpoint_url,
				 network, amount_atomic, asset, tx_signature,
				 response_data, value_extracted, duration_ms, success, error_msg, pipeline)
			VALUES
				(${runId}, ${'self'}, ${'Ring Reconciliation'}, ${'/api/x402-facilitator'},
				 ${'solana:mainnet'}, ${0}, ${ASSET}, ${null},
				 ${summary ? JSON.stringify(summary) : null},
				 ${summary ? JSON.stringify(summary) : null},
				 ${durationMs || 0}, ${success}, ${errorMsg || null}, ${'reconciliation'})
		`;
	} catch (err) {
		log.warn('ring_reconcile_log_insert_failed', { message: err?.message });
	}
}

/**
 * Run the ring reconciliation. Registry run()-contract; read-only on chain, so a
 * missing spend wallet never blocks it. Injectable for tests:
 *   ctx.sql          — DB tag (default shared sql)
 *   ctx.conn         — Solana connection (default keyless RPC)
 *   ctx.sendAlert    — ops alert fn (default sendOpsAlert)
 *   ctx.cache        — { get, set } for WARN throttling (default shared cache)
 *   ctx.ringEnabled  — boolean override for the tripwire's config check
 *   ctx.now          — epoch ms override (grace/tripwire windows in tests)
 */
export async function run(ctx = {}) {
	const runId = ctx.runId || randomUUID();
	const db = ctx.sql || defaultSql;
	const alert = ctx.sendAlert || sendOpsAlert;
	const cache = ctx.cache || { get: cacheGet, set: cacheSet };
	const nowMs = ctx.now ?? Date.now();
	const t0 = Date.now();

	try {
		await ensureSchema(db);
	} catch (err) {
		log.warn('ring_reconcile_schema_failed', { message: err?.message });
		return { success: false, skipped: true, amountAtomic: 0, errorMsg: `schema_failed: ${err?.message}` };
	}

	const conn = ctx.conn || solanaConnection({ url: SOLANA_RPC, commitment: 'confirmed' });

	// One WARN alert per class per day; CRITICALs bypass this and page immediately.
	async function warnThrottled(key, title, detail) {
		try {
			if (await cache.get(`ring-reconcile:warn:${key}`)) return;
			await cache.set(`ring-reconcile:warn:${key}`, 1, WARN_THROTTLE_SECONDS);
		} catch { /* throttle store down → still alert; dedup in alerts.js backstops */ }
		await alert(title, detail, { signature: `ring-reconcile:${key}` }).catch?.(() => {});
	}

	// ── Load all three books once.
	const settles = await loadSettleRows(db);
	const sweeps = await loadSweepRows(db);
	const buyers = await loadBuyerRows(db);

	const summary = {
		settles_checked: settles.length,
		settle_rows_truncated: settles.length >= MAX_SETTLE_ROWS,
		settles_confirmed: 0,
		settles_missing: 0,
		settles_failed: 0,
		settles_no_signature: 0,
		settles_unknown: 0,
		settles_amount_sampled: 0,
		amount_mismatches: 0,
		sweeps_checked: sweeps.length,
		sweeps_confirmed: 0,
		sweeps_missing: 0,
		sweeps_failed: 0,
		sweep_mismatches: 0,
		sweeps_unknown: 0,
		orphans_settle_side: 0,
		orphans_buyer_side: 0,
		fee_day: null,
		fee_divergence: null,
		tripwire_fired: false,
		parsed_tx_used: 0,
	};
	const critical = [];

	// ── Status lookup for every signature in both ring books, one batched pass.
	const allSigs = [...new Set([
		...settles.map((r) => r.tx_sig).filter(Boolean),
		...sweeps.map((r) => r.tx_sig).filter(Boolean),
	])];
	const statuses = allSigs.length ? await fetchOnChainStatuses(conn, allSigs) : new Map();

	let parsedBudget = ctx.maxParsedTx ?? MAX_PARSED_TX_PER_RUN;
	async function parseTx(sig) {
		if (parsedBudget <= 0) return { budgetExhausted: true, tx: null };
		parsedBudget -= 1;
		summary.parsed_tx_used += 1;
		try {
			const tx = await conn.getParsedTransaction(sig, { maxSupportedTransactionVersion: 1, commitment: 'confirmed' });
			return { budgetExhausted: false, tx };
		} catch {
			return { budgetExhausted: false, tx: null };
		}
	}

	// ── Check 3 first: sweeps draw the parsed-tx budget before settle sampling —
	//    each sweep moves the entire float, so full verification of every sweep
	//    outranks sampling one more settle.
	const treasuryAddress = env.X402_PAY_TO_SOLANA || process.env.X402_PAY_TO_SOLANA || null;
	// A split sweep (payer leg + master revshare leg) shares one tx_sig; the
	// treasury's on-chain delta must match the SUM of its legs, not each row.
	// SQL-aggregated so a page-truncated leg can never yield a partial sum.
	const sweepTxTotals = await loadSweepTxTotals(db);
	for (const row of sweeps) {
		const ref = String(row.id);
		if (!row.tx_sig) {
			summary.sweeps_missing += 1;
			critical.push({ kind: 'x402_ring_sweep_missing', ref, sig: null });
			await upsertVerdict(db, runId, {
				source: 'ring_ledger_sweep', sourceRef: ref, txSig: null,
				amountAtomic: row.amount_atomic, dbStatus: 'sweep_recorded',
				chainStatus: 'missing_signature', reconciled: false,
				discrepancy: 'x402_ring_sweep_missing',
				detail: { from: row.from_wallet, to: row.to_wallet },
			});
			continue;
		}
		const st = statuses.get(row.tx_sig);
		if (!st) { summary.sweeps_unknown += 1; continue; } // RPC gap — next run re-checks
		if (!st.found || st.err != null) {
			const kind = st.found ? 'x402_ring_sweep_failed' : 'x402_ring_sweep_missing';
			summary[st.found ? 'sweeps_failed' : 'sweeps_missing'] += 1;
			critical.push({ kind, ref, sig: row.tx_sig });
			await upsertVerdict(db, runId, {
				source: 'ring_ledger_sweep', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'sweep_recorded',
				chainStatus: st.found ? 'failed_onchain' : 'missing_onchain', reconciled: false,
				discrepancy: kind, detail: { from: row.from_wallet, to: row.to_wallet },
			});
			continue;
		}
		// Confirmed — now prove amount + direction from the parsed tx.
		const { budgetExhausted, tx } = await parseTx(row.tx_sig);
		if (budgetExhausted || !tx) {
			// Confirmed on-chain, movement unproven this run — reconciled with a
			// note; the rolling window re-samples it next tick.
			summary.sweeps_confirmed += 1;
			await upsertVerdict(db, runId, {
				source: 'ring_ledger_sweep', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'sweep_recorded',
				chainStatus: 'confirmed', reconciled: true, discrepancy: null,
				detail: { movement_verified: false },
			});
			continue;
		}
		const check = verifySweepMovement(row, tx, treasuryAddress, sweepTxTotals.get(row.tx_sig));
		if (!check.ok && !check.soft) {
			summary.sweep_mismatches += 1;
			critical.push({ kind: 'x402_ring_sweep_mismatch', ref, sig: row.tx_sig, reason: check.reason });
			await upsertVerdict(db, runId, {
				source: 'ring_ledger_sweep', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'sweep_recorded',
				chainStatus: 'amount_mismatch', reconciled: false,
				discrepancy: 'x402_ring_sweep_mismatch',
				detail: { reason: check.reason, from: row.from_wallet, to: row.to_wallet },
			});
		} else {
			summary.sweeps_confirmed += 1;
			await upsertVerdict(db, runId, {
				source: 'ring_ledger_sweep', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'sweep_recorded',
				chainStatus: 'confirmed', reconciled: true, discrepancy: null,
				detail: { movement_verified: check.ok },
			});
		}
	}

	// ── Checks 1 + 2: settle signature integrity for every row; amount fidelity
	//    for the most recent confirmed rows the remaining budget covers.
	const confirmedSettles = [];
	for (const row of settles) {
		const ref = String(row.id);
		if (!row.tx_sig) {
			summary.settles_no_signature += 1;
			critical.push({ kind: 'x402_ring_settle_missing', ref, sig: null });
			await upsertVerdict(db, runId, {
				source: 'ring_facilitator_settle', sourceRef: ref, txSig: null,
				amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
				chainStatus: 'missing_signature', reconciled: false,
				discrepancy: 'x402_ring_settle_missing',
				detail: { payer: row.payer, pay_to: row.pay_to },
			});
			continue;
		}
		const st = statuses.get(row.tx_sig);
		if (!st) { summary.settles_unknown += 1; continue; }
		if (!st.found || st.err != null) {
			const kind = st.found ? 'x402_ring_settle_failed' : 'x402_ring_settle_missing';
			summary[st.found ? 'settles_failed' : 'settles_missing'] += 1;
			critical.push({ kind, ref, sig: row.tx_sig });
			await upsertVerdict(db, runId, {
				source: 'ring_facilitator_settle', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
				chainStatus: st.found ? 'failed_onchain' : 'missing_onchain', reconciled: false,
				discrepancy: kind, detail: { payer: row.payer, pay_to: row.pay_to },
			});
			continue;
		}
		summary.settles_confirmed += 1;
		confirmedSettles.push(row);
	}

	for (const row of confirmedSettles) {
		if (parsedBudget <= 0) break;
		const ref = String(row.id);
		const { tx } = await parseTx(row.tx_sig);
		if (!tx) {
			// Signature confirmed; amount unproven this run — reconciled, resampled later.
			await upsertVerdict(db, runId, {
				source: 'ring_facilitator_settle', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
				chainStatus: 'confirmed', reconciled: true, discrepancy: null,
				detail: { amount_verified: false },
			});
			continue;
		}
		summary.settles_amount_sampled += 1;
		const check = verifySettleAmount(row, tx);
		if (!check.ok && !check.soft) {
			summary.amount_mismatches += 1;
			critical.push({ kind: 'x402_ring_amount_mismatch', ref, sig: row.tx_sig, reason: check.reason });
			await upsertVerdict(db, runId, {
				source: 'ring_facilitator_settle', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
				chainStatus: 'amount_mismatch', reconciled: false,
				discrepancy: 'x402_ring_amount_mismatch',
				detail: { reason: check.reason, payer: row.payer, pay_to: row.pay_to },
			});
		} else {
			await upsertVerdict(db, runId, {
				source: 'ring_facilitator_settle', sourceRef: ref, txSig: row.tx_sig,
				amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
				chainStatus: 'confirmed', reconciled: true, discrepancy: null,
				detail: { amount_verified: check.ok },
			});
		}
	}
	// Confirmed settles the budget did not reach are still signature-reconciled.
	for (const row of confirmedSettles.slice(summary.settles_amount_sampled)) {
		await upsertVerdict(db, runId, {
			source: 'ring_facilitator_settle', sourceRef: String(row.id), txSig: row.tx_sig,
			amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
			chainStatus: 'confirmed', reconciled: true, discrepancy: null,
			detail: { amount_verified: false },
		});
	}

	// ── Check 4: cross-log coherence, joined on signature, outside the grace window.
	const graceCutoff = nowMs - ORPHAN_GRACE_MINUTES * 60_000;
	const buyerSigs = new Set(buyers.map((b) => b.tx_signature).filter(Boolean));
	const settleSigs = new Set(settles.map((s) => s.tx_sig).filter(Boolean));

	for (const row of settles) {
		if (!row.tx_sig || buyerSigs.has(row.tx_sig)) continue;
		if (new Date(row.ts).getTime() > graceCutoff) continue;
		summary.orphans_settle_side += 1;
		await upsertVerdict(db, runId, {
			source: 'ring_log_coherence', sourceRef: `settle:${row.tx_sig}`, txSig: row.tx_sig,
			amountAtomic: row.amount_atomic, dbStatus: 'settle_ok',
			chainStatus: 'no_buyer_record', reconciled: false,
			discrepancy: 'x402_ring_log_orphan',
			detail: { side: 'settle_without_buyer', payer: row.payer, pay_to: row.pay_to },
		});
	}
	for (const row of buyers) {
		if (!String(row.endpoint_url || '').includes('ring-settle')) continue;
		if (!row.tx_signature || settleSigs.has(row.tx_signature)) continue;
		if (new Date(row.ts).getTime() > graceCutoff) continue;
		summary.orphans_buyer_side += 1;
		await upsertVerdict(db, runId, {
			source: 'ring_log_coherence', sourceRef: `buyer:${row.tx_signature}`, txSig: row.tx_signature,
			amountAtomic: null, dbStatus: 'buyer_paid',
			chainStatus: 'no_settle_record', reconciled: false,
			discrepancy: 'x402_ring_log_orphan',
			detail: { side: 'buyer_without_settle', endpoint: row.endpoint_url },
		});
	}
	const orphanTotal = summary.orphans_settle_side + summary.orphans_buyer_side;
	if (orphanTotal > 0) {
		await warnThrottled(
			'log-orphans',
			`⚠️ x402 ring cross-log orphans: ${orphanTotal}`,
			[
				`${summary.orphans_settle_side} settlement(s) with NO buyer record — value moved through our own facilitator with no spend we booked (the internal-leak signature).`,
				`${summary.orphans_buyer_side} ring buyer payment(s) with NO facilitator settle record.`,
				`Board: SELECT * FROM payment_reconciliation WHERE source = 'ring_log_coherence' AND reconciled = false`,
			].join('\n'),
		);
	}

	// ── Check 5: fee coherence for the last complete UTC day.
	const day = new Date(nowMs - 86_400_000).toISOString().slice(0, 10);
	summary.fee_day = day;
	try {
		const [logged] = await db`
			SELECT COALESCE(sum(fee_lamports), 0)::bigint AS total
			FROM x402_self_facilitator_log
			WHERE action = 'settle' AND ok = true
			  AND ts >= ${day}::date AND ts < ${day}::date + interval '1 day'
		`;
		let auditTotal = null;
		try {
			const [audit] = await db`
				SELECT total_fee_lamports FROM x402_fee_audit WHERE day = ${day}::date
			`;
			auditTotal = audit?.total_fee_lamports ?? null;
		} catch (err) {
			if (!err?.message?.includes('does not exist')) {
				log.warn('ring_reconcile_fee_audit_load_failed', { message: err?.message });
			}
			summary.fee_audit_available = false;
		}
		const divergence = feeDivergence(logged?.total, auditTotal);
		summary.fee_divergence = divergence;
		if (divergence != null && divergence > FEE_DIVERGENCE_THRESHOLD) {
			await upsertVerdict(db, runId, {
				source: 'ring_fee_coherence', sourceRef: day, txSig: null,
				amountAtomic: Number(logged?.total || 0), dbStatus: 'fees_logged',
				chainStatus: 'fee_divergence', reconciled: false,
				discrepancy: 'x402_ring_fee_divergence',
				detail: { day, logged_lamports: Number(logged?.total || 0), audit_lamports: Number(auditTotal), divergence },
			});
			await warnThrottled(
				`fee-divergence:${day}`,
				`⚠️ x402 ring fee books diverge ${(divergence * 100).toFixed(1)}% on ${day}`,
				`Facilitator log: ${logged?.total} lamports; fee-audit rollup: ${auditTotal} lamports. One of the two fee books is wrong — check x402_self_facilitator_log vs x402_fee_audit for ${day}.`,
			);
		} else if (divergence != null) {
			await upsertVerdict(db, runId, {
				source: 'ring_fee_coherence', sourceRef: day, txSig: null,
				amountAtomic: Number(logged?.total || 0), dbStatus: 'fees_logged',
				chainStatus: 'confirmed', reconciled: true, discrepancy: null,
				detail: { day, divergence },
			});
		}
	} catch (err) {
		log.warn('ring_reconcile_fee_check_failed', { message: err?.message });
	}

	// ── Zero-volume tripwire.
	const ringEnabled = ctx.ringEnabled ?? ringEnabledLocal();
	summary.ring_enabled = ringEnabled;
	if (ringEnabled) {
		const windowCutoff = nowMs - TRIPWIRE_WINDOW_MINUTES * 60_000;
		const recentSettles = settles.filter((r) => new Date(r.ts).getTime() >= windowCutoff).length;
		if (recentSettles === 0) {
			summary.tripwire_fired = true;
			await upsertVerdict(db, runId, {
				source: 'ring_tripwire', sourceRef: 'ring-silent', txSig: null,
				amountAtomic: null, dbStatus: 'ring_enabled',
				chainStatus: 'no_volume', reconciled: false,
				discrepancy: 'x402_ring_enabled_but_silent',
				detail: { window_minutes: TRIPWIRE_WINDOW_MINUTES },
			});
			await alert(
				'⚠️ x402 ring enabled but silent',
				`The self-hosted facilitator is enabled and configured, but x402_self_facilitator_log shows ZERO successful settles in the last ${TRIPWIRE_WINDOW_MINUTES} minutes. The ring should tick continuously — check the autonomous loop, the payer's USDC/SOL balances, and /api/x402-ring.`,
				{ signature: 'ring-reconcile:tripwire' },
			).catch?.(() => {});
		} else {
			// Volume present — clear any standing tripwire verdict so the board self-heals.
			await upsertVerdict(db, runId, {
				source: 'ring_tripwire', sourceRef: 'ring-silent', txSig: null,
				amountAtomic: null, dbStatus: 'ring_enabled',
				chainStatus: 'confirmed', reconciled: true, discrepancy: null,
				detail: { window_minutes: TRIPWIRE_WINDOW_MINUTES, settles_in_window: recentSettles },
			});
		}
	}

	// ── CRITICAL page: books disagree with the chain about ring money.
	if (critical.length > 0) {
		const counts = critical.reduce((m, c) => { m[c.kind] = (m[c.kind] || 0) + 1; return m; }, {});
		await alert(
			`🚨 x402 ring reconciliation: ${critical.length} discrepanc${critical.length === 1 ? 'y' : 'ies'}`,
			[
				...Object.entries(counts).map(([k, n]) => `${k}=${n}`),
				`sample: ${critical.slice(0, 5).map((c) => `${c.kind}:${c.ref}${c.reason ? `(${c.reason})` : ''}`).join(', ')}`,
				`full set: SELECT * FROM payment_reconciliation WHERE source LIKE 'ring_%' AND reconciled = false`,
			].join('\n'),
			{ signature: `ring-reconcile-critical:${Object.entries(counts).map(([k, n]) => `${k}:${n}`).join(',')}` },
		).catch?.(() => {});
	}

	const durationMs = Date.now() - t0;
	summary.discrepancies = critical.length + orphanTotal;
	await recordLogRow(db, runId, { durationMs, success: true, errorMsg: null, summary });

	log.info('ring_reconcile_complete', {
		run_id: runId,
		settles: summary.settles_checked,
		sweeps: summary.sweeps_checked,
		critical: critical.length,
		orphans: orphanTotal,
		tripwire: summary.tripwire_fired,
		parsed_tx: summary.parsed_tx_used,
		duration_ms: durationMs,
	});

	return {
		success: true,
		amountAtomic: 0, // read-only audit — no payment owed
		txSig: null,
		errorMsg: null,
		skipped: false,
		responseData: summary,
		signalData: null,
		note: `ring reconcile settles=${summary.settles_checked} sweeps=${summary.sweeps_checked} critical=${critical.length} orphans=${orphanTotal}${summary.tripwire_fired ? ' TRIPWIRE' : ''}`,
	};
}