openzoo 0.51.4 → 0.51.6

package/transmute/lib/deploy.js

@@ -1,357 +0,0 @@
-// `deploy`: push a built `<out>/.zoo/` to a cluster.
-//
-//   detect SBPF arch (rebuild if the .so was built for another one)
-//   → deploy or upgrade the program (keypair kept at .zoo/program-keypair.json)
-//   → putAsset every static file
-//   → write the manifest as the /.zoo/manifest.json asset
-//
-// Mainnet is refused without `yes` after the cost table has been printed.
-import fs from 'node:fs';
-import path from 'node:path';
-import { Keypair, PublicKey } from '@solana/web3.js';
-import { MANIFEST_PATH, CODE_PATH } from './wire.js';
-import { connect, deployProgram, upgradeProgram, getProgramInfo, putAsset, detectSbpfArch, pool, assetRent } from './solana.js';
-import { initSite, getSiteInfo } from './solana.js';
-import { loadWallet, rpcUrl } from './wallet.js';
-import { runCargoBuildSbf, estimateCost, formatCostTable, LAMPORTS_PER_SOL, INSTALL_HINT } from './build.js';
-import { DEFAULT_PORT } from './gateway.js';
-
-export const MANIFEST_CONTENT_TYPE = 'application/json; charset=utf-8';
-
-function readJson(p, fallback) {
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) { if (fallback !== undefined) return fallback; throw new Error(`${p}: ${e.message}`); }
-}
-function writeJson(p, obj) { fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n'); }
-
-/** Accept the app dir, its `.zoo-out`, or the `.zoo` dir itself; return the out dir. */
-export function resolveOutDir(dir = '.') {
-  const d = path.resolve(dir);
-  const candidates = [d, path.join(d, '.zoo-out'), path.dirname(d)];
-  for (const c of candidates) if (fs.existsSync(path.join(c, '.zoo', 'manifest.json'))) return c;
-  throw new Error(`${d}: no .zoo/manifest.json here or in .zoo-out/; run \`openzoo-transmute build\` first`);
-}
-
-export function isMainnet(cluster, rpc) {
-  const c = String(cluster || process.env.OPENZOO_CLUSTER || 'mainnet');
-  if (/^(localnet|localhost|local|devnet|testnet)$/.test(c)) return false;
-  if (/^https?:\/\//.test(c)) return /mainnet/i.test(c) || /(fluxrpc|helius|triton|quiknode|alchemy|ankr)/i.test(c) && !/devnet|testnet/i.test(c);
-  return /mainnet/i.test(c) || /mainnet/i.test(rpc || '');
-}
-
-/** Genesis hashes of the public clusters: the one signal an RPC URL cannot disguise. */
-export const GENESIS_HASHES = {
-  mainnet: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',
-  devnet: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG',
-  testnet: '4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY',
-};
-
-/** Which public cluster the connection actually serves, by genesis hash; null for a local/unknown one or when unreachable. */
-export async function genesisCluster(connection) {
-  try {
-    const h = await connection.getGenesisHash();
-    for (const [name, hash] of Object.entries(GENESIS_HASHES)) if (h === hash) return name;
-  } catch { /* unreachable: the URL heuristic stands alone */ }
-  return null;
-}
-
-export function clusterLabel(cluster) {
-  const c = cluster || process.env.OPENZOO_CLUSTER || 'mainnet';
-  if (/^https?:\/\//.test(c)) return /127\.0\.0\.1|localhost/.test(c) ? 'localnet' : c;
-  return c;
-}
-
-/** Load or create the site's program keypair (kept next to the build so redeploys upgrade in place). */
-export function programKeypairFor(zooDir, { create = true } = {}) {
-  const p = path.join(zooDir, 'program-keypair.json');
-  if (fs.existsSync(p)) return { keypair: Keypair.fromSecretKey(Uint8Array.from(readJson(p))), path: p, created: false };
-  if (!create) return null;
-  const kp = Keypair.generate();
-  fs.writeFileSync(p, JSON.stringify([...kp.secretKey]), { mode: 0o600 });
-  return { keypair: kp, path: p, created: true };
-}
-
-/**
- * @param {{outDir?:string, cluster?:string, keypair?:string, programId?:string, yes?:boolean, concurrency?:number,
- *          log?:Function, connection?:object, wallet?:object, skipAssets?:boolean, force?:boolean, cargo?:string}} o
- * @returns {Promise<{programId:string, signature:string|null, signatures:object, assets:{uploaded:number,skipped:number,failed:number,txs:number},
- *          manifestPda:string, url:string, cluster:string, rpc:string, arch:string, upgraded:boolean, deployedAt:string}>}
- */
-export async function deploy(o = {}) {
-  const log = o.log ?? console.log;
-  const outDir = resolveOutDir(o.outDir || '.');
-  const zooDir = path.join(outDir, '.zoo');
-  const manifest = readJson(path.join(zooDir, 'manifest.json'));
-  const buildInfo = readJson(path.join(zooDir, 'build.json'), {});
-  const staticPlan = readJson(path.join(zooDir, 'static-plan.json'), []);
-  const crateDir = path.join(zooDir, 'crate');
-  if ((buildInfo.target || manifest.target) === 'shared') return deployShared(o, { log, outDir, zooDir, manifest, buildInfo, staticPlan });
-
-  const rpc = o.connection?.rpcEndpoint || rpcUrl(o.cluster);
-  const cluster = clusterLabel(o.cluster);
-  const connection = o.connection || connect(rpc);
-  // The URL heuristic can miss a private mainnet RPC; the genesis hash cannot. Never weakens the guard.
-  let mainnet = isMainnet(o.cluster, rpc);
-  const genesis = await genesisCluster(connection);
-  if (genesis === 'mainnet' && !mainnet) { mainnet = true; log(`note: ${rpc.replace(/\?.*$/, '')} serves mainnet (genesis hash); treating it as mainnet`); }
-  const wallet = o.wallet || loadWallet({ keypair: o.keypair });
-  const payer = wallet.keypair;
-  log(`cluster ${cluster} (${rpc.replace(/\?.*$/, '')}) · payer ${payer.publicKey.toBase58()}${wallet.path ? ` (${wallet.path})` : ''}`);
-
-  // 1. Which SBPF version does the cluster accept, and does the .so match?
-  const arch = await detectSbpfArch(connection);
-  let soPath = buildInfo.soPath && fs.existsSync(buildInfo.soPath) ? buildInfo.soPath : null;
-  const needsRebuild = !soPath || buildInfo.arch !== arch;
-  if (needsRebuild && !fs.existsSync(path.join(crateDir, 'Cargo.toml'))) throw new Error(`${crateDir}: no crate; run build first`);
-
-  // 2. Which program? --program <id> → upgrade that one; else the keypair next to the build.
-  let programId, programKeypair = null, upgrade = false;
-  if (o.programId) {
-    programId = new PublicKey(o.programId);
-    const info = await getProgramInfo(connection, programId);
-    if (!info.exists) {
-      const kp = programKeypairFor(zooDir, { create: false });
-      if (!kp || !kp.keypair.publicKey.equals(programId)) throw new Error(`program ${programId.toBase58()} does not exist on ${cluster} and its keypair is not at ${zooDir}/program-keypair.json`);
-      programKeypair = kp.keypair;
-    } else upgrade = true;
-  } else {
-    const kp = programKeypairFor(zooDir);
-    programKeypair = kp.keypair;
-    programId = kp.keypair.publicKey;
-    if (kp.created) log(`new program keypair → ${kp.path} (keep it: redeploys upgrade this program in place)`);
-    const info = await getProgramInfo(connection, programId);
-    upgrade = info.exists;
-    if (upgrade && info.authority && !info.authority.equals(payer.publicKey)) throw new Error(`program ${programId.toBase58()} exists but its upgrade authority is ${info.authority.toBase58()}, not the payer; pass --keypair for that wallet`);
-  }
-
-  // 3. Cost sheet + mainnet guard — before anything is built or spent. The
-  //    estimate uses the .so we have (a rebuild for another arch barely moves it).
-  const manifestOut = { ...manifest, programId: programId.toBase58(), cluster, rpc: rpc.replace(/\?.*$/, ''), arch, deployedAt: new Date().toISOString() };
-  const manifestBytes = Buffer.byteLength(JSON.stringify(manifestOut));
-  const knownSoSize = soPath ? fs.statSync(soPath).size : (buildInfo.soSize ?? null);
-  let est = await estimateCost({ staticFiles: staticPlan, soSize: knownSoSize, manifestBytes, connection, upgrade });
-  log('');
-  log(formatCostTable(est));
-  log('');
-  const balance = await connection.getBalance(payer.publicKey);
-  log(`${upgrade ? 'upgrade' : 'deploy'} ${programId.toBase58()} (${knownSoSize == null ? 'not built yet' : knownSoSize.toLocaleString() + ' B, ' + (needsRebuild ? `rebuilding for ${arch}` : arch)}) + ${staticPlan.length} asset(s); payer balance ${(balance / LAMPORTS_PER_SOL).toFixed(4)} SOL`);
-  if (mainnet && !o.yes) throw new Error(`refusing to touch mainnet without --yes (estimated ${est.totalSol.toFixed(4)} SOL locked as rent)`);
-
-  // 4. Rebuild for the cluster's arch if needed, then check the balance against the real size.
-  if (needsRebuild) {
-    log(soPath ? `built for ${buildInfo.arch}, cluster wants ${arch}: rebuilding` : `no .so in ${zooDir}; building for ${arch}`);
-    const r = await runCargoBuildSbf(crateDir, { arch, outDir: path.join(zooDir, 'deploy'), log, cargo: o.cargo });
-    if (!r.ok) throw new Error(r.missing ? `cargo-build-sbf is not installed; install with: ${INSTALL_HINT}` : `cargo build-sbf failed: ${r.error}`);
-    soPath = r.soPath;
-    writeJson(path.join(zooDir, 'build.json'), { ...buildInfo, arch, soPath, soSize: fs.statSync(soPath).size, builtAt: new Date().toISOString() });
-  }
-  const so = fs.readFileSync(soPath);
-  if (so.length !== knownSoSize) est = await estimateCost({ staticFiles: staticPlan, soSize: so.length, manifestBytes, connection, upgrade });
-  if (balance < est.totalLamports) throw new Error(`insufficient balance: ${(balance / LAMPORTS_PER_SOL).toFixed(4)} SOL < ${est.totalSol.toFixed(4)} SOL needed${mainnet ? '' : ' (airdrop: solana airdrop 10 --url ' + rpc + ')'}`);
-
-  // 5. Program.
-  const signatures = {};
-  let progress = 0;
-  const onProgress = (d, n) => { if (d === n || d - progress >= Math.max(1, Math.floor(n / 10))) { progress = d; log(`  program bytes ${d}/${n} chunks`); } };
-  const t0 = Date.now();
-  if (upgrade) {
-    const r = await upgradeProgram(connection, { payer, programId, so, onProgress }).catch((e) => {
-      if (/exceeds the program's max data len/.test(String(e?.message))) throw new Error(`${e.message}; to deploy a fresh program remove ${path.join(zooDir, 'program-keypair.json')} and run deploy again`);
-      throw e;
-    });
-    signatures.program = r.signature;
-    log(`upgraded ${programId.toBase58()} in ${((Date.now() - t0) / 1000).toFixed(1)}s (${r.signature})`);
-  } else {
-    const r = await deployProgram(connection, { payer, programKeypair, so, onProgress, headroom: o.headroom ? Number(o.headroom) : 1 });
-    signatures.program = r.signature;
-    log(`deployed ${programId.toBase58()} in ${((Date.now() - t0) / 1000).toFixed(1)}s (${r.signature}); max data len ${r.maxDataLen.toLocaleString()} B`);
-  }
-
-  // 6. Assets.
-  const assets = { uploaded: 0, skipped: 0, failed: 0, txs: 0 };
-  const failures = [];
-  if (!o.skipAssets) {
-    const t1 = Date.now();
-    let done = 0;
-    await pool(staticPlan, async (f) => {
-      const label = `[${String(++done).padStart(String(staticPlan.length).length)}/${staticPlan.length}] ${f.path}`;
-      if (!f.file || !fs.existsSync(f.file)) { assets.failed++; failures.push(`${f.path}: source file missing (${f.file})`); log(`${label} MISSING ${f.file}`); return; }
-      const data = fs.readFileSync(f.file);
-      try {
-        const r = await putAsset(connection, { authority: payer, programId, path: f.path, contentType: f.contentType || 'application/octet-stream', data, force: o.force });
-        if (r.skipped) { assets.skipped++; log(`${label} unchanged (${data.length.toLocaleString()} B)`); }
-        else { assets.uploaded++; assets.txs += r.txs; log(`${label} ${data.length.toLocaleString()} B in ${r.txs} tx`); }
-      } catch (e) {
-        assets.failed++; failures.push(`${f.path}: ${e?.message || e}`); log(`${label} FAILED ${String(e?.message || e).split('\n')[0]}`);
-      }
-    }, { concurrency: o.concurrency || 4 });
-    log(`assets: ${assets.uploaded} uploaded, ${assets.skipped} unchanged, ${assets.failed} failed in ${((Date.now() - t1) / 1000).toFixed(1)}s`);
-  }
-
-  // 7. Manifest (always rewritten: it carries deployedAt).
-  const mr = await putAsset(connection, { authority: payer, programId, path: MANIFEST_PATH, contentType: MANIFEST_CONTENT_TYPE, data: Buffer.from(JSON.stringify(manifestOut)), force: true });
-  const manifestPda = mr.pda.toBase58();
-  log(`manifest → ${MANIFEST_PATH} (${manifestPda}, ${manifestBytes.toLocaleString()} B)`);
-
-  const url = `http://127.0.0.1:${DEFAULT_PORT}/`;
-  const result = {
-    programId: programId.toBase58(), signature: signatures.program || null, signatures, assets, manifestPda, url,
-    cluster, rpc, arch, upgraded: upgrade, deployedAt: manifestOut.deployedAt, failures,
-  };
-  writeJson(path.join(zooDir, 'deploy.json'), { ...result, payer: payer.publicKey.toBase58() });
-  log('');
-  log(`serve it:  openzoo-transmute serve ${programId.toBase58()} --cluster ${cluster}${wallet.path ? ` --keypair ${wallet.path}` : ''}`);
-  log(`then open  ${url}  (explorer at ${url}.zoo/)`);
-  if (failures.length) throw Object.assign(new Error(`${failures.length} asset(s) failed to upload:\n  ${failures.join('\n  ')}`), { result });
-  return result;
-}
-
-/** Rent one asset of `size` bytes would lock on this cluster, in SOL. */
-export async function assetRentSol(connection, size, contentType = '') {
-  return (await assetRent(connection, size, contentType)) / LAMPORTS_PER_SOL;
-}
-
-// ---------------------------------------------------------------- shared runtime
-
-/** Load or create the site keypair: its public key is the site id (looks like a program id, costs nothing). */
-export function siteKeypairFor(zooDir, { create = true } = {}) {
-  const p = path.join(zooDir, 'site-keypair.json');
-  if (fs.existsSync(p)) return { keypair: Keypair.fromSecretKey(Uint8Array.from(readJson(p))), path: p, created: false };
-  if (!create) return null;
-  const kp = Keypair.generate();
-  fs.writeFileSync(p, JSON.stringify([...kp.secretKey]), { mode: 0o600 });
-  return { keypair: kp, path: p, created: true };
-}
-
-/**
- * Deploy to the shared runtime: no program, only accounts — the site account,
- * the bytecode module at /.zoo/code.bin, the static assets and the manifest,
- * all PDAs of the runtime program namespaced by the site id.
- */
-async function deployShared(o, { log, outDir, zooDir, manifest, buildInfo, staticPlan }) {
-  const runtime = o.runtime || process.env.OPENZOO_VM_PROGRAM || manifest.runtime || buildInfo.runtime;
-  if (!runtime) throw new Error('shared target needs the runtime program id: --runtime <id> (or OPENZOO_VM_PROGRAM)');
-  const rpc = o.connection?.rpcEndpoint || rpcUrl(o.cluster);
-  const cluster = clusterLabel(o.cluster);
-  const connection = o.connection || connect(rpc);
-  let mainnet = isMainnet(o.cluster, rpc);
-  const genesis = await genesisCluster(connection);
-  if (genesis === 'mainnet' && !mainnet) { mainnet = true; log(`note: ${rpc.replace(/\?.*$/, '')} serves mainnet (genesis hash); treating it as mainnet`); }
-  const wallet = o.wallet || loadWallet({ keypair: o.keypair });
-  const payer = wallet.keypair;
-  const codePath = buildInfo.codePath && fs.existsSync(buildInfo.codePath) ? buildInfo.codePath : path.join(zooDir, 'code.bin');
-  if (!fs.existsSync(codePath)) throw new Error(`no bytecode module at ${codePath}; run build --target shared first`);
-  const code = fs.readFileSync(codePath);
-  const siteKp = o.site ? null : siteKeypairFor(zooDir);
-  const site = o.site ? new PublicKey(o.site) : siteKp.keypair.publicKey;
-  const runtimeInfo = await getProgramInfo(connection, runtime);
-  if (!runtimeInfo.exists) throw new Error(`runtime program ${runtime} is not deployed on ${cluster}`);
-  log(`cluster ${cluster} (${rpc.replace(/\?.*$/, '')}) · payer ${payer.publicKey.toBase58()} · runtime ${new PublicKey(runtime).toBase58()} · site ${site.toBase58()}${siteKp?.created ? ' (new)' : ''}`);
-
-  // Cost: site account + code + assets + manifest, all rent-exempt accounts.
-  const manifestOut = { ...manifest, target: 'shared', runtime: new PublicKey(runtime).toBase58(), site: site.toBase58(), cluster, rpc: rpc.replace(/\?.*$/, ''), deployedAt: new Date().toISOString() };
-  const manifestBytes = Buffer.byteLength(JSON.stringify(manifestOut));
-  const items = [{ label: 'site account', bytes: 66 }, { label: `code module (${code.length.toLocaleString()} B)`, bytes: code.length + 20 }];
-  for (const f of staticPlan) items.push({ label: f.path, bytes: (f.size ?? 0) + 7 + (f.contentType || '').length });
-  items.push({ label: '/.zoo/manifest.json', bytes: manifestBytes + 40 });
-  let total = 0;
-  for (const it of items) { it.lamports = await connection.getMinimumBalanceForRentExemption(it.bytes); total += it.lamports; }
-  const fees = 5000 * (3 + staticPlan.length * 3 + Math.ceil(code.length / 900) + 4);
-  log('  item                                bytes       SOL');
-  for (const it of items) log(`  ${it.label.padEnd(34)}${String(it.bytes).padStart(8)}  ${(it.lamports / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
-  log(`  ${'rent total'.padEnd(34)}${''.padStart(8)}  ${(total / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
-  log(`  ${'+ tx fees (approx.)'.padEnd(34)}${''.padStart(8)}  ${(fees / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
-  log(`  ${'TOTAL'.padEnd(34)}${''.padStart(8)}  ${((total + fees) / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
-  if (mainnet && !o.yes) throw new Error('this is mainnet: pass --yes to spend the amount above');
-  const balance = await connection.getBalance(payer.publicKey);
-  if (balance < total + fees) throw new Error(`payer has ${(balance / LAMPORTS_PER_SOL).toFixed(4)} SOL, needs ~${((total + fees) / LAMPORTS_PER_SOL).toFixed(4)}`);
-
-  const t0 = Date.now();
-  const si = await initSite(connection, { authority: payer, runtime, site });
-  log(`${si.created ? 'created' : 'reusing'} site account ${si.pda.toBase58()}`);
-  const cr = await putAsset(connection, { authority: payer, programId: runtime, site, path: CODE_PATH, contentType: 'application/x-zoo-bytecode', data: code, force: o.force });
-  log(`code → ${CODE_PATH} (${cr.pda.toBase58()}, ${code.length.toLocaleString()} B${cr.skipped ? ', unchanged' : ''})`);
-  let uploaded = 0, skipped = 0, failed = 0;
-  const failures = [];
-  if (!o.skipAssets) {
-    const files = staticPlan.filter((f) => f.file || f.path);
-    let done = 0;
-    await pool(files, async (f) => {
-      try {
-        const data = fs.readFileSync(f.file);
-        const r = await putAsset(connection, { authority: payer, programId: runtime, site, path: f.path, contentType: f.contentType || 'application/octet-stream', data, force: o.force });
-        if (r.skipped) skipped++; else uploaded++;
-        log(`[${++done}/${files.length}] ${f.path} ${r.skipped ? 'unchanged' : `${data.length.toLocaleString()} B in ${r.txs} tx`}`);
-      } catch (e) { failed++; failures.push({ path: f.path, error: String(e?.message || e) }); log(`[${++done}/${files.length}] ${f.path} FAILED: ${e?.message || e}`); }
-    }, { concurrency: o.concurrency ? Number(o.concurrency) : 4 });
-    log(`assets: ${uploaded} uploaded, ${skipped} unchanged, ${failed} failed`);
-  }
-  const mr = await putAsset(connection, { authority: payer, programId: runtime, site, path: MANIFEST_PATH, contentType: MANIFEST_CONTENT_TYPE, data: Buffer.from(JSON.stringify(manifestOut)), force: true });
-  log(`manifest → ${MANIFEST_PATH} (${mr.pda.toBase58()}, ${manifestBytes.toLocaleString()} B) in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
-  const out = { target: 'shared', site: site.toBase58(), programId: site.toBase58(), runtime: new PublicKey(runtime).toBase58(), sitePda: si.pda.toBase58(), manifestPda: mr.pda.toBase58(), assets: { uploaded, skipped, failed }, cluster, rpc, deployedAt: manifestOut.deployedAt, failures, url: `${process.env.OPENZOO_HUB_URL || 'https://sites.openzoo.fun'}/s/${site.toBase58()}` };
-  writeJson(path.join(zooDir, 'deploy.json'), out);
-  log(`\nserve it:  openzoo-transmute serve ${site.toBase58()} --runtime ${new PublicKey(runtime).toBase58()} --cluster ${cluster}`);
-  log(`or open    ${out.url}`);
-  return out;
-}
-
-// ---------------------------------------------------------------- runtime program
-
-const HERE_DEPLOY = path.dirname(new URL(import.meta.url).pathname);
-export const PREBUILT_DIR = path.resolve(HERE_DEPLOY, '..', 'prebuilt');
-export const RUNTIME_CRATE = path.resolve(HERE_DEPLOY, '..', 'runtime', 'zoo-vm');
-
-/** The zoo-vm .so for an SBPF arch: prebuilt (v0 = mainnet) or built from runtime/zoo-vm. */
-export async function runtimeSoFor(arch, { log = console.log, so } = {}) {
-  if (so) return { soPath: path.resolve(so), source: 'given' };
-  const pre = path.join(PREBUILT_DIR, `zoo_vm.${arch}.so`);
-  if (fs.existsSync(pre)) return { soPath: pre, source: 'prebuilt' };
-  if (!fs.existsSync(path.join(RUNTIME_CRATE, 'Cargo.toml'))) throw new Error(`no prebuilt zoo-vm for ${arch} (${pre}) and no runtime/zoo-vm crate to build it from`);
-  const r = await runCargoBuildSbf(RUNTIME_CRATE, { arch, outDir: path.join(RUNTIME_CRATE, 'target', 'deploy-' + arch), log });
-  if (!r.ok) throw new Error(r.missing ? `no prebuilt zoo-vm for ${arch}; install the toolchain to build it: ${INSTALL_HINT}` : `zoo-vm build failed: ${r.error}`);
-  return { soPath: r.soPath, source: 'built' };
-}
-
-/**
- * Deploy (or upgrade) the shared runtime program once per cluster. Sites then
- * cost only their accounts. Keypair kept at `programKeypair` (default
- * ./zoo-vm-keypair.json) so a redeploy upgrades in place.
- */
-export async function deployRuntime(o = {}) {
-  const log = o.log ?? console.log;
-  const rpc = rpcUrl(o.cluster);
-  const cluster = clusterLabel(o.cluster);
-  const connection = o.connection || connect(rpc);
-  let mainnet = isMainnet(o.cluster, rpc);
-  if ((await genesisCluster(connection)) === 'mainnet') mainnet = true;
-  const wallet = o.wallet || loadWallet({ keypair: o.keypair });
-  const payer = wallet.keypair;
-  const arch = await detectSbpfArch(connection);
-  const { soPath, source } = await runtimeSoFor(arch, { log, so: o.so });
-  const so = fs.readFileSync(soPath);
-  const kpPath = path.resolve(o.programKeypair || 'zoo-vm-keypair.json');
-  let programKeypair;
-  if (fs.existsSync(kpPath)) programKeypair = Keypair.fromSecretKey(Uint8Array.from(readJson(kpPath)));
-  else { programKeypair = Keypair.generate(); fs.writeFileSync(kpPath, JSON.stringify([...programKeypair.secretKey]), { mode: 0o600 }); log(`new runtime keypair → ${kpPath} (keep it: redeploys upgrade in place)`); }
-  const programId = programKeypair.publicKey;
-  const info = await getProgramInfo(connection, programId);
-  const upgrade = info.exists;
-  const est = await estimateCost({ staticFiles: [], soSize: so.length, manifestBytes: 0, connection, upgrade });
-  est.items = est.items.filter((i) => i.kind !== 'asset');
-  est.lamports = est.items.filter((i) => !i.transient).reduce((n, i) => n + i.lamports, 0); est.sol = est.lamports / LAMPORTS_PER_SOL;
-  est.totalLamports = est.lamports + est.transientLamports + est.feeLamports; est.totalSol = est.totalLamports / LAMPORTS_PER_SOL;
-  log(`cluster ${cluster} (${rpc.replace(/\?.*$/, '')}) · payer ${payer.publicKey.toBase58()} · runtime ${programId.toBase58()} (${upgrade ? 'upgrade' : 'new'}) · ${path.basename(soPath)} ${so.length.toLocaleString()} B ${arch} (${source})`);
-  log(formatCostTable(est));
-  const bal = await connection.getBalance(payer.publicKey);
-  if (bal < est.totalLamports) throw new Error(`payer has ${(bal / LAMPORTS_PER_SOL).toFixed(4)} SOL, needs ≈ ${est.totalSol.toFixed(4)} SOL`);
-  if (mainnet && !o.yes) throw new Error(`refusing to spend ≈ ${est.totalSol.toFixed(4)} SOL on mainnet without --yes`);
-  let done = 0; const total = Math.ceil(so.length / 900);
-  const onProgress = (n) => { done += 1; if (done % 25 === 0 || done === total) log(`  wrote ${Math.min(done, total)}/${total} chunks`); };
-  const t0 = Date.now();
-  const r = upgrade
-    ? await upgradeProgram(connection, { payer, programId, so, onProgress })
-    : await deployProgram(connection, { payer, programKeypair, so, onProgress, headroom: o.headroom ? Number(o.headroom) : 1 });
-  log(`${upgrade ? 'upgraded' : 'deployed'} runtime ${programId.toBase58()} in ${((Date.now() - t0) / 1000).toFixed(1)}s (${r.signature})`);
-  log(`\nsites now deploy against it:  openzoo-transmute build <dir> --target shared && openzoo-transmute deploy <dir> --runtime ${programId.toBase58()} --cluster ${cluster}`);
-  log(`hub: OPENZOO_VM_PROGRAM=${programId.toBase58()}`);
-  return { programId: programId.toBase58(), signature: r.signature, upgrade, arch, soPath, cluster, rpc, keypairPath: kpPath };
-}

package/transmute/lib/eligibility.js

@@ -1,211 +0,0 @@
-// Eligibility rules: which Lambdas can be re-hosted on chain, and why not.
-//
-// A handler is eligible when everything it does can be expressed in the
-// zoo-host subset: pure computation over JS values, the request/response
-// bridge, `@vercel/kv`, the baked environment table and the cluster clock.
-// Anything that reaches outside the transaction (network, filesystem,
-// timers, randomness) or outside the subset (classes, generators, regex)
-// makes the whole function ineligible; the reason carries `file:line` so the
-// user can fix or exclude it.
-import path from 'node:path';
-
-export class Ineligible extends Error {
-  constructor(reason, { file = null, line = null, node = null } = {}) {
-    super(reason);
-    this.name = 'Ineligible';
-    this.reason = reason;
-    this.file = file;
-    this.line = line ?? node?.loc?.start?.line ?? null;
-  }
-  toJSON() {
-    return { reason: this.reason, file: this.file, line: this.line };
-  }
-  /** "reason (file:line)" */
-  describe() {
-    const where = this.file ? ` (${this.file}${this.line ? ':' + this.line : ''})` : this.line ? ` (line ${this.line})` : '';
-    return this.reason + where;
-  }
-}
-
-/** Throw an Ineligible for an AST node. */
-export function ineligible(reason, node, file) {
-  return new Ineligible(reason, { file, node });
-}
-
-// ---------------------------------------------------------------- imports
-
-/**
- * Module specifiers we know how to bind. Each entry maps an imported name to
- * a "special" the lowering understands, or `null` for names that are types /
- * inert at runtime (safe to ignore).
- */
-export const ALLOWED_IMPORTS = {
-  '@vercel/kv': { kv: 'Kv', default: 'Kv', createClient: 'KvFactory', VercelKV: null },
-  'next/server': { NextResponse: 'NextResponse', NextRequest: null, userAgent: 'ineligible:userAgent() reads the request UA table, which is not available on chain', after: 'ineligible:after() schedules work past the response; there is no "after" on chain' },
-  'next': { NextApiRequest: null, NextApiResponse: null, NextApiHandler: null, PageConfig: null, GetServerSideProps: null },
-  'next/types': { '*': null },
-  '@vercel/node': { VercelRequest: null, VercelResponse: null, VercelApiHandler: null },
-  '@vercel/edge': { '*': 'ineligible:@vercel/edge helpers (geolocation/ipAddress/rewrite) read edge-network state that does not exist on chain' },
-  '@vercel/functions': { '*': 'ineligible:@vercel/functions (waitUntil/geolocation/ipAddress) is not available on chain: nothing runs after the transaction' },
-  'next/headers': { '*': 'ineligible:next/headers (cookies()/headers()) is not supported yet; read request.headers / request.cookies instead' },
-  'next/navigation': { '*': 'ineligible:next/navigation is a rendering API, not a route API' },
-  'next/cache': { '*': 'ineligible:next/cache (revalidatePath/revalidateTag/unstable_cache) has no meaning on chain' },
-};
-
-/** Resolve one import. Returns [{local, special|null}] or throws Ineligible. */
-export function bindImport(source, specifiers, { file, line } = {}) {
-  const where = { file, line };
-  if (source.startsWith('.') || source.startsWith('/') || source.startsWith('@/') || source.startsWith('~/')) {
-    throw new Ineligible(`import of local module \`${source}\`: local imports are not transmuted yet; inline the helper into the route file`, where);
-  }
-  if (source.startsWith('node:') || NODE_BUILTINS.has(source)) {
-    throw new Ineligible(`import of Node built-in \`${source}\`: no filesystem, network, crypto or process access on chain`, where);
-  }
-  const table = ALLOWED_IMPORTS[source];
-  if (!table) {
-    throw new Ineligible(`import of \`${source}\`: only @vercel/kv, next/server, and the next / @vercel/node types can be used on chain`, where);
-  }
-  const out = [];
-  for (const s of specifiers) {
-    const imported = s.imported === undefined ? 'default' : s.imported;
-    let special;
-    if (imported === '*') {
-      special = { t: 'Namespace', source };
-    } else {
-      const entry = imported in table ? table[imported] : table['*'];
-      if (entry === undefined) {
-        throw new Ineligible(`\`${imported}\` is not a known export of ${source} (supported: ${Object.keys(table).filter((k) => k !== '*').join(', ')})`, where);
-      }
-      if (typeof entry === 'string' && entry.startsWith('ineligible:')) {
-        throw new Ineligible(entry.slice('ineligible:'.length), where);
-      }
-      special = entry ? { t: entry } : null;
-    }
-    out.push({ local: s.local, imported, special });
-  }
-  return out;
-}
-
-export const NODE_BUILTINS = new Set([
-  'fs', 'fs/promises', 'path', 'os', 'http', 'https', 'net', 'dns', 'crypto', 'child_process', 'stream', 'util', 'url', 'zlib',
-  'events', 'buffer', 'querystring', 'readline', 'worker_threads', 'cluster', 'tls', 'dgram', 'assert', 'module', 'process', 'timers',
-  'timers/promises', 'string_decoder', 'perf_hooks', 'async_hooks', 'vm', 'v8', 'inspector', 'tty', 'punycode', 'constants', 'sys',
-]);
-
-// ---------------------------------------------------------------- globals
-
-/** Free identifiers that are meaningful on chain. Everything else is unknown. */
-export const KNOWN_GLOBALS = new Set([
-  'undefined', 'NaN', 'Infinity', 'Math', 'JSON', 'Object', 'Array', 'Number', 'String', 'Boolean', 'parseInt', 'parseFloat',
-  'isNaN', 'isFinite', 'encodeURIComponent', 'decodeURIComponent', 'encodeURI', 'decodeURI', 'Date', 'Error', 'TypeError',
-  'RangeError', 'SyntaxError', 'console', 'process', 'Response', 'URL', 'Promise', 'Request', 'Headers', 'globalThis',
-]);
-
-/** Free identifiers with a specific reason for being unavailable. */
-export const BANNED_GLOBALS = {
-  fetch: 'fetch(): network access is not available on chain (a Solana instruction cannot make HTTP requests)',
-  require: 'require(): dynamic module loading is not available on chain',
-  setTimeout: 'setTimeout: timers are not available on chain (instructions are synchronous)',
-  setInterval: 'setInterval: timers are not available on chain',
-  setImmediate: 'setImmediate: timers are not available on chain',
-  queueMicrotask: 'queueMicrotask: no event loop on chain',
-  Buffer: 'Buffer is not available on chain; work with strings and arrays',
-  crypto: 'crypto / Web Crypto is not available on chain',
-  TextEncoder: 'TextEncoder is not available on chain',
-  TextDecoder: 'TextDecoder is not available on chain',
-  XMLHttpRequest: 'XMLHttpRequest: network access is not available on chain',
-  WebSocket: 'WebSocket: network access is not available on chain',
-  window: '`window` does not exist in a Lambda',
-  document: '`document` does not exist in a Lambda',
-  eval: 'eval() is not supported',
-  Function: 'the Function constructor is not supported',
-  Map: 'Map is not supported on chain; use a plain object',
-  Set: 'Set is not supported on chain; use an array',
-  WeakMap: 'WeakMap is not supported on chain',
-  WeakSet: 'WeakSet is not supported on chain',
-  Symbol: 'Symbol is not supported on chain',
-  Proxy: 'Proxy is not supported on chain',
-  Reflect: 'Reflect is not supported on chain',
-  RegExp: 'regular expressions are not supported on chain',
-  Intl: 'Intl is not available on chain',
-  BigInt: 'BigInt is not supported on chain (numbers are f64)',
-  ArrayBuffer: 'typed arrays / ArrayBuffer are not supported on chain',
-  Uint8Array: 'typed arrays are not supported on chain',
-  Int32Array: 'typed arrays are not supported on chain',
-  Float64Array: 'typed arrays are not supported on chain',
-  DataView: 'DataView is not supported on chain',
-  structuredClone: 'structuredClone is not available on chain; use JSON.parse(JSON.stringify(x))',
-  FormData: 'FormData is not supported on chain; send JSON',
-  Blob: 'Blob is not supported on chain',
-  File: 'File is not supported on chain',
-  ReadableStream: 'streaming responses are not supported on chain',
-  WritableStream: 'streaming responses are not supported on chain',
-  TransformStream: 'streaming responses are not supported on chain',
-  AbortController: 'AbortController is not available on chain',
-  performance: 'performance.now() is not available on chain; use Date.now()',
-  navigator: '`navigator` does not exist in a Lambda',
-  atob: 'base64 helpers are not available on chain yet',
-  btoa: 'base64 helpers are not available on chain yet',
-  WebAssembly: 'WebAssembly is not available on chain',
-  URLSearchParams: 'constructing URLSearchParams is not supported yet; read request.nextUrl.searchParams / req.query',
-  Headers: 'constructing Headers is not supported; pass a plain object as `headers` in the Response init',
-  Request: 'constructing a Request is not supported on chain',
-};
-
-/** Method names the on-chain `Val::call` implements (union over receiver types). */
-export const RUNTIME_METHODS = new Set([
-  // strings
-  'toUpperCase', 'toLowerCase', 'trim', 'trimStart', 'trimEnd', 'includes', 'startsWith', 'endsWith', 'indexOf', 'split', 'slice',
-  'substring', 'substr', 'charAt', 'charCodeAt', 'replace', 'replaceAll', 'repeat', 'padStart', 'padEnd', 'toString', 'valueOf',
-  'concat', 'at',
-  // arrays
-  'push', 'pop', 'shift', 'unshift', 'join', 'splice', 'reverse', 'flat', 'map', 'filter', 'find', 'findIndex', 'some', 'every',
-  'forEach', 'reduce', 'flatMap', 'sort',
-  // numbers
-  'toFixed',
-  // objects
-  'hasOwnProperty',
-]);
-export const CALLBACK_METHODS = new Set(['map', 'filter', 'find', 'findIndex', 'some', 'every', 'forEach', 'reduce', 'flatMap', 'sort']);
-export const MUTATING_METHODS = new Set(['push', 'pop', 'shift', 'unshift', 'splice', 'reverse', 'sort']);
-
-/** `Math.*` the runtime implements. */
-export const MATH_FUNCS = new Set(['floor', 'ceil', 'round', 'trunc', 'abs', 'sqrt', 'pow', 'sign', 'log', 'log2', 'log10', 'exp', 'sin', 'cos', 'tan', 'atan2', 'min', 'max', 'hypot']);
-export const MATH_CONSTS = { PI: Math.PI, E: Math.E, LN2: Math.LN2, LN10: Math.LN10, LOG2E: Math.LOG2E, LOG10E: Math.LOG10E, SQRT2: Math.SQRT2, SQRT1_2: Math.SQRT1_2 };
-export const GLOBAL_FUNCS = new Set(['Number', 'String', 'Boolean', 'isNaN', 'isFinite', 'parseFloat', 'parseInt', 'encodeURIComponent', 'encodeURI', 'decodeURIComponent', 'decodeURI']);
-
-/** `kv.<method>` → runtime call. Anything else is ineligible. */
-export const KV_METHODS = {
-  get: 'kv_get', set: 'kv_set', incr: 'kv_incr', incrby: 'kv_incrby', decr: 'kv_decr', decrby: 'kv_decrby', del: 'kv_del', exists: 'kv_exists',
-};
-
-// ---------------------------------------------------------------- function metadata
-
-/** Reasons that come from the Lambda's config rather than its code. `null` when fine. */
-export function functionMetaReason(fn) {
-  if (fn.middleware) return 'middleware runs before routing on the edge network; the gateway serves routes directly, so middleware is not transmuted';
-  if (fn.supportsResponseStreaming) return 'streaming responses (supportsResponseStreaming) are not possible: an instruction answers once';
-  if (fn.prerender) return 'ISR / prerender config: this function is a rendered page cache, not an API handler';
-  if (fn.runtime && fn.runtime !== 'edge' && !/^nodejs\d+\.x$/.test(fn.runtime)) return `runtime \`${fn.runtime}\` is not JavaScript; only nodejs*.x and edge Lambdas are transmuted`;
-  if (!fn.sourceFile) return 'no source file for this function';
-  return null;
-}
-
-/** Non-blocking warnings for the whole deployment. */
-export function deploymentWarnings(deployment) {
-  const out = [];
-  for (const c of deployment.crons || []) out.push(`cron \`${c.schedule || '?'}\` → ${c.path || '?'}: crons are not supported on chain (nothing schedules an instruction); the route itself may still be served`);
-  for (const fn of deployment.functions || []) {
-    if (fn.middleware) out.push(`${fn.name}: middleware is skipped (see report.ineligible)`);
-    if (fn.prerender) out.push(`${fn.name}: ISR/prerender config is ignored`);
-    if (fn.maxDuration && fn.maxDuration > 60) out.push(`${fn.name}: maxDuration=${fn.maxDuration}s has no effect; an instruction is bounded by compute units, not seconds`);
-  }
-  for (const n of deployment.notes || []) out.push(n);
-  return out;
-}
-
-/** Display path for a function source relative to the deployment root. */
-export function displayFile(fn, root) {
-  if (!fn?.sourceFile) return fn?.name || '?';
-  return root ? path.relative(root, fn.sourceFile) || fn.sourceFile : fn.sourceFile;
-}