@artblocks/abx-cli 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/commands/project.js

@@ -0,0 +1,1299 @@
+/**
+ * Project lifecycle commands: `predict` (pre-compute a deploy address), `add` (register + index a
+ * project this node didn't deploy), `index` (re-index from chain), `verify` (re-hash served bytes
+ * vs. the on-chain commitment), `state`/`status` (on-chain snapshot / indexed-project rollup), and
+ * `forget` (drop the local registration; on-chain data is untouched).
+ */
+import { readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { verifyProvenance, AUTH_OPTIONS, CREATOR_TOKEN_INTERFACE_ID, PARAM_TYPES, hasOnChainUriLane, isCodeProject, isCurrentFactory, isCurrentOneOfOneEditionFactory, makePublicClient, makeWalletClient, normalizeAttributes, onChainUriReport, parseTraitPairs, predictClone, readParamHooks, readParamHooksLocked, readParamSchema, readParamSchemaKeys, readSetParamKeys, resolveChain, resolveSeriesCodeFactory, saltFor, saltGuard, sleep, readCollectionPolicy, tryReadContract, } from '@artblocks/abx-sdk';
+import { resolveBackend } from '@artblocks/abx-storage';
+import { currentRenderArtifact, verifyProject } from '@artblocks/abx-token-api';
+import { zeroAddress } from 'viem';
+import { CHAIN, activeBackendId, factoryAddress, localIndexer, remoteLocators, seriesFactoryAddress, oneOfOneEditionFactoryAddress, editionFactoryAddress, editionCodeFactoryAddress, storageOptions, } from '../config.js';
+import { isDryRun, parseSaltFlag } from '../flags.js';
+import { jsonSafe, withJson } from '../jsonout.js';
+import { allowLargeScan, bold, c, detectCanonicalFactory, dim, g, info, ok, registerAndIndexLocally, resolveScanFloor, warn } from '../output.js';
+import { parseCopies } from './deploy.js';
+import { canonicalSeedSource } from '../ownerops.js';
+import { detectTokenKind, describeKind } from '../kind.js';
+import { canonicalLabel, describeRemoteError, indexErrorAction, remoteFlag, reportRemoteIndexing, requireRemoteToken, rollUp, serviceClient, statusLabel, statusLine, statusRow, tokenSourceLabel, } from '../remote.js';
+import { describeSchema } from '../schema.js';
+import { looksPerTokenAttributes, parseSeriesTraitsById } from '../series-traits.js';
+// ── predict ──────────────────────────────────────────────────────────────────
+// Pre-compute a deploy address from a salt — so you can stand up the resolver and
+// reserve a vanity/known address before signing. The address is a pure function of
+// (factory, salt); the salt's leading 20 bytes are the front-run guard.
+export async function cmdPredict(flags) {
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    // Lane-aware: each deploy command uses a DIFFERENT factory, so the deterministic address differs.
+    // Infer the lane from the content flags so `predict` matches what will actually be deployed —
+    // otherwise a code/Series creator gets the 1/1 address (a real mismatch, not just a wrong echo).
+    const chainId = resolveChain(CHAIN).id;
+    const content = flags.script ? `--script ${flags.script}` :
+        flags['code-dir'] ? `--code-dir ${flags['code-dir']}` :
+            flags['image-renderer'] ? `--image-renderer ${flags['image-renderer']}` :
+                flags.dir ? `--dir ${flags.dir}` :
+                    flags.image ? `--image ${flags.image}` : '';
+    const baseCmd = (flags.script || flags['code-dir'] || flags['image-renderer'])
+        ? 'deploy-code'
+        : flags.dir
+            ? 'deploy-series'
+            : 'deploy';
+    // `--copies <n|open>` switches which factory's address is predicted — the SAME flag that
+    // switches which factory a real deploy uses (see commands/deploy.ts's `parseCopies`). Validated
+    // here too (not just deferred to the real deploy) so a malformed value fails before printing an
+    // address tied to it.
+    const editionSize = flags.copies !== undefined ? parseCopies(flags.copies) : undefined;
+    const isEdition = editionSize !== undefined;
+    const lane = isEdition
+        ? {
+            cmd: baseCmd,
+            factory: baseCmd === 'deploy-code'
+                ? editionCodeFactoryAddress(flags.factory)
+                : baseCmd === 'deploy-series'
+                    ? editionFactoryAddress(flags.factory)
+                    : oneOfOneEditionFactoryAddress(flags.factory),
+        }
+        : baseCmd === 'deploy-code'
+            ? { cmd: 'deploy-code', factory: resolveSeriesCodeFactory(chainId, flags.factory) }
+            : baseCmd === 'deploy-series'
+                ? { cmd: 'deploy-series', factory: seriesFactoryAddress(flags.factory) }
+                : { cmd: 'deploy', factory: factoryAddress(flags.factory) };
+    const factory = lane.factory;
+    if (!factory) {
+        throw new Error(`no canonical ${isEdition ? 'edition ' : ''}${lane.cmd} factory for '${CHAIN}' — run \`abx ${lane.cmd}${isEdition ? ` --copies ${flags.copies}` : ''}\` ` +
+            `once to deploy the trust anchor, or pass --factory 0x.. (or the ABX_* env).`);
+    }
+    // The current-factory guard is the 1/1 impl-version check (721 or its edition twin); the Series/
+    // Series-edition/code/code-edition lanes verify their own factory at deploy time instead —
+    // EditionCodeFactory mirrors SeriesCodeFactory's stance here (no version probe: a configured code
+    // factory with code is always accepted, and one found at its CREATE2 address is bytecode-bound to
+    // this build anyway, so there's nothing this check would catch that the real deploy doesn't
+    // already). predictDeterministicAddress works on any factory ABI.
+    if (lane.cmd === 'deploy') {
+        const current = isEdition ? await isCurrentOneOfOneEditionFactory(publicClient, factory) : await isCurrentFactory(publicClient, factory);
+        if (!current) {
+            throw new Error(`factory ${factory} is an older/incompatible version. Run \`abx deploy${isEdition ? ` --copies ${flags.copies}` : ''}\` once to deploy the current ` +
+                `trust anchor (ownerless + cheap), then predict again — or pass a current --factory.`);
+        }
+    }
+    let salt = parseSaltFlag(flags.salt);
+    if (!salt) {
+        // No explicit salt: reserve one to a deployer (front-run-proof). Default to the env key.
+        let deployer = flags.for;
+        if (!deployer)
+            deployer = makeWalletClient({ chainKey: CHAIN }).account.address;
+        salt = saltFor(deployer);
+        info(`reserved a fresh salt to ${deployer} (front-run-proof) — pass --salt to fix/vanity it`);
+    }
+    const guard = saltGuard(salt);
+    const clone = await predictClone(publicClient, { factory, salt });
+    console.log(`\n  ${bold('predicted address')}  ${g(clone)} ${dim(`(${lane.cmd} lane${isEdition ? ', edition' : ''})`)}`);
+    info(`salt   ${salt}`);
+    info(guard === zeroAddress ? 'guard  permissionless — anyone may deploy this salt' : `guard  reserved to ${guard} (only this signer can deploy it)`);
+    const copiesFlag = isEdition ? ` --copies ${editionSize === 0n ? 'open' : editionSize.toString()}` : '';
+    info(`deploy: ${bold(`abx ${lane.cmd}${content ? ` ${content}` : ''}${copiesFlag} --salt ${salt}`)}`);
+    if (lane.cmd === 'deploy' && !isEdition)
+        info(dim('(this is the 1/1 lane; a Series/code drop uses a different factory → a different address — pass --dir / --script to predict those, or use that command\'s --dry-run)'));
+    console.log('');
+}
+// ── add ──────────────────────────────────────────────────────────────────────
+// Register + index a project this node didn't deploy. LOCAL by default (this
+// machine's store); `--remote [url]` instead tells a HOSTED resolver to index it —
+// the bridge a local deploy can't make on its own (separate projection stores).
+export async function cmdAdd(address, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx add <address> [--from-block N] [--factory 0x..] [--label "..."] [--remote [name|url]]\n');
+        process.exitCode = 1;
+        return;
+    }
+    // REFUSE `--dry-run` rather than ignoring it. `add` is a write (a local registration + index, and
+    // with `--remote` a registration on someone else's service), and it has no preview mode — so
+    // silently proceeding to DO the thing when the caller explicitly asked to preview is the one
+    // outcome we must never produce. Name what's read-only instead.
+    if (isDryRun(flags)) {
+        throw new Error('`abx add` has no --dry-run: it registers + indexes for real (and with --remote it registers on that service). ' +
+            'Nothing here touches the chain, but it does write. To look before acting: `abx state <address>` (on-chain snapshot) ' +
+            'or `abx status <address> [--remote <name>]` (what a node already has). Re-run without --dry-run when you mean it.');
+    }
+    // `--attributes` is lane-aware here exactly as at deploy: a PER-TOKEN payload edits a Series'
+    // per-token off-chain traits; a flat payload (+ `--traits`) edits the collection/1-of-1 `attributes`.
+    // Ambiguity defaults to flat (see looksPerTokenAttributes), so a 1/1 add is never mis-read.
+    const attrRaw = flags.attributes ? readFileSync(resolvePath(process.cwd(), String(flags.attributes)), 'utf8') : undefined;
+    const perTokenEdit = attrRaw != null && looksPerTokenAttributes(attrRaw);
+    const flagTraits = [];
+    if (attrRaw != null && !perTokenEdit)
+        flagTraits.push(...normalizeAttributes(JSON.parse(attrRaw)));
+    if (flags.traits)
+        flagTraits.push(...parseTraitPairs(flags.traits));
+    const editedTokenAttributes = perTokenEdit ? parseSeriesTraitsById(attrRaw) : undefined;
+    const remote = remoteFlag(flags);
+    if (remote) {
+        requireRemoteToken(remote);
+        // Bridge what a remote resolver can't derive itself: the off-chain traits and the durable
+        // content locators (ipfs://…). Prefer flags; otherwise forward what the LOCAL deploy stored
+        // (the local registration), and compute locators from this machine's content index if needed.
+        const localReg = localIndexer().store.getRegistration(address);
+        const attributes = flagTraits.length
+            ? flagTraits
+            : localReg?.attributes
+                ? normalizeAttributes(JSON.parse(localReg.attributes))
+                : undefined;
+        // Bridge a Series' per-token off-chain traits to the remote resolver (the resolver has no other
+        // way to derive them — they're operator metadata, not chain state). A fresh per-token `--attributes`
+        // EDITS them; otherwise forward what the LOCAL deploy stored. Best-effort parse.
+        let tokenAttributes;
+        if (editedTokenAttributes && Object.keys(editedTokenAttributes).length) {
+            tokenAttributes = editedTokenAttributes;
+        }
+        else if (localReg?.tokenAttributes) {
+            try {
+                const obj = JSON.parse(localReg.tokenAttributes);
+                const norm = {};
+                for (const [id, v] of Object.entries(obj)) {
+                    const a = normalizeAttributes(v);
+                    if (a.length)
+                        norm[id] = a;
+                }
+                if (Object.keys(norm).length)
+                    tokenAttributes = norm;
+            }
+            catch { /* skip a malformed local column */ }
+        }
+        const contentLocators = await remoteLocators(address, localReg?.contentLocators, flags);
+        // Forward the deploy block, like every other field falls back to the local registration.
+        // (Its ABSENCE here was the bug: a hosted resolver defaulted to genesis and scanned the whole
+        // chain.) Re-sending the same floor stays incremental server-side, so a nudge ≠ a re-scan.
+        const body = {
+            chainId: resolveChain(CHAIN).id,
+            address,
+            fromBlock: await resolveScanFloor(address, localReg?.fromBlock, flags),
+            factory: await detectCanonicalFactory(address, flags.factory, localReg?.factory),
+            label: flags.label,
+            description: flags.description ?? localReg?.description,
+            externalUrl: flags['external-url'] ?? localReg?.externalUrl,
+            attributes,
+            tokenAttributes,
+            contentLocators: Object.keys(contentLocators).length ? contentLocators : undefined,
+            full: flags.full ? true : undefined,
+        };
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(registering with the remote resolver — NOT this machine)')}`);
+        if (body.contentLocators)
+            info(`bridging image locator → ${Object.values(body.contentLocators)[0]} ${dim('(so the resolver points at IPFS, not its own localhost)')}`);
+        let r;
+        try {
+            r = await serviceClient(remote).registerProject(body);
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote add');
+        }
+        await reportRemoteIndexing(remote, body.chainId, address, r, flags, 'indexed');
+        info(`it now serves ${remote.url}/t/${body.chainId}/${address.toLowerCase()}/0`);
+        // "Indexed" is not "correct". This line proves the service replayed the chain and will answer at
+        // that URL — it says nothing about whether the bytes it serves match the on-chain commitment, and
+        // two reviewers stopped here and reported a blank page as fixed. Name the step that checks.
+        info(`confirm what it actually serves (bytes vs. the on-chain hash): ${bold(`abx verify ${address} --remote ${remote.name?.toLowerCase() ?? remote.url}`)}`);
+        // Say what this registration did NOT buy. A project whose `tokenURIRenderer` is set answers
+        // `tokenURI` from the chain, so marketplaces and wallets read THAT document and never touch this
+        // service — the register is still useful (indexing, the live view, managed rendering for a code
+        // drop) but it changes nothing a collector sees. Without this line the readout is a list of
+        // successes that reads like a win, and a creator who was told "put it on a hosted service so it
+        // shows up properly" concludes their problem is solved when nothing about it moved.
+        const onChainRenderer = await tryReadContract(makePublicClient({ chainKey: CHAIN }), {
+            address,
+            abi: STATE_ABI,
+            functionName: 'tokenURIRenderer',
+        });
+        if (onChainRenderer && onChainRenderer !== zeroAddress) {
+            info(`${dim('note:')} this project resolves ${bold('tokenURI from the chain')} (renderer ${onChainRenderer}) — marketplaces read that, not this service. ` +
+                `Registering still gives you indexing, the live view and managed rendering, but it does not change the metadata a collector sees.`);
+        }
+        return;
+    }
+    // The local (non-`--remote`) path is shared with the deploy family's post-setup registration —
+    // see registerAndIndexLocally's doc comment (output.ts).
+    return registerAndIndexLocally(address, flags);
+}
+export async function cmdIndex(address, flags) {
+    const remote = remoteFlag(flags);
+    if (remote) {
+        if (!address || address.startsWith('--')) {
+            console.error('usage: abx index <address> --remote [name|url]   (re-index one project on a remote resolver)\n');
+            process.exitCode = 1;
+            return;
+        }
+        requireRemoteToken(remote);
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(re-indexing on the remote resolver — the post-deploy nudge)')}`);
+        const chainId = resolveChain(CHAIN).id;
+        let r;
+        try {
+            r = await serviceClient(remote).registerProject({ chainId, address, full: flags.full ? true : undefined });
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote index');
+        }
+        await reportRemoteIndexing(remote, chainId, address, r, flags, 're-indexed');
+        return;
+    }
+    allowLargeScan(flags);
+    const full = !!flags.full; // force a full replay from the deploy block (durability proof)
+    const indexer = localIndexer();
+    const line = (state, elapsedMs, mode) => ok(`${state.name ?? state.address}: ${state.eventCount} events in ${elapsedMs}ms ${dim(`(${mode})`)}`);
+    if (address) {
+        const { state, elapsedMs, mode } = await indexer.reindex(address, { full });
+        line(state, elapsedMs, mode);
+        return;
+    }
+    const results = await indexer.reindexAll({ full });
+    if (results.length === 0) {
+        console.log(dim('No registered projects. Deploy one with `abx deploy`.'));
+        return;
+    }
+    for (const { state, elapsedMs, mode } of results)
+        line(state, elapsedMs, mode);
+}
+// ── verify ─────────────────────────────────────────────────────────────────--
+// Re-hash a project's served bytes against its on-chain content commitment, from
+// chain + custody alone — no running server. The CLI form of the `/verify` route,
+// so an agent can confirm integrity right after deploy/mint without curling.
+export async function cmdVerify(address, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx verify <address> [--json] [--remote <name|url>]\n');
+        process.exitCode = 1;
+        return;
+    }
+    allowLargeScan(flags);
+    const remote = remoteFlag(flags);
+    if (remote)
+        return cmdVerifyRemote(address, remote);
+    // `--json` matters most here of all the read commands: verify already exits non-zero on a byte
+    // mismatch, so it is the one command a CI job would gate on — and gating on prose is what B19 is
+    // about. The payload's `ok` is the same boolean the exit code carries.
+    return withJson(flags, async (emit) => cmdVerifyBody(address, flags, emit));
+}
+export async function cmdVerifyBody(address, flags, emit) {
+    const indexer = localIndexer();
+    let state = indexer.getProject(address);
+    if (indexer.store.getRegistration(address)) {
+        ({ state } = await indexer.reindex(address)); // freshest state from chain
+    }
+    else if (!state) {
+        throw new Error(`${address} isn't indexed by this node. Run \`abx add ${address}\` first.`);
+    }
+    if (!state)
+        throw new Error(`could not load state for ${address}`);
+    // Accumulated as the checks run, re-emitted at each stage so a payload survives an early return.
+    const verifyReport = {
+        address,
+        chain: CHAIN,
+        name: state.name ?? null,
+        canonical: state.isCanonical, // TRUE tri-state: true | false | null (couldn't check)
+        owner: state.owner ?? null,
+        contentChecks: [],
+        contentIntegrity: 'no-commitments',
+        renders: null,
+        onChainUri: null,
+        ok: true,
+    };
+    emit(verifyReport);
+    console.log(bold(`\n  verify ${state.name ?? address}`));
+    // isCanonical is a TRUE TRI-STATE (true | false | null) and collapsing it lost the only
+    // distinction that matters: "the chain says this is NOT a clone of the configured factory" is a
+    // trust finding; "we couldn't run the check" (no factory configured, or none deployed on this
+    // chain) is an environment note. Two reviewers read the collapsed word as a second failure.
+    info(`canonical: ${canonicalLabel(state.isCanonical)} · owner ${state.owner ?? '—'}`);
+    const storage = resolveBackend(storageOptions());
+    const result = await verifyProject(state, storage);
+    const tokens = result.tokens ?? [];
+    let anyCheck = false;
+    let allGood = true;
+    for (const t of tokens) {
+        const tok = state.tokens.find((s) => s.tokenId === t.tokenId);
+        const life = tok?.lifecycle === 'live'
+            ? 'minted'
+            : tok?.lifecycle === 'burned'
+                ? 'BURNED'
+                : tok?.lifecycle === 'no-live-copies'
+                    ? 'no live copies'
+                    : 'not yet minted';
+        info(`token #${t.tokenId}: ${life}`);
+        for (const ch of t.checks) {
+            verifyReport.contentChecks.push({
+                tokenId: t.tokenId,
+                lifecycle: tok?.lifecycle ?? 'unminted',
+                kind: ch.kind,
+                // tri-state again: true (re-hashed, matched) · false (MISMATCH) · null (pointer-only,
+                // nothing local to recompute). Collapsing null into false would report a normal state as a
+                // failure, which is the bug this command exists to not have.
+                verified: ch.verified,
+            });
+            anyCheck = true;
+            if (ch.verified === true)
+                ok(`${ch.kind} matches on-chain commitment — content is authentic`);
+            else if (ch.verified === false) {
+                allGood = false;
+                console.log(`    ${c.red}✗${c.reset} ${ch.kind} MISMATCH — served bytes don't match the commitment`);
+            }
+            else
+                info(`${ch.kind} — pointer-only, not locally recomputable`);
+        }
+    }
+    if (!anyCheck && !isCodeProject(state))
+        info('no content commitments on this project');
+    verifyReport.contentIntegrity = !anyCheck ? 'no-commitments' : allGood ? 'ok' : 'mismatch';
+    verifyReport.ok = !anyCheck || allGood;
+    emit(verifyReport);
+    // Code projects have no on-chain `image` commitment (the still is rendered off-chain by the
+    // effect runner), so the hash checks above are silent for them. Instead report what actually
+    // matters after mint: does a REAL thumbnail exist yet, or is the marketplace image still the
+    // placeholder? Same seam the /…/image route serves from (currentRenderArtifact @ current
+    // inputsHash) — so this answers "did the render land?" with one command, right after token 0.
+    let renderGap = false;
+    if (isCodeProject(state)) {
+        const client = makePublicClient({ chainKey: CHAIN });
+        const storageForRender = resolveBackend(storageOptions());
+        const minted = state.tokens.filter((t) => t.lifecycle === 'live');
+        if (minted.length === 0)
+            info('no tokens minted yet — mint token #0, then re-run to check its thumbnail.');
+        // Live-data posture — the augment hook IS the opt-in: no hook ⇒ zero live reads (pure indexed
+        // params); hook set ⇒ the live view reads chain per view, and the STILL snapshots settled state
+        // (live data never re-addresses the render — that's the settled/full split).
+        info(state.paramHooks?.augmentHook
+            ? `live data: augment hook ${state.paramHooks.augmentHook} — live view reads chain per view; stills snapshot settled state`
+            : 'live data: none (settled params only — the live view makes zero extra chain reads)');
+        // Immutability of the WORK itself — the on-chain program (script chunks) and its library set.
+        // This is the gap `lock-field`/`lock-uri` don't cover: those freeze metadata, but the owner can
+        // still call `setScriptChunk`/`removeLastScriptChunk` until `lock-script` is sent. Report it so a
+        // "locked" drop isn't quietly still-mutable in the one place that carries the work.
+        verifyReport.script = state.script ? { locked: !!state.script.locked } : null;
+        verifyReport.dependencies = state.dependencies
+            ? { count: state.dependencies.list.length, locked: !!state.dependencies.locked }
+            : null;
+        emit(verifyReport);
+        if (state.script) {
+            if (state.script.locked)
+                ok('script: locked — the program bytes are frozen permanently (setScriptChunk reverts)');
+            else
+                console.log(`    ${c.orange}⚠${c.reset} script: UNLOCKED — the owner can still change the program. Freeze the work with ${bold(`abx lock-script ${address}`)} ${dim("(lock-field/lock-uri don't cover the script)")}`);
+        }
+        if (state.dependencies && state.dependencies.list.length > 0) {
+            if (state.dependencies.locked)
+                ok('dependencies: locked — the library set is frozen');
+            else
+                info(`dependencies: unlocked — freeze the list + registry pointer with \`abx lock-dependencies ${address}\` (that pins WHICH library each ref means; a Registry ref's bytes still live in the registry)`);
+        }
+        // The other two param hooks (if wired) — surfaced here since this is where hooks show. Quiet when
+        // unset (the common case). Manage all three with `abx set-param-hooks`.
+        if (state.paramHooks?.configureHook || state.paramHooks?.transferHook) {
+            const parts = [];
+            if (state.paramHooks.configureHook)
+                parts.push(`configure ${state.paramHooks.configureHook}`);
+            if (state.paramHooks.transferHook)
+                parts.push(`transfer ${state.paramHooks.transferHook}`);
+            info(`param hooks: ${parts.join(' · ')} ${dim('(configure = write-time veto · transfer = a VETO over transfers AND mints; manage with `abx set-param-hooks`)')}`);
+        }
+        // The hook lock is reported for every project with the surface, set hooks or not: a frozen empty
+        // trio is a real guarantee ("this project can never add a transfer veto"), and an unfrozen one is
+        // a live power even when no hook is set today. Folded from `ParamHooksFrozen`.
+        if (state.paramHooks) {
+            verifyReport.paramHooks = {
+                configureHook: state.paramHooks.configureHook,
+                augmentHook: state.paramHooks.augmentHook,
+                transferHook: state.paramHooks.transferHook,
+                locked: state.paramHooks.locked,
+            };
+            if (state.paramHooks.locked)
+                ok('param hooks: frozen — no hook address can change again (no transfer veto can ever be armed)');
+            else if (state.paramHooks.transferHook) {
+                console.log(`    ${c.orange}⚠${c.reset} param hooks: UNLOCKED, and a transfer hook is armed — it can block transfers and mints, and the owner can re-point it. Freeze the set with ${bold(`abx lock-param-hooks ${address}`)}`);
+            }
+            else {
+                info(`param hooks: unlocked — no hook is set, but the owner can still add one (a transfer hook can block transfers/mints). Freeze with \`abx lock-param-hooks ${address}\``);
+            }
+        }
+        // This checks THIS machine's store. A render PUBLISHED to a hosted resolver (locator bridge) lives
+        // on that resolver, NOT here — so a "not found" below can be a false negative for a hosted drop.
+        // `abx verify <addr> --remote <resolver>` probes what the resolver actually serves (the truthful check).
+        if (minted.length)
+            info(dim(`render check is against THIS node's store; for a HOSTED drop use \`abx verify ${address} --remote <resolver>\``));
+        // ONE line per outcome, not per token. This printed the same full-sentence advisory 32 times on a
+        // 32-token project (~4KB of identical text) and pushed the four lines that answer "did my deploy
+        // work" off the top of the screen; at a 1000-token supply it is unreadable. The per-token detail
+        // that survives is the token LIST, which is the only part that differs.
+        const missing = [];
+        let present = 0;
+        for (const token of minted) {
+            const { found } = await currentRenderArtifact(client, state, token, storageForRender, 'image');
+            if (found)
+                present++;
+            else
+                missing.push(String(token.tokenId));
+        }
+        verifyReport.renders = {
+            minted: minted.length,
+            present,
+            missing, // token ids, so a caller can re-render exactly these
+            // Named for what it IS: this node's store. A render PUBLISHED to a hosted resolver lives
+            // there, not here, so `missing` is a false negative for a hosted drop — hence the scope.
+            scope: "this node's store",
+        };
+        emit(verifyReport);
+        if (present)
+            ok(`${present}/${minted.length} minted token(s): real render present (in this node's store)`);
+        if (missing.length) {
+            renderGap = true;
+            const ids = missing.length > 12 ? `${missing.slice(0, 12).join(', ')}, …+${missing.length - 12} more` : missing.join(', ');
+            console.log(`    ${c.orange}⚠${c.reset} ${missing.length}/${minted.length} token(s) have no render in THIS node's store ${dim(`(#${ids})`)}`);
+            console.log(`      ${dim('published to a hosted resolver? check there:')} ${bold(`abx verify ${address} --remote <resolver>`)}`);
+            console.log(`      ${dim('else render them:')} ${bold(`abx render ${address}`)} ${dim('(once) ·')} ${bold('abx effects')} ${dim('(continuous)')}`);
+        }
+    }
+    // The on-chain URI lane (a non-zero tokenURIRenderer, or an animation field pointing at the
+    // generator): read the generator's honesty surface — onChainStatus (branch · chain-complete ·
+    // unresolved refs · URL budget) — then decode tokenURI straight from the contract and report
+    // what the animation_url actually is. All eth_calls; no server, no local store involved.
+    if (hasOnChainUriLane(state)) {
+        const client = makePublicClient({ chainKey: CHAIN });
+        // Is this actually a PROGRAM, or a static image that merely resolves on-chain? `hasOnChainUriLane`
+        // is true whenever a tokenURI renderer is set — which it is for EVERY fully-on-chain project,
+        // image or code. So an image drop ran the code-project checks and ended in two ⚠ ("generator
+        // reports NO code", "no animation_url") that are the DESIGN for a static image, not a defect.
+        // Two cold agents in one sweep flagged those warnings as the worst thing about `verify`: the
+        // command the skill points at to answer "did my on-chain drop work?" was ending in warnings on a
+        // drop that is completely fine, which teaches people to discount its warnings generally.
+        const isCodeProject = state.contractType === 'code' || state.contractType === 'edition-code';
+        try {
+            const report = await onChainUriReport(client, state, flags.generator);
+            const { status, probe } = report;
+            verifyReport.onChainUri = jsonSafe({
+                generator: report.generator,
+                tokenURIRenderer: state.tokenURIRenderer ?? null,
+                branch: status.branchName,
+                chainComplete: !!status.chainComplete,
+                unresolvedRefs: [...status.unresolvedRefs],
+                urlOverBudget: !!status.urlOverBudget,
+                probe: probe
+                    ? { tokenId: probe.tokenId, onChainJson: !!probe.onChainJson, animation: probe.animation }
+                    : null,
+            });
+            emit(verifyReport);
+            info(`on-chain URI lane: generator ${report.generator}${state.tokenURIRenderer ? ` · tokenURI renderer ${state.tokenURIRenderer}` : ' · tokenURIRenderer NOT set (animation field only — tokenURI still resolves off-chain)'}`);
+            if (status.branchName === 'template') {
+                ok(`generator branch: template — the document assembles from the on-chain script chunks`);
+                if (status.chainComplete) {
+                    ok('chain-complete — every dependency resolves to on-chain bytes; no server, gateway, or CDN in the graph');
+                    // chainComplete is a SERVING claim, not an immutability one. A `Registry` dependency is
+                    // fetched live from the registry contract on every read, so its bytes can change after
+                    // `lock-dependencies` froze the pointer — and this flag reported `true` on both sides of
+                    // exactly that swap during the audit. Say what it means rather than letting "complete" read
+                    // as "finished".
+                    info(dim('  chain-complete describes WHERE the bytes come from, not that they are frozen: a Registry dependency is re-fetched from the registry on every read, so its bytes can change even with lock-dependencies set. Locks freeze this contract; they cannot freeze another one.'));
+                }
+                else
+                    info('not chain-complete — CDN-served or unresolved dependencies (CDN entries serve fine; on-chain bytes are the durability floor)');
+                for (const ref of status.unresolvedRefs) {
+                    console.log(`    ${c.red}✗${c.reset} unresolved dependency ${bold(ref)} — the document carries an <!-- abx:unresolved --> marker; fix the ref or the registry pointer`);
+                }
+            }
+            else if (status.branchName === 'directory') {
+                ok('generator branch: directory — the code field emits a parameterized gateway URL');
+                if (status.urlOverBudget)
+                    console.log(`    ${c.orange}⚠${c.reset} the emitted URL exceeds the 8KB budget — gateway front-ends may drop it; prefer template mode, trim the param surface, or carry big values as locator params`);
+                else
+                    info('URL within the 8KB budget');
+            }
+            else if (isCodeProject) {
+                console.log(`    ${c.orange}⚠${c.reset} generator reports NO code (neither script chunks nor a code field) — animation_url degrades to an <!-- abx:no-code --> marker`);
+            }
+            else {
+                // A static image drop has no program by design — stating that is fine, warning about it is not.
+                info('no program on this project — a static image drop, so the metadata carries no animation_url (expected, not a gap)');
+            }
+            if (!probe) {
+                info('tokenURI probe skipped — no token minted yet (mint token #0, then re-run)');
+            }
+            else if (!probe.onChainJson) {
+                console.log(`    ${c.red}✗${c.reset} ${probe.accessor}(${probe.tokenId}) is NOT an on-chain data:application/json;base64 URI — got "${probe.uriPrefix}…"`);
+            }
+            else {
+                ok(`${probe.accessor}(${probe.tokenId}) resolves ON-CHAIN: data:application/json;base64 — decoded from the contract, no server`);
+                const a = probe.animation;
+                if (a.form === 'data-html') {
+                    if (a.marker)
+                        console.log(`    ${c.orange}⚠${c.reset} animation_url: data:text/html;base64 (${a.bytes} bytes decoded) but the document carries ${bold(a.marker)} — it degraded honestly instead of reverting`);
+                    else
+                        ok(`animation_url: data:text/html;base64 — ${a.bytes} bytes of HTML, decoded (the full document, inline)`);
+                }
+                else if (a.form === 'url') {
+                    ok(`animation_url: ${a.url} ${dim('(directory branch — the parameterized gateway URL, landed verbatim)')}`);
+                }
+                else if (a.form === 'data-other') {
+                    console.log(`    ${c.orange}⚠${c.reset} animation_url is a data: URI but not text/html — got "${a.prefix}…"`);
+                }
+                else if (isCodeProject) {
+                    console.log(`    ${c.orange}⚠${c.reset} no animation_url in the on-chain JSON — the generator field may be missing or unrenderable`);
+                }
+                // else: a static image has no animation_url and is not supposed to — say nothing.
+            }
+            // The READ-side envelope. Params enumerate on-chain, so the write side is unbounded — but
+            // tokenURI and tokenData assemble EVERY enumerated param per call, and that is what grows.
+            // ~64 keys is the documented design envelope; hard failure only nears at several hundred.
+            // Advisory (never a ✗) — a big surface is a legitimate choice, it just isn't free.
+            const set = await readSetParamKeys(client, state.address, probe ? BigInt(probe.tokenId) : undefined);
+            if (set) {
+                const total = new Set([...set.contract, ...set.token]).size;
+                if (total > 64) {
+                    console.log(`    ${c.orange}⚠${c.reset} ${total} params enumerate on-chain${probe ? ` for token #${probe.tokenId}` : ''} — tokenURI and tokenData assemble every one of them per call, so both grow with this count. ` +
+                        dim('The documented design envelope is ~64; past a few hundred a public eth_call can hit its gas cap.'));
+                }
+            }
+        }
+        catch (e) {
+            // First line only. A viem read error carries a multi-line dump (Contract Call / args / Docs /
+            // Version) that is meaningless to a creator and buried the actual sentence when this fired.
+            const first = String(e.message ?? e).split('\n')[0].trim();
+            console.log(`    ${c.orange}⚠${c.reset} on-chain URI check unavailable: ${first}`);
+        }
+    }
+    if (renderGap)
+        console.log(`\n  ${dim('live view animates regardless; the placeholder only affects the static marketplace thumbnail.')}\n`);
+    else
+        console.log(anyCheck && allGood ? `\n  ${g('✓ verified')} — the node serves exactly what the chain commits to.\n` : '\n');
+    // A byte-vs-chain mismatch is an integrity FAILURE, so fail the command. Verify's whole job is to
+    // answer "is what's served what the chain vouches for" — exiting 0 while printing ✗ meant nothing
+    // could gate on it (a script or CI would sail past a corrupted image). Deliberately narrow: a
+    // missing render / placeholder is a normal, expected state and still exits 0.
+    if (anyCheck && !allGood)
+        process.exitCode = 1;
+}
+// `abx verify <addr> --remote <url>` — verify what a HOSTED resolver actually serves (the local
+// `verify` checks THIS machine's store/backend, the wrong store for a hosted drop). Probes the real
+// `/…/image` route, so it accounts for the locator bridge (a 302 to ipfs/ar) exactly as a marketplace
+// sees it — the truthful "did the thumbnail land?" check after a remote render.
+export async function cmdVerifyRemote(address, remote) {
+    const base = remote.url.replace(/\/$/, '');
+    const chainId = resolveChain(CHAIN).id;
+    console.log(bold(`\n  verify ${address} ${dim(`(remote → ${base})`)}`));
+    // A DOWN endpoint and a wrong-address endpoint are different problems with different fixes, and a
+    // bare `fetch failed` says neither. `abx status --remote` already gets this right — match it, or the
+    // two commands disagree about the same condition (a reviewer's top misdiagnosis risk).
+    let stateRes;
+    try {
+        stateRes = await fetch(`${base}/api/project/${address}`);
+    }
+    catch {
+        throw new Error(`verify: nothing responded at ${base}${remote.source === 'named' ? ` (from ABX_REMOTE_${remote.name}_URL)` : ''}. Is it running, and is that the right address?`);
+    }
+    if (!stateRes.ok) {
+        throw new Error(`resolver ${base} doesn't serve ${address} (HTTP ${stateRes.status}) — register it first: abx add ${address} --remote ${remote.name?.toLowerCase() ?? base}`);
+    }
+    const state = (await stateRes.json());
+    info(`serving as "${state.name ?? address}"`);
+    // Is the resolver actively WATCHING the chain? Prove it from /api/watch (the meta the watcher
+    // stamps each tick) so a hosted operator who can't tail the log still sees liveness — and catches
+    // a silently-stalled watcher (pollAt gone stale) instead of assuming auto-updates still work.
+    const watch = (await fetch(`${base}/api/watch`)
+        .then((r) => (r.ok ? r.json() : null))
+        .catch(() => null));
+    if (watch?.watching) {
+        const heads = Object.entries(watch.chains).map(([ck, s]) => `${ck} @ block ${s.head}`).join(', ');
+        const ageS = watch.pollAt ? Math.round((Date.now() - Date.parse(watch.pollAt)) / 1000) : null;
+        const stalled = ageS !== null && ageS > Math.max(60, Math.round((Number(watch.intervalMs) / 1000) * 4));
+        const detail = `watching ${heads || 'chain'}${ageS !== null ? ` · last poll ${ageS}s ago` : ''}${watch.lastDeltaAt ? ` · last change ${watch.lastDeltaAt}` : ''}`;
+        if (stalled)
+            console.log(`    ${c.orange}⚠${c.reset} ${detail} — watcher looks STALLED; restart \`abx serve\``);
+        else
+            ok(detail);
+    }
+    else if (watch) {
+        console.log(`    ${dim('watcher OFF — changes land only via explicit add/index or a manual render (ABX_WATCH_INTERVAL_MS=0)')}`);
+    }
+    const minted = (state.tokens ?? []).filter((t) => t.lifecycle === 'live');
+    if (minted.length === 0) {
+        info('no tokens minted yet — mint token #0, then re-run.');
+        console.log('');
+        return;
+    }
+    // Prefer the resolver's effect-status API (the derived 4-state readout: up-to-date · rendering ·
+    // failed(error) · stale). Falls back to the raw /image probe for a resolver without the route.
+    const statusRes = await fetch(`${base}/api/project/${address}/effects`).catch(() => null);
+    if (statusRes?.ok) {
+        const report = (await statusRes.json());
+        for (const t of report.tokens) {
+            const label = `token #${t.tokenId} ${t.effectKey}`;
+            if (t.status === 'up-to-date')
+                ok(`${label}: up to date (real render at the current state)`);
+            else if (t.status === 'rendering')
+                info(`${label}: rendering — the effects runner is on it`);
+            else if (t.status === 'failed')
+                console.log(`    ${c.red}✗${c.reset} ${label}: FAILED${t.attempts ? ` after ${t.attempts} attempt(s)` : ''} — ${t.error ?? 'see runner logs'} ${dim(`(fix, then \`abx render ${address} ${t.tokenId} --force --remote ${base}\`)`)}`);
+            else
+                console.log(`    ${c.orange}⚠${c.reset} ${label}: stale — no render at the current state yet (the runner's next notify/sweep picks it up, or \`abx render ${address} --remote ${base}\`)`);
+        }
+        const { upToDate, stale, rendering, failed } = report.counts;
+        // RENDERS ONLY — say so. This report answers "is there a current render for each token", never
+        // "do the served bytes match the on-chain commitment"; those are different questions and this
+        // command promises the second one too. A project with no renders at all (a 1/1, an image Series)
+        // has nothing to be "up to date" ABOUT, so don't print a 0/N fraction — but don't let a green ✓
+        // here read as "the image is verified" either. Byte integrity comes from the check below.
+        if (report.tokens.length === 0) {
+            info(`renders    ${dim('none for this project (a static image needs no off-chain render)')}`);
+        }
+        else {
+            // Lead with the count that carries the polarity: "N of M current" never inverts on a skim the
+            // way "0/M up to date" does.
+            const summary = `${upToDate} of ${minted.length} token(s) current${rendering ? ` · ${rendering} rendering` : ''}${stale ? ` · ${stale} stale` : ''}${failed ? ` · ${failed} FAILED` : ''}`;
+            if (failed || stale)
+                console.log(`  ${c.orange}⚠${c.reset} renders: ${summary} ${dim('— live view animates regardless; only the static thumbnail is affected.')}`);
+            else
+                ok(`renders: ${summary}`);
+        }
+        await reportRemoteByteIntegrity(address, remote, base);
+        return;
+    }
+    let gap = false;
+    for (const t of minted) {
+        const img = await fetch(`${base}/t/${chainId}/${address}/${t.tokenId}/image`, { redirect: 'manual' });
+        const loc = img.headers.get('location');
+        const ct = img.headers.get('content-type') ?? '';
+        if (img.status >= 300 && img.status < 400 && loc)
+            ok(`token #${t.tokenId} image: real render — resolver 302s to ${loc}`);
+        else if (img.status === 200 && !/svg/i.test(ct))
+            ok(`token #${t.tokenId} image: real render present (${ct})`);
+        else {
+            gap = true;
+            console.log(`    ${c.orange}⚠${c.reset} token #${t.tokenId} image: PLACEHOLDER (${ct || 'svg'}) — run \`abx render ${address} --remote ${base}\`, or stand up the effects runner`);
+        }
+    }
+    console.log(gap
+        ? `  ${dim('live view animates regardless; the placeholder only affects the static marketplace thumbnail.')}`
+        : `  ${g('✓ thumbnails are real renders')} ${dim('— served straight from the resolver.')}`);
+    await reportRemoteByteIntegrity(address, remote, base);
+}
+/**
+ * The half `abx verify --remote` was missing: do the served BYTES still hash to the on-chain
+ * commitment? Everything above it checks renders (is a thumbnail current, is it a placeholder) — a
+ * different question, and a green ✓ there was reading as "the image is correct" when the bytes could
+ * genuinely mismatch.
+ *
+ * The service is the right place to answer it: it holds both the bytes and the chain, and it already
+ * exposes exactly this check (`GET /api/project/:addr/verify`, bearer-gated because it triggers
+ * outbound fetches). When we can't reach that — no credential, or an older node — say plainly that
+ * byte integrity was NOT checked rather than leaving the ✓ above to imply it was.
+ */
+export async function reportRemoteByteIntegrity(address, remote, base) {
+    if (!remote.token) {
+        warn(`byte integrity NOT checked — that check is credentialed on the service. Set ${remote.tokenVar} (or pass --remote-token) and re-run, or run ${bold(`abx verify ${address}`)} against a node that holds the bytes.`);
+        return;
+    }
+    let report;
+    try {
+        const res = await fetch(`${base}/api/project/${address}/verify`, { headers: { authorization: `Bearer ${remote.token}` } });
+        if (res.status === 401 || res.status === 403) {
+            warn(`byte integrity NOT checked — ${base} rejected ${tokenSourceLabel(remote)} for its verify route (the read plane served fine, so this is a credential/scoping issue, not a broken project).`);
+            return;
+        }
+        if (!res.ok) {
+            // Spec'd as part of `abx-token-api/v1`, so a conforming service has it — but say it neutrally:
+            // this is equally "an older self-hosted node" and "a provider that didn't implement it".
+            warn(`byte integrity NOT checked — ${base} serves no /api/project/…/verify route (HTTP ${res.status}). ` +
+                `Your own node? Redeploy it (\`abx deploy-resolver\`). A provider's? It's part of abx-token-api/v1 — ask them for it. ` +
+                `Meanwhile ${bold(`abx verify ${address}`)} checks the bytes on a node that holds them.`);
+            return;
+        }
+        report = (await res.json());
+    }
+    catch {
+        warn(`byte integrity NOT checked — couldn't reach ${base}'s verify route.`);
+        return;
+    }
+    const checked = (report.tokens ?? []).filter((t) => t.checks.length > 0);
+    if (checked.length === 0) {
+        info(`bytes      ${dim('no on-chain byte commitment to check (this project commits no image hash)')}`);
+        return;
+    }
+    const bad = checked.filter((t) => t.checks.some((k) => !k.verified));
+    if (bad.length === 0) {
+        ok(`bytes: ${checked.length} token(s) hash-match their on-chain commitment ${dim('(what the service serves IS what the chain vouches for)')}`);
+        return;
+    }
+    const spec = remote.name?.toLowerCase() ?? base;
+    console.log(`  ${c.red}✗${c.reset} ${bold('BYTE MISMATCH')} on token(s) ${bad.map((t) => `#${t.tokenId}`).join(', ')} — ${base} does NOT serve bytes that hash to the on-chain commitment ` +
+        `${dim('(this is what a marketplace shows as a blank or placeholder image)')}. The chain is the truth, so the served copy is the wrong one. Two causes, two fixes:`);
+    info(`durable bytes exist (ipfs://, ar://) but weren't bridged → ${bold(`abx add ${address} --remote ${spec}`)} forwards the locator, then re-run this.`);
+    info(`the bytes only exist on THIS machine (local fs custody) → a hosted resolver can never serve them: ${bold('abx storage upload')} to a durable backend + re-point the field, or serve the project from a node that holds them.`);
+    process.exitCode = 1; // same rule as the local lane: an integrity mismatch fails the command
+}
+// ── state: a one-glance operational snapshot of a deployed contract, read straight from chain ──
+// Read-only (no tx, no local index). Series-only getters revert on a 1/1, so each read is defensive
+// → the same command works for both. The agent-friendly "what's the state before/after an op" call.
+/**
+ * The `seed source` readout — three states, and the distinction between them is the whole reason the
+ * line exists. `0x0` is a code project that deliberately draws no mint seed; the canonical address is
+ * the shared pseudorandom `AbxSeedSource` (whose properties are documented and NOT lottery-grade);
+ * anything else is the creator's own contract, about which ABX knows and claims nothing. A buyer or an
+ * agent reading this needs to be able to tell "the standard one" from "someone's custom randomness"
+ * at a glance — flattening them to a bare address hides exactly the fact worth surfacing.
+ */
+function describeSeedSource(source) {
+    if (source === zeroAddress)
+        return dim('none (0x0 — no mint-time seed drawn at mint)');
+    if (source.toLowerCase() === canonicalSeedSource(resolveChain(CHAIN).id).toLowerCase()) {
+        return `${source} ${dim('(canonical AbxSeedSource — pseudorandom, not lottery-grade)')}`;
+    }
+    return `${source} ${dim('— CUSTOM IAbxSeedSource (not the canonical one; its randomness properties are the project’s to state)')}`;
+}
+export const STATE_ABI = [
+    { type: 'function', name: 'owner', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'totalSupply', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
+    { type: 'function', name: 'nextTokenId', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
+    { type: 'function', name: 'maxInvocations', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
+    { type: 'function', name: 'paused', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'minter', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'primaryPayee', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'tokenURIRenderer', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'royaltyInfo', stateMutability: 'view', inputs: [{ type: 'uint256' }, { type: 'uint256' }], outputs: [{ type: 'address' }, { type: 'uint256' }] },
+    // ERC-721C (creator token) — ERC-165 advertises ICreatorToken ONLY when enrolled at deploy.
+    { type: 'function', name: 'supportsInterface', stateMutability: 'view', inputs: [{ type: 'bytes4' }], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'getTransferValidator', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    // The royalty ceiling + burn opt-in are read via the SDK's `readCollectionPolicy` (one owner of
+    // those two getters, shared with every other integrator) — deliberately not re-declared here.
+    // Seed Source extension — composed by CODE projects only, so absent (undefined) on an image token.
+    // Shown because it is the one setting an owner can re-point mid-sale that changes what a LATER
+    // buyer receives; `SeedSourceSet` puts it on the spine, and this makes it readable in one command.
+    { type: 'function', name: 'seedSource', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+];
+/** The edition twin of {@link STATE_ABI} — `owner`/`maxInvocations`/`paused`/`minter`/
+ *  `primaryPayee`/`tokenURIRenderer`/`royaltyInfo` are shared, unchanged, function names (see
+ *  `kind.ts`'s own note on why); `totalSupply`/`maxSupply` take an id. The creator-token probe is
+ *  ALSO shared, unchanged: Limit Break uses the identical `ICreatorToken` ERC-165 id (0xad0d7f6c)
+ *  and `getTransferValidator()` surface for 721C and 1155C, and `CreatorToken1155` advertises them
+ *  the same way when enrolled — so an enrolled edition reports its validator exactly like a 721. */
+export const EDITION_STATE_ABI = [
+    { type: 'function', name: 'owner', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'maxInvocations', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint256' }] },
+    { type: 'function', name: 'totalSupply', stateMutability: 'view', inputs: [{ type: 'uint256' }], outputs: [{ type: 'uint256' }] },
+    { type: 'function', name: 'maxSupply', stateMutability: 'view', inputs: [{ type: 'uint256' }], outputs: [{ type: 'uint256' }] },
+    { type: 'function', name: 'paused', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'minter', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'primaryPayee', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'tokenURIRenderer', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    { type: 'function', name: 'royaltyInfo', stateMutability: 'view', inputs: [{ type: 'uint256' }, { type: 'uint256' }], outputs: [{ type: 'address' }, { type: 'uint256' }] },
+    // ERC-1155C (creator token) — identical ERC-165 id + getter as 721C; advertised only when enrolled.
+    { type: 'function', name: 'supportsInterface', stateMutability: 'view', inputs: [{ type: 'bytes4' }], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'getTransferValidator', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+    // The royalty ceiling + burn opt-in are read via the SDK's `readCollectionPolicy` (one owner of
+    // those two getters, shared with every other integrator) — deliberately not re-declared here.
+    // Seed Source extension — EditionCode composes it; the image editions don't. See STATE_ABI's note.
+    { type: 'function', name: 'seedSource', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+];
+/**
+ * The royalty ceiling line — and the headroom, which is the part a creator has not been told.
+ *
+ * A ceiling above the live rate means the owner can raise the rate to it unilaterally, and nobody
+ * looking at a listing can see that. So the useful sentence is not "your cap is 10%": it is that
+ * reducing the cap TO the current rate is what turns "5% today" into "5%, provably, forever".
+ * (Named by abx-services, 2026-08-20, as their `royalty-headroom` flag — a marketplace can compute
+ * it, so a creator should hear it from us first.)
+ */
+function royaltyCapLine(address, capBps, rateBps) {
+    const cap = `${capBps / 100}%`;
+    const tail = '(ceiling — owner-set at deploy, reduce-only)';
+    if (rateBps === null || capBps <= rateBps) {
+        return `${cap} ${dim(`${tail} — locked to the current rate: this royalty can never rise`)}`;
+    }
+    return (`${cap} ${dim(tail)}\n` +
+        `                 ${dim(`↳ headroom: the rate is ${rateBps / 100}%, and the owner may raise it to ${cap} without asking anyone.`)}\n` +
+        `                 ${dim(`  \`abx set-royalty-cap ${address} --cap ${rateBps}\` makes today's rate permanent.`)}`);
+}
+/**
+ * What a `canonical: NO` actually costs, said once and shared by both state readouts.
+ *
+ * A contract deployed outside a trust anchor is a real, working NFT — this is not a failure — but the
+ * one property it can never gain is the one platforms allowlist against, and it cannot be granted
+ * later at any price: canonicity is fixed at deploy by WHICH contract created it. So the readout says
+ * what was lost and what the only remedy is (redeploy through the factory, migrate holders), rather
+ * than printing a bare "NO" the reader has to interpret.
+ */
+function warnNotCanonical(address) {
+    warn(`${address} was not created by an ABX trust anchor, so ${bold('isAbxClone is false')} for it. It still works as ` +
+        `an NFT, but nothing that allowlists ABX collections — marketplaces, the App Store, this toolkit's own ` +
+        `provenance checks — can recognize it as one, and that cannot be added afterwards: canonicity is decided ` +
+        `by which contract deployed it. The only remedy is a fresh deploy through ${bold('abx deploy')} / ` +
+        `${bold('deploy-series')} / ${bold('deploy-code')} and moving holders to it. If this was deliberate ` +
+        `(a bespoke contract, a superseded factory), nothing here is broken — just make sure whoever owns the ` +
+        `project knows they chose it.`);
+}
+export async function cmdState(address, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx state <address>  — a read-only, on-chain operational snapshot\n');
+        process.exitCode = 1;
+        return;
+    }
+    // `--json` emits the same facts as data (B19: a value a program needs must be obtainable without
+    // parsing prose). The human narration below is unchanged and rides stderr under --json.
+    return withJson(flags, async (emit) => cmdStateBody(address, flags, emit));
+}
+export async function cmdStateBody(address, flags, emit) {
+    const publicClient = makePublicClient({ chainKey: CHAIN });
+    // Edition family branches to its own (leaner) readout — supply/maxSupply are per-id, so "supply
+    // X/Y minted" (a whole-contract fact on a 721) doesn't generalize; see cmdStateEditionBody.
+    const kind = await detectTokenKind(publicClient, address);
+    if (kind.isEdition)
+        return cmdStateEditionBody(address, publicClient, kind, emit);
+    // getter absent (extension not composed) or contract has no code → undefined, never a throw.
+    const read = (functionName, args = []) => tryReadContract(publicClient, { address, abi: STATE_ABI, functionName, args });
+    const [owner, totalSupply, nextTokenId, maxInvocations, paused, minter, primaryPayee, renderer, royalty, creatorToken, transferValidator, seedSource] = await Promise.all([
+        read('owner'),
+        read('totalSupply'),
+        read('nextTokenId'),
+        read('maxInvocations'),
+        read('paused'),
+        read('minter'),
+        read('primaryPayee'),
+        read('tokenURIRenderer'),
+        read('royaltyInfo', [0n, 10000n]),
+        read('supportsInterface', [CREATOR_TOKEN_INTERFACE_ID]),
+        read('getTransferValidator'),
+        read('seedSource'),
+    ]);
+    if (owner === undefined && totalSupply === undefined) {
+        throw new Error(`no ABX contract state at ${address} on ${CHAIN} (no code, or not an ABX token).`);
+    }
+    // Trust, not just shape. Everything above is readable off ANY ERC-721-ish address, so without this
+    // `state` described a hand-rolled contract exactly as confidently as a canonical clone. Canonicity
+    // is what platforms allowlist and it can never be added after deploy, so it belongs in the snapshot.
+    const provenance = await verifyProvenance(publicClient, address, resolveChain(CHAIN).id);
+    const isCanonical = provenance.canonical;
+    const isSeries = maxInvocations !== undefined; // series-only getter
+    const addrOrNone = (a) => (a && a !== zeroAddress ? a : dim('none'));
+    // The payload mirrors what is printed, with `undefined` (getter absent) kept distinct from a zero
+    // address (present and deliberately unset) — collapsing those is what makes a readout lie.
+    const zeroToNull = (a) => (a === undefined ? null : a === zeroAddress ? null : a);
+    const { maxRoyaltyBps: royaltyCap, burnable } = await readCollectionPolicy(publicClient, address);
+    const payload = jsonSafe({
+        address,
+        chain: CHAIN,
+        chainId: resolveChain(CHAIN).id,
+        type: isSeries ? 'series' : '1of1',
+        canonical: isCanonical, // tri-state: true | false | null (couldn't check) — never collapse it
+        // Provenance, not just trust: WHICH generation of the anchors stamped this clone, and the core
+        // version it therefore reports. `prior` is "canonically ABX, older" — a different fact from
+        // `canonical: false`, which the two used to share.
+        abxGeneration: provenance.generation,
+        abxCoreVersion: provenance.coreVersion,
+        owner: owner ?? null,
+        totalSupply: totalSupply ?? null,
+        nextTokenId: nextTokenId ?? null,
+        maxInvocations: maxInvocations ?? null,
+        paused: paused ?? null,
+        minter: zeroToNull(minter),
+        primaryPayee: zeroToNull(primaryPayee),
+        tokenURIRenderer: zeroToNull(renderer),
+        onChainTokenUri: !!(renderer && renderer !== zeroAddress),
+        royalty: royalty ? { receiver: royalty[0], bps: Number(royalty[1]) } : null,
+        royaltyCap,
+        burnable,
+        creatorToken: !!creatorToken,
+        transferValidator: creatorToken ? zeroToNull(transferValidator) : null,
+        // `undefined` (no extension — an image token) and `0x0` (a code project that opted out) are
+        // different facts; the JSON keeps them apart the same way every other getter here does.
+        seedSource: zeroToNull(seedSource),
+        hasSeedSource: seedSource !== undefined,
+        params: { governed: [], contractScopeSet: [] },
+    });
+    emit(payload);
+    console.log(bold(`\n  ${isSeries ? 'Series' : '1/1'} state`) + dim(`  ${address} · ${CHAIN}`));
+    info(`canonical      ${canonicalLabel(isCanonical, provenance)}`);
+    if (isCanonical === false)
+        warnNotCanonical(address);
+    info(`owner          ${owner ?? dim('?')}`);
+    if (isSeries) {
+        // Fully minted (totalSupply == maxInvocations) ⇒ fixed supply exhausted: the collection is
+        // COMPLETE and `unpause` is moot (nothing left for anyone to mint). Say so, so a fully-minted
+        // paused series doesn't read as "unfinished, go unpause".
+        const soldOut = totalSupply !== undefined && maxInvocations !== undefined && totalSupply >= maxInvocations;
+        info(`supply         ${totalSupply ?? 0n} / ${maxInvocations} minted   ${dim(soldOut ? '(complete — fixed supply fully minted)' : `(nextTokenId ${nextTokenId ?? 0n})`)}`);
+        info(`paused         ${paused ? `${c.orange}true${c.reset}  ${dim(soldOut ? '— moot: all tokens minted, nothing left to mint' : '— owner-only minting until `abx unpause`')}` : `false ${dim('— open to minter/public')}`}`);
+        info(`minter         ${addrOrNone(minter)}${minter && minter !== zeroAddress ? '' : dim('  (owner-only)')}`);
+        info(`primary payee  ${addrOrNone(primaryPayee)}`);
+    }
+    else {
+        info(`supply         ${totalSupply ?? 0n} / 1 minted`);
+    }
+    if (royalty)
+        info(`royalty        ${Number(royalty[1]) / 100}% → ${royalty[0]}`);
+    if (royaltyCap !== null)
+        info(`royalty cap    ${royaltyCapLine(address, royaltyCap, royalty ? Number(royalty[1]) : null)}`);
+    if (burnable !== null)
+        info(`burnable       ${burnable ? `${c.orange}true${c.reset} ${dim('— holders may burn their own token')}` : dim('false — no token can be destroyed')}`);
+    info(`renderer       ${renderer && renderer !== zeroAddress ? `on-chain (${renderer})` : dim('off-chain (stored URI base / override)')}`);
+    // ERC-721C: shown ONLY for an enrolled collection — an unenrolled token is a plain ERC-721
+    // (indistinguishable from a pre-721C token) and shows nothing new here.
+    if (creatorToken) {
+        info(`721C validator ${transferValidator && transferValidator !== zeroAddress ? transferValidator : `${c.orange}suspended${c.reset} ${dim('(zero — enforcement off; re-enable with `abx set-transfer-validator`)')}`}`);
+    }
+    if (seedSource !== undefined)
+        info(`seed source    ${describeSeedSource(seedSource)}`);
+    // The PostParam surface, read straight from chain: `paramSchemaKeys()` is the DECLARED (governed)
+    // set — append-only, and it includes keys declared but never yet written, which nothing off-chain
+    // could otherwise discover — and `contractParamKeys()` is the collection-scope set values. Both
+    // are maintained by the contract's own write paths, so there is no list to drift. Read-only,
+    // best-effort, and skipped entirely for a project that has none (a 1/1, a legacy pre-enumeration
+    // project, or a code project with no params).
+    try {
+        const keys = (await readParamSchemaKeys(publicClient, address)) ?? [];
+        const rows = keys.length
+            ? await Promise.all(keys.map(async (key) => ({ key, s: await readParamSchema(publicClient, address, key) })))
+            : [];
+        const governed = rows.filter((r) => r.s.exists);
+        const now = Math.floor(Date.now() / 1000);
+        payload.params.governed = jsonSafe(governed.map(({ key, s }) => ({
+            key,
+            // Canonical NAMES, not the raw enum indices — a caller must not have to know the Solidity
+            // enum's ordering to read this (the same reason `retired` is a boolean below).
+            paramType: PARAM_TYPES[s.paramType] ?? String(s.paramType),
+            auth: AUTH_OPTIONS[s.auth] ?? String(s.auth),
+            authAddress: s.authAddress === zeroAddress ? null : s.authAddress,
+            lockAfter: s.lockAfter,
+            // A past lockAfter IS how a param is retired — surfaced as a boolean so a caller doesn't
+            // have to re-derive the convention from a timestamp.
+            retired: s.lockAfter !== 0 && s.lockAfter < now,
+            selectOptions: s.selectOptions,
+        })));
+        emit(payload);
+        if (governed.length) {
+            console.log(`\n  ${bold('PostParams')}  ${dim(`${governed.length} governed · collectors/creator set these; the generator injects them`)}`);
+            for (const { key, s } of governed) {
+                const retired = s.lockAfter !== 0 && s.lockAfter < now;
+                const locks = s.lockAfter !== 0 && !retired ? dim(`  locks ${new Date(s.lockAfter * 1000).toISOString().slice(0, 10)}`) : '';
+                const tag = retired ? `  ${c.orange}retired${c.reset}${dim(' — writes revert')}` : locks;
+                console.log(`    ${describeSchema({ key, paramType: s.paramType, auth: s.auth, authAddress: s.authAddress, lockAfter: 0, min: s.min, max: s.max, selectOptions: s.selectOptions })}${tag}`);
+            }
+        }
+        // Collection-scope values (every token sees these). `seed` is per-token and never enumerated —
+        // it is a tokenData coordinate, read directly.
+        const set = await readSetParamKeys(publicClient, address);
+        if (set?.contract.length) {
+            payload.params.contractScopeSet = [...set.contract].sort();
+            emit(payload);
+            info(`${dim('contract-scope params set:')} ${[...set.contract].sort().join(', ')} ${dim('(apply to every token)')}`);
+        }
+        // The hooks, and whether they can still change. This is a BUYER's read, which is why it lives in
+        // `state` next to the validator rather than only in `verify`: the transfer hook is a veto over
+        // transfers and mints, so "which hooks, and are they frozen" is exactly the pair someone needs
+        // before buying. Printed whenever the surface exists — including with all three unset, because
+        // "none, and frozen" is the strongest thing this line can say and it must be visible.
+        const hooks = await readParamHooks(publicClient, address);
+        if (hooks) {
+            const locked = await readParamHooksLocked(publicClient, address);
+            const shown = [['configure', hooks.configureHook], ['augment', hooks.augmentHook], ['transfer', hooks.transferHook]]
+                .filter(([, a]) => a !== zeroAddress)
+                .map(([role, a]) => `${role} ${a}`);
+            payload.params.hooks = jsonSafe({
+                configureHook: hooks.configureHook === zeroAddress ? null : hooks.configureHook,
+                augmentHook: hooks.augmentHook === zeroAddress ? null : hooks.augmentHook,
+                transferHook: hooks.transferHook === zeroAddress ? null : hooks.transferHook,
+                // `null` = could not be established (see readParamHooksLocked). Never collapse it to false:
+                // "unknown" and "the owner can still arm a transfer veto" are different answers.
+                locked: locked ?? null,
+            });
+            emit(payload);
+            const lockNote = locked === true
+                ? `${c.green}frozen${c.reset} ${dim('— no hook address can ever change again')}`
+                : locked === false
+                    ? `${c.orange}not frozen${c.reset} ${dim('— the owner can re-point these (`abx lock-param-hooks` freezes them forever)')}`
+                    : dim('freeze state unknown (the node refused the check)');
+            info(`param hooks    ${shown.length ? shown.join(' · ') : dim('none set')}   ${lockNote}`);
+            if (hooks.transferHook !== zeroAddress) {
+                info(dim(`               the transfer hook is a VETO: if it reverts, the transfer fails — and mints too (mint = transfer from 0x0).`));
+            }
+        }
+    }
+    catch {
+        /* best-effort — a non-code project has no params surface to read */
+    }
+    console.log('');
+}
+/**
+ * The edition (ERC-1155) half of {@link cmdStateBody}: `owner`/`paused`/`minter`/`primaryPayee`/
+ * `royalty`/`renderer` are the SAME facts, read the SAME way (shared, unchanged function names);
+ * what differs is supply — there's no whole-contract `totalSupply()`, only a per-id one, so the
+ * headline is id #0's copies (the flagship OneOfOneEdition case, and a representative sample for
+ * EditionImage/EditionCode) with a pointer at `abx tokens` for the full per-id breakdown.
+ */
+async function cmdStateEditionBody(address, publicClient, kind, emit) {
+    const read = (functionName, args = []) => tryReadContract(publicClient, { address, abi: EDITION_STATE_ABI, functionName, args });
+    const [owner, maxInvocations, paused, minter, primaryPayee, renderer, royalty, creatorToken, transferValidator, seedSource] = await Promise.all([
+        read('owner'),
+        read('maxInvocations'), // absent on a 1/1-edition — its id space is fixed to {0}
+        read('paused'),
+        read('minter'),
+        read('primaryPayee'),
+        read('tokenURIRenderer'),
+        read('royaltyInfo', [0n, 10000n]),
+        read('supportsInterface', [CREATOR_TOKEN_INTERFACE_ID]),
+        read('getTransferValidator'),
+        read('seedSource'),
+    ]);
+    if (owner === undefined)
+        throw new Error(`no ABX contract state at ${address} on ${CHAIN} (no code, or not an ABX token).`);
+    const [supply0, maxSupply0, provenance] = await Promise.all([
+        read('totalSupply', [0n]),
+        read('maxSupply', [0n]),
+        verifyProvenance(publicClient, address, resolveChain(CHAIN).id), // the edition twin owes the same answer
+    ]);
+    const isCanonical = provenance.canonical;
+    const addrOrNone = (a) => (a && a !== zeroAddress ? a : dim('none'));
+    const zeroToNull = (a) => (a === undefined ? null : a === zeroAddress ? null : a);
+    const { maxRoyaltyBps: royaltyCap, burnable } = await readCollectionPolicy(publicClient, address);
+    const payload = jsonSafe({
+        address,
+        chain: CHAIN,
+        chainId: resolveChain(CHAIN).id,
+        type: kind.kind,
+        canonical: isCanonical, // tri-state, same as the 721 readout
+        abxGeneration: provenance.generation,
+        abxCoreVersion: provenance.coreVersion,
+        owner: owner ?? null,
+        maxInvocations: maxInvocations ?? null,
+        supply0: supply0 ?? null,
+        maxSupply0: maxSupply0 ?? null,
+        paused: paused ?? null,
+        minter: zeroToNull(minter),
+        primaryPayee: zeroToNull(primaryPayee),
+        tokenURIRenderer: zeroToNull(renderer),
+        onChainTokenUri: !!(renderer && renderer !== zeroAddress),
+        royalty: royalty ? { receiver: royalty[0], bps: Number(royalty[1]) } : null,
+        royaltyCap,
+        burnable,
+        creatorToken: !!creatorToken,
+        transferValidator: creatorToken ? zeroToNull(transferValidator) : null,
+        seedSource: zeroToNull(seedSource),
+        hasSeedSource: seedSource !== undefined,
+    });
+    emit(payload);
+    console.log(bold(`\n  ${describeKind(kind)} state`) + dim(`  ${address} · ${CHAIN}`));
+    info(`canonical      ${canonicalLabel(isCanonical, provenance)}`);
+    if (isCanonical === false)
+        warnNotCanonical(address);
+    info(`owner          ${owner ?? dim('?')}`);
+    const capNote = (cap) => (cap !== undefined && cap > 0n ? `${cap} cap` : 'open — no cap');
+    if (kind.kind === '1of1-edition') {
+        info(`supply         ${supply0 ?? 0n} cop${(supply0 ?? 0n) === 1n ? 'y' : 'ies'} of #0   ${dim(`(${capNote(maxSupply0)})`)}`);
+    }
+    else {
+        info(`id space       up to ${maxInvocations ?? '?'} distinct id(s)`);
+        info(`#0 copies      ${supply0 ?? 0n}   ${dim(`(${capNote(maxSupply0)} — per-id breakdown: \`abx tokens ${address}\`)`)}`);
+    }
+    info(`paused         ${paused ? `${c.orange}true${c.reset}  ${dim('— owner-only minting until `abx unpause`')}` : `false ${dim('— open to minter/public')}`}`);
+    info(`minter         ${addrOrNone(minter)}${minter && minter !== zeroAddress ? '' : dim('  (owner-only)')}`);
+    info(`primary payee  ${addrOrNone(primaryPayee)}`);
+    if (royalty)
+        info(`royalty        ${Number(royalty[1]) / 100}% → ${royalty[0]}`);
+    if (royaltyCap !== null)
+        info(`royalty cap    ${royaltyCapLine(address, royaltyCap, royalty ? Number(royalty[1]) : null)}`);
+    if (burnable !== null)
+        info(`burnable       ${burnable ? `${c.orange}true${c.reset} ${dim('— holders may burn their own token')}` : dim('false — no token can be destroyed')}`);
+    info(`renderer       ${renderer && renderer !== zeroAddress ? `on-chain (${renderer})` : dim('off-chain (stored URI base / override)')}`);
+    // ERC-1155C: shown ONLY for an enrolled collection — same rule (and same interface id) as 721C.
+    if (creatorToken) {
+        info(`1155C validator ${transferValidator && transferValidator !== zeroAddress ? transferValidator : `${c.orange}suspended${c.reset} ${dim('(zero — enforcement off; re-enable with `abx set-transfer-validator`)')}`}`);
+    }
+    if (seedSource !== undefined)
+        info(`seed source    ${describeSeedSource(seedSource)}`);
+    // EditionCode composes ConfigurableParams exactly like SeriesCode, so an edition has hooks too —
+    // and the transfer hook's veto reaches a mint, which on this lane is a buyer picking an id. Report
+    // the same pair as the 721 body (which hooks, and whether they can still change); silent for the
+    // image/1-of-1 edition twins, which have no params surface at all.
+    const hooks = await readParamHooks(publicClient, address);
+    if (hooks) {
+        const locked = await readParamHooksLocked(publicClient, address);
+        const shown = [['configure', hooks.configureHook], ['augment', hooks.augmentHook], ['transfer', hooks.transferHook]]
+            .filter(([, a]) => a !== zeroAddress)
+            .map(([role, a]) => `${role} ${a}`);
+        payload.paramHooks = jsonSafe({
+            configureHook: hooks.configureHook === zeroAddress ? null : hooks.configureHook,
+            augmentHook: hooks.augmentHook === zeroAddress ? null : hooks.augmentHook,
+            transferHook: hooks.transferHook === zeroAddress ? null : hooks.transferHook,
+            locked: locked ?? null, // null = unknown; never collapse it to false
+        });
+        emit(payload);
+        const lockNote = locked === true
+            ? `${c.green}frozen${c.reset} ${dim('— no hook address can ever change again')}`
+            : locked === false
+                ? `${c.orange}not frozen${c.reset} ${dim('— the owner can re-point these (`abx lock-param-hooks` freezes them forever)')}`
+                : dim('freeze state unknown (the node refused the check)');
+        info(`param hooks    ${shown.length ? shown.join(' · ') : dim('none set')}   ${lockNote}`);
+        if (hooks.transferHook !== zeroAddress) {
+            info(dim(`               the transfer hook is a VETO: if it reverts, the transfer fails — and mints too (mint = transfer from 0x0).`));
+        }
+    }
+    console.log('');
+}
+/**
+ * `abx status [address] [--remote [name|url]] [--watch]` — INDEXING status: where a project sits in
+ * the lifecycle (`queued | backfilling | live | stale | failed`) and how far behind head it is.
+ *
+ * One vocabulary for both sides of the membrane, which is the point: bare = this node, `--remote` =
+ * ask the service, and the same five words either way. Distinct from `abx state <address>`, which
+ * reads the CHAIN (owner, royalty, locks) and knows nothing about who is serving it.
+ */
+export async function cmdStatus(address, flags) {
+    // `abx status --remote <name>` has no address — without this guard the flag itself lands in
+    // rest[0] and gets sent as the address path segment (the same guard every other command applies).
+    if (address?.startsWith('--'))
+        address = undefined;
+    const remote = remoteFlag(flags);
+    if (remote)
+        return cmdStatusRemote(address, remote, flags);
+    const indexer = localIndexer();
+    const regs = indexer.store.listRegistrations();
+    if (address) {
+        const reg = indexer.store.getRegistration(address);
+        if (!reg)
+            throw new Error(`${address} isn't tracked by this node. Add it with \`abx add ${address}\`, or ask a service: \`abx status ${address} --remote <name>\``);
+        const s = indexer.getProject(address);
+        const row = indexer.indexStatus(address);
+        const head = indexer.store.getMeta(`watch:${reg.chainKey}:head`);
+        // Don't print the address twice when there's no name to lead with.
+        console.log(s?.name ? `\n  ${bold(s.name)}  ${dim(address)}` : `\n  ${bold(address)}`);
+        statusRow('status', statusLine({
+            chainId: resolveChain(reg.chainKey).id,
+            address,
+            status: row.status,
+            fromBlock: reg.fromBlock,
+            toBlock: s?.toBlock ?? null,
+            headBlock: head,
+            eventCount: s?.eventCount ?? 0,
+            tokenCount: s?.tokens.length ?? 0,
+            mintedCount: 0,
+            reconstructedAt: s?.reconstructedAt ?? null,
+            ...(row.errorClass ? { error: { class: row.errorClass, message: row.errorMessage ?? undefined } } : {}),
+        }));
+        statusRow('floor', `${reg.fromBlock}${row.attempts ? dim(`   attempts ${row.attempts}`) : ''}`);
+        statusRow('indexed', s ? `${s.eventCount} events · ${s.tokens.length} token(s) ${dim(`· ${s.reconstructedAt}`)}` : dim('no projection yet'));
+        if (!head)
+            statusRow('head', dim("unknown — this node isn't watching the chain (ABX_WATCH_INTERVAL_MS=0, or `abx serve` isn't running)"));
+        console.log('');
+        return;
+    }
+    console.log(bold(`\n  ABX self-host node`));
+    info(`chain: ${CHAIN} · factory: ${factoryAddress() ?? 'none'} · storage: ${activeBackendId()} · data: ${indexer.store.path}`);
+    if (regs.length === 0) {
+        console.log(dim('\n  No projects yet. `abx demo` to create one.\n'));
+        return;
+    }
+    console.log('');
+    for (const reg of regs) {
+        const s = indexer.getProject(reg.address);
+        const st = indexer.indexStatus(reg.address).status;
+        const mark = st === 'failed' || st === 'stale' ? `${c.orange}●${c.reset}` : s ? g('●') : dim('○');
+        const tail = s ? `${s.eventCount} events` : dim('(registered, not indexed)');
+        console.log(`  ${mark} ${s?.name ?? reg.address}  ${dim(reg.address)}  ${tail}  ${statusLabel(st)}`);
+    }
+    console.log(dim(`\n  one project in detail: abx status <address>\n`));
+}
+/** The `--remote` half of {@link cmdStatus}: one project, or the roll-up for every project the token
+ *  can see. `--watch` tails until everything reaches a terminal state. */
+export async function cmdStatusRemote(address, remote, flags) {
+    requireRemoteToken(remote);
+    const client = serviceClient(remote);
+    const chainId = resolveChain(CHAIN).id;
+    const watch = flags.watch !== undefined;
+    const spec = remote.name ? remote.name.toLowerCase() : remote.source === 'default' ? '' : remote.url;
+    info(`${bold('REMOTE')} → ${remote.url}  ${dim('(indexing status as the service reports it)')}`);
+    if (address) {
+        for (;;) {
+            let s;
+            try {
+                s = await client.projectStatus(chainId, address);
+            }
+            catch (err) {
+                throw describeRemoteError(err, remote, 'remote status');
+            }
+            console.log(`\n  ${bold(address)}`);
+            statusRow('status', statusLine(s));
+            statusRow('floor', `${s.fromBlock}${s.attempts ? dim(`   attempts ${s.attempts}`) : ''}`);
+            statusRow('indexed', `${s.eventCount} events · ${s.tokenCount} token(s)${s.reconstructedAt ? dim(` · ${s.reconstructedAt}`) : ''}`);
+            // Spell out what `watching` MEANS on the line itself — a bare `no` sent a reviewer to a
+            // different command's output to find out whether it was a problem (it usually isn't).
+            if (s.watcher) {
+                statusRow('watching', s.watcher.watching
+                    ? `${g('yes')}${s.watcher.head ? dim(` · head ${s.watcher.head}`) : ''}${dim(' — it tails new blocks, so on-chain changes land on their own')}`
+                    : `${dim('no')} ${dim('— this service updates on an explicit add/index, not by tailing new blocks (normal for many providers)')}`);
+            }
+            // Don't leave a creator staring at a red word with no next move. `failed` especially reads as
+            // terminal when it isn't — name what it means and the one command that follows it.
+            if (!watch && s.status !== 'live') {
+                if (s.status === 'failed' && s.error)
+                    statusRow('what now', indexErrorAction(s.error.class));
+                statusRow('follow', dim(`this is not final — ${bold(`abx status ${address} --remote${spec ? ` ${spec}` : ''} --watch`)} tails it until it settles`));
+            }
+            console.log('');
+            if (!watch || s.status === 'live' || s.status === 'failed')
+                return;
+            await sleep(3000);
+        }
+    }
+    for (;;) {
+        let projects;
+        try {
+            projects = await client.listProjects();
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote status');
+        }
+        if (projects.length === 0) {
+            console.log(dim('\n  no projects visible to this token\n'));
+            return;
+        }
+        console.log('');
+        for (const p of projects) {
+            console.log(`  ${g('●')} ${p.name ?? p.label ?? p.address}  ${dim(p.address)}  ` +
+                `${p.status ? statusLabel(p.status) : dim('status not reported')}` +
+                `${p.error ? ` ${c.orange}${p.error.class}${c.reset}` : ''}  ${dim(`${p.tokenCount ?? '?'} token(s)`)}`);
+        }
+        console.log(`\n  ${rollUp(projects)}\n`);
+        const settled = projects.every((p) => !p.status || p.status === 'live' || p.status === 'failed');
+        if (!watch || settled)
+            return;
+        await sleep(3000);
+    }
+}
+// ── forget ────────────────────────────────────────────────────────────────--
+// Drop a project this node tracks (registration + projection) — for cleaning up
+// test/junk deploys. On-chain data is untouched; `abx add` can re-register it.
+export async function cmdForget(address, flags) {
+    if (!address || address.startsWith('--')) {
+        console.error('usage: abx forget <address> [--remote [name|url]]\n');
+        process.exitCode = 1;
+        return;
+    }
+    const remote = remoteFlag(flags);
+    if (remote) {
+        requireRemoteToken(remote);
+        info(`${bold('REMOTE')} → ${remote.url}  ${dim('(deregistering on the remote resolver — NOT this machine)')}`);
+        let removed;
+        try {
+            ({ removed } = await serviceClient(remote).removeProject(resolveChain(CHAIN).id, address));
+        }
+        catch (err) {
+            throw describeRemoteError(err, remote, 'remote forget');
+        }
+        if (removed)
+            ok(`remote resolver forgot ${address} — it will stop serving it. On-chain data is untouched.`);
+        else
+            console.log(dim(`  ${address} wasn't registered on ${remote.url} — nothing to forget.`));
+        return;
+    }
+    const indexer = localIndexer();
+    if (!indexer.store.getRegistration(address)) {
+        console.log(dim(`  ${address} isn't tracked by this node — nothing to forget.`));
+        return;
+    }
+    indexer.store.deregister(address);
+    ok(`forgot ${address} — dropped its registration + projection. On-chain data is untouched.`);
+}
+//# sourceMappingURL=project.js.map