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.

28.4 KB
Raw Blame
// Guard-logic tests for the consolidation sweep (api/_lib/economy-sweepback.js)
// and its ledger rows (buildSweepbackRows in api/_lib/economy-ledger.js). Both
// planSweepback and buildSweepbackRows are pure, so the floors, dust guard,
// drain headroom, and the rising running balance are asserted without RPC, keys,
// or a database.
import { test } from 'vitest';
import assert from 'node:assert/strict';
import {
	planSweepback,
	reclaimableSol,
	MIN_SWEEP_SOL,
	DRAIN_HEADROOM_LAMPORTS,
	planAgentReclaim,
	agentReclaimFloorSol,
	isPlatformOwnedAgent,
	PLATFORM_AGENT_OWNER_EMAIL,
	agentCandidateFromRow,
	reclaimKeepLineSol,
	floorBlockedSkip,
	floorHeldSol,
} from '../api/_lib/economy-sweepback.js';
import { MIN_OPERATIONAL_WALLET_SOL } from '../api/_lib/agent-trade-guards.js';
import { autoFundTargetSol } from '../api/_lib/agent-funding-policy.js';

// reclaimableSol: the emergency consolidation's sizing. The load-bearing property
// is anti-oscillation: it must NEVER leave an engine below minSol, or the topup
// (which funds anything below minSol) would immediately re-fund it and the two
// crons would ping-pong, burning fees forever.
test('reclaimableSol never leaves an engine below its floor', () => {
	for (const [current, min] of [
		[3, 1], [0.6, 0.2], [1.076, 1], [0.05, 0.02], [0.3, 0.03], [10, 0.05],
	]) {
		const r = reclaimableSol(current, min);
		assert.ok(current - r >= min, `left ${current - r} below floor ${min}`);
	}
});

test('reclaimableSol pulls the idle excess above the floor+buffer', () => {
	// launcher floored at 1 SOL sitting on 3 → reclaim ~1.9 (leaves 1.1 = min + 10%)
	assert.ok(Math.abs(reclaimableSol(3, 1) - 1.9) < 1e-6);
	// a2a floored at 0.02 on 0.035 → keep 0.025, reclaim 0.01 (== dust floor)
	assert.ok(reclaimableSol(0.035, 0.02) >= MIN_SWEEP_SOL - 1e-9);
});

test('reclaimableSol returns 0 when the engine is at or below its floor', () => {
	assert.equal(reclaimableSol(1, 1), 0);          // exactly at floor
	assert.equal(reclaimableSol(0.5, 1), 0);        // below floor
	assert.equal(reclaimableSol(1.05, 1), 0);       // within the buffer, not worth dust
});
import { ECONOMY_MASTER_ADDRESS } from '../api/_lib/economy-master.js';
import { buildSweepbackRows, buildAgentReclaimRows, hashEntry } from '../api/_lib/economy-ledger.js';
import { SOLANA_SIGNERS } from '../api/_lib/solana-signers.js';

test('defaults are the documented guard values', () => {
	assert.equal(MIN_SWEEP_SOL, 0.01);
	// Must stay above the ~890,880-lamport rent-exempt minimum: the runtime
	// rejects a transfer that leaves a system account above zero but below rent
	// exemption, so a smaller headroom would make every drain transaction fail.
	assert.equal(DRAIN_HEADROOM_LAMPORTS, 1_000_000);
	assert.ok(DRAIN_HEADROOM_LAMPORTS > 890_880);
});

test('excess mode: sweeps only what is above the float', () => {
	const { plan, totalSol } = planSweepback([
		{ name: 'a', pubkey: 'A', currentSol: 0.5, floorSol: 0.15 },
	]);
	assert.equal(plan.length, 1);
	assert.equal(plan[0].sol, 0.35);
	assert.equal(totalSol, 0.35);
});

test('excess mode: a signer at or below its float is never touched', () => {
	const { plan, skipped } = planSweepback([
		{ name: 'at-float', pubkey: 'A', currentSol: 0.15, floorSol: 0.15 },
		{ name: 'below-float', pubkey: 'B', currentSol: 0.05, floorSol: 0.15 },
	]);
	assert.equal(plan.length, 0);
	assert.deepEqual(
		skipped.map((s) => s.reason),
		['at_or_below_float', 'at_or_below_float'],
	);
});

test('excess mode: dust above the float is skipped (fee churn guard)', () => {
	const { plan, skipped } = planSweepback([
		{ name: 'dusty', pubkey: 'A', currentSol: 0.155, floorSol: 0.15 },
	]);
	assert.equal(plan.length, 0);
	assert.equal(skipped[0].reason, 'at_or_below_float');
});

test('drain mode: ignores the float, keeps only fee headroom', () => {
	const { plan } = planSweepback(
		[{ name: 'a', pubkey: 'A', currentSol: 0.15, floorSol: 0.15 }],
		{ mode: 'drain' },
	);
	assert.equal(plan.length, 1);
	assert.equal(plan[0].sol, 0.15 - DRAIN_HEADROOM_LAMPORTS / 1e9);
});

test('drain mode: an empty wallet is skipped, not overdrawn', () => {
	const { plan, skipped } = planSweepback(
		[{ name: 'empty', pubkey: 'A', currentSol: 0.000005, floorSol: 0.15 }],
		{ mode: 'drain' },
	);
	assert.equal(plan.length, 0);
	assert.equal(skipped[0].reason, 'below_dust_threshold');
});

test('minSweepSol override tightens the dust guard', () => {
	const { plan } = planSweepback(
		[{ name: 'a', pubkey: 'A', currentSol: 1.04, floorSol: 1 }],
		{ minSweepSol: 0.05 },
	);
	assert.equal(plan.length, 0);
});

test('registry: token-holding wallets are flagged so excess mode spares their tokens', () => {
	const flagged = SOLANA_SIGNERS.filter((s) => s.holdsTokens).map((s) => s.name);
	for (const name of ['three-buyback', 'club-treasury', 'platform-treasury', 'coin-treasury']) {
		assert.ok(flagged.includes(name), `${name} must keep its operational token float`);
	}
});

test('registry: the circulation treasury is funded and swept like any engine', () => {
	const spec = SOLANA_SIGNERS.find((s) => s.name === 'circulation-treasury');
	assert.ok(spec, 'circulation-treasury must be in the registry');
	assert.equal(spec.env, 'CIRCULATION_TREASURY_SECRET');
	assert.ok(spec.refillTo > spec.minSol);
});

test('ledger rows: inflows raise the running balance and the summary closes the batch', () => {
	const rows = buildSweepbackRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: {
			mode: 'excess',
			masterSolBefore: 10,
			masterSolAfter: 10.35,
			sweptSol: [
				{ name: 'a', pubkey: 'A', sol: 0.2, signature: 'sigA' },
				{ name: 'b', pubkey: 'B', sol: 0.15, signature: 'sigB' },
			],
			sweptTokens: [{ name: 'a', pubkey: 'A', mint: 'M', amount: '5', decimals: 6, signature: 'sigT' }],
			failed: [{ name: 'c', pubkey: 'C', sol: 0.1, reason: 'send_failed' }],
			skipped: [],
			receivedSol: 0.35,
		},
		solUsd: 100,
		now: 1_700_000_000_000,
	});
	assert.equal(rows.length, 5);
	assert.equal(rows[0].event, 'inflow');
	assert.equal(rows[0].master_sol_after, 10.2);
	assert.equal(rows[1].master_sol_after, 10.35);
	assert.equal(rows[1].usd_value, 15);
	assert.equal(rows[2].event, 'inflow_token');
	assert.deepEqual(rows[2].detail, { mint: 'M', amount: '5', decimals: 6 });
	assert.equal(rows[3].event, 'inflow_failed');
	assert.equal(rows[3].reason, 'send_failed');
	const summary = rows[4];
	assert.equal(summary.event, 'sweepback');
	assert.equal(summary.sol, 0.35);
	assert.equal(summary.master_sol_after, 10.35);
	assert.equal(summary.detail.sol_transfers, 2);
	assert.equal(summary.detail.token_transfers, 1);
});

test('ledger rows: a no-op sweep still writes the sweepback heartbeat', () => {
	const rows = buildSweepbackRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: { mode: 'excess', sweptSol: [], sweptTokens: [], failed: [], skipped: [], receivedSol: 0 },
		now: 1_700_000_000_000,
	});
	assert.equal(rows.length, 1);
	assert.equal(rows[0].event, 'sweepback');
	assert.equal(rows[0].sol, 0);
});

test('ledger rows: hash-chainable with the same hashEntry the topup uses', () => {
	const rows = buildSweepbackRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: {
			mode: 'excess',
			masterSolBefore: 1,
			sweptSol: [{ name: 'a', pubkey: 'A', sol: 0.2, signature: 'sig' }],
			sweptTokens: [],
			failed: [],
			skipped: [],
			receivedSol: 0.2,
		},
		now: 1_700_000_000_000,
	});
	let prev = '';
	for (const [i, r] of rows.entries()) {
		const row = { ...r, seq: i + 1 };
		const hash = hashEntry(prev, row);
		assert.equal(typeof hash, 'string');
		assert.equal(hash.length, 64);
		prev = hash;
	}
});

// ── platform agent reclaim ───────────────────────────────────────────────────
// The agent-wallet reclaim closes the one-way master → agent funding path that
// stranded 7.2 of the fleet's 7.53 SOL while the fee wallet sat under its settle
// floor. Its safety story is entirely in these pure functions: who may be swept,
// and how much must be left behind.

const PLATFORM = PLATFORM_AGENT_OWNER_EMAIL;
const BOT = '[email protected]';

test('isPlatformOwnedAgent accepts only house and bot accounts', () => {
	assert.equal(isPlatformOwnedAgent(PLATFORM), true);
	assert.equal(isPlatformOwnedAgent(BOT), true);
	assert.equal(isPlatformOwnedAgent('[email protected]'), true); // case-insensitive
	// Customers, in every shape they appear in the users table.
	assert.equal(isPlatformOwnedAgent('[email protected]'), false);
	assert.equal(isPlatformOwnedAgent('[email protected]'), false);
	assert.equal(isPlatformOwnedAgent('[email protected]'), false);
	// Near-miss domains must not squeak through a suffix check.
	assert.equal(isPlatformOwnedAgent('[email protected]'), false);
	assert.equal(isPlatformOwnedAgent(null), false);
	assert.equal(isPlatformOwnedAgent(''), false);
	assert.equal(isPlatformOwnedAgent(undefined), false);
});

test('agentReclaimFloorSol leaves a working trader its trade capital', () => {
	// An enabled strategy keeps 2x its own per-trade size, so reclaim can never
	// starve an agent that is actively trading.
	assert.ok(agentReclaimFloorSol({ enabled: true, perTradeSol: 0.05 }) >= 0.1);
	assert.ok(agentReclaimFloorSol({ enabled: true, perTradeSol: 0.207 }) >= 0.414);
	// No enabled strategy → only fee headroom is retained.
	const idle = agentReclaimFloorSol({ enabled: false, perTradeSol: 0.5 });
	assert.ok(idle > 0 && idle < 0.05);
	// Malformed strategy rows fall back to the idle floor, never to zero.
	assert.ok(agentReclaimFloorSol({ enabled: true, perTradeSol: 0 }) > 0);
	assert.ok(agentReclaimFloorSol({ enabled: true, perTradeSol: NaN }) > 0);
	assert.ok(agentReclaimFloorSol({}) > 0);
});

test('agentReclaimFloorSol keeps a small-size arm able to actually trade', () => {
	// The state this closes: an enabled arm sized at 0.002 SOL/trade kept a floor of
	// 0.004 SOL, which cannot pay the token ATA's rent, the fee/tip headroom AND the
	// firewall's simulated round-trip — so every entry aborted at a safety check the
	// wallet could no longer afford to run. Funded on every dashboard, dead in fact.
	const tiny = agentReclaimFloorSol({ enabled: true, perTradeSol: 0.002 });
	assert.ok(tiny >= MIN_OPERATIONAL_WALLET_SOL, `floor ${tiny} must cover one complete trade`);
	// The working-capital multiple still applies on top for a larger arm.
	assert.ok(agentReclaimFloorSol({ enabled: true, perTradeSol: 0.05 }) >= 0.1 + MIN_OPERATIONAL_WALLET_SOL);
	// A disabled arm is still swept to the bare idle floor — this changes nothing there.
	assert.ok(agentReclaimFloorSol({ enabled: false, perTradeSol: 0.002 }) < MIN_OPERATIONAL_WALLET_SOL);
});

test('agentReclaimFloorSol never sweeps an auto-funded wallet below its refill target', () => {
	// The oscillation this closes, measured on mainnet: the funder refilled an arm to
	// its target, the reclaim swept it back minutes later, repeat — 0.24 SOL round
	// -tripped six times in 15 minutes across two arms, and the arms never held a
	// balance long enough to trade. A reclaim floor under the funding target is a
	// perpetual-motion fee burner.
	const target = autoFundTargetSol();
	assert.ok(agentReclaimFloorSol({ enabled: true, autoFundEnabled: true, perTradeSol: 0.002 }) >= target);
	// It holds for a switched-off arm too: `enabled` is not what triggers a refill.
	assert.ok(agentReclaimFloorSol({ enabled: false, autoFundEnabled: true, perTradeSol: 0.002 }) >= target);
	// An agent the funder does not manage can still be swept to the bare idle floor.
	assert.ok(agentReclaimFloorSol({ enabled: false, autoFundEnabled: false, perTradeSol: 0.002 }) < target);
});

test('planAgentReclaim leaves an enabled arm enough to place its next trade', () => {
	const { plan } = planAgentReclaim([
		{
			agentId: 'arm', name: 'rules-classic', address: 'Arm111',
			owner: '[email protected]', sol: 0.05,
			strategy: { enabled: true, perTradeSol: 0.002 },
		},
	]);
	if (plan.length) {
		const retained = 0.05 - plan[0].sol;
		assert.ok(retained >= MIN_OPERATIONAL_WALLET_SOL, `retained ${retained} SOL must still fund a trade`);
	}
});

test('planAgentReclaim never plans a customer wallet, whatever the balance', () => {
	const { plan, skipped } = planAgentReclaim([
		{ agentId: 'a', name: 'Customer Sniper', address: 'Cust111', owner: '[email protected]', sol: 2.13 },
		{ agentId: 'b', name: 'Customer Agent', address: 'Cust222', owner: '[email protected]', sol: 0.136 },
	]);
	assert.equal(plan.length, 0);
	assert.equal(skipped.length, 2);
	assert.ok(skipped.every((s) => s.reason === 'not_platform_owned'));
});

test('planAgentReclaim skips agents with capital committed to open positions', () => {
	const { plan, skipped } = planAgentReclaim([
		{ agentId: 'a', name: 'Swarm 1', address: 'S1', owner: PLATFORM, sol: 5, openPositions: 1 },
	]);
	assert.equal(plan.length, 0);
	assert.equal(skipped[0].reason, 'capital_committed');
});

test('planAgentReclaim leaves every swept agent at or above its floor', () => {
	const candidates = [
		{ agentId: 'a', name: 'three', address: 'T1', owner: PLATFORM, sol: 0.35147, strategy: { enabled: true, perTradeSol: 0.05 } },
		{ agentId: 'b', name: 'Atlas #22', address: 'A1', owner: BOT, sol: 0.07839, strategy: { enabled: false } },
		{ agentId: 'c', name: 'Swarm 2', address: 'S2', owner: PLATFORM, sol: 0.0354, strategy: { enabled: true, perTradeSol: 0.207 } },
	];
	const { plan } = planAgentReclaim(candidates);
	for (const p of plan) {
		const c = candidates.find((x) => x.address === p.address);
		assert.ok(c.sol - p.sol >= p.floorSol, `${p.name} would drop below its floor`);
	}
	// Swarm 2 trades 0.207 SOL a pop and holds 0.0354 — far under floor, never swept.
	assert.equal(plan.find((p) => p.name === 'Swarm 2'), undefined);
	// The genuinely idle bot wallet is the kind of stranded capital this exists for.
	assert.ok(plan.some((p) => p.name === 'Atlas #22'));
});

test('planAgentReclaim honours the dust guard and the per-run wallet cap', () => {
	const dust = planAgentReclaim([
		{ agentId: 'a', name: 'Persona', address: 'P1', owner: BOT, sol: 0.0051, strategy: { enabled: false } },
	]);
	assert.equal(dust.plan.length, 0);
	assert.match(dust.skipped[0].reason, /^at_or_below_floor:/);
	assert.equal(dust.skipped[0].heldSol, 0.0051);

	const many = Array.from({ length: 10 }, (_, i) => ({
		agentId: `a${i}`, name: `Persona ${i}`, address: `P${i}`, owner: BOT, sol: 1, strategy: { enabled: false },
	}));
	const capped = planAgentReclaim(many, { maxWallets: 3 });
	assert.equal(capped.plan.length, 3);
	assert.equal(capped.skipped.filter((s) => s.reason === 'run_cap_reached').length, 7);
	assert.ok(capped.totalSol > 0);
});

// The row -> candidate mapping. This is the seam the pure-function tests above
// cannot see: every guard they assert reads a field that agentCandidateFromRow
// must actually carry off the SQL row. When `auto_fund_enabled` was missing from
// that mapping the anti-oscillation floor silently read `undefined` and collapsed
// to 0 in production while this suite stayed green, so the mapping itself is
// pinned here, field by field.
test('agentCandidateFromRow carries every guard-bearing field off the SQL row', () => {
	const row = {
		agent_id: 'ag_1',
		name: 'Atlas #22',
		address: 'A1',
		owner: BOT,
		secret: 'enc',
		open_positions: 2,
		strategy_enabled: true,
		auto_fund_enabled: true,
		per_trade_lamports: 2_000_000,
	};
	const c = agentCandidateFromRow(row, 0.5);

	assert.equal(c.agentId, 'ag_1');
	assert.equal(c.address, 'A1');
	assert.equal(c.owner, BOT);
	assert.equal(c.secret, 'enc');
	assert.equal(c.sol, 0.5);
	// Ownership, committed capital, and both floor inputs must survive the mapping:
	// planAgentReclaim and agentReclaimFloorSol read exactly these.
	assert.equal(c.openPositions, 2);
	assert.equal(c.strategy.enabled, true);
	assert.equal(c.strategy.autoFundEnabled, true);
	assert.equal(c.strategy.perTradeSol, 0.002);

	// The regression proper: an auto-funded agent's floor must reach the funder's
	// target through the mapping, not just when a test hand-builds the strategy.
	assert.ok(agentReclaimFloorSol(c.strategy) >= autoFundTargetSol());
});

test('agentCandidateFromRow defaults a bare row without inventing consent', () => {
	// No strategy row at all (the LEFT JOIN missed): every flag must read false, and
	// `undefined` must never reach the anti-oscillation floor as a truthy value.
	const c = agentCandidateFromRow(
		{ agent_id: 'ag_2', name: null, address: 'A2', owner: BOT, secret: 'enc' },
		0.1,
	);
	assert.equal(c.name, 'Agent');
	assert.equal(c.openPositions, 0);
	assert.equal(c.strategy.enabled, false);
	assert.equal(c.strategy.autoFundEnabled, false);
	assert.equal(c.strategy.perTradeSol, 0);

	// Postgres can hand back `false`/null for the flag; neither is consent.
	const off = agentCandidateFromRow({ agent_id: 'a', address: 'A', owner: BOT, secret: 's', auto_fund_enabled: false }, 1);
	assert.equal(off.strategy.autoFundEnabled, false);
	const nul = agentCandidateFromRow({ agent_id: 'a', address: 'A', owner: BOT, secret: 's', auto_fund_enabled: null }, 1);
	assert.equal(nul.strategy.autoFundEnabled, false);
});

// ── agent-reclaim ledger rows ────────────────────────────────────────────────
// The agent leg was the only money path in the economy that wrote NOTHING to the
// book of record when it failed. "The reclaim ran and every wallet was
// unreadable" and "the reclaim never ran" were the same absence of rows, and on
// 2026-07-29 that ambiguity cost ~11 hours with the sponsor under its settle
// floor. These pin the three row kinds and, above all, that the summary is
// written even when nothing moved.

test('agent reclaim: a failed send writes an inflow_failed row naming the reason', () => {
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		masterSolBefore: 0.2,
		deficitSol: 0.4,
		result: {
			reclaimedSol: 0.05,
			moves: [{ agentId: 'ag1', name: 'bot-one', address: 'A1', sol: 0.05, signature: 'sig1' }],
			failed: [{ name: 'bot-two', address: 'A2', sol: 0.07, stage: 'send', reason: 'blockhash not found' }],
			skipped: [{ name: 'bot-three', reason: 'at_or_below_floor' }],
			readErrors: [],
		},
		solUsd: 100,
		now: 1_700_000_000_000,
	});
	assert.equal(rows.length, 3);
	assert.equal(rows[0].event, 'inflow');
	assert.equal(rows[0].master_sol_after, 0.25);
	assert.equal(rows[0].tx_signature, 'sig1');
	assert.equal(rows[1].event, 'inflow_failed');
	assert.equal(rows[1].reason, 'blockhash not found');
	assert.equal(rows[1].target_pubkey, 'A2');
	assert.equal(rows[1].detail.stage, 'send');
	// A failed send must not move the running balance.
	assert.equal(rows[1].master_sol_after, 0.25);
	assert.equal(rows[2].event, 'agent_reclaim');
	assert.equal(rows[2].detail.deficit_sol, 0.4);
	assert.deepEqual(rows[2].detail.skipped_reasons, { at_or_below_floor: 1 });
});

test('agent reclaim: an undecryptable secret keeps its stage, so it is not chased as an RPC fault', () => {
	// A WebCrypto AES-GCM OperationError wearing a Solana costume. The SOL behind
	// it is unreachable until the right WALLET_ENCRYPTION_KEY is present, and no
	// RPC tier or deposit changes that.
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: {
			reclaimedSol: 0,
			moves: [],
			failed: [{ name: 'bot', address: 'A', sol: 0.3, stage: 'recover', reason: 'secret_undecryptable: OperationError' }],
			skipped: [],
			readErrors: [],
		},
		now: 1_700_000_000_000,
	});
	assert.equal(rows[0].event, 'inflow_failed');
	assert.equal(rows[0].detail.stage, 'recover');
	assert.match(rows[0].reason, /^secret_undecryptable/);
	assert.equal(rows[1].reason, 'blocked');
});

test('agent reclaim: unreadable balances are recorded as blocked, not as an empty fleet', () => {
	// The 2026-07-29 shape exactly: every lane in quota cooldown, so every read
	// failed and nothing was ever planned. Sizing a funding ask from this run
	// would be wrong; the summary says `blocked` so nobody does.
	const readErrors = Array.from({ length: 25 }, (_, i) => ({
		name: `bot-${i}`, address: `A${i}`, reason: 'rpc_error: 429 Too Many Requests',
	}));
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: { reclaimedSol: 0, moves: [], failed: [], skipped: [], readErrors },
		now: 1_700_000_000_000,
	});
	// Capped rows, uncapped counts: the chain stays bounded, the truth does not.
	assert.equal(rows.length, 21);
	assert.equal(rows[0].event, 'inflow_failed');
	assert.equal(rows[0].detail.stage, 'read');
	assert.match(rows[0].reason, /rpc_error/);
	const summary = rows[20];
	assert.equal(summary.event, 'agent_reclaim');
	assert.equal(summary.reason, 'blocked');
	assert.equal(summary.detail.read_errors, 25);
	assert.equal(summary.detail.read_errors_logged, 20);
});

test('agent reclaim: a no-op run still writes the summary, and says nothing was reclaimable', () => {
	// The load-bearing case. Without this row, "ran and found nothing" and "never
	// ran" are indistinguishable, and only one of them needs the owner's money.
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: {
			reclaimedSol: 0, moves: [], failed: [], readErrors: [],
			skipped: [{ name: 'a', reason: 'at_or_below_floor' }, { name: 'b', reason: 'capital_committed' }],
		},
		now: 1_700_000_000_000,
	});
	assert.equal(rows.length, 1);
	assert.equal(rows[0].event, 'agent_reclaim');
	assert.equal(rows[0].reason, 'nothing_reclaimable');
	assert.equal(rows[0].sol, 0);
	assert.deepEqual(rows[0].detail.skipped_reasons, { at_or_below_floor: 1, capital_committed: 1 });
});

test('agent reclaim: a leg that threw records its own error rather than a clean zero', () => {
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: { reclaimedSol: 0, moves: [], failed: [], skipped: [], readErrors: [], error: 'agent_reclaim_failed' },
		now: 1_700_000_000_000,
	});
	assert.match(rows[0].reason, /^leg_error: agent_reclaim_failed/);
});

test('agent reclaim: a dry run is recorded as a dry run', () => {
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		result: { reclaimedSol: 0.1, moves: [{ name: 'a', address: 'A', sol: 0.1, dryRun: true }], failed: [], skipped: [], readErrors: [], dryRun: true },
		now: 1_700_000_000_000,
	});
	assert.equal(rows[1].detail.dry_run, true);
});

test('agent reclaim: rows chain like every other ledger batch', () => {
	// The rows are appended to the same tamper-evident chain, so they must hash
	// the same way. A row shape the hasher cannot read breaks verifyChain from
	// that point on, which reads as a tamper, not as a bug.
	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		masterSolBefore: 1,
		result: {
			reclaimedSol: 0.2,
			moves: [{ name: 'a', address: 'A', sol: 0.2, signature: 'sigA' }],
			failed: [{ name: 'b', address: 'B', sol: 0.1, stage: 'send', reason: 'send_failed' }],
			skipped: [], readErrors: [],
		},
		now: 1_700_000_000_000,
	});
	let prev = '';
	const hashes = rows.map((r, i) => {
		const h = hashEntry(prev, { ...r, seq: i + 1 });
		prev = h;
		return h;
	});
	assert.equal(new Set(hashes).size, rows.length);
	assert.ok(hashes.every((h) => /^[0-9a-f]{64}$/.test(h)));
});

// A floor skip has to say WHICH situation it is. `at_or_below_floor` alone was the
// only thing three consecutive triage sessions saw for every reclaim source, and it
// reads as "this wallet is empty" while equally meaning "this wallet holds real SOL
// behind a floor somebody configured". The first needs owner capital; the second
// needs a floor reviewed. In production the x402 ring treasury held 0.055 SOL against
// a 0.1 SOL floor and printed exactly like the 110 genuinely-empty agent wallets
// beside it, so the operator instruction "owner SOL is needed when every reclaim
// source reports at_or_below_floor" fired while the platform already owned enough SOL
// to restart the rail 45 times over.
test('a floor skip separates a fenced wallet from an empty one, with both numbers', () => {
	const fenced = floorBlockedSkip('x402-treasury', 0.054995, 0.1);
	const empty = floorBlockedSkip('Swarm 2', 0, 0.01);

	// The keep line is the number that actually blocked the sweep, not the bare floor.
	assert.equal(fenced.keepSol, reclaimKeepLineSol(0.1));
	assert.equal(fenced.reason, `at_or_below_floor:0.054995<${reclaimKeepLineSol(0.1)}`);
	assert.equal(fenced.heldSol, 0.054995);
	assert.equal(fenced.floorSol, 0.1);

	assert.equal(empty.heldSol, 0);
	assert.match(empty.reason, /^at_or_below_floor:0</);

	// The two cases are now distinguishable by the field an operator acts on.
	assert.notEqual(fenced.reason, empty.reason);
	assert.ok(fenced.heldSol > 0 && empty.heldSol === 0);
});

// The reason and the sizing must read the same keep line, or the message would
// explain a refusal the code did not make.
test('the reported keep line is the one that made the sweep return nothing', () => {
	for (const [held, floor] of [[0.054995, 0.1], [0.0051, 0.01], [0, 0.05], [1.2, 0.05]]) {
		const skip = floorBlockedSkip('w', held, floor);
		const swept = reclaimableSol(held, floor);
		if (swept === 0) assert.ok(held < skip.keepSol + MIN_SWEEP_SOL, `${held}/${floor}`);
		// Invariant the keep line exists to hold: never leave a wallet under its floor.
		assert.ok(skip.keepSol >= skip.floorSol);
	}
});

// The other half of the same defect: a wallet ABOVE its keep line whose excess is
// merely under the minimum sweep. Production 2026-09-24 printed
// `at_or_below_floor:0.019334483<0.01` for 31 agent wallets, a reason whose own two
// numbers disprove it, while those wallets held 0.161 SOL of excess between them.
test('a wallet above its keep line reports sweep dust, never a floor it is not at', () => {
	const dust = floorBlockedSkip('Sable #25', 0.019334483, 0.005);
	assert.equal(dust.keepSol, 0.01);
	assert.equal(dust.excessSol, 0.009334483);
	assert.equal(dust.reason, `below_min_sweep:0.009334483<${MIN_SWEEP_SOL}`);
	assert.doesNotMatch(dust.reason, /at_or_below_floor/);
	// The sizing agrees: this is exactly the case reclaimableSol returns 0 for.
	assert.equal(reclaimableSol(0.019334483, 0.005), 0);

	// The planner passes its own minimum through, so the reason names the threshold used.
	const planned = planAgentReclaim([
		{ agentId: 'a', name: 'Sable #25', address: 'S25', owner: BOT, sol: 0.0193, strategy: { enabled: false } },
	], { minSweepSol: 0.02 });
	assert.match(planned.skipped[0].reason, /^below_min_sweep:[0-9.]+<0\.02$/);

	// A wallet genuinely under its keep line still reads as a floor skip.
	assert.match(floorBlockedSkip('Swarm 1', 0.02499497, 0.05).reason, /^at_or_below_floor:/);
});

test('floorHeldSol totals only the SOL a floor is fencing', () => {
	const skipped = [
		floorBlockedSkip('treasury', 0.054995, 0.1),
		floorBlockedSkip('a2a-payer', 0.0009, 0.05),
		floorBlockedSkip('Swarm 2', 0, 0.01),
		{ name: 'circulation-treasury', reason: 'feed_sink_exempt' },
	];
	assert.equal(floorHeldSol(skipped), 0.055895);
	// Genuinely empty sources total zero, which is the only state that needs owner SOL.
	assert.equal(floorHeldSol([floorBlockedSkip('a', 0, 0.01), floorBlockedSkip('b', 0, 0.01)]), 0);
	assert.equal(floorHeldSol([]), 0);
	assert.equal(floorHeldSol(undefined), 0);
});

// The ledger histogram counts skip CLASSES. Once a floor skip carries its numbers,
// keying that histogram on the whole reason string would give a fleet-wide run one
// bucket per wallet balance (110 buckets of 1 on the production fleet) and destroy
// the count the field exists to provide. Bucketing on the text before the colon is
// what keeps the two changes compatible.
test('ledger skip histogram buckets by class, so numbered reasons do not fragment it', () => {
	const skipped = [
		floorBlockedSkip('bot-one', 0.0009, 0.01),
		floorBlockedSkip('bot-two', 0.0031, 0.01),
		floorBlockedSkip('bot-three', 0, 0.01),
		{ name: 'bot-four', reason: 'capital_committed' },
	];
	// Every floor skip here carries a different number.
	assert.equal(new Set(skipped.slice(0, 3).map((x) => x.reason)).size, 3);

	const rows = buildAgentReclaimRows({
		masterPubkey: ECONOMY_MASTER_ADDRESS,
		masterSolBefore: 0.2,
		deficitSol: 0.4,
		result: { reclaimedSol: 0, moves: [], failed: [], skipped, readErrors: [] },
		solUsd: 100,
		now: 1_700_000_000_000,
	});
	const summary = rows[rows.length - 1];
	assert.deepEqual(summary.detail.skipped_reasons, { at_or_below_floor: 3, capital_committed: 1 });
	// And the fenced total rides along, so "nothing_reclaimable" can be read honestly.
	assert.equal(summary.detail.skipped_floor_held_sol, 0.004);
	assert.equal(summary.reason, 'nothing_reclaimable');
});