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.

72.6 KB
Raw Blame
// @ts-check
// Autonomous agent activity engine.
//
// The platform operates a pool of real agents — each a published marketplace
// listing with its own custodial Solana (and optionally EVM) wallet. On every
// tick this engine makes those agents do real, on-chain things with one another:
// send SOL tips, pay each other for services (recorded as x402 spends), trade
// coins through the platform's own pump.fun trade engine, launch coins through
// the platform launcher, register on-chain identities, and leave marketplace
// reviews. Every event flows through the SAME real code paths a human-owned agent
// uses, so it all lands in the live money feed as genuine wallet activity — no
// synthetic rows, no fake numbers.
//
// Funds originate from a single treasury wallet the operator funds. The engine
// tops agent wallets up from the treasury just-in-time and keeps per-tick amounts
// small. Everything is gated behind CIRCULATION_ENABLED + a treasury secret; with
// neither set the engine is fully inert.

import { sql } from './db.js';
import { blockhashKey, getRecentBlockhashInfo, mintDecimals } from './solana/read-guards.js';
import { env } from './env.js';
import { confirmOrThrow } from './solana/confirm.js';
import { randomUUID } from 'node:crypto';
import { scrubSecrets } from './scrub-secrets.js';
import {
	ensureAgentWallet,
	recoverSolanaAgentKeypair,
	getOrCreateAgentEvmWallet,
	recoverAgentKey,
} from './agent-wallet.js';
import { recordCustodyEvent } from './agent-trade-guards.js';
import { solanaConnection } from './agent-pumpfun.js';
import { createSession } from './auth.js';
import { solUsdPrice } from './avatar-wallet.js';
import { CHAIN_BY_ID } from './erc8004-chains.js';
import { publicUrl as r2PublicUrl, thumbnailUrl } from './r2.js';
import { claimSeedUsername, seedDisplayName } from './seed-username.js';
import { pinToIPFS } from './ipfs-pin.js';
import { confirmSkillPurchase, resolvePayoutAddress } from './purchase-confirm.js';
import { consumeTrialUse, logSkillUsage } from './skill-access.js';
import { resolveMarketplaceFee } from './marketplace-platform-fee.js';
import { submitProtected } from './execution-engine.js';
import { insertNotification } from './notify.js';
import { invalidateSkillPriceCache } from './skill-price-cache.js';
import {
	PERSONAS,
	COIN_THEMES,
	PAYMENT_SERVICES,
	REVIEW_LINES,
	OWNER_FIRST_NAMES,
	SKILL_LISTINGS,
	ASSET_BLURBS,
	GENERIC_SKILLS,
	pick,
	pickTwo,
} from './circulation-personas.js';

const SOL = 1_000_000_000;

// Conservative, real economics. Every number here is small on purpose — the goal
// is a steady, believable heartbeat, not volume for its own sake.
const FEE_BUFFER = Math.floor(0.0009 * SOL); // tx fees + ATA rent headroom
const AGENT_FLOOR = Math.floor(0.02 * SOL); // top a working wallet up to this
const LAUNCH_FLOOR = Math.floor(0.034 * SOL); // pump create + tiny dev buy + fees
const TIP_MIN = Math.floor(0.001 * SOL);
const TIP_MAX = Math.floor(0.006 * SOL);
const PAY_MIN = Math.floor(0.0012 * SOL);
const PAY_MAX = Math.floor(0.01 * SOL);

// ── Adaptive rate governor ────────────────────────────────────────────────────
// The engine used to plan a fixed actionsPerTick regardless of what the treasury
// could afford. When the treasury ran dry every action still did its RPC reads
// and then threw Skip("treasury balance ... too low"), so the loop burned work to
// produce nothing and the Money Pulse went silent until a human topped it up
// (observed 2026-07-20: circulation dead for 11h while the x402 ring kept running).
//
// Instead the tick now reads the treasury once and scales itself: it funds as
// many SOL-spending actions as it can actually afford, and fills the rest of the
// budget with actions that cost nothing on-chain, so the economy degrades to a
// quieter-but-alive state and automatically speeds back up as the ring's revenue
// share refills the treasury. Self-balancing instead of burst-then-dead.
const COSTLY_ACTIONS = new Set(['tip', 'payment', 'trade', 'launch', 'deploy', 'buy_skill', 'buy_asset']);

/**
 * The light-action mix, weighted HARD toward real marketplace purchases (value
 * delivered plus take-rate earned) and away from the bare p2p `payment`
 * transfer, which moves SOL but delivers nothing.
 *
 * Anything not in COSTLY_ACTIONS costs nothing on-chain and so stays eligible
 * when the paid budget is exhausted. `use_trial` is deliberately free and
 * weighted at the trial rate: it is the funnel's missing middle, since a trial
 * that is never spent never reaches the exhausted state that makes its holder
 * eligible to buy.
 *
 * Exported so a test can hold every weighted kind to having a real handler.
 */
export const LIGHT_ACTION_WEIGHTS = [
	['buy_skill', 34],
	['tip', 18],
	['trade', 12],
	['trial', 12],
	['use_trial', 12],
	['buy_asset', 8],
	['review', 8],
	['payment', 6],
];

/** Action kinds the engine can actually execute. */
export function actionKinds() {
	return Object.keys(ACTIONS);
}

/** True when this kind spends on-chain and is gated by the paid budget. */
export function isCostlyAction(kind) {
	return COSTLY_ACTIONS.has(kind);
}
/** Leave this much SOL so the treasury can always pay its own transfer fees. */
const TREASURY_RESERVE_SOL = Number(process.env.CIRCULATION_TREASURY_RESERVE_SOL) || 0.005;
/** Typical just-in-time top-up one paid action draws (observed ~0.012 SOL). */
const EST_ACTION_SOL = Number(process.env.CIRCULATION_EST_ACTION_SOL) || 0.012;

/**
 * How many SOL-spending actions this tick can afford. Pure so the throttle curve
 * is unit-testable without a chain or a treasury.
 * @param {{treasurySol:number, actionsPerTick:number, reserveSol?:number, costPerActionSol?:number}} p
 * @returns {{paidBudget:number, throttled:boolean, spendableSol:number, reason:string|null}}
 */
export function planBudget({
	treasurySol,
	actionsPerTick,
	reserveSol = TREASURY_RESERVE_SOL,
	costPerActionSol = EST_ACTION_SOL,
}) {
	const cap = Math.max(0, Number(actionsPerTick) || 0);
	const spendable = Math.max(0, (Number(treasurySol) || 0) - reserveSol);
	const affordable = costPerActionSol > 0 ? Math.floor(spendable / costPerActionSol) : cap;
	const paidBudget = Math.max(0, Math.min(cap, affordable));
	return {
		paidBudget,
		throttled: paidBudget < cap,
		spendableSol: Math.round(spendable * 1e6) / 1e6,
		reason: paidBudget === 0 ? 'treasury_below_reserve' : (paidBudget < cap ? 'treasury_low' : null),
	};
}

const THREE_MINT = () => env.THREE_TOKEN_MINT || 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';

// Marketplace economics. Listings are priced in whole $THREE; buyers acquire $THREE
// through the same real trade engine before paying, so the only funding rail is the
// SOL treasury. Prices are deliberately small — a believable marketplace heartbeat,
// not volume for its own sake.
const THREE_DECIMALS = 6;
const SKILL_PRICE_MIN_THREE = 80; // whole $THREE
const SKILL_PRICE_MAX_THREE = 1200;
const ASSET_PRICE_MIN_THREE = 600;
const ASSET_PRICE_MAX_THREE = 4000;
const THREE_TOPUP_SOL = 0.012; // smallest $THREE top-up buy, and the quote probe size
// Ceiling on ONE top-up buy. The per-tick share of the treasury caps it further
// (see perActionSolCap), so this is the hard stop, not the usual spend.
const THREE_TOPUP_MAX_SOL = Number(process.env.CIRCULATION_THREE_TOPUP_MAX_SOL) || 0.06;

const roundSol = (n) => Math.round(Number(n) * 1e6) / 1e6;

/**
 * Size a $THREE top-up buy against what the buyer actually needs.
 *
 * Pure, so the refusal rule is unit-testable without a chain: a shortfall that
 * costs more than `maxSol` returns `sufficient:false` and the caller skips
 * WITHOUT trading, rather than buying a fixed slice that cannot clear the price
 * and paying a fee for the privilege on every tick.
 *
 * @param {{needAtomic:bigint|string, haveAtomic:bigint|string, atomicPerSol:number,
 *   maxSol:number, minSol?:number}} p
 * @returns {{sol:number, sufficient:boolean, shortfallAtomic:string,
 *   reason?:string, wantedSol?:number}}
 */
export function planThreeTopUp({ needAtomic, haveAtomic, atomicPerSol, maxSol, minSol = 0 }) {
	const shortfall = BigInt(needAtomic) - BigInt(haveAtomic);
	if (shortfall <= 0n) return { sol: 0, sufficient: true, shortfallAtomic: '0' };

	const rate = Number(atomicPerSol);
	if (!Number.isFinite(rate) || rate <= 0) {
		return { sol: 0, sufficient: false, shortfallAtomic: shortfall.toString(), reason: 'no_rate' };
	}

	// 8% over the quoted rate: the fill moves the curve and pays fees, so buying
	// exactly the quoted shortfall reliably lands a hair under the price.
	const wanted = roundSol(Math.max(minSol, (Number(shortfall) / rate) * 1.08));
	if (wanted > maxSol) {
		return { sol: 0, sufficient: false, shortfallAtomic: shortfall.toString(), reason: 'above_cap', wantedSol: wanted };
	}
	return { sol: wanted, sufficient: true, shortfallAtomic: shortfall.toString() };
}
const SKILLS_PER_SELLER = 3; // how many skills a seller lists before it's "stocked"

function threeAtomic(whole) {
	return BigInt(Math.round(whole)) * 10n ** BigInt(THREE_DECIMALS);
}

function clampInt(v, dflt, lo, hi) {
	const n = Number.parseInt(String(v ?? ''), 10);
	if (!Number.isFinite(n)) return dflt;
	return Math.min(hi, Math.max(lo, n));
}

export function config() {
	const enabledRaw = String(process.env.CIRCULATION_ENABLED ?? '').toLowerCase();
	return {
		enabled: enabledRaw === '1' || enabledRaw === 'true' || enabledRaw === 'yes',
		network: process.env.CIRCULATION_NETWORK === 'devnet' ? 'devnet' : 'mainnet',
		treasurySecret: (process.env.CIRCULATION_TREASURY_SECRET || '').trim(),
		evmTreasurySecret: (process.env.CIRCULATION_EVM_TREASURY_SECRET || '').trim(),
		evmChainId: clampInt(process.env.CIRCULATION_EVM_CHAIN_ID, 8453, 1, 1_000_000_000),
		poolTarget: clampInt(process.env.CIRCULATION_POOL_TARGET, 14, 2, 2000),
		growthPerTick: clampInt(process.env.CIRCULATION_GROWTH_PER_TICK, 3, 1, 40),
		actionsPerTick: clampInt(process.env.CIRCULATION_ACTIONS_PER_TICK, 2, 1, 12),
		origin: env.APP_ORIGIN || 'https://three.ws',
	};
}

// A skip is an expected, recoverable non-event (treasury low, pool too small) —
// never an error. It is logged and the tick moves on.
class Skip extends Error {}

function randBetween(lo, hi) {
	return lo + Math.floor(Math.random() * Math.max(1, hi - lo));
}

// ── one-time schema guard ─────────────────────────────────────────────────────
// Self-contained so the engine works whether or not the migration has been
// applied yet. CREATE TABLE IF NOT EXISTS is idempotent and cheap.
let _ensured = false;
async function ensureSchema() {
	if (_ensured) return;
	await sql`
		create table if not exists circulation_actions (
			id                   bigserial primary key,
			kind                 text not null,
			network              text,
			actor_agent_id       uuid,
			counterparty_agent_id uuid,
			signature            text,
			amount_lamports      bigint,
			status               text not null default 'ok',
			detail               jsonb not null default '{}'::jsonb,
			created_at           timestamptz not null default now()
		)
	`;
	await sql`create index if not exists circulation_actions_created on circulation_actions(created_at desc)`;
	await sql`create index if not exists circulation_actions_kind on circulation_actions(kind, created_at desc)`;
	_ensured = true;
}

async function logAction(row) {
	try {
		await sql`
			insert into circulation_actions
				(kind, network, actor_agent_id, counterparty_agent_id, signature, amount_lamports, status, detail)
			values (
				${row.kind}, ${row.network ?? null}, ${row.actorAgentId ?? null}, ${row.counterpartyAgentId ?? null},
				${row.signature ?? null}, ${row.amountLamports != null ? String(row.amountLamports) : null},
				${row.status ?? 'ok'}, ${JSON.stringify(scrubSecrets(row.detail ?? {}))}::jsonb
			)
		`;
	} catch (e) {
		console.warn('[circulation] logAction failed', e?.message);
	}
}

// `interval` is a plain Postgres interval string (e.g. '1 day', '45 minutes')
// bound as a parameter — no embedded quotes.
async function recentCount(kind, interval) {
	const [r] = await sql`
		select count(*)::int as count from circulation_actions
		where kind = ${kind} and status = 'ok' and created_at > now() - ${interval}::interval
	`;
	return r?.count ?? 0;
}

// ── treasury + low-level Solana transfer ──────────────────────────────────────

function decodeSecretKey(secret, bs58) {
	let bytes = null;
	try {
		const d = bs58.decode(secret);
		if (d.length === 64) bytes = d;
	} catch { /* not base58 */ }
	if (!bytes) {
		try {
			const b = Buffer.from(secret, 'base64');
			if (b.length === 64) bytes = b;
		} catch { /* not base64 */ }
	}
	if (!bytes) {
		try {
			const arr = JSON.parse(secret);
			if (Array.isArray(arr) && arr.length === 64) bytes = Uint8Array.from(arr);
		} catch { /* not json */ }
	}
	return bytes ? Uint8Array.from(bytes) : null;
}

async function treasuryKeypair(cfg) {
	if (!cfg.treasurySecret) throw new Skip('CIRCULATION_TREASURY_SECRET unset');
	const { Keypair } = await import('@solana/web3.js');
	const bs58 = (await import('bs58')).default;
	const bytes = decodeSecretKey(cfg.treasurySecret, bs58);
	if (!bytes) throw new Error('CIRCULATION_TREASURY_SECRET must be a 64-byte base58, base64, or JSON-array secret key');
	return Keypair.fromSecretKey(bytes);
}

async function transferSol(conn, fromKp, toAddress, lamports) {
	const {
		PublicKey,
		SystemProgram,
		TransactionMessage,
		VersionedTransaction,
		ComputeBudgetProgram,
	} = await import('@solana/web3.js');
	const toPk = new PublicKey(toAddress);

	// Retry once on "Blockhash not found" — the blockhash can expire between
	// getLatestBlockhash and sendTransaction if there is any delay (RPC round-trips,
	// key decryption, etc.). A single retry with a fresh blockhash is sufficient
	// because the new hash is guaranteed valid for ~150 blocks (~60s).
	const MAX_ATTEMPTS = 2;
	let lastErr;
	for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
		// The retry exists to escape an expired blockhash, so it forces a fresh
		// read; the first attempt may take the cached one. When the chain cannot be
		// read at all, the guard serves a cached hash that is still inside its
		// validity window rather than failing the transfer outright.
		const { blockhash, lastValidBlockHeight } = await getRecentBlockhashInfo(
			conn,
			blockhashKey({ url: env.SOLANA_RPC_URL }),
			{ forceFresh: attempt > 0 },
		);
		const message = new TransactionMessage({
			payerKey: fromKp.publicKey,
			recentBlockhash: blockhash,
			instructions: [
				ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 60_000 }),
				ComputeBudgetProgram.setComputeUnitLimit({ units: 1_000 }),
				SystemProgram.transfer({ fromPubkey: fromKp.publicKey, toPubkey: toPk, lamports }),
			],
		}).compileToV0Message();
		const tx = new VersionedTransaction(message);
		tx.sign([fromKp]);
		try {
			const signature = await conn.sendTransaction(tx, { maxRetries: 5 });
			// HTTP-polling confirm — routes through the RPC failover fetch and opens
			// no WebSocket, so a throttled provider can't trigger web3.js's WS 429
			// reconnect storm. Throws on a landed-but-reverted transfer.
			await confirmOrThrow(conn, { signature, blockhash, lastValidBlockHeight }, 'confirmed');
			return signature;
		} catch (err) {
			const msg = err?.message || '';
			if (attempt < MAX_ATTEMPTS - 1 && /Blockhash not found|BlockhashNotFound/i.test(msg)) {
				lastErr = err;
				continue;
			}
			throw err;
		}
	}
	throw lastErr;
}

async function solBalance(conn, address) {
	const { PublicKey } = await import('@solana/web3.js');
	return BigInt(await conn.getBalance(new PublicKey(address), 'confirmed'));
}

// Top `agent` up to `floor` from the treasury when it is short. Returns the funding
// signature if a transfer happened, else null. Throws Skip when the treasury itself
// cannot cover the top-up — the tick records the skip and waits for a refill.
async function ensureFunded(conn, treasuryKp, agent, floor) {
	const have = await solBalance(conn, agent.address);
	if (have >= BigInt(floor)) return null;
	const need = BigInt(floor) - have + BigInt(FEE_BUFFER);
	const treasuryHave = await solBalance(conn, treasuryKp.publicKey.toBase58());
	if (treasuryHave < need + BigInt(FEE_BUFFER)) {
		throw new Skip(`treasury balance ${(Number(treasuryHave) / SOL).toFixed(4)} SOL too low to fund ${(Number(need) / SOL).toFixed(4)} SOL`);
	}
	const sig = await transferSol(conn, treasuryKp, agent.address, Number(need));
	await logAction({
		kind: 'fund',
		network: config().network,
		actorAgentId: agent.id,
		signature: sig,
		amountLamports: Number(need),
		detail: { to: agent.address, floor },
	});
	return sig;
}

// ── pool management ───────────────────────────────────────────────────────────

// After this many consecutive key-recovery failures an agent's custodial secret
// is treated as unrecoverable (encrypted under a rotated/lost WALLET_ENCRYPTION_KEY)
// and it is quarantined out of the pool. Its funds are orphaned regardless; the
// point is to stop the selector re-picking a permanently-dead wallet every tick,
// which silently starves the live feed (a handful of broken agents can absorb
// every trade slot, exactly the July 2026 flatline). Deterministic once broken,
// so the threshold only guards against a transient decrypt hiccup.
const KEY_FAIL_QUARANTINE = clampInt(process.env.CIRCULATION_KEY_FAIL_QUARANTINE, 3, 1, 100);

async function loadPool() {
	const rows = await sql`
		select id, user_id, name, avatar_id, meta
		from agent_identities
		where (meta->>'circulation') = 'true' and deleted_at is null
		  and coalesce((meta->>'circulation_key_broken')::boolean, false) = false
		order by created_at asc
	`;
	return rows
		.map((r) => ({
			id: r.id,
			userId: r.user_id,
			name: r.name,
			avatarId: r.avatar_id,
			meta: r.meta || {},
			address: r.meta?.solana_address || null,
		}))
		.filter((a) => a.address);
}

// Record the outcome of a custodial-key use for an agent. A failure increments a
// consecutive-failure counter and, at the threshold, sets `circulation_key_broken`
// so loadPool stops selecting it (and logs a one-off quarantine action). A success
// clears the counter. Fire-and-forget by callers — never block the action path.
async function recordKeyResult(agentId, agentName, ok) {
	try {
		if (ok) {
			await sql`
				update agent_identities
				set meta = meta - 'circulation_key_fail_count'
				where id = ${agentId} and (meta ? 'circulation_key_fail_count')`;
			return;
		}
		const rows = await sql`
			update agent_identities
			set meta = jsonb_set(
				coalesce(meta, '{}'::jsonb),
				'{circulation_key_fail_count}',
				to_jsonb(coalesce((meta->>'circulation_key_fail_count')::int, 0) + 1)
			)
			where id = ${agentId}
			returning (meta->>'circulation_key_fail_count')::int as fails`;
		const fails = rows?.[0]?.fails ?? 0;
		if (fails >= KEY_FAIL_QUARANTINE) {
			await sql`
				update agent_identities
				set meta = jsonb_set(
					jsonb_set(coalesce(meta, '{}'::jsonb), '{circulation_key_broken}', 'true'::jsonb),
					'{circulation_key_broken_at}', to_jsonb(now()::text)
				)
				where id = ${agentId}`;
			await logAction({
				kind: 'quarantine',
				actorAgentId: agentId,
				detail: { reason: 'key_recover_failed', consecutive_failures: fails, agent: agentName },
			});
		}
	} catch (e) {
		console.warn('[circulation] recordKeyResult failed', e?.message);
	}
}

// True when a failed trade/tip result is an unrecoverable custodial-key failure.
function isKeyRecoverFailure(result) {
	return result?.code === 'key_recover_failed';
}

function slugify(s) {
	return String(s)
		.toLowerCase()
		.replace(/[^a-z0-9]+/g, '-')
		.replace(/^-+|-+$/g, '')
		.slice(0, 40);
}

// Clone a random public avatar into `userId`'s ownership so the new agent has a
// real 3D body + thumbnail (reusing the platform's own generated gallery) and so
// the coin launcher can use it as the token image. Returns the new avatar id or
// null when no public avatar exists yet.
//
// Clones are public — every platform-generated body belongs in the galleries so
// users see the full breadth of what the platform makes. The way clones stop
// looking repetitive is upstream: the source pool must be genuinely diverse
// (see the composer lane in api/_lib/avatar-composer/), so a random draw lands
// on a distinct avatar instead of one of a handful of recolored base bodies.
//
// Exported: api/cron/agent-avatar-backfill.js reuses this to heal pre-existing
// agents whose avatar_id is NULL, so every agent card can show a real preview.
export async function cloneAvatarFor(userId, name) {
	// Prefer a humanoid with a ready-made thumbnail — the clone inherits the
	// thumbnail_key, so the agent card gets an instant preview instead of
	// waiting a cron tick for a render. Props/accessories and thumbnail-less
	// rows are only a fallback for a thin pool.
	let [src] = await sql`
		select id, storage_key, thumbnail_key, size_bytes, content_type, source, tags, model_category
		from avatars
		where visibility = 'public' and deleted_at is null and storage_key is not null
		  and model_category = 'avatar' and thumbnail_key is not null
		order by random()
		limit 1
	`;
	if (!src) {
		[src] = await sql`
			select id, storage_key, thumbnail_key, size_bytes, content_type, source, tags, model_category
			from avatars
			where visibility = 'public' and deleted_at is null and storage_key is not null
			order by random()
			limit 1
		`;
	}
	if (!src) return null;
	const slug = `${slugify(name)}-${randomUUID().slice(0, 6)}`;
	const [row] = await sql`
		insert into avatars
			(owner_id, slug, name, description, storage_key, size_bytes, content_type,
			 source, source_meta, thumbnail_key, visibility, tags, model_category, created_at, updated_at)
		values (
			${userId}, ${slug}, ${name}, ${'Operated by a three.ws agent'},
			${src.storage_key}, ${src.size_bytes ?? 0}, ${src.content_type || 'model/gltf-binary'},
			${src.source || 'import'}, ${JSON.stringify({ circulation: true, cloned_from: src.id })}::jsonb,
			${src.thumbnail_key ?? null}, 'public', ${src.tags ?? []}, ${src.model_category ?? null}, now(), now()
		)
		returning id
	`;
	return row?.id ?? null;
}

// Create exactly one new pool agent for the next unused persona. Idempotent per
// persona (a persona already represented is skipped). Returns a short descriptor
// or null when the persona set is exhausted.
async function createPoolAgent() {
	// Variant-based scaling: the pool grows past the 16 base personas by minting
	// additional accounts that reuse a persona's craft but get their own owner,
	// wallet, name suffix, and marketplace listing. Selection is deterministic on
	// the current count so repeated calls produce distinct accounts.
	const [{ count }] = await sql`
		select count(*)::int as count from agent_identities
		where (meta->>'circulation') = 'true' and deleted_at is null
	`;
	if (count >= 5000) return null; // hard safety ceiling

	const persona = PERSONAS[count % PERSONAS.length];
	const variant = Math.floor(count / PERSONAS.length);
	const agentName = variant === 0 ? persona.name : `${persona.name} #${variant + 1}`;

	const ownerWord = `${pick(OWNER_FIRST_NAMES)}${persona.handle}`.replace(/[^a-z0-9]/g, '');
	const username = await claimSeedUsername(slugify(ownerWord) || persona.handle);
	// Only reachable if a persona ever ships with an empty handle, but a null
	// username would insert a nameless account rather than skip the tick.
	if (!username) return { skipped: 'no_username', persona: persona.handle };
	const email = `${username}@agents.three.ws`;
	const displayName = seedDisplayName(username);

	const [user] = await sql`
		insert into users (email, display_name, username, plan, email_verified, service_account, created_at, updated_at)
		values (${email}, ${displayName}, ${username}, 'free', false, true, now(), now())
		on conflict do nothing
		returning id
	`;
	if (!user?.id) return { skipped: 'user_conflict', persona: persona.handle };

	const avatarId = await cloneAvatarFor(user.id, agentName).catch(() => null);

	const meta = { circulation: true, persona: persona.handle, variant };
	const [agent] = await sql`
		insert into agent_identities
			(user_id, name, description, system_prompt, greeting, category, tags, capabilities,
			 avatar_id, is_published, published_at, meta, created_at, updated_at)
		values (
			${user.id}, ${agentName}, ${persona.description}, ${persona.system_prompt}, ${persona.greeting},
			${persona.category}, ${persona.tags}, ${JSON.stringify({ bullets: [], skills: [], library: [] })}::jsonb,
			${avatarId}, true, now(), ${JSON.stringify(meta)}::jsonb, now(), now()
		)
		returning id
	`;
	if (!agent?.id) {
		await sql`delete from users where id = ${user.id}`.catch(() => {});
		return { skipped: 'agent_insert_failed', persona: persona.handle };
	}

	// First published version, mirroring the marketplace publish path.
	await sql`
		insert into agent_versions (agent_id, version, system_prompt, greeting, category, tags, capabilities, changelog, created_by)
		values (${agent.id}, 1, ${persona.system_prompt}, ${persona.greeting}, ${persona.category}, ${persona.tags},
		        ${JSON.stringify({ bullets: [], skills: [], library: [] })}::jsonb, 'Initial release', ${user.id})
		on conflict do nothing
	`.catch(() => {});

	// Provision the custodial Solana wallet immediately so the agent can transact.
	await ensureAgentWallet(agent.id, user.id, { reason: 'circulation_provision' }).catch((e) => {
		console.warn('[circulation] wallet provision failed', e?.message);
	});

	await logAction({ kind: 'provision', actorAgentId: agent.id, detail: { persona: persona.handle, username, avatar: !!avatarId } });
	return { created: agent.id, persona: persona.handle, username };
}

// ── helpers shared by actions ─────────────────────────────────────────────────

async function loadAgentMeta(agentId) {
	const [row] = await sql`select id, user_id, meta from agent_identities where id = ${agentId} and deleted_at is null limit 1`;
	return row || null;
}

async function senderKeypair(agent, reason) {
	const full = await loadAgentMeta(agent.id);
	const secret = full?.meta?.encrypted_solana_secret;
	if (!secret) throw new Error('agent has no custodial secret');
	try {
		const kp = await recoverSolanaAgentKeypair(secret, {
			agentId: agent.id,
			userId: agent.userId,
			reason,
			meta: { source: 'circulation' },
		});
		recordKeyResult(agent.id, agent.name, true).catch(() => {});
		return kp;
	} catch (e) {
		// A decrypt failure here is the same unrecoverable-key condition the trade
		// path reports as key_recover_failed; count it toward quarantine.
		recordKeyResult(agent.id, agent.name, false).catch(() => {});
		throw e;
	}
}

// ── marketplace helpers ───────────────────────────────────────────────────────

// Register the agent's custodial Solana wallet as its default payout wallet so
// buyers' funds resolve a destination (resolvePayoutAddress reads this table).
// Idempotent — mirrors the upsert in /api/monetization/wallet.
async function ensurePayoutWallet(agent) {
	if (!agent.address) throw new Skip('seller has no custodial wallet');
	await sql`
		insert into agent_payout_wallets
			(user_id, agent_id, address, chain, is_default, preferred_network, approved_at, effective_at, set_by)
		values (${agent.userId}, ${agent.id}, ${agent.address}, 'solana', true, 'mainnet', now(), now(), 'platform')
		on conflict (user_id, agent_id, chain) do update set
			address = excluded.address, is_default = true, approved_at = now(), effective_at = now(), set_by = 'platform'
	`;
}

// Read an owner's $THREE balance in atomic units (0 when the token account does
// not exist yet). Cheap, read-only.
async function threeBalanceAtomic(conn, ownerAddress) {
	const { PublicKey } = await import('@solana/web3.js');
	const { getAssociatedTokenAddressSync } = await import('@solana/spl-token');
	const ata = getAssociatedTokenAddressSync(new PublicKey(THREE_MINT()), new PublicKey(ownerAddress));
	try {
		const bal = await conn.getTokenAccountBalance(ata, 'confirmed');
		return BigInt(bal?.value?.amount ?? '0');
	} catch {
		return 0n; // no ATA / not found
	}
}

// Guarantee `agent` holds at least `needAtomic` $THREE. Tops the wallet up with SOL
// from the treasury, then buys $THREE through the real trade engine. Returns when
// the balance clears; throws Skip if it still falls short (the tick records the skip
// and a later tick retries once the buy settles).
async function ensureThree(ctx, agent, needAtomic) {
	const { conn, treasuryKp, network } = ctx;
	let have = await threeBalanceAtomic(conn, agent.address);
	if (have >= needAtomic) return have;

	const { PublicKey } = await import('@solana/web3.js');
	const { executeAgentTrade } = await import('../agents/agent-trade.js');
	const { quoteTrade } = await import('../agents/solana-trade.js');
	const mintPk = new PublicKey(THREE_MINT());

	// Price the buy BEFORE funding or spending anything. This used to buy a fixed
	// THREE_TOPUP_SOL of $THREE no matter what the listing cost: at roughly 100
	// $THREE per 0.012 SOL, every listing above ~100 $THREE fell short, skipped,
	// and paid a real trade fee to do it, then repeated on the next tick and the
	// next. Skills list at 80-1200 $THREE and assets at 600-4000, so most of the
	// marketplace was structurally unbuyable and marketplace GMV read zero while
	// the fees still went out.
	const capSol = Math.min(THREE_TOPUP_MAX_SOL, Number(ctx.perActionSolCap) || THREE_TOPUP_SOL);
	let atomicPerSol = 0;
	try {
		const q = await quoteTrade({
			conn,
			side: 'buy',
			mintPk,
			mintStr: THREE_MINT(),
			network,
			solAmount: THREE_TOPUP_SOL,
			slippageBps: 700,
		});
		atomicPerSol = Number(q.outAtomics) / THREE_TOPUP_SOL;
	} catch (e) {
		throw new Skip(`could not quote $THREE: ${e?.message || 'quote_failed'}`);
	}

	const planned = planThreeTopUp({
		needAtomic,
		haveAtomic: have,
		atomicPerSol,
		maxSol: capSol,
		minSol: THREE_TOPUP_SOL,
	});
	// Refusing here is the point: a listing this tick cannot fund is skipped
	// without spending, instead of buying a partial position and failing anyway.
	if (!planned.sufficient) {
		throw new Skip(
			planned.reason === 'above_cap'
				? `listing needs ~${planned.wantedSol} SOL of $THREE, over this tick's ${roundSol(capSol)} SOL cap`
				: 'could not price $THREE for the top-up buy',
		);
	}

	// Fund the BUY, not just the idle floor: a 0.02 SOL floor cannot settle a
	// 0.04 SOL purchase, and the trade would abort on headroom after the transfer.
	const needLamports = Math.floor(planned.sol * SOL) + FEE_BUFFER;
	await ensureFunded(conn, treasuryKp, agent, Math.max(AGENT_FLOOR, needLamports));

	const full = await loadAgentMeta(agent.id);
	if (!full) throw new Skip('agent vanished');

	const result = await executeAgentTrade({
		id: agent.id,
		userId: agent.userId,
		meta: full.meta,
		input: {
			side: 'buy',
			mint: THREE_MINT(),
			mintPk,
			amount: planned.sol,
			isMax: false,
			slippageBps: 700,
			slippagePct: 7,
			network,
			simulate: false,
			idempotencyKey: randomUUID(),
		},
		source: 'discretionary',
	});
	if (!result.ok) {
		if (isKeyRecoverFailure(result)) recordKeyResult(agent.id, agent.name, false).catch(() => {});
		throw new Skip(`could not acquire $THREE: ${result.code || 'trade_error'}${result.message ? ` — ${result.message}` : ''}`);
	}

	// Give the buy a moment to settle, then re-read.
	for (let i = 0; i < 6; i++) {
		have = await threeBalanceAtomic(conn, agent.address);
		if (have >= needAtomic) return have;
		await new Promise((r) => setTimeout(r, 2500));
	}
	throw new Skip('still short on $THREE after top-up buy — will retry next tick');
}

// Build, sign, and submit an SPL transferChecked of `atomic` $THREE from `fromKp`
// to `toAddress`, tagging it with a Solana-Pay `referenceKey` so confirm/validate
// can find it on-chain. Buyer pays the seller-ATA rent idempotently. Returns the
// confirmed signature.
// Transfer $THREE to a recipient, tagging the leg with a Solana-Pay reference so
// confirmSkillPurchase can find it. When `feeLeg` is supplied ({ wallet, atomics }),
// a SECOND transferChecked routes the platform fee to the treasury in the SAME
// transaction — the exact split confirmSkillPurchase verifies. `atomic` is the
// CREATOR leg (price − fee); pass the full price with no feeLeg for a plain transfer.
async function transferThreeWithReference(conn, fromKp, toAddress, atomic, referenceKey, network, feeLeg = null) {
	const { PublicKey } = await import('@solana/web3.js');
	const {
		getAssociatedTokenAddressSync,
		createTransferCheckedInstruction,
		createAssociatedTokenAccountIdempotentInstruction,
	} = await import('@solana/spl-token');

	const mintKey = new PublicKey(THREE_MINT());
	const recipKey = new PublicKey(toAddress);
	// $THREE's decimals are a constant, so this costs no network read and a dead
	// RPC cannot stall a circulation transfer over a value we already know.
	const decimals = await mintDecimals(conn, mintKey);
	const fromAta = getAssociatedTokenAddressSync(mintKey, fromKp.publicKey);
	const toAta = getAssociatedTokenAddressSync(mintKey, recipKey);

	const transferIx = createTransferCheckedInstruction(
		fromAta, mintKey, toAta, fromKp.publicKey, atomic, decimals,
	);
	transferIx.keys.push({ pubkey: referenceKey, isSigner: false, isWritable: false });

	const ixs = [
		createAssociatedTokenAccountIdempotentInstruction(fromKp.publicKey, toAta, recipKey, mintKey),
		transferIx,
	];

	if (feeLeg && feeLeg.atomics > 0n && feeLeg.wallet) {
		const feeKey = new PublicKey(feeLeg.wallet);
		const feeAta = getAssociatedTokenAddressSync(mintKey, feeKey);
		ixs.push(createAssociatedTokenAccountIdempotentInstruction(fromKp.publicKey, feeAta, feeKey, mintKey));
		ixs.push(createTransferCheckedInstruction(
			fromAta, mintKey, feeAta, fromKp.publicKey, feeLeg.atomics, decimals,
		));
	}

	const { signature } = await submitProtected({ network, connection: conn, payer: fromKp, instructions: ixs });
	return signature;
}

// Skills currently listed (active, $THREE-priced), joined to the seller's owner so
// the purchase action can exclude self-dealing. ONLY circulation sellers — agents
// we own — are ever included. Manufactured demand never reaches a real user's
// wallet, so no SOL or $THREE ever leaves the closed loop. Each row is tagged
// seller_kind so callers can reason about it.
async function listedSkills() {
	return sql`
		select asp.agent_id, asp.skill, asp.amount, asp.currency_mint, asp.trial_uses,
		       ai.user_id as seller_user_id, ai.name as seller_name, 'circulation' as seller_kind
		from agent_skill_prices asp
		join agent_identities ai on ai.id = asp.agent_id
		where asp.is_active = true
		  and asp.currency_mint = ${THREE_MINT()}
		  and (ai.meta->>'circulation') = 'true'
		  and ai.deleted_at is null
	`;
}

// ── actions ───────────────────────────────────────────────────────────────────

// Agent A sends a real SOL tip to agent B. Recorded on B exactly like a verified
// peer tip, so it lands in the feed as an inbound tip with A as the counterparty.
async function actionTip(ctx) {
	const { conn, treasuryKp, pool, network, solUsd } = ctx;
	const [sender, receiver] = pickTwo(pool);
	if (!sender || !receiver || sender.id === receiver.id) throw new Skip('need two distinct agents');

	const amount = randBetween(TIP_MIN, TIP_MAX);
	await ensureFunded(conn, treasuryKp, sender, Math.max(AGENT_FLOOR, amount + FEE_BUFFER));

	const kp = await senderKeypair(sender, 'circulation_tip');
	const signature = await transferSol(conn, kp, receiver.address, amount);

	const usd = solUsd ? (amount / SOL) * solUsd : null;
	await recordCustodyEvent({
		agentId: receiver.id,
		userId: null,
		eventType: 'tip',
		category: 'tip',
		network,
		asset: 'SOL',
		amountLamports: amount,
		usd,
		destination: receiver.address,
		signature,
		status: 'confirmed',
		idempotencyKey: `tip:${signature}`,
		meta: { source: 'p2p_tip', from: sender.address, block_time: new Date().toISOString(), decimals: 9 },
	});

	await logAction({ kind: 'tip', network, actorAgentId: receiver.id, counterpartyAgentId: sender.id, signature, amountLamports: amount, detail: { from: sender.name, to: receiver.name } });
	return { kind: 'tip', from: sender.name, to: receiver.name, sol: amount / SOL, signature };
}

// Agent A pays agent B for a service. Real SOL transfer, recorded on the PAYER as
// an x402-category spend so it surfaces in the feed as an agent-to-agent payment.
async function actionPayment(ctx) {
	const { conn, treasuryKp, pool, network, solUsd } = ctx;
	const [payer, payee] = pickTwo(pool);
	if (!payer || !payee || payer.id === payee.id) throw new Skip('need two distinct agents');

	const amount = randBetween(PAY_MIN, PAY_MAX);
	await ensureFunded(conn, treasuryKp, payer, Math.max(AGENT_FLOOR, amount + FEE_BUFFER));

	const kp = await senderKeypair(payer, 'circulation_payment');
	const signature = await transferSol(conn, kp, payee.address, amount);

	const service = pick(PAYMENT_SERVICES);
	const usd = solUsd ? (amount / SOL) * solUsd : null;
	await recordCustodyEvent({
		agentId: payer.id,
		userId: payer.userId,
		eventType: 'spend',
		category: 'x402',
		network,
		asset: 'SOL',
		amountLamports: amount,
		usd,
		destination: payee.address,
		signature,
		status: 'confirmed',
		reason: 'a2a_payment',
		idempotencyKey: `pay:${signature}`,
		meta: { source: 'a2a_payment', service, to_agent: payee.name, to: payee.address, block_time: new Date().toISOString() },
	});

	await logAction({ kind: 'payment', network, actorAgentId: payer.id, counterpartyAgentId: payee.id, signature, amountLamports: amount, detail: { service, from: payer.name, to: payee.name } });
	return { kind: 'payment', from: payer.name, to: payee.name, service, sol: amount / SOL, signature };
}

async function pickTradableMint(network) {
	if (network === 'mainnet' && Math.random() < 0.6) return THREE_MINT();
	const rows = await sql`
		select pam.mint from pump_agent_mints pam
		join agent_identities ai on ai.id = pam.agent_id
		where pam.network = ${network} and (ai.meta->>'circulation') = 'true'
		order by pam.created_at desc
		limit 20
	`;
	if (rows.length) return pick(rows).mint;
	return network === 'mainnet' ? THREE_MINT() : null;
}

// Agent buys a small amount of a coin through the real, fully-guarded trade engine.
async function actionTrade(ctx) {
	const { conn, treasuryKp, pool, network } = ctx;
	const agent = pick(pool);
	await ensureFunded(conn, treasuryKp, agent, AGENT_FLOOR);

	const mint = await pickTradableMint(network);
	if (!mint) throw new Skip('no tradable mint available');

	const { PublicKey } = await import('@solana/web3.js');
	const { executeAgentTrade } = await import('../agents/agent-trade.js');
	const full = await loadAgentMeta(agent.id);
	if (!full) throw new Skip('agent vanished');

	const amount = Number((0.002 + Math.random() * 0.008).toFixed(5)); // 0.002–0.010 SOL
	const result = await executeAgentTrade({
		id: agent.id,
		userId: agent.userId,
		meta: full.meta,
		input: {
			side: 'buy',
			mint,
			mintPk: new PublicKey(mint),
			amount,
			isMax: false,
			slippageBps: 500,
			slippagePct: 5,
			network,
			simulate: false,
			idempotencyKey: randomUUID(),
		},
		source: 'discretionary',
	});

	if (!result.ok) {
		if (isKeyRecoverFailure(result)) recordKeyResult(agent.id, agent.name, false).catch(() => {});
		throw new Skip(`trade rejected: ${result.code || 'error'}${result.message ? ` — ${result.message}` : ''}`);
	}
	recordKeyResult(agent.id, agent.name, true).catch(() => {});
	await logAction({ kind: 'trade', network, actorAgentId: agent.id, signature: result.data?.signature, amountLamports: Math.round(amount * SOL), detail: { mint, agent: agent.name } });
	return { kind: 'trade', agent: agent.name, mint, sol: amount, signature: result.data?.signature };
}

// Internal authenticated POST as a given owner (mints a short-lived session and
// passes it as the host session cookie). Used for the launcher endpoints, which
// authenticate via the session cookie.
async function postAs(origin, ownerUserId, path, body, timeoutMs = 55_000) {
	const token = await createSession({ userId: ownerUserId, userAgent: 'circulation', ip: null });
	let res;
	try {
		res = await fetch(`${origin}${path}`, {
			method: 'POST',
			headers: {
				'content-type': 'application/json',
				cookie: `__Host-sid=${token}`,
				'user-agent': 'threews-circulation/1.0',
			},
			body: JSON.stringify(body),
			signal: AbortSignal.timeout(timeoutMs),
		});
	} catch (err) {
		if (err?.name === 'TimeoutError' || err?.name === 'AbortError') return { status: 0, body: null, timedOut: true };
		throw err;
	}
	let parsed = null;
	try { parsed = await res.json(); } catch { /* non-JSON */ }
	return { status: res.status, body: parsed };
}

// Agent launches a coin through the platform's own pump.fun launcher (build
// metadata → server-signed launch-agent). Records into pump_agent_mints, so it
// surfaces in the feed and the launch directory as a real on-chain launch.
async function actionLaunch(ctx) {
	const { conn, treasuryKp, pool, network, origin } = ctx;
	// Prefer an agent that has not launched recently.
	const recent = await sql`
		select actor_agent_id from circulation_actions
		where kind = 'launch' and created_at > now() - interval '2 days'
	`;
	const launchedSet = new Set(recent.map((r) => r.actor_agent_id));
	const candidates = pool.filter((a) => a.avatarId && !launchedSet.has(a.id));
	const agent = candidates.length ? pick(candidates) : pool.find((a) => a.avatarId);
	if (!agent) throw new Skip('no launch-ready agent (needs an avatar image)');

	await ensureFunded(conn, treasuryKp, agent, LAUNCH_FLOOR);

	const theme = pick(COIN_THEMES);
	const meta = await postAs(origin, agent.userId, '/api/pump/build-metadata', {
		name: theme.name,
		symbol: theme.symbol,
		description: theme.description,
		agent_id: agent.id,
		avatar_id: agent.avatarId,
	});
	if (meta.timedOut) throw new Skip('metadata build timed out');
	if (meta.status !== 200 || !meta.body?.metadata_url) {
		throw new Skip(`metadata build ${meta.status}: ${meta.body?.error || 'no url'}`);
	}

	const launch = await postAs(origin, agent.userId, '/api/pump/launch-agent', {
		agent_id: agent.id,
		name: theme.name,
		symbol: theme.symbol,
		uri: meta.body.metadata_url,
		network,
		quote_currency: 'sol',
		sol_buy_in: 0.001,
		buyback_bps: 0,
		coin_type: 'agent',
	});
	if (launch.timedOut) throw new Skip('launch timed out');
	if (launch.status !== 200 || !(launch.body?.mint || launch.body?.data?.mint)) {
		throw new Skip(`launch ${launch.status}: ${launch.body?.error || launch.body?.message || 'no mint'}`);
	}
	const mint = launch.body?.mint || launch.body?.data?.mint;

	await logAction({ kind: 'launch', network, actorAgentId: agent.id, signature: mint, detail: { name: theme.name, symbol: theme.symbol, mint, agent: agent.name } });
	return { kind: 'launch', agent: agent.name, name: theme.name, symbol: theme.symbol, mint };
}

// Owner of one agent leaves a real marketplace review on another agent's listing.
async function actionReview(ctx) {
	const { pool } = ctx;
	const [reviewer, target] = pickTwo(pool);
	if (!reviewer || !target || reviewer.id === target.id || reviewer.userId === target.userId) {
		throw new Skip('need two agents with distinct owners');
	}
	const rating = Math.random() < 0.75 ? 5 : 4;
	const body = pick(REVIEW_LINES);
	await sql`
		insert into agent_reviews (agent_id, user_id, rating, body)
		values (${target.id}, ${reviewer.userId}, ${rating}, ${body})
		on conflict (agent_id, user_id)
		do update set rating = excluded.rating, body = excluded.body, updated_at = now()
	`;
	await logAction({ kind: 'review', actorAgentId: reviewer.id, counterpartyAgentId: target.id, detail: { rating, target: target.name } });
	return { kind: 'review', by: reviewer.name, on: target.name, rating };
}

// A seller agent lists one more skill on its marketplace profile: a real
// agent_skill_prices row priced in $THREE (some trial-eligible), plus the skill
// surfaced on the agent's published capabilities so it's a visible listing — not
// just a price row. Registers the seller's payout wallet so buyers can pay it.
async function actionListSkill() {
	const [seller] = await sql`
		select ai.id, ai.user_id, ai.name, ai.category, ai.capabilities, ai.meta
		from agent_identities ai
		where (ai.meta->>'circulation') = 'true' and ai.deleted_at is null
		  and ai.meta->>'solana_address' is not null
		  and (
			select count(*) from agent_skill_prices asp
			where asp.agent_id = ai.id and asp.is_active = true and asp.currency_mint = ${THREE_MINT()}
		  ) < ${SKILLS_PER_SELLER}
		order by random()
		limit 1
	`;
	if (!seller) throw new Skip('every seller is fully stocked');

	const sellerAgent = { id: seller.id, userId: seller.user_id, name: seller.name, address: seller.meta?.solana_address };
	await ensurePayoutWallet(sellerAgent);

	const catalog = SKILL_LISTINGS[seller.category] || GENERIC_SKILLS;
	const listed = new Set((await sql`select skill from agent_skill_prices where agent_id = ${seller.id}`).map((r) => r.skill));
	const choices = catalog.filter((s) => !listed.has(s));
	if (!choices.length) throw new Skip('seller has listed its whole catalog');
	const skill = pick(choices);

	const priceWhole = randBetween(SKILL_PRICE_MIN_THREE, SKILL_PRICE_MAX_THREE);
	const amount = threeAtomic(priceWhole).toString();
	const trialUses = Math.random() < 0.4 ? 1 : 0;

	await sql`
		insert into agent_skill_prices
			(agent_id, skill, amount, currency_mint, chain, is_active, trial_uses,
			 mint_decimals, pricing_type, gate_type)
		values
			(${seller.id}, ${skill}, ${amount}, ${THREE_MINT()}, 'solana', true, ${trialUses},
			 ${THREE_DECIMALS}, 'fixed', 'price')
		on conflict (agent_id, skill) do update set
			amount = excluded.amount, currency_mint = excluded.currency_mint, chain = excluded.chain,
			is_active = true, trial_uses = excluded.trial_uses, mint_decimals = excluded.mint_decimals,
			updated_at = now()
	`;

	const skills = Array.isArray(seller.capabilities?.skills) ? seller.capabilities.skills : [];
	if (!skills.includes(skill)) {
		const next = { ...(seller.capabilities || {}), skills: [...skills, skill] };
		await sql`update agent_identities set capabilities = ${JSON.stringify(next)}::jsonb, updated_at = now() where id = ${seller.id}`;
	}
	await invalidateSkillPriceCache(seller.id).catch(() => {});

	await logAction({ kind: 'list_skill', actorAgentId: seller.id, detail: { skill, price_three: priceWhole, trial: !!trialUses, seller: seller.name } });
	return { kind: 'list_skill', seller: seller.name, skill, price_three: priceWhole, trial: !!trialUses };
}

// A buyer agent purchases a listed skill from another agent. The buyer signs a real
// $THREE SPL transfer (acquiring $THREE first if short, via the same trade engine),
// then confirmSkillPurchase validates on-chain, records the seller's revenue, and
// grants persistent access — the identical path a human-owned agent uses.
async function actionBuySkill(ctx) {
	const { conn, pool, network } = ctx;
	const listings = await listedSkills();
	if (!listings.length) throw new Skip('no skills listed yet');
	const listing = pick(listings);

	const candidates = pool.filter((a) => a.userId !== listing.seller_user_id && a.id !== listing.agent_id);
	if (!candidates.length) throw new Skip('no eligible buyer');
	const buyer = pick(candidates);

	// A confirmed purchase means the buyer owns the skill outright. A trial only
	// blocks while it still has uses left: once those run out, that agent is
	// precisely the one the funnel exists to convert, so it must stay buyable.
	// Treating a spent trial as ownership is what pinned marketplace revenue at a
	// structural zero, since every trial permanently retired its (buyer, seller,
	// skill) triple from the paid path.
	const [owned] = await sql`
		select 1 from skill_purchases
		where user_id = ${buyer.userId} and agent_id = ${listing.agent_id} and skill = ${listing.skill}
		  and (status = 'confirmed' or (status = 'trial' and coalesce(trial_remaining, 0) > 0))
		limit 1
	`;
	if (owned) throw new Skip('buyer already owns this skill');

	const amountAtomic = BigInt(listing.amount);
	await ensureThree(ctx, buyer, amountAtomic);

	const recipient = await resolvePayoutAddress(listing.agent_id, 'solana').catch(() => null);
	if (!recipient) throw new Skip('seller payout wallet missing');

	// Platform fee — the same take-rate the real /marketplace purchase path charges,
	// so the demo loop validates true unit economics. When the fee is OFF (default)
	// resolveMarketplaceFee returns 0 and this degrades to a plain full-price transfer
	// (today's behaviour, no risk). When ON, the buyer's single tx splits creator-net
	// to the seller and the fee to the treasury — exactly what confirmSkillPurchase
	// verifies — and the fee is persisted so the Pulse take-rate reads real on-chain fees.
	let feeAtomics = 0n;
	let feeWallet = null;
	try {
		const fee = await resolveMarketplaceFee({ grossAtomics: amountAtomic });
		if (fee?.feeAtomics > 0n && fee.recipient && fee.feeAtomics < amountAtomic) {
			feeAtomics = fee.feeAtomics;
			feeWallet = fee.recipient.toBase58();
		}
	} catch { /* fee is best-effort; a resolution miss never blocks the sale */ }
	const creatorAtomic = amountAtomic - feeAtomics;

	const { Keypair } = await import('@solana/web3.js');
	const referenceKp = Keypair.generate();
	const reference = referenceKp.publicKey.toBase58();

	const [pur] = await sql`
		insert into skill_purchases
			(user_id, agent_id, skill, status, reference, amount, currency_mint, chain, expires_at, kind,
			 platform_fee_amount, platform_fee_wallet)
		values
			(${buyer.userId}, ${listing.agent_id}, ${listing.skill}, 'pending', ${reference},
			 ${listing.amount}, ${THREE_MINT()}, 'solana', now() + interval '15 minutes', 'purchase',
			 ${feeAtomics.toString()}, ${feeWallet})
		returning id, user_id, agent_id, skill, status, amount, currency_mint, chain, reference, expires_at,
		          platform_fee_amount, platform_fee_wallet
	`;
	pur.mint_decimals = THREE_DECIMALS;

	const buyerKp = await senderKeypair(buyer, 'circulation_skill_purchase');
	let txSig;
	try {
		txSig = await transferThreeWithReference(
			conn, buyerKp, recipient, creatorAtomic, referenceKp.publicKey, network,
			feeAtomics > 0n ? { wallet: feeWallet, atomics: feeAtomics } : null,
		);
	} catch (e) {
		await sql`update skill_purchases set status = 'failed' where id = ${pur.id} and status = 'pending'`.catch(() => {});
		throw new Skip(`skill payment failed: ${e?.message?.slice(0, 160)}`);
	}

	const result = await confirmSkillPurchase({ ...pur, tx_signature: txSig, referrer_user_id: null });
	if (result.status !== 'confirmed') {
		throw new Skip(`skill purchase ${result.status}: ${(result.message || '').slice(0, 120)}`.trim());
	}

	const priceThree = Number(amountAtomic / 10n ** BigInt(THREE_DECIMALS));
	await recordCustodyEvent({
		agentId: buyer.id,
		userId: buyer.userId,
		eventType: 'spend',
		category: 'marketplace',
		network,
		asset: 'THREE',
		amountRaw: amountAtomic,
		destination: recipient,
		signature: txSig,
		status: 'confirmed',
		reason: 'skill_purchase',
		idempotencyKey: `skillbuy:${txSig}`,
		meta: { source: 'marketplace_skill', skill: listing.skill, seller: listing.seller_name, amount_three: priceThree, decimals: THREE_DECIMALS, to: recipient, block_time: new Date().toISOString() },
	}).catch((e) => console.warn('[circulation] custody event failed', e?.message));

	await logAction({ kind: 'buy_skill', network, actorAgentId: buyer.id, counterpartyAgentId: listing.agent_id, signature: txSig, detail: { skill: listing.skill, buyer: buyer.name, seller: listing.seller_name, amount_three: priceThree } });
	return { kind: 'buy_skill', buyer: buyer.name, seller: listing.seller_name, skill: listing.skill, three: priceThree, signature: txSig };
}

// A buyer agent starts a free trial on a trial-eligible listed skill. No payment —
// a real skill_purchases trial row, exactly like /api/marketplace/start-trial.
async function actionTrial(ctx) {
	const { pool } = ctx;
	const trialable = (await listedSkills()).filter((l) => (l.trial_uses || 0) > 0);
	if (!trialable.length) throw new Skip('no trial-eligible skills listed');
	const listing = pick(trialable);

	const candidates = pool.filter((a) => a.userId !== listing.seller_user_id && a.id !== listing.agent_id);
	if (!candidates.length) throw new Skip('no eligible trial taker');
	const taker = pick(candidates);

	const [blocked] = await sql`
		select 1 from skill_purchases
		where user_id = ${taker.userId} and agent_id = ${listing.agent_id} and skill = ${listing.skill}
		  and (status in ('confirmed','trial') or kind = 'trial') limit 1
	`;
	if (blocked) throw new Skip('taker already engaged this skill');

	const reference = randomUUID().replace(/-/g, '') + randomUUID().replace(/-/g, '');
	await sql`
		insert into skill_purchases
			(user_id, agent_id, skill, status, kind, reference, amount, currency_mint, chain, trial_remaining)
		values
			(${taker.userId}, ${listing.agent_id}, ${listing.skill}, 'trial', 'trial', ${reference},
			 ${listing.amount}, ${THREE_MINT()}, 'solana', ${listing.trial_uses})
	`;
	await logAction({ kind: 'trial', actorAgentId: taker.id, counterpartyAgentId: listing.agent_id, detail: { skill: listing.skill, taker: taker.name, seller: listing.seller_name } });
	return { kind: 'trial', taker: taker.name, seller: listing.seller_name, skill: listing.skill };
}

// A trial holder spends one of its remaining trial runs, through the same
// consumeTrialUse + logSkillUsage path a human-owned agent uses. Free: no chain
// write, so it runs even when the paid budget is zero.
//
// This is the only thing that drains trial_remaining for circulation agents.
// consumeTrialUse is otherwise reachable only from the x402 agent-action route,
// which these agents never call, so before this existed every trial sat at full
// count forever and blocked its holder from ever converting to a paid purchase.
async function actionUseTrial(ctx) {
	const { pool } = ctx;
	const byUser = new Map(pool.map((a) => [a.userId, a]));
	const userIds = [...byUser.keys()].filter(Boolean);
	if (!userIds.length) throw new Skip('no agents with accounts');

	const rows = await sql`
		select user_id, agent_id, skill, trial_remaining
		from skill_purchases
		where status = 'trial' and coalesce(trial_remaining, 0) > 0
		  and user_id = ANY(${userIds}::uuid[])
		order by random() limit 25
	`;
	if (!rows.length) throw new Skip('no active trial to use');

	const row = pick(rows);
	const actor = byUser.get(row.user_id);
	const remaining = await consumeTrialUse(row.user_id, row.agent_id, row.skill);
	// Null means another tick spent the last use between the select and the
	// update; that is ordinary contention, not a fault.
	if (remaining === null) throw new Skip('trial already spent');
	logSkillUsage({ userId: row.user_id, agentId: row.agent_id, skillName: row.skill });

	await logAction({
		kind: 'use_trial',
		actorAgentId: actor.id,
		counterpartyAgentId: row.agent_id,
		detail: { skill: row.skill, taker: actor.name, trial_remaining: remaining },
	});
	return { kind: 'use_trial', taker: actor.name, skill: row.skill, trial_remaining: remaining };
}

// A seller agent lists its 3D avatar as a purchasable asset (real asset_prices row,
// priced in $THREE). Registers the payout wallet so the asset can be bought.
async function actionListAsset() {
	const [row] = await sql`
		select ai.id as agent_id, ai.user_id, ai.name, ai.avatar_id, ai.meta
		from agent_identities ai
		where (ai.meta->>'circulation') = 'true' and ai.deleted_at is null
		  and ai.avatar_id is not null
		  and ai.meta->>'solana_address' is not null
		  and not exists (
			select 1 from asset_prices ap
			where ap.item_type = 'avatar' and ap.item_id = ai.avatar_id and ap.is_active = true
		  )
		order by random()
		limit 1
	`;
	if (!row) throw new Skip('no unlisted avatars to sell');

	const seller = { id: row.agent_id, userId: row.user_id, name: row.name, address: row.meta?.solana_address };
	await ensurePayoutWallet(seller);

	const priceWhole = randBetween(ASSET_PRICE_MIN_THREE, ASSET_PRICE_MAX_THREE);
	const amount = threeAtomic(priceWhole).toString();
	await sql`
		insert into asset_prices (item_type, item_id, owner_user_id, amount, currency_mint, chain, mint_decimals, is_active)
		values ('avatar', ${row.avatar_id}, ${row.user_id}, ${amount}, ${THREE_MINT()}, 'solana', ${THREE_DECIMALS}, true)
		on conflict (item_type, item_id) do update set
			amount = excluded.amount, currency_mint = excluded.currency_mint, chain = excluded.chain,
			mint_decimals = excluded.mint_decimals, owner_user_id = excluded.owner_user_id,
			is_active = true, updated_at = now()
	`;
	await logAction({ kind: 'list_asset', actorAgentId: row.agent_id, detail: { item: 'avatar', avatar_id: row.avatar_id, price_three: priceWhole, blurb: pick(ASSET_BLURBS), seller: row.name } });
	return { kind: 'list_asset', seller: row.name, avatar_id: row.avatar_id, price_three: priceWhole };
}

// A buyer agent purchases a listed avatar. Real $THREE SPL transfer tagged with the
// Solana-Pay reference, validated on-chain, then asset_purchases is confirmed and
// both sides notified — the same settlement the buy-asset endpoint performs.
async function actionBuyAsset(ctx) {
	const { conn, pool, network } = ctx;
	const listings = await sql`
		select ap.item_type, ap.item_id, ap.owner_user_id, ap.amount
		from asset_prices ap
		where ap.is_active = true and ap.currency_mint = ${THREE_MINT()} and ap.item_type = 'avatar'
		  and exists (
			select 1 from agent_identities ai
			where ai.user_id = ap.owner_user_id and (ai.meta->>'circulation') = 'true' and ai.deleted_at is null
		  )
	`;
	if (!listings.length) throw new Skip('no avatars listed for sale');
	const listing = pick(listings);

	const candidates = pool.filter((a) => a.userId !== listing.owner_user_id);
	if (!candidates.length) throw new Skip('no eligible buyer');
	const buyer = pick(candidates);

	const [owned] = await sql`
		select 1 from asset_purchases
		where buyer_user_id = ${buyer.userId} and item_type = 'avatar' and item_id = ${listing.item_id}
		  and status = 'confirmed' limit 1
	`;
	if (owned) throw new Skip('buyer already owns this avatar');

	const [payoutRow] = await sql`
		select address from agent_payout_wallets
		where user_id = ${listing.owner_user_id} and chain = 'solana' and is_default = true
		  and approved_at is not null and effective_at <= now()
		order by created_at asc limit 1
	`;
	const payout = payoutRow?.address;
	if (!payout) throw new Skip('seller payout wallet missing');

	const amountAtomic = BigInt(listing.amount);
	await ensureThree(ctx, buyer, amountAtomic);

	const { Keypair, PublicKey } = await import('@solana/web3.js');
	const { findReference, validateTransfer } = await import('@solana/pay');
	const BigNumber = (await import('bignumber.js')).default;

	const referenceKp = Keypair.generate();
	const reference = referenceKp.publicKey.toBase58();

	const [pur] = await sql`
		insert into asset_purchases
			(buyer_user_id, item_type, item_id, seller_user_id, status, reference,
			 amount, currency_mint, chain, payout_address, expires_at)
		values
			(${buyer.userId}, 'avatar', ${listing.item_id}, ${listing.owner_user_id}, 'pending', ${reference},
			 ${listing.amount}, ${THREE_MINT()}, 'solana', ${payout}, now() + interval '15 minutes')
		returning id
	`;

	const buyerKp = await senderKeypair(buyer, 'circulation_asset_purchase');
	let txSig;
	try {
		txSig = await transferThreeWithReference(conn, buyerKp, payout, amountAtomic, referenceKp.publicKey, network);
	} catch (e) {
		await sql`update asset_purchases set status = 'expired' where id = ${pur.id} and status = 'pending'`.catch(() => {});
		throw new Skip(`asset payment failed: ${e?.message?.slice(0, 160)}`);
	}

	const expected = new BigNumber(String(amountAtomic)).dividedBy(new BigNumber(10).pow(THREE_DECIMALS));
	try {
		await findReference(conn, referenceKp.publicKey, { finality: 'confirmed' });
		await validateTransfer(
			conn, txSig,
			{ recipient: new PublicKey(payout), amount: expected, splToken: new PublicKey(THREE_MINT()), reference: referenceKp.publicKey },
			{ commitment: 'confirmed' },
		);
	} catch (e) {
		throw new Skip(`asset transfer not validated: ${e?.message?.slice(0, 160)}`);
	}

	await sql`
		update asset_purchases set status = 'confirmed', tx_signature = ${txSig}, confirmed_at = now(), updated_at = now()
		where id = ${pur.id} and status = 'pending'
	`;
	const priceThree = Number(amountAtomic / 10n ** BigInt(THREE_DECIMALS));
	await insertNotification(listing.owner_user_id, 'asset_purchased', {
		item_type: 'avatar', item_id: listing.item_id, amount: String(listing.amount), currency_mint: THREE_MINT(), tx_signature: txSig, purchase_id: pur.id,
	}).catch(() => {});
	await insertNotification(buyer.userId, 'asset_purchase_confirmed', {
		item_type: 'avatar', item_id: listing.item_id, amount: String(listing.amount), currency_mint: THREE_MINT(), tx_signature: txSig, purchase_id: pur.id,
	}).catch(() => {});

	await recordCustodyEvent({
		agentId: buyer.id,
		userId: buyer.userId,
		eventType: 'spend',
		category: 'marketplace',
		network,
		asset: 'THREE',
		amountRaw: amountAtomic,
		destination: payout,
		signature: txSig,
		status: 'confirmed',
		reason: 'asset_purchase',
		idempotencyKey: `assetbuy:${txSig}`,
		meta: { source: 'marketplace_asset', item_type: 'avatar', amount_three: priceThree, decimals: THREE_DECIMALS, to: payout, block_time: new Date().toISOString() },
	}).catch((e) => console.warn('[circulation] custody event failed', e?.message));

	await logAction({ kind: 'buy_asset', network, actorAgentId: buyer.id, signature: txSig, detail: { item: 'avatar', avatar_id: listing.item_id, buyer: buyer.name, amount_three: priceThree } });
	return { kind: 'buy_asset', buyer: buyer.name, avatar_id: listing.item_id, three: priceThree, signature: txSig };
}

// Register an agent's on-chain (ERC-8004) identity. Funds the agent's EVM wallet
// for gas from the EVM treasury, pins an agent card, signs register(string), and
// confirms it through the platform's verify endpoint. Gated behind an EVM
// treasury secret — skipped cleanly when unset.
async function actionDeploy(ctx) {
	const { pool, origin, cfg } = ctx;
	if (!cfg.evmTreasurySecret) throw new Skip('EVM treasury not configured');

	const { Wallet, Contract, parseEther, formatEther } = await import('ethers');
	const { evmFallbackProvider } = await import('./evm/rpc.js');
	const chainId = cfg.evmChainId;
	const chain = CHAIN_BY_ID[chainId];
	if (!chain) throw new Skip(`unsupported EVM chain ${chainId}`);
	const registryAddr = chain.registry;

	// Pick an agent not yet registered on-chain.
	const candidates = pool.filter((a) => !a.meta?.onchain);
	const agent = candidates.length ? pick(candidates) : null;
	if (!agent) throw new Skip('all agents already deployed on-chain');

	const provider = await evmFallbackProvider(chainId);
	const treasury = new Wallet(cfg.evmTreasurySecret, provider);

	const { address: evmAddress } = await getOrCreateAgentEvmWallet(agent.id, { chainId });

	// Fund gas if the agent wallet is light.
	const bal = await provider.getBalance(evmAddress);
	const gasFloor = parseEther('0.00025');
	if (bal < gasFloor) {
		const tbal = await provider.getBalance(treasury.address);
		const topUp = gasFloor - bal;
		if (tbal < topUp + parseEther('0.0001')) throw new Skip(`EVM treasury low (${formatEther(tbal)} ETH)`);
		const fundTx = await treasury.sendTransaction({ to: evmAddress, value: topUp });
		await fundTx.wait();
	}

	// Build + pin the agent card the registry URI will resolve to.
	const card = await buildAgentCard(agent, origin);
	const pinned = await pinToIPFS(Buffer.from(JSON.stringify(card, null, 2)), 'agent.json').catch(() => null);
	const uri = pinned?.uri;
	if (!uri) throw new Skip('could not pin agent card');

	// Recover the agent's EVM key and register on-chain.
	const full = await loadAgentMeta(agent.id);
	const encKey = full?.meta?.encrypted_wallet_key;
	if (!encKey) throw new Skip('agent has no EVM key');
	const pkHex = await recoverAgentKey(encKey, { agentId: agent.id, userId: agent.userId, reason: 'circulation_deploy' });
	const signer = new Wallet(pkHex, provider);
	const registry = new Contract(
		registryAddr,
		['function register(string) returns (uint256)', 'event Registered(uint256 indexed agentId, string metadataURI, address indexed owner)'],
		signer,
	);
	const tx = await registry['register(string)'](uri);
	const receipt = await tx.wait();

	// Parse the Registered event for the assigned agent id.
	let onChainId = null;
	for (const lg of receipt.logs || []) {
		try {
			const parsed = registry.interface.parseLog(lg);
			if (parsed?.name === 'Registered') { onChainId = parsed.args[0].toString(); break; }
		} catch { /* not our event */ }
	}
	if (!onChainId) throw new Error('Registered event not found in receipt');

	// Confirm + bind through the platform endpoint (writes the on-chain index + badge).
	const confirm = await postAs(origin, agent.userId, '/api/erc8004/register-confirm', {
		chainId,
		txHash: receipt.hash,
		agentId: onChainId,
		metadataUri: uri,
		ownerAddress: evmAddress,
		agentDbId: agent.id,
	}, 30_000);
	if (confirm.status !== 200) throw new Error(`register-confirm ${confirm.status}: ${confirm.body?.error || 'failed'}`);

	await logAction({ kind: 'deploy', actorAgentId: agent.id, signature: receipt.hash, detail: { chainId, onChainId, agent: agent.name } });
	return { kind: 'deploy', agent: agent.name, chainId, onChainId, txHash: receipt.hash };
}

async function buildAgentCard(agent, origin) {
	let image = null;
	let glb = null;
	if (agent.avatarId) {
		const [av] = await sql`select storage_key, thumbnail_key from avatars where id = ${agent.avatarId} and deleted_at is null limit 1`;
		image = thumbnailUrl(av?.thumbnail_key);
		if (av?.storage_key) glb = r2PublicUrl(av.storage_key);
	}
	return {
		name: agent.name,
		description: agent.meta?.description || `${agent.name}, an autonomous agent on three.ws`,
		image: image || `${origin}/og.png`,
		url: `${origin}/agents/${agent.id}`,
		active: true,
		x402Support: true,
		services: glb ? [{ name: 'avatar', endpoint: glb, type: 'model/gltf-binary' }] : [],
	};
}

// ── tick orchestration ────────────────────────────────────────────────────────

// Choose the action mix for this tick. Launch/deploy are heavyweight and run
// solo. Everything else can batch up to actionsPerTick.
async function planActions(cfg, poolSize, budget = null) {
	const plan = [];
	// No affordable paid slots → don't even price the heavyweight solo actions;
	// they are the most expensive things the engine does.
	const paidAllowed = budget ? budget.paidBudget > 0 : true;
	const launchesToday = await recentCount('launch', '1 day');
	const deploysToday = await recentCount('deploy', '1 day');
	const launchesHour = await recentCount('launch', '45 minutes');

	// Heavyweight, low-frequency, solo actions get first refusal.
	const r = Math.random();
	if (paidAllowed && poolSize >= 2 && launchesHour === 0 && launchesToday < 8 && r < 0.14) {
		return ['launch'];
	}
	if (paidAllowed && cfg.evmTreasurySecret && poolSize >= 1 && deploysToday < 6 && r >= 0.14 && r < 0.2) {
		return ['deploy'];
	}

	// Bootstrap / replenish marketplace inventory first so there's always
	// something to buy. A seller lists skills until each agent averages a few
	// listings; avatars get listed at about half that rate.
	const [{ c: listedSkillCount }] = await sql`
		select count(*)::int as c from agent_skill_prices asp
		join agent_identities ai on ai.id = asp.agent_id
		where asp.is_active = true and asp.currency_mint = ${THREE_MINT()}
		  and (ai.meta->>'circulation') = 'true' and ai.deleted_at is null
	`;
	const [{ c: listedAssetCount }] = await sql`
		select count(*)::int as c from asset_prices ap
		where ap.is_active = true and ap.currency_mint = ${THREE_MINT()} and ap.item_type = 'avatar'
		  and exists (select 1 from agent_identities ai where ai.user_id = ap.owner_user_id and (ai.meta->>'circulation') = 'true')
	`;
	// Keep marketplace inventory ahead of demand — buy_skill is now the dominant
	// action, so each agent should average ~3 active listings so a buyer can always
	// find a fresh skill it doesn't already own.
	if (listedSkillCount < poolSize * 3) plan.push('list_skill');
	if (listedAssetCount < Math.floor(poolSize / 2)) plan.push('list_asset');

	// Fill the remaining budget with light actions (see LIGHT_ACTION_WEIGHTS).
	const weighted = LIGHT_ACTION_WEIGHTS;
	// Fill against the affordable budget: once the paid slots are used up, only
	// actions that cost nothing on-chain remain eligible, so a lean treasury
	// yields a quieter-but-live tick instead of a wall of guaranteed skips.
	let paidLeft = budget ? budget.paidBudget : cfg.actionsPerTick;
	while (plan.length < cfg.actionsPerTick) {
		const eligible = paidLeft > 0 ? weighted : weighted.filter(([kind]) => !COSTLY_ACTIONS.has(kind));
		if (!eligible.length) break;
		const total = eligible.reduce((s, [, w]) => s + w, 0);
		let roll = Math.random() * total;
		for (const [kind, w] of eligible) {
			roll -= w;
			if (roll <= 0) {
				plan.push(kind);
				if (COSTLY_ACTIONS.has(kind)) paidLeft -= 1;
				break;
			}
		}
	}
	return plan;
}

const ACTIONS = {
	tip: actionTip,
	payment: actionPayment,
	trade: actionTrade,
	launch: actionLaunch,
	review: actionReview,
	deploy: actionDeploy,
	list_skill: actionListSkill,
	buy_skill: actionBuySkill,
	trial: actionTrial,
	use_trial: actionUseTrial,
	list_asset: actionListAsset,
	buy_asset: actionBuyAsset,
};

/**
 * Run one activity tick. Safe to call on a schedule; fully inert unless enabled
 * and funded. Never throws — every failure is contained and reported.
 */
export async function runCirculationTick() {
	const cfg = config();
	if (!cfg.enabled) return { ok: true, skipped: 'disabled' };

	await ensureSchema();

	// Grow the pool toward target, up to growthPerTick new agents per tick so a
	// large target (hundreds–thousands) fills in a reasonable number of ticks.
	let pool = await loadPool();
	const grew = [];
	let createdAny = false;
	for (let i = 0; i < cfg.growthPerTick && pool.length + i < cfg.poolTarget; i++) {
		try {
			const r = await createPoolAgent();
			if (!r) break; // safety ceiling hit
			grew.push(r);
			if (r.created) createdAny = true;
		} catch (e) {
			console.warn('[circulation] pool growth failed', e?.message);
			break;
		}
	}
	if (createdAny) pool = await loadPool();

	if (pool.length < 2) {
		return { ok: true, pool: pool.length, grew, note: 'pool warming up' };
	}

	let treasuryKp;
	try {
		treasuryKp = await treasuryKeypair(cfg);
	} catch (e) {
		if (e instanceof Skip) return { ok: true, pool: pool.length, grew, skipped: e.message };
		throw e;
	}

	const conn = solanaConnection(cfg.network);
	let solUsd = null;
	try { solUsd = await solUsdPrice(); } catch { /* usd is decoration */ }

	// One treasury read per tick drives the governor. A failed read must not stall
	// the economy, so it degrades to "assume fundable" and the per-action
	// ensureFunded checks stay the backstop.
	let treasurySol = null;
	try {
		treasurySol = (await conn.getBalance(treasuryKp.publicKey)) / SOL;
	} catch (e) {
		console.warn('[circulation] treasury balance read failed', e?.message);
	}
	const budget = treasurySol === null
		? null
		: planBudget({ treasurySol, actionsPerTick: cfg.actionsPerTick });
	if (budget?.throttled) {
		console.warn('[circulation] throttled', {
			reason: budget.reason,
			treasury_sol: Number(treasurySol.toFixed(6)),
			paid_budget: budget.paidBudget,
			actions_per_tick: cfg.actionsPerTick,
		});
	}

	// What ONE paid action may draw this tick. The governor plans `paidBudget`
	// actions against `spendableSol`, so an action that can size its own spend
	// (the $THREE top-up) has to stay inside its share or it silently overspends
	// the estimate the budget was built from and starves the actions behind it.
	const perActionSolCap = budget && budget.paidBudget > 0
		? Math.max(THREE_TOPUP_SOL, roundSol(budget.spendableSol / budget.paidBudget))
		: THREE_TOPUP_SOL;

	const ctx = { conn, treasuryKp, pool, network: cfg.network, origin: cfg.origin, solUsd, cfg, perActionSolCap };
	const plan = await planActions(cfg, pool.length, budget);

	const results = [];
	for (const kind of plan) {
		const fn = ACTIONS[kind];
		if (!fn) continue;
		try {
			results.push({ ok: true, ...(await fn(ctx)) });
		} catch (e) {
			if (e instanceof Skip) {
				results.push({ ok: false, kind, skipped: e.message });
				await logAction({ kind, network: cfg.network, status: 'skipped', detail: { reason: e.message } });
			} else {
				console.error('[circulation] action failed', kind, e?.message);
				results.push({ ok: false, kind, error: e?.message });
				await logAction({ kind, network: cfg.network, status: 'error', detail: { error: e?.message?.slice(0, 300) } });
			}
		}
	}

	return {
		ok: true,
		pool: pool.length,
		grew,
		network: cfg.network,
		...(budget
			? {
				treasury_sol: Number(treasurySol.toFixed(6)),
				paid_budget: budget.paidBudget,
				...(budget.throttled ? { throttled: budget.reason } : {}),
			}
			: {}),
		actions: results,
	};
}