Multi-specialism + governance-aware adapter spec gaps — surfaced by hello adapter validation

[bokelley]

Context

While building a multi-tenant + multi-specialism hello adapter for @adcp/sdk (branch adcontextprotocol/adcp-client@bokelley/hello-adapters-gov-rights, tracking issue adcp-client#1387) and running it through protocol expert review, several spec-level gaps surfaced. Three already filed individually: #3892 (rights_grant_id storyboard capture), #3913 (storyboard runner context seeding), #3914 (GOVERNANCE_DENIED storyboard convention). This is the meta-issue for the rest.

Items

Wire schema gaps

• Add account: AccountReference to AcquireRightsRequest. Every governance-aware brand agent needs operator+brand to look up the account-scoped governance binding. The brand-rights compliance storyboard already sends account: { brand, operator } in acquire_rights_denied's sample request, but the schema doesn't define it — so the framework strips/ignores it for account resolution and adapters fall back to req.buyer.domain (which is the brand, not the buyer's account). Same shape every other governance-aware tool already has.

• Add optional plan_id to SyncGovernanceRequest.accounts[].governance_agents[]. The wire request binds a governance agent URL to an account but doesn't reference which plan that agent is authoritative for. Adopters today invent conventions ("first plan wins", "active plan") because the wire is silent. Explicit plan_id removes the guesswork and matches how brand agents actually consult governance on acquire_rights.

• Doc-comment clarification on GOVERNANCE_DENIED placement. error-code.json says it means "registered governance agent denied the transaction" — but is the canonical wire shape (a) AcquireRightsRejected with reason referencing the denial, or (b) thrown AdcpError projected as adcp_error.code: GOVERNANCE_DENIED, or (c) AcquireRightsError.errors[].code: GOVERNANCE_DENIED? Different storyboards interpret differently (brand_rights/governance_denied storyboard: expect_error: code: GOVERNANCE_DENIED is non-spec — AcquireRightsRejected is the canonical denial shape #3914 documents one mismatch). Suggest spec doc-comment: prefer Rejected arm for adopter-controlled denial; reserve thrown error for governance-call FAILURE (timeout / unreachable / config error), parallel to GOVERNANCE_UNAVAILABLE.

• Broaden estimated_impressions MUST. Spec at acquire-rights-request.json:64 requires estimated_impressions only when the request carries an intent-phase governance_context AND CPM pricing. But governance-aware brand agents that bind via sync_governance (not via inline governance_context token) STILL need to project CPM spend — and "implementer-chosen defaults are non-conformant" per the same spec note. Resolution: any governance-aware CPM projection requires estimated_impressions, not just intent-phase context-token flows. Otherwise adopters either invent non-conformant defaults or block compliance scenarios that reasonable buyer flows produce.

• Loosen ^https:// URL pattern for cross-agent dial-out URLs in dev. The schema rejects http://localhost:3003/mcp as a governance_agent_url even when the storyboard runner is invoked with --allow-http. Hello adapters demonstrating cross-agent integration locally need a way to register a dev-mode URL. Suggest: ^(https://|http://(localhost|127\.0\.0\.1)(:[0-9]+)?(/.*)?$). Same fix benefits webhook URLs and any *_url field used for cross-agent calls.

Storyboard runner

• Wire --default-agent CLI flag. The default_agent storyboard YAML field landed via Storyboard schema: per-storyboard default_agent field for multi-agent runner routing #3894, but bin/adcp.js storyboard run doesn't accept a CLI override. Cross-specialism storyboards (governance + brand-rights, governance + media-buy) can't be tested against a multi-specialism agent without per-step agent: annotations. Companion to storyboard runner: no way to seed $context.governance_agent_url for full storyboard run mode #3913 (no --context for full runs).

Spec-repo CI

• Assert every storyboard step's expect_error.code and context_outputs.path resolve to fields/codes the spec schemas define. The rights_grant_id (brand-rights storyboard captures rights_grant_id from acquire_rights — spec field is rights_id #3892) and GOVERNANCE_DENIED (brand_rights/governance_denied storyboard: expect_error: code: GOVERNANCE_DENIED is non-spec — AcquireRightsRejected is the canonical denial shape #3914) bugs were both "storyboard authored a non-spec opinion" — adopter-friendly tests caught real regressions but only after they'd shipped. CI gate that walks the storyboard cache and validates every assertion against the spec schema definitions would catch this class of drift at storyboard-author time, not at adopter-validation time.

Cross-references

• Already filed: brand-rights storyboard captures rights_grant_id from acquire_rights — spec field is rights_id #3892 (rights_grant_id capture in brand-rights storyboard), storyboard runner: no way to seed $context.governance_agent_url for full storyboard run mode #3913 (runner context seeding), brand_rights/governance_denied storyboard: expect_error: code: GOVERNANCE_DENIED is non-spec — AcquireRightsRejected is the canonical denial shape #3914 (GOVERNANCE_DENIED storyboard convention)
• Related downstream meta-issue: adcp-client#1387 (SDK side of the same gaps)

[bokelley]

Triage

Classification: Spec gap (mix of schema additions, doc clarification, CI tooling)
Bucket(s): spec/protocol, compliance-suite, governance
Status: drafting-pr (items 1, 3, 7) / ready-for-human (items 2, 4, 5) / cross-repo (item 6)

What the experts said:

• ad-tech-protocol-expert: items 1 and 3 are non-breaking and correct; item 2 needs WG clarification on plan_id semantics (filter hint vs. mandatory assertion?) before the field is normative; item 4 is breaking-shaped even on experimental (coordinate release); item 5 belongs in the runner layer, not the published schema
• adtech-product-expert: items 1 and 2 both unblock real adopter paths (governance arch broken without item 1); item 4 needs at least one concrete adopter on the sync_governance+CPM path before broadening the MUST; item 5 is a permanent security regression if put in the stable schema

My take: Three items are clear and non-breaking — PR drafted. Three items need WG input before they can land.

Draft PR: #3920 covers items 1 (add account to AcquireRightsRequest), 3 (GOVERNANCE_DENIED wire-arm clarification), and 7 (storyboard error-code CI lint + fix brand_not_found violation in brand/index.yaml). Targets 3.0.x; patch changeset.

@bokelley, your calls on the flagged items:

Item 2 — plan_id in SyncGovernanceRequest.accounts[].governance_agents[]: governance_agents items are additionalProperties: false on a stable schema (minor bump required). The field shape is clear, but the semantics aren't: is plan_id a filter hint to the seller ("only call governance for this plan"), a mandatory assertion ("fail if plan doesn't match"), or routing metadata ("use this agent when check_governance names this plan")? check_governance already carries plan_id per-call, so what does the registration-time binding add? Define the semantics first, then execute.

Item 4 — broaden estimated_impressions MUST to sync_governance+CPM paths: The gap is real and the fix direction is correct, but this adds a normative MUST that breaks currently-conformant implementations using sync_governance+CPM without the field. Per experimental-status.mdx: 6-week notice + next minor. Confirm this is in-scope for 3.1 and flag any known implementations that would need updating.

Item 5 — loosen ^https:// URL pattern for governance_agent_url: This relaxes a security constraint on a stable schema — every production validator downstream inherits the loosened pattern. The storyboard runner's --allow-http flag is the right layer. Options: (a) env-var-gated schema override in the runner at load time, (b) x-dev-override annotation the runner respects but production validators ignore. Please confirm the runner approach and I'll execute that instead.

Item 6 — --default-agent CLI flag: Cross-repo (adcp-client SDK bin/adcp.js). Not actionable in this spec repo.

---

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

---

Generated by Claude Code

[bokelley]

Landed across three PRs:

• spec(brand): account on acquire_rights/update_rights + bound CPM projection #3923 (merged) — account: AccountReference on AcquireRightsRequest + UpdateRightsRequest. Broadened the estimated_impressions MUST on acquire_rights to cover the sync_governance-bound path (was inline-governance_context-only). Doc-comment on SyncGovernanceRequest clarifying account-scoped binding (closes the plan_id ambiguity by making the existing model explicit). Stale anchor #buyer-side-governance-invocation → #spend-commit-invocation fixed across the touched validation prose.

• spec(errors): wire-placement guidance for GOVERNANCE_DENIED and GOVERNANCE_UNAVAILABLE #3929 (merged) — Wire-placement guidance for GOVERNANCE_DENIED and GOVERNANCE_UNAVAILABLE in error-code.json#enumDescriptions. Denial is a structured business outcome (use the rejection arm when the response defines one — AcquireRightsRejected, CreativeRejected — otherwise errors[] + adcp_error); unavailability is a system error (always errors[] + adcp_error, transport markers always flip). Parallel storyboard-authoring note in error-handling.mdx so authors know to assert on status: \"rejected\" for tasks with a discriminated rejection arm rather than error_code (the spec-correct response carries no code on the wire).

• ci(storyboards): lint context_outputs.path against the response schema #3937 (merged) — scripts/lint-storyboard-context-output-paths.cjs walking every storyboard, validating context_outputs[].path resolves to a defined field in the referenced response schema. Caught one real typo on land (offering_id → offering.offering_id in si_get_offering). Two captures through spec-sanctioned extension points (error.details polymorphism, idempotency_key echo) documented in an allowlist with reason strings. The expect_error.code half of the CI gate was already covered by lint-error-codes.cjs.

Deliberately deferred (in PR descriptions):

• plan_id field on sync_governance.accounts[].governance_agents[] — addressed via doc-comment instead. The wire commits to account-wide binding (maxItems: 1, singular governance_context envelope, account-keyed check_governance resolution); adding plan_id would conflict with that model. If a real adopter surfaces a multi-op-co pattern, the answer is "open a second account," not per-plan binding inside one.

• Loosened ^https:// URL pattern for dev-mode http://localhost in governance_agent_url / webhook URLs — this belongs in the storyboard runner's --allow-http mode, not the wire spec. Putting dev-mode bytes in the persisted wire schema lets non-dev senders inadvertently persist localhost URLs into real seller accounts.

• Storyboard runner --default-agent flag — separate runner work.

• update_rights commit-delta projection MUST — account was added in spec(brand): account on acquire_rights/update_rights + bound CPM projection #3923 (the trivial parallel), but the projection rule needs delta semantics design (impression_cap delta vs. pricing_option-switch delta) that deserves its own pass.

New follow-ups surfaced by expert review on #3937 (worth their own issues):

1. validations[].path lint — parallel to context_outputs.path but with different semantics (assertion against discriminated arms).
2. error-details-by-code resolver to lift the details.suggested_billing allowlist entry.
3. Spec issue to require idempotency_key echo on responses (currently relies on additionalProperties: true runtime convention; idempotency-replay conformance can't be checked without it).
4. expected_arm annotation on storyboard steps to disambiguate oneOf responses (would let pathResolves walk only the expected variant rather than accept any-arm).

Closing this meta-issue.