refactor(762b): unify OG cache invalidation via shared helper + identity-refresh shape parity

[whoabuddy]

Background

Council Cycle 9 (steel-yeti, 3-of-4 convergent) flagged a shape inconsistency introduced during the P3.2/P3.3 edge-cache campaign:

• app/api/challenge/route.ts was updated to use a unified addressesToBust: Set<string> + grouped Promise.all shape
• app/api/identity/[address]/refresh/route.ts retained the older middlewarePurges: Promise<void>[] array pattern

This inconsistent precedent means the two primary write paths have diverged in shape, making future maintenance harder and increasing the risk of alias coverage drift.

secret-mars narrowing note (Cairn Q1)

When extracting the shared helper, the middleware-OG purge component should be narrowed to btc/stx forms only. Per Phase 2.3 crawler-handler scope, middleware OG cache is exclusively keyed on btc:/stx: prefixes — purgeMiddlewareOgCache(taproot) and purgeMiddlewareOgCache(bnsName) are currently no-op purges (harmless but wasteful). By contrast, the /api/og purge via buildEdgeCacheKey("/api/og", addr) correctly keeps full enumeration since /api/og/[address] does support taproot/bnsName lookups.

Proposed implementation

Extract invalidateAllOgCaches(kv: KVNamespace, addresses: Set<string>, opts: { includeMiddleware: boolean }) in lib/edge-cache.ts. The helper would:

1. Always invalidate /api/og cache for all addresses in the set
2. When includeMiddleware: true, also run middleware-OG purge but filtered to btc/stx forms only

Adopt this helper in both:

• app/api/challenge/route.ts (already has the Set shape; wire up the helper)
• app/api/identity/[address]/refresh/route.ts (migrate from middlewarePurges: Promise<void>[] array to Set + helper)

Alias-parity gap (host loop finding)

identity-refresh's cachedAddresses Set includes {btc, stx, taproot?, previousBnsName?, nextBnsName?} but does NOT include previousTaprootAddress for the update-taproot action case. This is a minor alias-parity gap relative to challenge route's full previous-alias coverage. Folding this fix into the same cleanup pass is natural — extend cachedAddresses to include previousTaprootAddress when the refresh action changed it.

Scope

• lib/edge-cache.ts — add shared helper
• app/api/challenge/route.ts — adopt helper
• app/api/identity/[address]/refresh/route.ts — migrate shape + fix alias gap

References

• Council Cycle 9: steel-yeti advisory on feat(762b): edge-cache crawler OG render in middleware (caches.default, 5min TTL) #774 (2026-05-12T17:23:41Z)
• secret-mars narrowing note: Cairn Q1 on feat(762b): edge-cache crawler OG render in middleware (caches.default, 5min TTL) #774 (2026-05-12T16:50:39Z)
• Closes related shape debt from feat(762b): edge-cache crawler OG render in middleware (caches.default, 5min TTL) #774 and feat(762b): edge-cache /api/og/[address] (caches.default, 24h TTL) #775
• Parent campaign: perf(kv): migrate rate-limits + identity/BNS cache off VERIFIED_AGENTS KV (next cost-driver after #760) #762