tracking: DecisioningPlatform as the canonical AdCP adapter contract — alignment, migration, and positioning

[bokelley]

🚧 DO NOT TRIAGE — tracking / positioning issue, owned by @bokelley. Work is decomposed across child issues #477, #478, #479. Do not assign work directly here.

Why this issue exists

When an AdCP operator sits down to build a multi-tenant sales agent today, the natural design instinct is to define an AdServerAdapter ABC — a contract their adapters (GAM, Kevel, Triton, in-house) implement, with a registry that dispatches per tenant. We've now seen this pattern emerge independently in at least one mature downstream (~15K LOC of Layer-2 infrastructure built around a custom AdServerAdapter).

The SDK already ships the contract: adcp.decisioning.DecisioningPlatform + specialism mixins (SalesPlatform, SignalsPlatform, CreativePlatform, GovernancePlatform, etc.) + AccountStore + BuyerAgentRegistry + TaskRegistry + webhook_emit + dispatch + compose. Operators who write their own AdServerAdapter ABC are building a parallel implementation of DecisioningPlatform.

This isn't anyone's fault. The SDK has historically been positioned as "protocol runtime + types," not "the canonical adapter contract." Operators who want a multi-tenant adapter pattern have to dig into adcp.decisioning and infer the seam from the reference seller, which assumes one platform per process.

This tracking issue captures the strategic alignment work: make DecisioningPlatform the obvious answer to "what's the AdCP adapter contract?", with worked examples for the multi-platform case and migration patterns for operators with parallel abstractions.

Scope (constituent issues)

The actual work is decomposed into three child issues:

• feat(examples): multi-platform-per-process proof — mock platforms with PlatformRouter, refactor v3 reference seller along the way #477 — Multi-platform proof + ref seller refactor. Two pure-Python in-process mock platforms (MockGuaranteedPlatform, MockNonGuaranteedPlatform) + PlatformRouter recipe + storyboard validation across two tenants. Refactors examples/v3_reference_seller/ to use PlatformRouter as the single composition pattern. The canonical worked example for multi-tenant adapter migration.

• feat(decisioning): project full get_adcp_capabilities response schema into DecisioningCapabilities #479 — Capabilities projection. Project full get_adcp_capabilities response schema into DecisioningCapabilities (currently 7 fields, spec defines ~25 across 13 blocks). Removes the need for adopters to override get_adcp_capabilities with hand-built dicts. Makes DecisioningCapabilities a complete declarative surface.

• feat(webhooks): HMAC/bearer outbound delivery + Docker localhost normalization for parity with operator-shaped webhook senders #478 — Webhook delivery extensions. HMAC + bearer + Docker localhost normalization + Standard Webhooks scheme on the existing WebhookSender / WebhookDeliverySupervisor. Closes the "operator-shaped legacy webhook" gap that pushes operators to roll their own.

What's deliberately NOT in scope

• Promoting PlatformRouter from example → SDK runtime (adcp.decisioning.dispatch.PlatformRouter). Wait until the example proves out under feat(examples): multi-platform-per-process proof — mock platforms with PlatformRouter, refactor v3 reference seller along the way #477, then file a follow-up.
• Building a codemod from any specific operator's adapter shape to DecisioningPlatform. Operators are too divergent to make a single codemod useful. Migration docs cover the patterns; codemod work is per-adopter and lives in their repos.
• Inventory / product-catalog primitives as SDK seams. Latent — no current downstream blocking on them. Defer until a second sales-agent operator validates demand.
• Adapter SPI / entry-point discovery (third-party adapter packages discoverable via pip install adcp-<vendor>-adapter). Defer until feat(examples): multi-platform-per-process proof — mock platforms with PlatformRouter, refactor v3 reference seller along the way #477 proves the multi-platform pattern in practice. Premature standardization risks codifying the wrong shape.
• Adopter-specific migration PRs. Those are downstream work in adopter repos, not SDK work. We supply patterns and worked examples; adopters choose if and when to migrate.

Success criteria

This tracking issue closes when:

• Child issues feat(examples): multi-platform-per-process proof — mock platforms with PlatformRouter, refactor v3 reference seller along the way #477, feat(webhooks): HMAC/bearer outbound delivery + Docker localhost normalization for parity with operator-shaped webhook senders #478, feat(decisioning): project full get_adcp_capabilities response schema into DecisioningCapabilities #479 have all merged
• docs/decisioning/adapter-contract.md documents the canonical contract and links the worked examples
• At least one external downstream has either (a) migrated to DecisioningPlatform against the new patterns, or (b) provided concrete feedback on what's still missing
• The SDK README / landing docs surface "build an AdCP adapter" as a first-class workflow with a clear entry point

Why this matters strategically

Three downstream effects, in order of immediacy:

1. Reduces duplicate-implementation cost for operators. Every operator writing their own AdServerAdapter is rebuilding what DecisioningPlatform already does — usually with worse multi-tenant ergonomics, less spec coverage, and webhook delivery bugs the SDK has already solved (signed-bytes-vs-sent-bytes, retry/circuit-breaker, durable queue).

2. Establishes the marketplace seam. Once DecisioningPlatform is the obvious answer, third parties (publishers, SSPs, vendors) can ship adapter packages against a stable contract. Today there's no contract to ship against — every adapter is monorepo-bound.

3. Aligns SDK positioning with AAO mission. The SDK shifts from "Python types + protocol runtime" to "the runtime everyone uses to build AdCP-conformant adapters." That's the ecosystem play; the protocol-library framing leaves the high-leverage layer (Layer 2) unowned and re-implemented N times.

Open positioning questions (no decision needed yet)

• Should adcp.adapters exist as a package namespace? Today everything platform-shaped lives under adcp.decisioning. "Adapter" might be more discoverable for operators arriving from a multi-tenant-SaaS background; "decisioning platform" is more accurate to the AdCP spec. Possible to ship adcp.adapters as an alias namespace re-exporting adcp.decisioning symbols.

• Should the SDK ship reference adapters? A Python-native mock adapter is built in feat(examples): multi-platform-per-process proof — mock platforms with PlatformRouter, refactor v3 reference seller along the way #477. Whether adcp-<vendor>-adapter packages are an SDK-org concern or community-owned projects is a positioning call we can defer.

---

This issue is positioning, not engineering. Engineering happens in #477 / #478 / #479. Don't let this issue accumulate scope creep — the moment something concrete needs doing, it gets a child issue.

[bokelley]

Triage

Classification: tracking/meta
Bucket(s): cross-cutting (examples, docs, client, handlers)
Status: deferred

My take: This is a parent tracking issue; all concrete engineering is decomposed into open child issues #477, #478, #479. Nothing to execute or clarify here — scope, success criteria, and ownership are fully defined in the children.

Blocked-on: #477, #478, #479 — resurfaces on merge.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code