feat(contracts): Safe-multisig PKP owner backfill tooling + verifier (#575)

[clawdbot-glitch003]

Follow-up to #577 (merged). Operational tooling to actually run the #575 backfill through the diamond owner Safe, plus an independent verifier — and a correctness fix to the ownership source.

Context from running it against Base mainnet

The diamond 0xaAaA…7Aa is live with the #575 facets (getPkpOwnerMaster present). Owner is a 2-of-4 Safe (0xF688…1098); configOperator is an EOA. There are 14,070 PKPs across 485 accounts, all currently unbound, zero multi-account conflicts (no hijack has landed on-chain).

The correctness fix: enumerate accounts, don't scan events

While validating, I found the event-only approach (the backfill-pkp-owners task from #577) is incomplete: 436 PKPs exist in the on-chain allPkpIds ledger with no WalletDerivationRegistered event — they were migrated into the diamond's storage at deployment without emitting. allPkpIdsAt(1) (the very first PKP) is one of them. An event-only scan silently drops all 436, and its coverage check couldn't catch the gap because it only looked at event-derived pkpIds.

Fix: reconstruct ownership from account enumeration (listPkps) — the exact pkpData mapping the node reads to sign. It covers every PKP (migrated + evented) and is authoritative. A pkpId held by >1 account is an on-chain hijack (none exist now) and is excluded unless --allow-conflicts, which then disambiguates via first-registrant events. The old EOA task is switched to the same source.

What's here

• tasks/lib/pkp-owners.ts — shared: account-enumeration ownership, Safe batch build, calldata + MultiSend decode.
• pkp-backfill:gen-safe — emits safe-backfill-NN.json (Safe Transaction Builder format, multisend-bundled, sized to Base's 400M block limit) + a manifest.
• pkp-backfill:verify-safe — decodes the JSON and checks every binding against account-enumeration ownership, live getPkpOwnerMaster (unbound or already-correct), and full coverage (no unbound PKP missing). This is the "check the Safe JSON against on-chain" tool.
• backfill-pkp-owners (EOA path) — switched to account enumeration, fixing the 436-miss gap.
• tasks/README-pkp-backfill.md — operator runbook.
• Tests: ABI-drift guard (my ABI's selectors + event topic vs the compiled facets), encode/decode round-trip, MultiSend unwrap, bad-selector rejection.

Verified end-to-end against mainnet (read-only)

Generated 8 Safe files covering all 14,070 bindings (~53M gas each), then verify-safe:

Decoded 14070 distinct bindings across 15 call(s).
accounts=485 distinct=14070 conflicts=0
  14070 will be written, 0 already correct.
  0 unbound owned pkpId(s) missing from JSON.
VERIFY: PASS — the Safe JSON matches authoritative on-chain ownership.

Spot-checked allPkpIdsAt(1) (0x6020…, previously missed): now bound to its holding account's hash.

Generated JSON lands in .context/pkp-backfill/ (gitignored); not committed.

Deploy note

backfillPkpOwners is idempotent (skip-if-set), so the 8 Safe txs can be signed/executed in any order and re-run safely. Re-run verify-safe after execution — every pkpId should report "already correct" and 0 remaining.

🤖 Generated with Claude Code

[clawdbot-glitch003]

Added: contract cleanup (this becomes the next facet upgrade)

The one-time backfill is complete on Base mainnet — all 14,070 pre-existing PKPs are bound (verified 0 unbound, 0 conflicts, 0 bound-to-non-owner across all 486 accounts). So this PR now also removes the spent migration machinery from the contract, to ship in the next facet upgrade:

• WritesFacet: removed backfillPkpOwners() and the PkpOwnerBackfilled event.
• ViewsFacet.getWalletDerivation: removed the owner == 0 compatibility fallback — enforcement is now unconditional (fail-closed). registerWalletDerivation always sets the owner when it writes pkpData, and the backfill bound every legacy PKP, so a non-zero derivation always has a non-zero owner; an owner == 0 now reverts instead of serving the path.
• Kept getPkpOwnerMaster (ongoing audits) and the core first-owner binding in registerWalletDerivation.
• Updated Foundry tests (dropped the backfill test; the owner == 0 test now asserts fail-closed), DiamondDeploy selectors, and regenerated the alloy bindings.

The Safe/EOA backfill tasks are kept as the historical record of how the migration was run and marked HISTORICAL — their on-chain target no longer exists after this upgrade's cut.

Verification: forge test 50/50, cargo check clean, tooling mocha 6/6, tsc clean.

Deploy note: this requires a diamondCut that (a) replaces WritesFacet (drops the backfillPkpOwners selector) and (b) replaces ViewsFacet (getWalletDerivation behavior change). Do it after the configOperator is restored from the temp EOA (0x4141…) back to 0x7774… — don't stack a facet upgrade while the operator role sits on a throwaway key.

[GTC6244]

@glitch003 - do you want this committed, or can we close ?