feat(testing): brand-rights + SI seeded bridges (#1755 phase 4)

[bokelley]

Summary

Phase 4 of the TestControllerBridge seeded-callback umbrella (#1755). Extends TestControllerBridge<TAccount> with three opt-in callbacks for brand-rights and sponsored-intelligence read tools:

Callback	Tool	Shape	Dedup key
getSeededBrandIdentity	get_brand_identity	singleton replace	brand_id
getSeededRights	get_rights	append-merge	rights_id
getSeededSiOffering	si_get_offering	singleton replace	offering.offering_id

SI investigation outcome

The umbrella issue flagged SI as a "design wildcard" because the SI flow has session-keyed state (si_initiate_session issues sessions; si_send_message advances them). Schema audit shows si_get_offering is the OUT-LIER inside that flow — it is a stateless catalog lookup:

• Request schema (SIGetOfferingRequest, src/lib/types/tools.generated.ts:12571): top-level offering_id: string is the only addressing field. No session_id, no offering_token.
• Response schema (SIGetOfferingResponse, line 12600): the response PRODUCES an offering_token for a FUTURE session but does not CONSUME one. The lookup itself is request-shaped, not session-shaped.

Conclusion: the standard singleton-replace pattern fits cleanly. Bridge is shipped.

The session-stateful SI tools (si_initiate_session, si_send_message, si_terminate_session) remain intentionally out of scope — a seeded fixture cannot honestly serve session state accumulated across prior conversational turns. If a future storyboard needs to seed in-session messages, that will need a different seam (likely session-store-keyed, not bridge-keyed).

Schema citations

• get_brand_identity — GetBrandIdentityRequest (core.generated.ts:5939, brand_id: string required), GetBrandIdentitySuccess (line 5996, top-level brand_id: string). Singleton response.
• get_rights — GetRightsRequest (line 6328, NL query: string), GetRightsSuccess.rights[] (line 6386, each entry has rights_id: string). Array response (discovery / search). No pagination / query_summary per AdCP 3.0.11.
• si_get_offering — SIGetOfferingRequest (tools.generated.ts:12571, offering_id: string required), SIGetOfferingResponse (line 12600, offering?: { offering_id?: string, ... }). Singleton response.

Tools skipped + why

• acquire_rights / update_rights — mutating; seeded read paths only per phase 4 scope. The original umbrella explicitly lists these as out of scope.
• si_initiate_session / si_send_message / si_terminate_session — mutating + session-stateful. A seeded fixture would lie about session state. Documented in code + changeset.
• creative_approval — listed under BrandRightsHandlers in the SDK but is webhook-only (not an MCP/A2A tool) per AdCP 3.0; not a discovery / read tool.

Established precedents followed

• Seeded wins on collision (both list path and singleton path)
• Triply-gated dispatch: controller present + sandbox marker on request + resolved account is sandbox: true when present
• Singleton replace preserves both handler's context AND ext (PR feat(testing): governance/property-lists/content-standards/collection-lists seeded bridges (#1755 phase 2) #1761 lesson)
• Validation: warn-and-drop, never throws
• Duplicate-id detection on singleton replace fixtures (first occurrence wins, mirrors filterValidSeededAccountFinancials)
• Type imports from generated wire types; core.generated for brand-rights types (per src/lib/types/index.ts:268), tools.generated for SI types

Test count delta

+21 new tests, all passing.

• 6 get_brand_identity (replace match / no match / context+ext preserve / sandbox-gate / validation-drop+duplicate)
• 6 get_rights (append / seeded-only / handler-only / collision / sandbox-gate / validation-drop)
• 6 si_get_offering (replace match / no match / context+ext preserve / sandbox-gate / validation-drop+duplicate)
• 3 bridgeFromSessionStore selector wiring (one per new callback)
• 1 selector-omission check

Total: 8716 pass / 0 fail across full npm test.

Doc + selectors added

• BridgeFromSessionStoreOptions gains selectSeededBrandIdentity, selectSeededRights, selectSeededSiOffering
• docs/guides/VALIDATE-YOUR-AGENT.md "Platform-proxy sellers" table extended with the three new selectors mapped to their specialism phases (brand-rights identity / rights discovery; sponsored-intelligence offering lookup)
• Validation-drop summary extended with the new dedup keys

Test plan

• npm run typecheck — clean on changed files
• npm run format:check — clean
• npm test (full root suite) — 8716 pass / 0 fail
• npm run build:lib — succeeds

Related

• Umbrella: feat(testing): next-phase TestControllerBridge seeded callbacks for proxy sellers #1755
• Phase 1: feat(testing): getSeededMediaBuyDelivery bridge callback + nit tests (#1755 phase 1) #1759 (getSeededMediaBuyDelivery)
• Phase 2: feat(testing): governance/property-lists/content-standards/collection-lists seeded bridges (#1755 phase 2) #1761 (governance bridges)

🤖 Generated with Claude Code

[bokelley]

Doc-only nit addressed

Added a JSDoc note on replaceSiOfferingIfSeeded capturing the future-coupling concern raised in protocol review: when phase 5 adds a stateful SI session bridge, the seeded offering_token here must match the seeded session's offering_token. Today, si_initiate_session is explicitly out of scope so no coupling exists; the comment is a tripwire for future readers.