@artblocks/abx-storage 0.1.0-alpha.2 → 0.1.0-alpha.21

package/CHANGELOG.md

@@ -0,0 +1,552 @@
+# @artblocks/abx-storage
+
+## 0.1.0-alpha.21
+
+### Patch Changes
+
+- c9f7aeb: Fold the burn, and make "canonically ABX v2" sayable — from abx-services' 2026-08-20 reply
+  (`reviews/2026-08/services-reply-docs-23.md`). All off-chain: no contract changed, no address moved.
+
+  **SDK — `foldSpine` now folds an ERC-721 burn, and `TokenState.minted` is replaced by `lifecycle`
+  (BREAKING).** A burn wrote the zero address into `TokenState.owner` — where nothing downstream could
+  tell it from a holder — and `minted` latched `true` at mint and was never recomputed, so a burned
+  token reconstructed as live. `lifecycle: 'unminted' | 'live' | 'burned' | 'no-live-copies'` replaces it,
+  and `owner` is `null` for a burned id rather than a sentinel. An enum rather than the `minted` +
+  `burned` pair the report asked for: a boolean whose `false` has two meanings leaves the burn case one
+  forgotten field away from rendering as "not yet minted", which is exactly what our own CLI did.
+
+  **`'burned'` is terminal and ERC-721-only; an edition at zero live copies is `'no-live-copies'`.** The
+  first cut of this enum shared `'burned'` across both standards, on the grounds that "one vocabulary on
+  both lanes" was the honest shape. It wasn't: the correct _response_ to destruction differs by standard
+  (a 721 id is gone forever and must `410`; an edition id can mint again and must not), so a shared word
+  put every consumer one forgotten `contractType` branch away from serving `410 Gone` for a token the
+  contract still resolves — and our own migration note told the first consumer to map the shared word
+  straight onto their `410` sites. abx-services caught it in review before it published. Splitting the
+  word moves the rule out of prose and into the type: **`lifecycle === 'burned'` is safe to treat as
+  permanent on either standard, with no carve-out**, which let the reference resolver's `isEditionState`
+  guard go away entirely. Pinned from both ends — no edition history can fold to `'burned'`, and the
+  route asserts its own standard-blindness.
+
+  **The two lanes now agree id-for-id.** The same review found `TokenRow.lifecycle` (head reads) reporting
+  `'unknown'` for a fully-burned edition id while the fold reported `'burned'` for that same id — under a
+  docstring claiming the two lanes used the same words. That is the sibling-drift class this repo treats
+  as a bug (see `TokenState.maxSupply`'s note, the last time one field name carried two meanings). Both
+  lanes now answer `'no-live-copies'` there: the fold _could_ distinguish never-minted from fully-burned
+  and deliberately does not, because the distinction has no consumer. `'unknown'` survives for the one
+  case where a head read genuinely cannot say — a 1/1 has no mint frontier, so a reverting `ownerOf`
+  there is evidence of nothing.
+
+  What the latched boolean was costing, all in our own tree: the effects harness re-rendered destroyed
+  tokens on every sweep, forever; `onchain-uri`'s probe reads the LOWEST live id, so burning token 0 made
+  a healthy collection's on-chain-URI lane report as **broken**; the resolver served metadata — and the
+  pre-mint _warming placeholder_, i.e. "still loading" forever — for ids the contract disowns; `mintedCount`
+  never went down; and `abx state` printed "not yet minted" for a token that had been destroyed.
+
+  **SDK — `BurnConfigured` and `MaxRoyaltyBpsUpdated` fold into `ProjectState.burnable` /
+  `.maxRoyaltyBps`.** Both events shipped in the ABI and in `SPINE_EVENT_DOC` and reached no field of
+  state; the upgrade memo then told consumers the doc entry _was_ the fold, which it has never been (it
+  supplies `register`/`what` on the event record, full stop). Both are tri-state: `null` means the spine
+  never stated it — an implementation with no `burn` entrypoint and an unpublished ceiling — which is not
+  `false`, and not 10%. The ceiling is deliberately not nested inside `royalty`, since clearing a royalty
+  nulls that field while the ceiling stays binding on chain.
+
+  **SDK — a fold-coverage guard, because this was the second instance in four days.** `DefaultMaxSupplySet`
+  did the same thing on 2026-08-17. `SPINE_EVENT_NO_FOLD` now lists the events that deliberately reach no
+  state _and why_ (a ping whose value is a head read, a factory's own log, a minter sibling, an allowance),
+  and `spine-fold-coverage.test.ts` asserts every decodable event is either folded or excused. A new event
+  is unfolded and unexcused until someone decides which.
+
+  **SDK — a burned 1/1 no longer vanishes from `listTokens`.** The id range fell back to `totalSupply`
+  (live: mints − burns) when a token type exposes no `nextTokenId`, so burning a 1/1's only token made the
+  listing enumerate ZERO ids — `abx tokens` printed nothing at all, indistinguishable from a collection
+  with no tokens. A 1/1's id space is `{0}` forever regardless of what is live. Found by burning a real
+  token on Sepolia rather than by any fixture, which is the only way this one surfaces.
+
+  **SDK — head reads can now say `burned`.** `nextTokenId` is a mint frontier that only rises, so an id
+  below it whose `ownerOf` reverts was minted and destroyed. `TokenRow.lifecycle` (`'live'` / `'burned'` /
+  `'unminted'` / `'unknown'`) and `TokenListing.burnedCount` (`nextTokenId − totalSupply`) drop out of that,
+  with no event log. `'unknown'` stays a real member where the chain declines to say: a 1/1 has no frontier,
+  and an edition's `supply == 0` cannot distinguish never-minted from fully-burned.
+
+  **SDK — `burned` joins `ServiceErrorCode`, paired with `410 Gone`.** A remote token API had nothing
+  honest to say about a destroyed id and was sending `410` with `code: 'not_registered'` — a statement
+  about the _contract_. The rule behind the pairing is the general one: **a resolver answers what the
+  contract's own URI getter answers.** A burned 721's `tokenURI` reverts `NonexistentToken`, so serving a
+  document would contradict the contract; an ERC-1155's `uri(id)` has no existence gate and a zero-supply
+  id can mint again, so **an edition never 410s** — it serves, with `supply: 0`.
+
+  **SDK — `readCollectionPolicy`, `canonicalFactories`, `verifyProvenance`: protocol knowledge moves out
+  of the CLI.** The CLI was declaring its own ABI fragments for `burnable`/`maxRoyaltyBps` and reading
+  them itself in two places, so no other integrator could reach either fact. `canonicalFactories(chainId)`
+  replaces two copies of the six-anchor enumeration inside `anchors.ts` — the list whose completeness _is_
+  the trust model. `verifyCanonical` gains `opts.factories`, which **replaces** the manifest set rather
+  than appending to it, so a multi-tenant operator's pinned allowlist can drive the gate without silently
+  widening it.
+
+  **SDK — anchor generations: "canonically ABX v2", not a bare `false`.** `verifyCanonical` reported
+  "deployed by an ABX factory since replaced" and "deployed outside the toolkit entirely" identically —
+  its own docstring admitted it — and the first is a perfectly good collection. `ANCHOR_GENERATIONS` keys
+  each generation of the six trust anchors by the **on-chain core version** its clones report, and
+  `verifyProvenance` returns `{canonical, generation: 'current' | 'prior' | null, coreVersion, factory,
+anchorsAnswered}`. The version is on the clone itself, so the answer is chain-verified rather than a
+  manifest claim, and it keeps working after a factory retires. Retired generations never feed
+  `verifyCanonical`: provenance is not trust — a superseded generation can predate a security remediation.
+  Pre-launch testnet generations are deliberately not backfilled.
+
+  **Redeploy process — a token-layer runtime change is a new anchor generation.** It bumps
+  `AbxVersion.CORE_VERSION` and moves the SDK's `isCurrent*` probes in lockstep. That is now a checklist
+  step (`contracts/README.md`, `CLAUDE.md`) _enforced by_ `deployments.test.ts`: recorded generations must
+  have unique, increasing core versions and the newest must match the constant in `AbxVersion.sol`, so a
+  batch cannot record a generation without bumping or bump without recording. The gap that prompted it: the
+  2026-08-20 batch added `burn()`, `burnable()`, `maxRoyaltyBps()` and `reduceMaxRoyaltyBps()` to the CORE
+  base — burn is not an extension, so no extension version moved either — and left the constant at 2, so
+  `abxVersion() == 2` cannot tell a burn-capable token from a pre-burn one.
+
+  **CLI — the royalty ceiling is shown with its rate, and headroom is named.** A ceiling above the live
+  rate is royalty the owner can add unilaterally, and a listing page never shows it. `abx state` prints the
+  pair and, when there is headroom, says the useful thing: reducing the cap **to** the current rate is what
+  turns "5% today" into "5%, provably, forever". (Named by abx-services as their `royalty-headroom` flag —
+  a marketplace can compute it, so a creator should hear it from us first.)
+
+  **Reference stack — the same fixes, so the reference is exemplary rather than the counter-example.**
+  `mintedCount` keeps its name and counts LIVE ids, with `burnedCount` added only when non-zero (so a
+  project with no burns serves byte-identical JSON, and a consumer's fixtures keep telling the truth);
+  the indexer projection carries `lifecycle`; the effects status route and the render sweep skip destroyed
+  ids; the dashboard badges a burned token instead of calling it minted; and `abx verify` / the migrate and
+  re-point probes never choose a burned token as their subject.
+
+  **CLI — `--send` is accepted on the deploy paths, and two lane flags is refused.** Every deploy's help
+  advertises the signing lanes as `--send hot/env key · --sign wallet page · --unsigned print tx`, in 25
+  places, and `--send` was the one of the three the deploy allowlist rejected: typing what the help showed
+  produced `unrecognized flag(s): --send` from the guard whose whole purpose is catching flags that would
+  be silently ignored — the guard firing on the tool's own documentation. Found by using the CLI as a cold
+  reader of its own `--help` while setting up an on-chain test. While there, lane resolution moved from
+  truthiness to **presence** (`--sign=` parses to `''`, which is falsy, so a caller who explicitly named
+  the wallet lane was routed to the unattended env key — the one direction of that bug that costs
+  something), and naming two lanes at once now refuses instead of resolving by an undocumented precedence.
+
+  **Packaging — every published tarball ships its CHANGELOG.** `files` was `['dist', 'LICENSE']` on the
+  SDK, indexer, storage, effects and token-api, so the only package whose release notes reached consumers
+  was the CLI. A downstream team upgrading the SDK had no CHANGELOG in the tarball and diffed two `dist/`
+  trees to find out what moved — then reported the release notes as missing, which cost a whole exchange
+  to adjudicate. One line each.
+
+  **Docs + spec.** The event spine gains a Burn section and the `MaxRoyaltyBpsUpdated` row, both with the
+  fold rules an indexer relies on; three stale deploy-event-order lists are corrected; the remote-services
+  error taxonomy gains the `410 burned` row and the edition carve-out; `owner-powers` explains headroom and
+  burn permanence; and `indexing-notes` states plainly that documenting an event is not folding it.
+
+- Updated dependencies [c9f7aeb]
+  - @artblocks/abx-sdk@0.1.0-alpha.21
+
+## 0.1.0-alpha.20
+
+### Patch Changes
+
+- Updated dependencies [84ca9dd]
+- Updated dependencies [84ca9dd]
+  - @artblocks/abx-sdk@0.1.0-alpha.20
+
+## 0.1.0-alpha.19
+
+### Patch Changes
+
+- Updated dependencies [b1c333d]
+- Updated dependencies [b1c333d]
+  - @artblocks/abx-sdk@0.1.0-alpha.19
+
+## 0.1.0-alpha.18
+
+### Patch Changes
+
+- Updated dependencies [77a6248]
+- Updated dependencies [77a6248]
+  - @artblocks/abx-sdk@0.1.0-alpha.18
+
+## 0.1.0-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [c5b8ec3]
+- Updated dependencies [5b29f53]
+  - @artblocks/abx-sdk@0.1.0-alpha.17
+
+## 0.1.0-alpha.16
+
+### Patch Changes
+
+- Updated dependencies [9c287c0]
+- Updated dependencies [b5744a1]
+- Updated dependencies [9c287c0]
+  - @artblocks/abx-sdk@0.1.0-alpha.16
+
+## 0.1.0-alpha.15
+
+### Patch Changes
+
+- Updated dependencies [7fec2d7]
+  - @artblocks/abx-sdk@0.1.0-alpha.15
+
+## 0.1.0-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [f64a31f]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+- Updated dependencies [1b6b741]
+  - @artblocks/abx-sdk@0.1.0-alpha.14
+
+## 0.1.0-alpha.13
+
+### Patch Changes
+
+- Updated dependencies [528c6c6]
+  - @artblocks/abx-sdk@0.1.0-alpha.13
+
+## 0.1.0-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [afa9dd4]
+- Updated dependencies [8c254d5]
+  - @artblocks/abx-sdk@0.1.0-alpha.12
+
+## 0.1.0-alpha.11
+
+### Patch Changes
+
+- d40caf4: Requested by an integrator (abx-services) — the conformance surface now lives in the neutral
+  layer. Five pieces that only token-api or storage exposed before, and that any third-party
+  resolver needs to reproduce the reference behavior byte-for-byte, move into `@artblocks/abx-sdk`:
+
+  - **The generator-document family** (`ABX_JS`, `escapeInlineScript`/`escapeInlineJson`,
+    `buildGeneratorDocument`, `injectTokenDataIntoHtml` — new `src/generator-document.ts`): pure
+    string operations with no resolver-specific behavior, so the SDK, `abx preview`, and any
+    third-party provider now share one definition instead of the CLI importing token-api just for
+    this.
+  - **The registry-dependency family** (`DEPENDENCY_REGISTRY_ABI`, `activeRegistry`,
+    `resolveRegistryDep`, `registryDepUrl`, `dependencyScriptTags`, `URL_BUDGET_BYTES`), merged into
+    the SDK's existing `deps.ts` alongside its registry-pointer logic. `node:zlib` can't come along
+    — SDK core has to stay reachable from a browser bundle — so decompression is now an INJECTED
+    `inflate?: (bytes: Uint8Array) => Uint8Array` threaded through `resolveRegistryDep`/
+    `dependencyScriptTags`; omitting it when a resolved dep actually needs decompressing throws a
+    new typed `InflateRequiredError` naming the fix, rather than crashing opaquely or silently
+    degrading. `@artblocks/abx-sdk/node` gains `nodeInflate` (a one-line `gunzipSync` wrapper) so a
+    Node host wires it in one line; a browser host passes a `DecompressionStream`-based
+    implementation instead. (Merge note: the prior `dependencyRegistryReadAbi` and token-api's
+    `DEPENDENCY_REGISTRY_ABI` declared the identical `getDependencyDetails` entry twice — deduped
+    into one array that also carries `getDependencyScript`.)
+  - **`contentTypeFromPath`** (new `src/mime.ts`): the MIME extension-map lookup, verbatim.
+  - **Gateway resolution, split pure/env** (new `src/gateways.ts`): `resolveGatewayBase` is now PURE
+    (no env read — takes resolved `{ipfs?, arweave?}` overrides) and `gatewayUrlFor` moves alongside
+    it; `gatewayConfigFromEnv()` is the one place that reads `ABX_IPFS_GATEWAY`/
+    `ABX_ARWEAVE_GATEWAY`, kept separate so a host with its own gateway config never has to touch
+    `process.env` through this module at all.
+  - **`exponentialBackoffDelay(attempt, baseMs, capMs)`** (`util.ts`): `min(baseMs * 2^(attempt-1),
+capMs)`, 1-indexed like the existing `linearBackoffDelay`. Prefer it for a sustained rate limit
+    or an overloaded upstream; `linearBackoffDelay` stays right for a one-off transient failure.
+    `service.ts`'s own retry ladder is unchanged (still linear — its rationale comment stands).
+
+  Token-api and storage keep every existing export working, re-exported from the SDK where the
+  implementation moved — no removals, and token-api's own `nodeInflate`-pre-wired wrappers mean its
+  internal call sites (`code.ts`'s document assembly, `deps.ts`'s `depStatusReport`) needed no
+  signature changes at all. The browser-bundle test (`packages/sdk/test/browser-bundle.test.ts`)
+  stays green with all of this now exported from the core index — proof that the injected-`inflate`
+  design actually keeps `node:zlib` out of the bundle.
+
+- Updated dependencies [d40caf4]
+- Updated dependencies [d40caf4]
+  - @artblocks/abx-sdk@0.1.0-alpha.11
+
+## 0.1.0-alpha.10
+
+### Minor Changes
+
+- 11fa933: The extraction phase of the simplification refactor: business logic that lived only inside the CLI
+  is now importable — the CLI calls the same functions you can.
+
+  **Into the SDK:** the five trust-anchor bootstraps (`ensureFactory`, `ensureSeriesFactory`,
+  `ensureSeriesCodeFactory`, `ensureRenderer`, `ensureSeedSource` — `anchors.ts`, on the same
+  injected-`send` + `onEvent` pattern as `ensureChunkStore`, with a typed `AnchorUnavailableError`),
+  `detectCanonicalFactory`/`resolveScanFloor`, the on-chain-URI setup composer (`onchain-uri.ts`),
+  interrupted-deploy resume planning (`resume.ts`), migration plan/parity reconciliation
+  (`migrate.ts`), the `abx.js` static analyzer (`inspect.ts`), dependency setup legs (`deps.ts`),
+  content-staging plans (`staging.ts` — `planStagedContent`, `stageFieldContent` with `StagingEvent`),
+  `mintedTokenIds`, and a typed `readSaleConfig` for the fixed-price minter.
+
+  **Into storage:** `uploadAndLocate`, `repinNodeCustody` (the byte-custody half of migration),
+  `decideImageContentLane`, `assessStorageReadiness`/`assessTurboFunds` (the Arweave/Turbo funding
+  math), and `awaitLocatorReady` (poll a locator until it serves).
+
+  **CLI hardening that fell out of the dedup:** one risk gate (`gatedSend`) now guards every write —
+  `--dry-run` and `--confirm` mean the same thing on every command, all owner-ops gain `--confirm`,
+  and a write reaching the send lane under `--dry-run` is structurally impossible (grep-enforced by
+  test). One `CHAIN` source of truth; one memoized local-indexer accessor.
+
+### Patch Changes
+
+- 11fa933: The remaining phases of the simplification refactor that hadn't yet gotten a changeset: the CLI's
+  internal module split, the token-api/effects/mint-page convergence on the SDK, the shipped skill's
+  rewrite for the simplified surface, and a new SDK README.
+
+  - **`abx`'s `main.ts` split into domain command modules** (`commands/{deploy,project,reads,service,
+scaffold,storage}.ts`, shared `output.ts`/`errors.ts`), with one exit-discipline rule
+    (`process.exitCode` + return, or a typed `CliError`, everywhere — bare `process.exit` only at the
+    entry guard, the top-level catch, and the keep-alive SIGINT handler). Purely internal: a 207-fixture
+    byte-diff matrix (every help text, dry-run, error path, and exit code) confirmed identical output
+    before and after.
+  - **token-api / effects / mint-page converge on the SDK**: `@artblocks/abx-storage` gains one
+    `resolveGatewayBase` (`readiness.ts`), replacing three near-identical copies (two in token-api, one
+    inline in storage itself); token-api exports `buildGeneratorDocument` so the CLI's `abx preview`
+    consumes the real generator-document assembler instead of a hand-kept duplicate; the effects runner
+    now resolves its config via the SDK's `readEnv` and gets a `makePublicClient` fallback transport, so
+    `ABX_RPC_URL` accepts a comma-separated failover list like every other RPC var; the scaffolded
+    mint-page app now imports ABIs from `@artblocks/abx-sdk/abi` and a browser-safe `makePublicClient` +
+    typed `readSaleConfig` instead of hand-rolled fetch/decode, and pins its generated `package.json` to
+    the SDK's _resolved_ version via a new `@artblocks/abx-sdk/package.json` export (alpha version
+    counters diverge per package under changesets, so pinning the CLI's own number could produce an
+    unsatisfiable range).
+  - **The shipped skill (`.claude/skills/abx-self-host/`) is rewritten for the surface phases 0–5
+    actually shipped**: every warning made obsolete by an enforcement is deleted rather than softened —
+    predict-only deploy-preview addresses, the `approvals N` line, the single `ABX_REMOTE_SELF_*`
+    credential grammar, `doctor`'s version/provenance ladder, `storage show --check`, the render/storage
+    combo validator's dry-run row, and `ABX_DEPLOYER_PK` as the only key name. Retired names swept from
+    `dev-loop-test`, the agent-eval scenarios, and spec prose. The skill ships bundled inside this CLI
+    package (co-versioned via `SKILL.md` frontmatter), so it rides this same patch.
+  - **New `packages/sdk/README.md`**: what the SDK is, the send-injection model (`PreparedTx` +
+    `SendTx`, `makeHotSender` for a hot key, bring-your-own for a wallet/multisig), a complete
+    deploy → upload → mint → read walkthrough against real exports, and browser-use notes (explicit
+    `rpcUrls`, no env, the `/node` subpath is Node-only). Included in the npm tarball automatically
+    (README is one of the files npm always packs, regardless of the `files` allowlist).
+
+- 11fa933: Phase 5 interface unifications: the self resolver becomes a named remote, doctor absorbs the
+  version/install/provenance ladder, deploy previews stop showing addresses they can't keep,
+  approvals are counted honestly, render×storage combos are validated once, and storage config gets
+  a real probe.
+
+  - **Self resolver is a named remote (breaking, client-side only)**: the CLIENT credential for the
+    local/self resolver moves from `ABX_RESOLVER_ADMIN_TOKEN` to the named-remote grammar
+    (`ABX_REMOTE_SELF_URL` / `ABX_REMOTE_SELF_TOKEN` — "self" is just a conventional remote name, zero
+    special-casing). The SERVER side (token-api control-plane auth, `provision.ts`, the Fly.io secret)
+    keeps its old name — it's the service's own config, not a client credential, so deployed resolvers
+    need no change. The old client var, if still set, is now a pointed `CliError` naming both new vars
+    (no silent fallback); `abx doctor` flags it too, and the near-miss `_KEY`-vs-`_TOKEN` detector keeps
+    working under the unified grammar.
+  - **`abx doctor` absorbs the version/install/provenance ladder** the skill used to only teach in
+    prose: one new ✓/✗ block for binary provenance (source checkout / npm install / npx — the silent-
+    stale-npx-cache trap), npm currency (reuses the existing cached update check), and skill↔CLI
+    version match (reuses `abx skill`'s own discovery). Each row names the exact fix.
+  - **Deploy previews stop showing addresses they can't keep**: `--dry-run` (`deploy` /
+    `deploy-series` / `deploy-code`) **without `--salt`** no longer prints a "deterministic address" —
+    that salt was just freshly, randomly reserved, so the address was real for that one preview and
+    never reproducible by a plain re-run. It now prints the salt itself, prominently, plus how to pin
+    it: re-run with `--salt <shown>` (guaranteed same address), or `abx predict --salt <shown> --for
+<signer>`. **With `--salt`, the address prints exactly as before** (it IS stable) — `abx predict`
+    is unchanged. The same rule applies to `--json`: without `--salt`, `address` reports `null` rather
+    than a value the real deploy won't land at (`saltPinned` still says why).
+  - **`approvals` — a labeled, honest signature count**: every deploy-family `--dry-run` preview and
+    `--confirm` summary now carries one uniform `approvals N wallet approval(s)` line/clause — the
+    number of **wallet TX signatures** the real run will ask for (a connected-wallet storage upload,
+    e.g. Arweave via `--storage-signer eth`, is a message signature, not a transaction, and stays
+    listed separately, as it already was). It's derived from the exact same staging/setup-multicall
+    math that sizes the wallet-lane session's own `total`, so the two can never disagree — this caught
+    (and fixed) `deploy-code`'s wallet-lane session `total` being hardcoded to `2` even on the 1-tx path
+    (no chunks/schema/deps/on-chain-uri legs/setup-carried mints), which would have shown "transaction
+    1 of 2" and then silently never asked for a second.
+  - **One validator for render×storage combos**: `@artblocks/abx-storage` gains
+    `validateRenderStorageCombo()` (`content-plan.ts`) — the single source of truth for two known-bad
+    configurations, each checked against the ACTUAL fact that makes it bad (not against an unrelated
+    flag): (1) `--image-base` needs a backend that can overwrite a stable per-token key in place; an
+    ipfs/arweave-_shaped URL_ is refused regardless of this deploy's own `--backend`, because those are
+    content-addressed — a re-upload gets a new address, so no fixed URL can point at it. (2) publishing
+    a render to a resolver that doesn't share this machine's disk needs a backend that can hand back a
+    public URL at all — `fs` (or `cloud` with no public base) can't. `deploy-code` wires this into BOTH
+    its real-run refusal (`--image-base`) and a new `render/storage ✓|✗ <reason>` dry-run row;
+    `requirePublishableBackend` (the existing `abx render --remote` / `abx effects` guard) now consults
+    the same validator for its ok/not-ok decision, so the two surfaces can't drift apart.
+  - **`abx storage show --check`**: a real read/write against the resolved storage config, not just
+    "is it configured." `cloud` PUTs a tiny object through the signed API and GETs it back over the
+    PUBLIC base with a plain unsigned fetch — the only check that catches the R2/S3
+    endpoint-vs-public-base trap (`health()` alone only proves the API credentials work); on failure
+    both URLs print, so the mismatch is visible. `ipfs`/`fs` reuse their existing `health()` verbatim
+    (gateway/API reachability, dir writability — no upload, no pin — reused, not reimplemented).
+    `arweave` adds an identity+balance READ, never a paid upload. Exit code is meaningful (0 ok / 1 any
+    ✗) so a script can gate a launch on it. `abx doctor`'s storage row now runs the same fuller probe
+    (bounded to 1.5s, matching its other fast network checks) instead of a bare `health()` call.
+
+- Updated dependencies [11fa933]
+- Updated dependencies [11fa933]
+- Updated dependencies [11fa933]
+  - @artblocks/abx-sdk@0.1.0-alpha.10
+
+## 0.1.0-alpha.9
+
+### Patch Changes
+
+- df298d8: `abx storage status <locator>` — is it retrievable yet, or only accepted?
+
+  Backlog B21, and the second half of a gap two independent integrations hit eight days apart. An upload
+  service answers "accepted" the moment it holds your bytes; a gateway serves them only once they
+  propagate, and on Arweave that runs to minutes. Nothing in the upload result distinguished the two, so
+  the natural implementation — upload during a mint, write the locator into the token — mints a token
+  that renders broken for the first minutes of its life.
+
+  The first reporter rebuilt this layer themselves (ranged GETs, a propagating/ready model, retry ladders
+  lengthened after measuring real times) and concluded "every serious integrator will rebuild some
+  version of this." The second published 32 renders and found **32/32 404ing on `arweave.net` while 22/32
+  already served from `permagate.io` and `vilenarios.com`**, with the uploader reporting `CONFIRMED`
+  throughout — and the expensive part is what a creator does next, since a placeholder on a fresh drop
+  reads as a failed render, so you re-run `abx render --force` and re-upload everything for nothing.
+
+  That second observation shapes the design: propagation is **per-gateway**, so the check probes the
+  gateway your project actually uses _plus two others_, which buys a third verdict the reporters' own
+  two-state model couldn't express.
+
+  - **`ready`** — your gateway serves the bytes. Safe to reference.
+  - **`propagating`** — another gateway serves them, so the data **provably exists** on the network and
+    yours is merely behind. Waiting is the fix, and the command says plainly not to re-upload.
+  - **`unreachable`** — nothing probed serves them. Deliberately _not_ called propagating: from outside,
+    a locator that is still settling and one that is simply wrong look identical, and reporting the
+    friendlier of the two is how a tool teaches someone to ignore it. When every gateway rejects the id
+    itself (a 4xx that isn't 404) rather than just missing it, that _is_ evidence, and the output says
+    "malformed locator, waiting will not fix it" — the inverse mistake of waiting out a typo costs more
+    than a needless re-upload.
+
+  Accepts every form a locator arrives in (`ar://`, `ipfs://`, a gateway URL, a bare txid/CID, with a
+  directory path suffix), reads **headers only** via a ranged request with the body cancelled — so
+  checking a 40 MB asset doesn't download it — and **exits non-zero unless ready**, which makes waiting a
+  one-liner instead of a retry ladder: `until abx storage status <loc> --json; do sleep 10; done`.
+
+  The primitive is `locatorStatus()` in `@artblocks/abx-storage`, not CLI-only (per B20): anything
+  programmatic should call it in-process rather than spawning the CLI per check. `abx render`'s existing
+  propagation note now points at the command, so the advisory has an answer attached.
+
+- Updated dependencies [df298d8]
+- Updated dependencies [df298d8]
+  - @artblocks/abx-sdk@0.1.0-alpha.9
+
+## 0.1.0-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [e325b46]
+  - @artblocks/abx-sdk@0.1.0-alpha.8
+
+## 0.1.0-alpha.7
+
+### Patch Changes
+
+- 1b50f9d: Fixes from an integrator batch: a machine-readable `tokenuri`, one Arweave identity across CLI and SDK, a correct OpenSea refresh, and attach telling the truth.
+
+  **`abx tokenuri --json`.** The command abbreviated long values (`… (382 chars)`) with no way to turn it
+  off, so for a token whose whole point is on-chain content it returned something that _looked_ like the
+  metadata and wasn't. An integrator scraped it, stored a `data:` URI cut to 96 characters, and only
+  found out in production; they abandoned the CLI as a read path and reimplemented `eth_call`. `--json`
+  now emits the verbatim decoded document — no banner, no ANSI, no truncation — so
+  `abx tokenuri <addr> --json | jq` is a supported read path. The human view still abbreviates, and now
+  says `[--json for the full value]`.
+
+  **One Arweave identity, resolved in one place.** `arweaveConfigFromEnv()` read `ARWEAVE_JWK` and
+  nothing else, while the CLI mints and manages `.abx-self-host/arweave-key.json`. Porting a working CLI
+  flow to the SDK — same machine, minutes later — failed every upload with "Arweave via Turbo needs an
+  identity", a message that says storage was never configured when the truth was that two layers
+  disagreed about where the identity lives. `@artblocks/abx-storage` now exports `resolveArweaveJwk()`
+  (env → managed key file) and the CLI delegates to it. Its diagnostics come with it: an empty key file
+  now reports the **path** and the remedy instead of `Unexpected end of JSON input`, and a corrupt one
+  says the same.
+
+  **`abx refresh` on the default chain.** The OpenSea slug map held only `sepolia` and `mainnet`, so
+  `base-sepolia` — the CLI's own default — fell through to the raw key: the refresh POST went to a slug
+  OpenSea doesn't know, and the printed link pointed at **mainnet** `opensea.io` for a testnet token.
+  Slugs are now correct (`base_sepolia`), `testnet` comes from the chain registry rather than a second
+  hand-maintained set, and a chain with no known slug produces **no link** instead of a wrong one. Same
+  shape as the hardcoded explorer table that once sent every Base Sepolia link to Etherscan.
+
+  **`abx attach` names its dependency.** Attaching artifacts to a project that resolves on-chain now
+  warns, before the send, that they will **not** appear in `tokenURI` — the on-chain renderer carries
+  reserved fields only, and the artifacts manifest comes from a resolver. A team attached five audio
+  stems to a fully-on-chain token and found them "paid for, stored on-chain, and invisible"; the note
+  that existed was one dim line that read as a footnote rather than as a missing service.
+
+  **`ensureChunkStore` moved to the SDK.** The bootstrap every on-chain-content path needs existed only
+  inside the CLI, so an SDK integrator got `resolveChunkStore()` (may return undefined) plus a separate
+  `storeSupportsWriteContent()` they had to remember — forget it and an incapable store fails _deep
+  inside a mint, after transactions have landed_. One team hand-rolled the guard for exactly that reason.
+  `ensureChunkStore(publicClient, send, {chainId, override, onEvent})` is now exported; the SDK reports
+  progress through `onEvent` instead of printing, and the CLI keeps its narration.
+
+  **`abx storage upload --json`.** The locator as data. They scraped this line, captured its ANSI colour
+  codes along with the URL, wrote the result into a _stored_ player URL, and found out when it 404'd in
+  production. In `--json` mode stdout carries the JSON and nothing else; progress moves to stderr.
+
+  **`--backend ipfs` no longer hides a missing credential.** Without `PINATA_JWT` the backend resolves to
+  **kubo against a local node**, so a dry run looked fine and the real upload failed for anyone not running
+  one. The preview now says so. Related correction: the skill claimed "a backend missing its secret falls
+  back to `fs`" — it does not. `cloud` refuses up front naming the missing values, and `ipfs` goes to the
+  local node; nothing silently degrades to local disk. Both sides now say the same thing.
+
+  Reported in the 2026-08-03 MXRR integration batch (feedback 869f27b1, a256217f, 119d7e8e, 975c363e,
+  e38216db, e267078b).
+
+- Updated dependencies [1b50f9d]
+- Updated dependencies [1b50f9d]
+  - @artblocks/abx-sdk@0.1.0-alpha.7
+
+## 0.1.0-alpha.6
+
+### Patch Changes
+
+- Updated dependencies [1158420]
+- Updated dependencies [1158420]
+- Updated dependencies [1158420]
+  - @artblocks/abx-sdk@0.1.0-alpha.6
+
+## 0.1.0-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [feba8c2]
+  - @artblocks/abx-sdk@0.1.0-alpha.5
+
+## 0.1.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [67b686b]
+  - @artblocks/abx-sdk@0.1.0-alpha.4
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [a72723d]
+  - @artblocks/abx-sdk@0.1.0-alpha.3
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [3745bd3]
+- Updated dependencies [3745bd3]
+  - @artblocks/abx-sdk@0.1.0-alpha.2
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [4074766]
+  - @artblocks/abx-sdk@0.1.0-alpha.1

package/dist/arweave.d.ts

@@ -256,4 +256,18 @@ export declare class ArweaveBackend implements StorageBackend {
  *  secrets). `ABX_ARWEAVE_ETH_SIGNER_KEY` selects an EVM Turbo identity (the CLI usually sets this
  *  from the resolved signing key instead). */
 export declare function arweaveConfigFromEnv(): ArweaveConfig;
+/** Where the CLI keeps the Turbo identity it creates and manages on first upload. */
+export declare function arweaveKeyFilePath(): string;
+/**
+ * The ONE place either layer resolves an Arweave identity: `ARWEAVE_JWK` (an explicit, inline
+ * secret) if set, else the CLI-managed key file.
+ *
+ * That fallback is the whole point. The CLI mints and manages `.abx-self-host/arweave-key.json` on
+ * first upload, but this function used to read `ARWEAVE_JWK` and nothing else — so an integrator
+ * porting a working CLI flow to the SDK, on the same machine, minutes later, had every upload fail
+ * with "Arweave via Turbo needs an identity". The message said storage was never configured; the
+ * truth was that two layers disagreed about where the identity lives, and it named neither the file
+ * nor the mismatch. They reimplemented this lookup themselves to get moving.
+ */
+export declare function resolveArweaveJwk(): ArweaveJwk | undefined;
 //# sourceMappingURL=arweave.d.ts.map

package/dist/arweave.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arweave.d.ts","sourceRoot":"","sources":["../src/arweave.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"arweave.d.ts","sourceRoot":"","sources":["../src/arweave.ts"],"names":[],"mappings":"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"}

package/dist/arweave.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
 import { privateKeyToAccount } from 'viem/accounts';
 import { ContentIndex } from './content-index.js';
 import { arweaveAddress } from './arweave-identity.js';
@@ -440,10 +442,47 @@ export function arweaveConfigFromEnv() {
         provider: process.env.ABX_ARWEAVE_PROVIDER,
         uploadUrl: process.env.ABX_ARWEAVE_UPLOAD_URL,
         token: process.env.ARWEAVE_UPLOAD_TOKEN,
-        jwk: parseJwkEnv(process.env.ARWEAVE_JWK),
+        jwk: resolveArweaveJwk(),
         ethSignerKey: process.env.ABX_ARWEAVE_ETH_SIGNER_KEY,
     };
 }
+/** Where the CLI keeps the Turbo identity it creates and manages on first upload. */
+export function arweaveKeyFilePath() {
+    const dataDir = process.env.ABX_DATA_DIR ?? resolvePath(process.cwd(), '.abx-self-host');
+    return process.env.ABX_ARWEAVE_KEY_FILE ?? resolvePath(dataDir, 'arweave-key.json');
+}
+/**
+ * The ONE place either layer resolves an Arweave identity: `ARWEAVE_JWK` (an explicit, inline
+ * secret) if set, else the CLI-managed key file.
+ *
+ * That fallback is the whole point. The CLI mints and manages `.abx-self-host/arweave-key.json` on
+ * first upload, but this function used to read `ARWEAVE_JWK` and nothing else — so an integrator
+ * porting a working CLI flow to the SDK, on the same machine, minutes later, had every upload fail
+ * with "Arweave via Turbo needs an identity". The message said storage was never configured; the
+ * truth was that two layers disagreed about where the identity lives, and it named neither the file
+ * nor the mismatch. They reimplemented this lookup themselves to get moving.
+ */
+export function resolveArweaveJwk() {
+    const fromEnv = parseJwkEnv(process.env.ARWEAVE_JWK);
+    if (fromEnv)
+        return fromEnv;
+    const file = arweaveKeyFilePath();
+    if (!existsSync(file))
+        return undefined;
+    const raw = readFileSync(file, 'utf8');
+    if (raw.trim() === '') {
+        // An empty key file is a real state (an interrupted first upload), and the bare parser error it
+        // used to produce — "Unexpected end of JSON input" from `abx doctor` — pointed at a parser
+        // rather than the file or the remedy.
+        throw new Error(`Arweave key file ${file} is empty — delete it and re-run; the CLI mints a fresh managed identity on the next upload.`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Arweave key file ${file} is not valid JSON — delete it to regenerate, or point ABX_ARWEAVE_KEY_FILE at a valid JWK.`);
+    }
+}
 function parseJwkEnv(raw) {
     if (!raw)
         return undefined;