Spec inconsistency: `Submitted` arm in per-tool response `oneOf` for 4 of 6 HITL tools

[bokelley]

Summary

The AdCP 3.0 GA cache ships HITL *-async-response-submitted.json schemas for 6 tools (per core/async-response-data.json), but only 2 of 6 roll the Submitted arm into their per-tool xxx-response.json oneOf discriminated union. The other 4 are inconsistent — Submitted exists in the async-response-data union but not in the per-tool response schema.

This breaks SDK codegen: tools where xxx-response.json includes the Submitted arm get a typed response union (Success | Error | Submitted); tools where Submitted lives only in async-response-data.json get a narrower Success | Error union, leaving SDK adopters unable to write type-safe *Task HITL methods for those tools.

Tools and current state

Tool	xxx-response.json includes Submitted in oneOf?	xxx-async-response-submitted.json exists?
create_media_buy	✅ Yes	✅ Yes
sync_creatives	✅ Yes	✅ Yes
update_media_buy	❌ No	✅ Yes
build_creative	❌ No	✅ Yes
sync_catalogs	❌ No	✅ Yes
get_products	❌ No (success-body shape, not oneOf at top level)	✅ Yes

Verified against schemas/cache/3.0.0/ in @adcp/client@5.18.0.

Why this matters

Adopters building HITL agents need a typed seam to model "buyer gets the submitted envelope; platform does the work later" workflows. The @adcp/client SDK exposes per-tool xxxTask methods on the platform interface for tools where the response union includes Submitted — that's working today for create_media_buy and sync_creatives (e.g., trafficker review workflows for guaranteed/broadcast TV inventory).

For the other 4 tools, adopters can't ship typed HITL surfaces today even though the spec clearly intends them:

• update_media_buy — operator re-approval of mid-flight changes
• build_creative — slow generative pipelines (multi-minute LLM workflows)
• sync_catalogs — retail-media catalog ingestion + dedup against existing inventory
• get_products — proposal-mode sales (custom curation, brief-to-product matching)

These are real, common HITL workflows. Workarounds exist (publishStatusChange event bus + buyer subscribes to status updates) but they're strictly worse than a typed Submitted arm — buyers can't pattern-match on the response shape, can't cache, can't write idempotent retries against a stable task_id that arrives in the immediate response.

Proposed fix

Update the 4 xxx-response.json schemas to include the Submitted arm in their top-level oneOf, matching the pattern used by create-media-buy-response.json and sync-creatives-response.json:

{
  "oneOf": [
    { "$ref": "/schemas/3.0.0/.../xxx-success.json" },
    { "$ref": "/schemas/3.0.0/.../xxx-error.json" },
    { "$ref": "/schemas/3.0.0/.../xxx-async-response-submitted.json" }
  ]
}

Files to change:

• schemas/v3/media-buy/update-media-buy-response.json — add UpdateMediaBuyAsyncSubmitted arm
• schemas/v3/media-buy/build-creative-response.json — add BuildCreativeAsyncSubmitted arm
• schemas/v3/media-buy/sync-catalogs-response.json — add SyncCatalogsAsyncSubmitted arm
• schemas/v3/media-buy/get-products-response.json — restructure to oneOf at top level OR add a parallel Submitted discriminated path

The submitted-arm schemas already exist (xxx-async-response-submitted.json); this is purely a oneOf extension on the per-tool response schemas.

Backward compatibility

Additive — existing receivers that only handle Success/Error continue working. Buyers gain a new permitted response shape. Spec-validating receivers that strictly check the per-tool oneOf start accepting Submitted envelopes for these tools, which they already accept conceptually via async-response-data.json.

Reference

• SDK PR adopting the dual-method shape (HITL split): feat(server): DecisioningPlatform v6.0 preview surface adcp-client#1005
• SDK code where this gap is documented: src/lib/server/decisioning/runtime/validate-platform.ts (DUAL_METHOD_PAIRS + comment) and src/lib/server/decisioning/specialisms/sales.ts (codegen-gap JSDoc on update_media_buy, get_products)

Context

Filing on behalf of @adcp/client v6.0 preview adopters (training-agent, agentic-adapters, scope3) who hit this when migrating to the typed HITL surface.

[bokelley]

Triage

Classification: Conformance failure (spec inconsistency)
Bucket(s): spec / protocol, schema
Status: drafting-pr (partial) + ready-for-human (get_products)

What the experts said:

• ad-tech-protocol-expert: non-breaking additive for all 3 agreed tools; inline arm pattern (not $ref) is correct — the *-async-response-submitted.json files are task-completion artifact payloads, not initial-response arms; discriminant guards are sound
• adtech-product-expert: ship update_media_buy, build_creative, sync_catalogs — real HITL workflows, typed Submitted is clearly better than event-bus workaround; defer get_products — "submitted" on a query endpoint is semantically unusual and may belong on a separate request_curation/submit_brief tool

My take: Draft PR #3404 covers the 3 unambiguous tools. The get_products question has expert split: protocol says the restructuring is technically non-breaking; product says the semantics are wrong for a query endpoint and it might warrant a separate tool.

@bokelley, your call on get_products:

Option A — add Submitted arm to get-products-response.json (restructure flat schema to oneOf):

// get-products-response.json — wrap existing flat shape in oneOf
-{ "type": "object", "properties": { "products": [...], ... }, "required": ["products"] }
+{ "oneOf": [
+  { "title": "GetProductsSuccess", "required": ["products"], ... },
+  { "title": "GetProductsSubmitted", "required": ["status", "task_id"],
+    "properties": { "status": { "const": "submitted" }, "task_id": "...",
+                    "estimated_completion": "...", "context": ..., "ext": ... } }
+] }

Wire-additive for JSON consumers; changes SDK union type from plain object to discriminated union.

Option B — defer get_products as a separate tool design discussion:

// get-products stays flat; submit_brief / request_curation introduced in 3.x
// as the canonical async product-search entry point

Avoids semantically confusing "query returning submitted"; keeps HITL surface clean.

The remaining 3 tools shipped in #3404. This issue stays open as tracker for get_products.

---

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

---

Generated by Claude Code