@artblocks/abx-cli 0.1.0-alpha.40 → 0.1.0-alpha.41

package/dist/commands/project.js

@@ -6,12 +6,12 @@
  */
 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, rpcEnvVar, tryReadContract, } from '@artblocks/abx-sdk';
+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, rpcEnvVar, tryReadContract, encodeTag, METADATA_FIELD, METADATA_REPRESENTATION, fieldOf, isCurrentRenderer, isCurrentGenerator, } 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 { isDryRun, parseBlockTagFlag, 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';
@@ -239,14 +239,20 @@ export async function cmdIndex(address, flags) {
     }
     allowLargeScan(flags);
     const full = !!flags.full; // force a full replay from the deploy block (durability proof)
+    // Stop the scan at a REORG-SAFE boundary instead of the head. `latest` (the default) can include
+    // blocks that a reorg later replaces, which would persist a watermark for history that no longer
+    // exists; `safe`/`finalized` trade freshness for a boundary the chain won't take back. Resolved to
+    // a concrete block number before scanning (see resolveBlockTag) — a stored watermark is always a
+    // number, never a tag.
+    const blockTag = parseBlockTagFlag(flags['to-block']);
     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 });
+        const { state, elapsedMs, mode } = await indexer.reindex(address, { full, blockTag });
         line(state, elapsedMs, mode);
         return;
     }
-    const results = await indexer.reindexAll({ full });
+    const results = await indexer.reindexAll({ full, blockTag });
     if (results.length === 0) {
         console.log(dim('No registered projects. Deploy one with `abx deploy`.'));
         return;
@@ -266,13 +272,79 @@ export async function cmdVerify(address, flags) {
     }
     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. The payload's `ok` is the same
     // boolean the exit code carries; callers never need to parse prose.
+    //
+    // The remote lane used to route around `withJson` entirely (`return cmdVerifyRemote(address,
+    // remote)`), so `abx verify <addr> --remote <r> --json` printed the same human prose as without
+    // the flag and emitted NOTHING on stdout — the one lane of this command a CI job is most likely
+    // to run (checking what a HOSTED resolver serves) had no machine-readable output at all. Both
+    // lanes now go through the same `withJson` wrapper and emit the same payload shape.
+    if (remote)
+        return withJson(flags, async (emit) => cmdVerifyRemote(address, remote, emit));
     return withJson(flags, async (emit) => cmdVerifyBody(address, flags, emit));
 }
+/**
+ * Pure by design — every caller (`cmdVerifyBody`'s local lane and `cmdVerifyRemote`'s hosted lane)
+ * feeds it facts it already gathered rather than each re-deriving its own verdict, so the two
+ * lanes' JSON payloads read the same word for the same situation.
+ *
+ * `isCode` selects which signal decides the verdict: a code project's render presence
+ * (`minted`/`present`), or — for everything else — whether a byte-check actually ran
+ * (`anyCheck`) versus a locator this run could not independently re-hash (`unrecomputablePointers`).
+ * The two signals are never combined into one number on purpose: "3 of 5 renders present" and "2
+ * locator commitments unconfirmed" are different facts about different projects, and mixing them
+ * would produce a verdict that answers neither question honestly.
+ */
+export function computeAvailability(opts) {
+    if (opts.isCode) {
+        if (opts.minted === 0)
+            return { status: 'unknown', note: 'no tokens minted yet — nothing to render' };
+        if (opts.present === opts.minted)
+            return { status: 'available', note: `${opts.present}/${opts.minted} minted token(s) have a real render` };
+        if (opts.present === 0)
+            return { status: 'unavailable', note: `0/${opts.minted} minted token(s) have a real render — every one is still a placeholder` };
+        return { status: 'partial', note: `${opts.present}/${opts.minted} minted token(s) have a real render` };
+    }
+    if (opts.anyCheck) {
+        return { status: 'available', note: 'served bytes were fetched and compared against the on-chain commitment (see `ok` for whether they matched)' };
+    }
+    if (opts.unrecomputablePointers > 0) {
+        return {
+            status: 'unknown',
+            note: `${opts.unrecomputablePointers} locator commitment(s) (ipfs/arweave/url) exist but were not independently re-fetched by this command`,
+        };
+    }
+    return { status: 'available', note: 'no content commitments on this project — nothing to serve' };
+}
+/** Locator representations `verifyProject` never emits a check for (only `keccak256`/`sha256`
+ *  fields get one) — a real commitment this command cannot re-hash from the field alone: ipfs/
+ *  arweave carry a content-addressed locator this run doesn't fetch, and url/url-template carry
+ *  no hash at all. Reported as a `verified: null` entry, same tri-state slot a hash check uses,
+ *  so a caller sees ONE consistent shape rather than silence for these tokens. */
+const POINTER_REPRESENTATIONS = new Set([
+    METADATA_REPRESENTATION.ipfs,
+    METADATA_REPRESENTATION.arweave,
+    METADATA_REPRESENTATION.url,
+    METADATA_REPRESENTATION.urlTemplate,
+]);
+/**
+ * Does this token's `image` field carry a locator commitment `verifyProject` never produced a
+ * check for? Exported and pure (a plain `fields` array in, a verdict out — no chain, no indexer)
+ * so #112's three-way distinction is unit-testable directly, rather than only reachable through a
+ * full `cmdVerifyBody` run against real chain state.
+ *
+ * Returns the representation name to report (`ipfs`/`arweave`/`url`/`url-template`) when the image
+ * field is a bare locator, else `null` — including when there's no `image` field at all, which is
+ * "no commitment", a different fact from "an unrecomputable one".
+ */
+export function pointerOnlyImageCheck(fields) {
+    const image = fieldOf(fields, METADATA_FIELD.image);
+    if (image && POINTER_REPRESENTATIONS.has(image.representation))
+        return image.representation;
+    return null;
+}
 export async function cmdVerifyBody(address, flags, emit) {
     const indexer = localIndexer();
     let state = indexer.getProject(address);
@@ -296,6 +368,9 @@ export async function cmdVerifyBody(address, flags, emit) {
         renders: null,
         onChainUri: null,
         ok: true,
+        // A SIBLING of `ok`, not a rename — see `computeAvailability`'s doc comment for why the two
+        // must never collapse into one bit. Filled in below, once the facts it's computed from exist.
+        availability: null,
     };
     emit(verifyReport);
     console.log(bold(`\n  verify ${state.name ?? address}`));
@@ -309,6 +384,12 @@ export async function cmdVerifyBody(address, flags, emit) {
     const tokens = result.tokens ?? [];
     let anyCheck = false;
     let allGood = true;
+    // Locator commitments (ipfs/arweave/url/url-template `image` fields) `verifyProject` never
+    // produces a check for — see `POINTER_REPRESENTATIONS`'s doc comment. Counted SEPARATELY from
+    // `anyCheck`/`allGood` on purpose: a pointer this command didn't re-fetch is not an integrity
+    // verdict either way, so it must never move `contentIntegrity`/`ok` — it feeds `availability`
+    // instead, below.
+    let unrecomputablePointers = 0;
     for (const t of tokens) {
         const tok = state.tokens.find((s) => s.tokenId === t.tokenId);
         const life = tok?.lifecycle === 'live'
@@ -339,8 +420,27 @@ export async function cmdVerifyBody(address, flags, emit) {
             else
                 info(`${ch.kind} — pointer-only, not locally recomputable`);
         }
+        // `verifyProject` only ever emits a check for a keccak256/sha256-committed `image` field, so a
+        // token whose image is a bare LOCATOR (ipfs/arweave/url/url-template) gets `t.checks === []` —
+        // indistinguishable, before this, from "no commitment at all". That was the real gap #112
+        // named: a real, independently-lockable commitment silently read as nothing. Surface it as the
+        // same tri-state slot a hash check uses (`verified: null`), so a caller sees one consistent
+        // shape instead of two different kinds of silence.
+        if (t.checks.length === 0 && tok) {
+            const pointerKind = pointerOnlyImageCheck(tok.fields);
+            if (pointerKind) {
+                unrecomputablePointers++;
+                verifyReport.contentChecks.push({
+                    tokenId: t.tokenId,
+                    lifecycle: tok.lifecycle,
+                    kind: pointerKind,
+                    verified: null,
+                });
+                info(`${pointerKind} — pointer-only, not locally recomputable (no outbound fetch from this command)`);
+            }
+        }
     }
-    if (!anyCheck && !isCodeProject(state))
+    if (!anyCheck && unrecomputablePointers === 0 && !isCodeProject(state))
         info('no content commitments on this project');
     verifyReport.contentIntegrity = !anyCheck ? 'no-commitments' : allGood ? 'ok' : 'mismatch';
     verifyReport.ok = !anyCheck || allGood;
@@ -351,6 +451,9 @@ export async function cmdVerifyBody(address, flags, emit) {
     // 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;
+    // Hoisted above the `isCodeProject` branch: `availability` (computed right after it, whether or
+    // not this project turns out to be a code project) needs the render counts that branch produces.
+    let codeRenders = null;
     if (isCodeProject(state)) {
         const client = makePublicClient({ chainKey: CHAIN });
         const storageForRender = resolveBackend(storageOptions());
@@ -439,6 +542,7 @@ export async function cmdVerifyBody(address, flags, emit) {
             // there, not here, so `missing` is a false negative for a hosted drop — hence the scope.
             scope: "this node's store",
         };
+        codeRenders = { minted: minted.length, present };
         emit(verifyReport);
         if (present)
             ok(`${present}/${minted.length} minted token(s): real render present (in this node's store)`);
@@ -450,6 +554,16 @@ export async function cmdVerifyBody(address, flags, emit) {
             console.log(`      ${dim('else render them:')} ${bold(`abx render ${address}`)} ${dim('(once) ·')} ${bold('abx effects')} ${dim('(continuous)')}`);
         }
     }
+    // The availability verdict — computed here, after both the byte-integrity pass and the render
+    // pass above have run, from facts they already gathered (no new reads). See `computeAvailability`.
+    verifyReport.availability = jsonSafe(computeAvailability({
+        isCode: isCodeProject(state),
+        minted: codeRenders?.minted ?? 0,
+        present: codeRenders?.present ?? 0,
+        anyCheck,
+        unrecomputablePointers,
+    }));
+    emit(verifyReport);
     // 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
@@ -465,9 +579,23 @@ export async function cmdVerifyBody(address, flags, emit) {
         try {
             const report = await onChainUriReport(client, state, flags.generator);
             const { status, probe } = report;
+            // #128: the factory-generation half of "is this pinned to a superseded deployment" already
+            // ships (ANCHOR_GENERATIONS + verifyCanonical, in the `canonical`/`abxGeneration` line above);
+            // this is the SINGLETON half — these two pointers were already read and printed here, just
+            // never compared. Binary by design (see `isCurrentGenerator`'s doc): current / not-current,
+            // never "superseded-but-known", because neither manifest keeps a prior address to recognize a
+            // mismatch against. A `false` here is NOT a defect report — an older-but-working renderer or
+            // generator still serves; it just isn't what a fresh deploy would get today.
+            const generatorCurrent = isCurrentGenerator(state.chainId, report.generator);
+            const rendererCurrent = state.tokenURIRenderer ? await isCurrentRenderer(client, state.tokenURIRenderer) : null;
             verifyReport.onChainUri = jsonSafe({
                 generator: report.generator,
+                generatorCurrent, // true | false | null (no canonical generator recorded for this chain)
                 tokenURIRenderer: state.tokenURIRenderer ?? null,
+                // null ⇒ no renderer set at all (nothing to compare) — distinct from `false` (set, but not
+                // spec v11). See `isCurrentRenderer`: a read failure ALSO reports `false`, same as a stale
+                // renderer — the underlying probe cannot tell those apart, so neither can this field.
+                tokenURIRendererCurrent: rendererCurrent,
                 branch: status.branchName,
                 chainComplete: !!status.chainComplete,
                 unresolvedRefs: [...status.unresolvedRefs],
@@ -478,6 +606,16 @@ export async function cmdVerifyBody(address, flags, emit) {
             });
             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 (generatorCurrent === true)
+                ok(`generator is the CURRENT canonical one for ${CHAIN}`);
+            else if (generatorCurrent === false) {
+                info(`generator is NOT the current canonical one for ${CHAIN} ${dim('(a prior deployment this project is pinned to, or a fully custom field renderer — it still works; repoint with')} ${bold(`abx set-field ${address} --field animation_url --representation renderer --value <generator> --collection`)}${dim(')')}`);
+            } // null: no canonical generator recorded for this chain at all — nothing to compare against, so say nothing rather than a false "NOT current".
+            if (rendererCurrent === true)
+                ok(`tokenURI renderer is CURRENT (spec v11)`);
+            else if (rendererCurrent === false) {
+                info(`tokenURI renderer is NOT current (spec v11) ${dim(`— an older renderer still serves fine; it just doesn't have v11's capabilities (see the renderer's changelog in deployments.ts). Repoint with`)} ${bold(`abx set-renderer ${address} --collection`)}${dim(' (and without --collection for the per-token pointer)')}`);
+            }
             if (status.branchName === 'template') {
                 ok(`generator branch: template — the document assembles from the on-chain script chunks`);
                 if (status.chainComplete) {
@@ -569,9 +707,25 @@ export async function cmdVerifyBody(address, flags, emit) {
 // `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) {
+export async function cmdVerifyRemote(address, remote, emit) {
     const base = remote.url.replace(/\/$/, '');
     const chainId = resolveChain(CHAIN).id;
+    // Same shape, same field names as the local lane's `verifyReport` (cmdVerifyBody) wherever the
+    // two lanes answer the same question, so a caller doesn't need a second parser for `--remote`.
+    // `--remote --json` used to emit NOTHING at all — this command routed around `withJson` entirely
+    // (see `cmdVerify`) — so every field here is new, not a rename of something that already worked.
+    const verifyReport = {
+        address,
+        remote: base,
+        name: null,
+        watching: null,
+        contentChecks: [],
+        contentIntegrity: 'no-commitments',
+        renders: null,
+        availability: null,
+        ok: true,
+    };
+    emit(verifyReport);
     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. Match `abx status --remote` so both commands describe the same
@@ -587,6 +741,7 @@ export async function cmdVerifyRemote(address, remote) {
         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());
+    verifyReport.name = state.name ?? null;
     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
@@ -594,6 +749,8 @@ export async function cmdVerifyRemote(address, remote) {
     const watch = (await fetch(`${base}/api/watch`)
         .then((r) => (r.ok ? r.json() : null))
         .catch(() => null));
+    verifyReport.watching = watch?.watching ?? null;
+    emit(verifyReport);
     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;
@@ -610,6 +767,8 @@ export async function cmdVerifyRemote(address, remote) {
     const minted = (state.tokens ?? []).filter((t) => t.lifecycle === 'live');
     if (minted.length === 0) {
         info('no tokens minted yet — mint token #0, then re-run.');
+        verifyReport.availability = jsonSafe({ status: 'unknown', note: 'no tokens minted yet' });
+        emit(verifyReport);
         console.log('');
         return;
     }
@@ -647,27 +806,48 @@ export async function cmdVerifyRemote(address, remote) {
             else
                 ok(`renders: ${summary}`);
         }
-        await reportRemoteByteIntegrity(address, remote, base);
+        verifyReport.renders = jsonSafe({ minted: minted.length, upToDate, stale, rendering, failed, tokens: report.tokens });
+        verifyReport.availability = jsonSafe(computeAvailability({ isCode: report.tokens.length > 0, minted: minted.length, present: upToDate, anyCheck: false, unrecomputablePointers: 0 }));
+        emit(verifyReport);
+        const integrity = await reportRemoteByteIntegrity(address, remote, base);
+        verifyReport.contentIntegrity = integrity.status;
+        verifyReport.contentChecks = integrity.checks;
+        verifyReport.ok = integrity.status !== 'mismatch';
+        emit(verifyReport);
         return;
     }
     let gap = false;
+    let present = 0;
+    const missing = [];
     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)
+        if (img.status >= 300 && img.status < 400 && loc) {
+            present++;
             ok(`token #${t.tokenId} image: real render — resolver 302s to ${loc}`);
-        else if (img.status === 200 && !/svg/i.test(ct))
+        }
+        else if (img.status === 200 && !/svg/i.test(ct)) {
+            present++;
             ok(`token #${t.tokenId} image: real render present (${ct})`);
+        }
         else {
             gap = true;
+            missing.push(t.tokenId);
             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);
+    verifyReport.renders = jsonSafe({ minted: minted.length, present, missing, scope: 'the resolver (raw image probe — no /effects route)' });
+    verifyReport.availability = jsonSafe(computeAvailability({ isCode: true, minted: minted.length, present, anyCheck: false, unrecomputablePointers: 0 }));
+    emit(verifyReport);
+    const integrity = await reportRemoteByteIntegrity(address, remote, base);
+    verifyReport.contentIntegrity = integrity.status;
+    verifyReport.contentChecks = integrity.checks;
+    verifyReport.ok = integrity.status !== 'mismatch';
+    emit(verifyReport);
 }
 /**
  * The half `abx verify --remote` was missing: do the served BYTES still hash to the on-chain
@@ -683,14 +863,14 @@ export async function cmdVerifyRemote(address, remote) {
 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;
+        return { status: 'not-checked', checks: [] };
     }
     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;
+            return { status: 'not-checked', checks: [] };
         }
         if (!res.ok) {
             // Spec'd as part of `abx-token-api/v1`, so a conforming service has it — but say it neutrally:
@@ -698,23 +878,24 @@ export async function reportRemoteByteIntegrity(address, remote, base) {
             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;
+            return { status: 'not-checked', checks: [] };
         }
         report = (await res.json());
     }
     catch {
         warn(`byte integrity NOT checked — couldn't reach ${base}'s verify route.`);
-        return;
+        return { status: 'not-checked', checks: [] };
     }
     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;
+        return { status: 'no-commitments', checks: [] };
     }
+    const flatChecks = checked.flatMap((t) => t.checks.map((k) => ({ tokenId: t.tokenId, kind: k.kind, verified: k.verified })));
     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;
+        return { status: 'ok', checks: flatChecks };
     }
     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 ` +
@@ -722,6 +903,7 @@ export async function reportRemoteByteIntegrity(address, remote, base) {
     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
+    return { status: 'mismatch', checks: flatChecks };
 }
 // ── 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
@@ -761,6 +943,16 @@ export const STATE_ABI = [
     // 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 irreversible locks #122 asked `state` to report in full (previously only `paramHooksLocked`
+    // showed here). `tokenURILocked`/`contractURILocked`/`contractFieldLocked` exist on every ABX
+    // token (baseline URI + On-Chain Metadata surface); `scriptLocked`/`dependenciesLocked` exist only
+    // on the two code twins — see `readCollectionLocks`, which gates those two on `isCode` rather than
+    // trusting a revert to mean "unknown" for a contract that never had the surface at all.
+    { type: 'function', name: 'tokenURILocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'contractURILocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'scriptLocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'dependenciesLocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'contractFieldLocked', stateMutability: 'view', inputs: [{ type: 'bytes32' }], outputs: [{ type: 'bool' }] },
 ];
 /** The edition twin of {@link STATE_ABI} — `owner`/`maxInvocations`/`paused`/`minter`/
  *  `primaryPayee`/`tokenURIRenderer`/`royaltyInfo` are shared, unchanged, function names (see
@@ -785,6 +977,13 @@ export const EDITION_STATE_ABI = [
     // 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 same lock surface as STATE_ABI's edit — see the note there. Identical getter names on both
+    // standards (verified against the generated ABI: every edition twin exposes the same five).
+    { type: 'function', name: 'tokenURILocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'contractURILocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'scriptLocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'dependenciesLocked', stateMutability: 'view', inputs: [], outputs: [{ type: 'bool' }] },
+    { type: 'function', name: 'contractFieldLocked', stateMutability: 'view', inputs: [{ type: 'bytes32' }], outputs: [{ type: 'bool' }] },
 ];
 /**
  * The royalty ceiling line — and the headroom, which is the part a creator has not been told.
@@ -876,6 +1075,101 @@ function warnNotCanonical(address) {
         `(a bespoke contract, a superseded factory), nothing here is broken — just make sure whoever owns the ` +
         `project knows they chose it.`);
 }
+/**
+ * The bounded field-lock scan #122's triage settled on: every field this node can enumerate is one
+ * of the protocol registry's `METADATA_FIELD` keys (site/content/docs/protocol/metadata.mdx), read
+ * with `contractFieldLocked`. A creator's own custom field (`stems`, `palette`, …) is a real,
+ * independently-lockable key — but this node can only learn its NAME from the spine's
+ * `ContractFieldLocked` event, which needs an indexer, not a bare head read. So this reports "none
+ * of the STANDARD fields are locked", never "no fields are locked" — the caveat has to travel with
+ * the data, not live only in a comment a caller never sees.
+ */
+async function readFieldLocks(publicClient, address, abi) {
+    return Promise.all(Object.values(METADATA_FIELD).map(async (field) => ({
+        field,
+        locked: (await tryReadContract(publicClient, { address, abi, functionName: 'contractFieldLocked', args: [encodeTag(field)] })) ?? null,
+    })));
+}
+/**
+ * Read every applicable irreversible lock for one collection: token/contract URI config, the
+ * bounded standard field set, and — for a code project — the script and dependency freezes.
+ * `paramHooks.locked` is deliberately NOT read here: `cmdStateBody`/`cmdStateEditionBody` already
+ * read it (`readParamHooksLocked`) as part of the existing param-hooks readout, and re-reading it
+ * would cost a second `eth_call` for a fact already on hand — see the callers, which pass it into
+ * {@link printLocks} instead.
+ *
+ * `isCode` gates `scriptLocked`/`dependenciesLocked`: those getters exist ONLY on the two code
+ * twins (SeriesCode/EditionCode), so asking a plain image/Series contract for them isn't a failed
+ * read to report as "unknown" — it's a surface that was never there, reported as `null` (not
+ * applicable) via the OUTER object rather than the boolean inside it.
+ */
+export async function readCollectionLocks(publicClient, address, abi, isCode) {
+    const read = (fn) => tryReadContract(publicClient, { address, abi, functionName: fn });
+    const [tokenURI, contractURI, fields, script, dependencies] = await Promise.all([
+        read('tokenURILocked'),
+        read('contractURILocked'),
+        readFieldLocks(publicClient, address, abi),
+        isCode ? read('scriptLocked') : Promise.resolve(undefined),
+        isCode ? read('dependenciesLocked') : Promise.resolve(undefined),
+    ]);
+    return {
+        tokenURI: tokenURI ?? null,
+        contractURI: contractURI ?? null,
+        fields,
+        script: isCode ? { locked: script ?? null } : null,
+        dependencies: isCode ? { locked: dependencies ?? null } : null,
+    };
+}
+/** One lock's human verdict — the same three words everywhere this prints, so a reader learns the
+ *  vocabulary once. */
+function lockVerdict(locked) {
+    return locked === true
+        ? `${c.green}frozen${c.reset}`
+        : locked === false
+            ? `${c.orange}unlocked${c.reset}`
+            : dim('unknown (node refused the check)');
+}
+/**
+ * Print + emit the "Locks" section shared by both `state` bodies (721 and edition) — the one
+ * coherent summary #122 asked for, in place of a lone `paramHooks.locked` line. Every lock is its
+ * own independent switch (freezing one does nothing to any other), which is easy to miss when each
+ * only ever appeared alone — so the header says so explicitly, and every line names the exact
+ * command that freezes THAT lock and nothing else.
+ */
+function printLocks(address, locks, hasParamHooks, paramHooksLock, payload, emit) {
+    const lockedFieldNames = locks.fields.filter((f) => f.locked === true).map((f) => f.field);
+    const unknownFieldCount = locks.fields.filter((f) => f.locked === null).length;
+    payload.locks = jsonSafe({
+        tokenURI: locks.tokenURI,
+        contractURI: locks.contractURI,
+        script: locks.script,
+        dependencies: locks.dependencies,
+        // `null` ⇒ no ConfigurableParams surface on this contract (not a code project) — matching the
+        // `script`/`dependencies` null-means-N/A convention rather than reusing LockRead's "unknown".
+        paramHooks: hasParamHooks ? (paramHooksLock ?? null) : null,
+        fields: {
+            // The bounded scan, keyed by name — automation gets the same three-way distinction the human
+            // line does (true/false/null), never a collapsed "none locked".
+            checked: locks.fields,
+            note: "checks only the standard METADATA_FIELD set (site/content/docs/protocol/metadata.mdx); a project's own custom field keys are real and independently lockable but are NOT enumerated here — that needs an indexer over ContractFieldLocked events.",
+        },
+    });
+    emit(payload);
+    console.log(`\n  ${bold('Locks')}  ${dim('each is INDEPENDENT — freezing one does nothing to the others')}`);
+    info(`tokenURI       ${lockVerdict(locks.tokenURI)}   ${dim(`\`abx lock-uri ${address}\` freezes the pointer + renderer forever`)}`);
+    info(`contractURI    ${lockVerdict(locks.contractURI)}   ${dim(`\`abx lock-uri ${address} --collection\` freezes the pointer + renderer forever`)}`);
+    if (locks.script)
+        info(`script         ${lockVerdict(locks.script.locked)}   ${dim(`\`abx lock-script ${address}\` freezes the program bytes forever`)}`);
+    if (locks.dependencies)
+        info(`dependencies   ${lockVerdict(locks.dependencies.locked)}   ${dim(`\`abx lock-dependencies ${address}\` freezes the library set forever`)}`);
+    if (hasParamHooks)
+        info(`param hooks    ${lockVerdict(paramHooksLock ?? null)}   ${dim(`\`abx lock-param-hooks ${address}\` freezes all three hook addresses forever (detail above)`)}`);
+    info(lockedFieldNames.length
+        ? `fields         ${c.green}locked${c.reset}: ${lockedFieldNames.join(', ')}`
+        : `fields         ${dim('none of the standard fields are locked')}`);
+    info(dim(`               checked the standard METADATA_FIELD set only (${locks.fields.length} keys${unknownFieldCount ? `, ${unknownFieldCount} unreadable` : ''}) — a custom field key is real and lockable but not enumerable without an indexer. ` +
+        `\`abx lock-field ${address} --field <name> [--collection | --token 0]\` freezes one.`));
+}
 export async function cmdState(address, flags) {
     if (!address || address.startsWith('--')) {
         console.error('usage: abx state <address>  — a read-only, on-chain operational snapshot\n');
@@ -1001,6 +1295,10 @@ export async function cmdStateBody(address, flags, emit) {
     // 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).
+    // Hoisted above the try block: the Locks section (printed after it, see `printLocks`) reuses
+    // whatever this reads rather than paying for a second `eth_call` on the same fact.
+    let hooks = null;
+    let paramHooksLock;
     try {
         const rawKeys = await readParamSchemaKeys(publicClient, address);
         const enumerable = rawKeys !== null;
@@ -1054,9 +1352,9 @@ export async function cmdStateBody(address, flags, emit) {
         // 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);
+        hooks = await readParamHooks(publicClient, address);
         if (hooks) {
-            const locked = await readParamHooksLocked(publicClient, address);
+            paramHooksLock = await readParamHooksLocked(publicClient, address);
             const shown = [['configure', hooks.configureHook], ['augment', hooks.augmentHook], ['transfer', hooks.transferHook]]
                 .filter(([, a]) => a !== zeroAddress)
                 .map(([role, a]) => `${role} ${a}`);
@@ -1066,12 +1364,12 @@ export async function cmdStateBody(address, flags, emit) {
                 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,
+                locked: paramHooksLock ?? null,
             });
             emit(payload);
-            const lockNote = locked === true
+            const lockNote = paramHooksLock === true
                 ? `${c.green}frozen${c.reset} ${dim('— no hook address can ever change again')}`
-                : locked === false
+                : paramHooksLock === 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}`);
@@ -1083,6 +1381,10 @@ export async function cmdStateBody(address, flags, emit) {
     catch {
         /* best-effort — a non-code project has no params surface to read */
     }
+    // The coherent lock summary #122 asked for — every irreversible switch this node can read, side
+    // by side, independent of whether this project happens to compose the params surface above.
+    const locks = await readCollectionLocks(publicClient, address, STATE_ABI, kind.kind === 'code');
+    printLocks(address, locks, !!hooks, paramHooksLock, payload, emit);
     console.log('');
 }
 /**
@@ -1223,8 +1525,9 @@ async function cmdStateEditionBody(address, publicClient, kind, emit) {
     // 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);
+    let paramHooksLock;
     if (hooks) {
-        const locked = await readParamHooksLocked(publicClient, address);
+        paramHooksLock = await readParamHooksLocked(publicClient, address);
         const shown = [['configure', hooks.configureHook], ['augment', hooks.augmentHook], ['transfer', hooks.transferHook]]
             .filter(([, a]) => a !== zeroAddress)
             .map(([role, a]) => `${role} ${a}`);
@@ -1232,12 +1535,12 @@ async function cmdStateEditionBody(address, publicClient, kind, emit) {
             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
+            locked: paramHooksLock ?? null, // null = unknown; never collapse it to false
         });
         emit(payload);
-        const lockNote = locked === true
+        const lockNote = paramHooksLock === true
             ? `${c.green}frozen${c.reset} ${dim('— no hook address can ever change again')}`
-            : locked === false
+            : paramHooksLock === 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}`);
@@ -1245,6 +1548,9 @@ async function cmdStateEditionBody(address, publicClient, kind, emit) {
             info(dim(`               the transfer hook is a VETO: if it reverts, the transfer fails — and mints too (mint = transfer from 0x0).`));
         }
     }
+    // The coherent lock summary #122 asked for — see cmdStateBody's identical call for why.
+    const locks = await readCollectionLocks(publicClient, address, EDITION_STATE_ABI, kind.kind === 'edition-code');
+    printLocks(address, locks, !!hooks, paramHooksLock, payload, emit);
     console.log('');
 }
 /**