feat: #225 E7 — ERC-4337 accept-batch callData builders (atomic P.2+P.3)

CLAUDE.md

@@ -271,6 +271,8 @@ same change** (the keep-the-docs-in-sync rule).
 
 ## Heima EVM compatibility level — keep `evm_version = "london"` in foundry.toml (but NOT because Heima is "London")
 
+> **Migration index:** every Heima-vs-Ethereum EVM divergence the repo works around (this `evm_version` pin, the `eth_estimateGas`-reverts-on-`handleOps` gas-limit pins, the mixHash-less-receipt on-chain re-verify posture, the `cast send --create` deploy path, the year-prefixed `chain_id`) is consolidated as a **gap → symptom → workaround → code site → what-changes-on-eth** inventory in [`docs/spec/heima-eth-gap.md`](docs/spec/heima-eth-gap.md), with a Heima→Ethereum migration checklist. This section stays the canonical home for the *capability proofs* below; the gap doc defers here for them.
+
 **Two separate things — do not conflate them (the earlier revision of this section did):**
 
 1. **EVM *execution* level (which opcodes the chain runs) = Cancun.** Heima's Frontier `stable2412` `pallet_evm` returns `&CANCUN_CONFIG` from `frame/evm/src/lib.rs::config()` (the `// London` doc-comment one line up is stale upstream). **Verified on-chain** (local `heima-node --dev`, 2026-06-01) by deploying + *executing* contracts that use post-London opcodes:
@@ -300,7 +302,16 @@ Determine the real opcode level any time by *executing* a probe on a dev chain (
 
 ## Deployed contract registry
 
-Live contract addresses on each chain (Heima mainnet v2 set, the ERC-4337 master infra #164, historical v1) plus the prod/test EVM deployer wallets are kept in [`docs/spec/deployed-contracts.md`](docs/spec/deployed-contracts.md) — the single canonical registry, indexed from `arch.md` §5. (`docs/contracts.md` is now a redirect to it.) The same addresses are also written to `scripts/operator-workstation.env` (via `env_set` in `scripts/heima-bring-up.sh` step 6) for shell-script consumption — those env-file entries are the operational source of truth and `docs/spec/deployed-contracts.md` is the human-readable canonical record (deployer, deploy date, block, explorer links, ABI summary).
+Live contract addresses on each chain plus the prod/test EVM deployer wallets are documented in [`docs/spec/deployed-contracts.md`](docs/spec/deployed-contracts.md) — **human PROSE only** (deployer wallets, ABI summaries, cutover/historical notes, explorer links), indexed from `arch.md` §5. (`docs/contracts.md` redirects to it.) It **no longer carries an address table** — the addresses live in the chain profile (below).
+
+**The machine-readable SOURCE OF TRUTH is the chain profile [`crates/agentkeys-core/chain-profiles/<chain>.json`](crates/agentkeys-core/chain-profiles/heima.json)** — a strict-typed `ChainProfile` (Rust struct + `include_str!` + the `chain_profile::tests::heima_carries_full_contract_registry_and_version` pinning test). Its `contracts[]` array holds each contract's address; `contract_set_version` holds the deployed SET version. `scripts/heima-bring-up.sh` step 6b **rewrites it programmatically on every fresh deploy** (alongside `scripts/operator-workstation.env`, the shell mirror, step 6). The **expected** source version lives in [`crates/agentkeys-chain/VERSION`](crates/agentkeys-chain/VERSION). (The former `deployed-contracts.json` was folded INTO the chain profile — do not re-create it.)
+
+**Two HARD rules when any contract changes:**
+
+1. **Idempotency is by VERSION, not bytecode.** Solidity bytecode isn't reliably comparable (embedded metadata hash + immutables), so do NOT diff bytecode. A redeploy is warranted when `crates/agentkeys-chain/VERSION` ≠ the chain profile's `contract_set_version` (or there's no on-chain code). **Bump `VERSION` when you change a contract** → the next deploy redeploys + bumps the profile's `contract_set_version`. A `VERSION` mismatch while code is already live is a **hard stop** (the script prints the mismatch + asks for an explicit opt-in — orphaning state costs mainnet gas), not an auto-redeploy. `FORCE_DEPLOY=1 heima-bring-up.sh` is a **BLIND manual override**; for the #225 account-auth cutover use [`scripts/heima-cutover-account-auth.sh`](scripts/heima-cutover-account-auth.sh) (probes the live `setScope` selector `d8e9e3c6` + skips when already live).
+2. **A new deploy auto-updates the two machine mirrors; YOU update only the prose + rebuild.** `heima-bring-up.sh` writes the chain profile (`contracts[]` + `contract_set_version`) + `operator-workstation.env` automatically. You ALSO touch `docs/spec/deployed-contracts.md` **only if the design/version changed** (the version line + any ABI/cutover note — no address table to edit), and since the profile is `include_str!`-compiled, **rebuild the broker/daemon/UI** (`setup-broker-host.sh --ref main`) so they serve the new addresses. `arch.md` §5 links to the registry (no literal addresses to edit). **Confirm locally — NOT a per-PR CI workflow (CI is reserved for heavier checks):** `bash scripts/check-deployed-contracts-sync.sh` (verifies the chain profile ⟷ `operator-workstation.env`).
+
+   **COMMIT + PUSH the two machine mirrors BEFORE you redeploy the broker (HARD — real #225 split-registry incident).** The broker host deploys from `origin/<branch>` and compiles the chain profile in via `include_str!`. If the freshly-rewritten `heima.json` + `operator-workstation.env` are left uncommitted (or committed-but-unpushed), `setup-broker-host.sh --ref <branch>` rebuilds the broker on the **OLD** registry while the local daemon onboards into the **NEW** one. The broker then reads `operatorMasterWallet` from the orphaned registry, builds the accept UserOp for the wrong (stale) master account, and `handleOps` reverts **`SIG_VALIDATION_FAILED`** — an accept failure that looks like a "wrong passkey" bug but is actually a split registry. Order: deploy → **commit + push `heima.json` + `operator-workstation.env`** → `setup-broker-host.sh --ref <branch>` on the host. `heima-bring-up.sh`'s step-7 guard warns loudly if you skip the commit.
 
 Verify all contracts are live + functional any time: