feat(buyer-agent-registry): add caching + rate-limiting + audit emission to PgBuyerAgentRegistry

[bokelley]

Context

PgBuyerAgentRegistry (and the v3 ref seller's TenantScopedBuyerAgentRegistry which delegates to it) hits the database on every dispatch with:

• no in-process cache
• no rate limit
• no audit emission on resolve outcomes

Production sellers will eat unnecessary DB load, and the lookup endpoint becomes a credential-stuffing oracle for an attacker who can probe it.

Refs:

• src/adcp/decisioning/pg/buyer_agent_registry.py
• examples/v3_reference_seller/src/buyer_registry.py

Acceptance Criteria

• In-process TTL cache (default 60s, configurable) keyed on the lookup tuple
• Per-tenant (or per-source-IP) rate limit on the resolve path, configurable
• Audit event emitted on every resolve outcome (hit / miss / rate-limited / error) via the existing audit hook
• Metrics hooks (counter for hits/misses/rate-limits, latency histogram)
• Cache invalidation on registry mutations (sync / delete)
• Unit tests cover cache hit/miss/expiry, rate-limit triggering, audit emission

[bokelley]

Triage

Classification: Feature request
Bucket(s): client (label client not in repo label list — gap noted)
Status: ready-for-human

What the experts said:

• security-reviewer: Rate limiting is impossible at the registry layer (no tenant/IP in resolve_* signatures); default 60s TTL creates a blocked-agent enforcement window where a fraud-cut agent continues to dispatch; thread safety across asyncio.to_thread workers requires threading.Lock throughout.
• code-reviewer: Default-on 60s TTL silently breaks the "status change takes effect immediately" contract tested for set_status; per-tenant rate limiting requires either a Protocol signature amendment or an explicit ContextVar carrier the framework doesn't currently set on the registry call path.
• ad-tech-protocol-expert: Registry-layer rate limiting is an antipattern — belongs at SkillMiddleware/HTTP layer where source IP and caller_identity are available; default 60s TTL violates AdCP's commercial-identity safety invariant (blocked agent authorized for up to 60s more spend); pre-dispatch audit events lack caller_identity and a skill operation, producing a heterogeneous event stream.

My take: The caching and audit emission items are implementable with clear fixes — opt-in TTL default, threading.Lock discipline, and a distinct operation prefix like registry.resolve.* for pre-dispatch events. The rate-limiting item needs a design decision: it belongs at the SkillMiddleware layer, and per-tenant keying can't work without context that isn't in the BuyerAgentRegistry Protocol today. Recommend splitting: (1) opt-in TTL cache + invalidation hooks as a non-breaking, execute-ready change; (2) a separate design discussion for rate limiting via middleware composition.

Flagging for @bokelley's architectural call.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01Qy5BDxx7bfeYHdDU5me45f

---

Generated by Claude Code

[bokelley]

Splitting as recommended.

This issue, execute now — non-breaking, opt-in:

• TTL cache with ttl_seconds: float | None = None (default off — preserves the "status change takes effect immediately" contract). Adopters opt in explicitly.
• Invalidation hooks on set_status / equivalent mutation paths so opt-in cache stays correct when called through the registry.
• threading.Lock discipline throughout for asyncio.to_thread worker safety.
• Pre-dispatch audit events use registry.resolve.* as the operation prefix to keep the event stream homogeneous and distinguishable from skill-dispatch audits.

Deferred to a new issue — rate limiting at SkillMiddleware:
Registry layer is the wrong seam (no tenant/IP/caller_identity in resolve_* signatures). Please open a follow-up "feat(middleware): per-tenant rate limiting for buyer-agent resolution" and link this issue. I'll triage it separately.

Please draft for the caching + audit half only.

[bokelley]

/triage execute

Decisions resolved in the prior comment. Please proceed to drafting.