@adcp/sdk 6.6.0 → 6.8.0

package/skills/build-seller-agent/SKILL.md

@@ -9,6 +9,8 @@ description: Use when building an AdCP seller agent — a publisher, SSP, or ret
 
 A seller agent receives briefs from buyers, returns products with pricing, accepts media buys, manages creatives, and reports delivery. The business model — what you sell, how you price it, and whether humans approve deals — shapes every implementation decision. Determine that first.
 
+> **Common shape gotchas:** `BuildCreativeReturn` has 4 valid shapes (framework auto-wraps the bare manifest), `VASTAsset` requires an embedded `delivery_type` discriminator. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) for patterns adopters consistently get wrong on first pass — schema validators catch these at runtime; type checkers don't.
+
 ## When to Use
 
 - User wants to build an agent that sells ad inventory
@@ -21,25 +23,27 @@ A seller agent receives briefs from buyers, returns products with pricing, accep
 - Serving audience segments → `skills/build-signals-agent/`
 - Rendering creatives from briefs → that's a creative agent
 
+**Often claimed alongside:** [`audience-sync`](../build-seller-agent/SKILL.md) (walled-garden social + identity provider patterns), [`signal-marketplace`](../build-signals-agent/SKILL.md) (DSP-side data surface), [`sales-catalog-driven`](../build-retail-media-agent/SKILL.md) (retail-media catalog + dynamic-creative). See [Common multi-specialism bundles](../../examples/README.md#common-multi-specialism-bundles).
+
 ## <a name="the-baseline-what-every-sales--agent-must-implement"></a>The baseline: what every sales-\* agent MUST implement
 
 Every sales-_ specialism (including `sales-social`, `sales-broadcast-tv`, `sales-retail-media`, `sales-catalog-driven`, etc.) is **additive on top of this baseline**. If you claim any `sales-_` specialism, you implement these tools regardless of the specialism-specific deltas below.
 
 **Required tools** (tested by the `media_buy_seller` storyboard bundle at `compliance/cache/3.0.0/protocols/media-buy/`):
 
-| Tool                     | Purpose                                                                            | `SalesPlatform` method   |
-| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------ |
-| `get_adcp_capabilities`  | Declare protocols + specialisms + features                                         | auto (framework)         |
-| `sync_accounts`          | Advertiser onboarding, per-tenant account creation                                 | `accounts.upsert`        |
-| `list_accounts`          | Account lookup by brand/operator; buyers listing their accounts on your platform   | `accounts.list`          |
-| `get_products`           | Product catalog discovery from a brief; returns `{ products: [...] }`              | `sales.getProducts`      |
-| `list_creative_formats`  | Formats your agent accepts                                                         | `sales.listCreativeFormats` |
-| `create_media_buy`       | Accept a campaign with packages, budget, flight dates                              | `sales.createMediaBuy`   |
-| `update_media_buy`       | Bid, budget, status, package mutations over the campaign lifecycle                 | `sales.updateMediaBuy`   |
-| `get_media_buys`         | Read campaigns back with full state (status, budget, packages, targeting overlays) | `sales.getMediaBuys`     |
-| `sync_creatives`         | Accept creative assets and return per-asset status                                 | `sales.syncCreatives`    |
-| `list_creatives`         | Read the creative library back with pagination                                     | `sales.listCreatives`    |
-| `get_media_buy_delivery` | Delivery + spend reporting with `reporting_period`, per-package billing rows       | `sales.getMediaBuyDelivery` |
+| Tool                     | Purpose                                                                                                                                                                                                                                                                                                                                        | `SalesPlatform` method      |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| `get_adcp_capabilities`  | Declare protocols + specialisms + features                                                                                                                                                                                                                                                                                                     | auto (framework)            |
+| `sync_accounts`          | Advertiser onboarding, per-tenant account creation                                                                                                                                                                                                                                                                                             | `accounts.upsert`           |
+| `list_accounts`          | Account lookup by brand/operator; buyers listing their accounts on your platform                                                                                                                                                                                                                                                               | `accounts.list`             |
+| `get_products`           | Product catalog discovery from a brief; returns `{ products: [...] }`. **Surface `Product.forecast: DeliveryForecast`** when you have per-targeting estimates — see [`sales-guaranteed`](specialisms/sales-guaranteed.md#forecast-productforecast) and [`sales-social`](specialisms/sales-social.md#planning-surface) for projection patterns. | `sales.getProducts`         |
+| `list_creative_formats`  | Formats your agent accepts                                                                                                                                                                                                                                                                                                                     | `sales.listCreativeFormats` |
+| `create_media_buy`       | Accept a campaign with packages, budget, flight dates                                                                                                                                                                                                                                                                                          | `sales.createMediaBuy`      |
+| `update_media_buy`       | Bid, budget, status, package mutations over the campaign lifecycle                                                                                                                                                                                                                                                                             | `sales.updateMediaBuy`      |
+| `get_media_buys`         | Read campaigns back with full state (status, budget, packages, targeting overlays)                                                                                                                                                                                                                                                             | `sales.getMediaBuys`        |
+| `sync_creatives`         | Accept creative assets and return per-asset status                                                                                                                                                                                                                                                                                             | `sales.syncCreatives`       |
+| `list_creatives`         | Read the creative library back with pagination                                                                                                                                                                                                                                                                                                 | `sales.listCreatives`       |
+| `get_media_buy_delivery` | Delivery + spend reporting with `reporting_period`, per-package billing rows                                                                                                                                                                                                                                                                   | `sales.getMediaBuyDelivery` |
 
 > **`sales-guaranteed` minimum tool surface** — register ALL of these or storyboard scenarios will cascade-skip with `skip_reason: missing_tool`:
 > `get_adcp_capabilities`, `sync_accounts`, `list_accounts`, `get_products`, `list_creative_formats`, `create_media_buy`, `update_media_buy`, `get_media_buys`, `sync_creatives`, `get_media_buy_delivery`
@@ -99,7 +103,7 @@ Your compliance obligations come from the specialisms you claim in `get_adcp_cap
 
 | Specialism             | Status  | Delta from baseline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | See                                                        |
 | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `sales-guaranteed`     | stable  | IO approval is **task-layer**, not MediaBuy-layer. Return a task envelope (MCP Tasks SDK) with `status: 'submitted'` + `task_id` + `message`. Do NOT return `media_buy_id` or `packages` yet — those land on the final artifact when the task completes. There is no `pending_approval` MediaBuy status.                                                                                                                                                                                                                                     | [§ sales-guaranteed](#specialism-sales-guaranteed)         |
+| `sales-guaranteed`     | stable  | `create_media_buy` has **three return shapes** (IO-task envelope / `pending_creatives` / `active`) plus `TERMS_REJECTED` for aggressive `measurement_terms`. **Read the companion before coding** — applying only the task-envelope path fails 5 storyboard `create_media_buy` steps that probe the synchronous branches.                                                                                                                                                                                                                    | [§ sales-guaranteed](#specialism-sales-guaranteed)         |
 | `sales-non-guaranteed` | stable  | Instant `status: 'active'` with `confirmed_at`; accept `bid_price` on packages; expose `update_media_buy` for bid/budget changes                                                                                                                                                                                                                                                                                                                                                                                                             | [§ sales-non-guaranteed](#specialism-sales-non-guaranteed) |
 | `sales-broadcast-tv`   | stable  | Top-level `agency_estimate_number`; per-package `measurement_terms.billing_measurement`; Ad-ID `industry_identifiers` on creatives; `measurement_windows` (Live/C3/C7) on delivery                                                                                                                                                                                                                                                                                                                                                           | [§ sales-broadcast-tv](#specialism-sales-broadcast-tv)     |
 | `sales-streaming-tv`   | preview | v3.1 placeholder (empty `phases`) — ship the baseline, declare `channels: ['ctv'] as const` on products                                                                                                                                                                                                                                                                                                                                                                                                                                      | Baseline only                                              |
@@ -355,9 +359,7 @@ class WebhookSeller implements DecisioningPlatform {
             task: {
               task_id: taskId,
               status: outcome.approved ? 'completed' : 'rejected',
-              result: outcome.approved
-                ? { media_buy_id: outcome.media_buy_id, packages: outcome.packages }
-                : undefined,
+              result: outcome.approved ? { media_buy_id: outcome.media_buy_id, packages: outcome.packages } : undefined,
             },
           },
           operation_id: `create_media_buy.${taskId}`, // stable across retries — framework reuses same idempotency_key
@@ -436,7 +438,23 @@ Each pricing option can set `min_spend_per_package` to enforce minimum budgets.
 
 For all `PricingOption` variants and `Product` required fields, see [`docs/TYPE-SUMMARY.md`](../../docs/TYPE-SUMMARY.md).
 
-### 4. Approval Workflow
+### 4. Forecast & planning surface
+
+`Product.forecast: DeliveryForecast` is how sellers answer the planning question every buyer asks first — "what reach for $X," "what budget hits Y conversions," "is this guaranteed inventory still available." The protocol covers forward, reverse, availability, package, and reach/frequency curves via `forecast_range_unit`. Read the spec for the full surface, including budget-curve, availability, GRP, and outcome-forecast worked examples: [Delivery Forecasts](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#delivery-forecasts).
+
+Per-specialism canonical units (SDK-skill guidance — pick what fits your seller type):
+
+| Specialism             | `forecast_range_unit`         | What the curve says                           |
+| ---------------------- | ----------------------------- | --------------------------------------------- |
+| `sales-non-guaranteed` | `'spend'`                     | Forward — impressions/clicks per budget tier  |
+| `sales-guaranteed`     | `'availability'`              | Reserved inventory check, budget omitted      |
+| `sales-broadcast-tv`   | `'reach_freq'` or `'package'` | GRP curves OR daypart packages                |
+| `sales-social`         | `'conversions'` / `'clicks'`  | Reverse — Meta-style goal-based planning      |
+| `sales-retail-media`   | `'conversions'`               | Outcome-based (purchase-attribution use case) |
+
+Adapters typically populate this from existing upstream forecast/availability/reach-estimation endpoints (GAM `forecastService.getDeliveryForecast`, Meta `/delivery_estimate`, walled-garden `/audience_reach_estimate`, etc.) — the mapping is one-to-one once you pick the right unit.
+
+### 5. Approval Workflow
 
 For guaranteed buys, choose one:
 
@@ -446,7 +464,7 @@ For guaranteed buys, choose one:
 
 Non-guaranteed buys are always instant confirmation.
 
-### 5. Creative Management
+### 6. Creative Management
 
 - **Standard** — `list_creative_formats` + `sync_creatives`. Buyer uploads assets, seller validates.
 - **Catalog-driven** — buyer syncs product catalog via `sync_catalogs`. Common for retail media.
@@ -529,15 +547,15 @@ productsResponse({
 
 Return `adcpError(...)` for all business validation failures. Error-code matrix — all spec-defined rejections on `create_media_buy` / `update_media_buy`:
 
-| Tool | Condition | Code |
-| --- | --- | --- |
-| `create_media_buy` | `performance_standards` or `measurement_terms` on a package are unacceptable | `adcpError('TERMS_REJECTED', { message: '...' })` |
-| `create_media_buy` | `product_id` on a package not in catalog | `adcpError('PRODUCT_NOT_FOUND', { field: 'packages[N].product_id' })` |
+| Tool               | Condition                                                                    | Code                                                                    |
+| ------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `create_media_buy` | `performance_standards` or `measurement_terms` on a package are unacceptable | `adcpError('TERMS_REJECTED', { message: '...' })`                       |
+| `create_media_buy` | `product_id` on a package not in catalog                                     | `adcpError('PRODUCT_NOT_FOUND', { field: 'packages[N].product_id' })`   |
 | `create_media_buy` | product exists but inventory sold out / unavailable for the requested flight | `adcpError('PRODUCT_UNAVAILABLE', { field: 'packages[N].product_id' })` |
-| `create_media_buy` | budget below the product's floor price | `adcpError('BUDGET_TOO_LOW', { message: '...' })` |
-| `create_media_buy` | reversed dates, schema violation | `adcpError('INVALID_REQUEST', { message: '...' })` |
-| `update_media_buy` | `media_buy_id` not found | `adcpError('MEDIA_BUY_NOT_FOUND', { field: 'media_buy_id' })` |
-| `update_media_buy` | `package_id` within a valid buy not found | `adcpError('PACKAGE_NOT_FOUND', { field: 'package_id' })` |
+| `create_media_buy` | budget below the product's floor price                                       | `adcpError('BUDGET_TOO_LOW', { message: '...' })`                       |
+| `create_media_buy` | reversed dates, schema violation                                             | `adcpError('INVALID_REQUEST', { message: '...' })`                      |
+| `update_media_buy` | `media_buy_id` not found                                                     | `adcpError('MEDIA_BUY_NOT_FOUND', { field: 'media_buy_id' })`           |
+| `update_media_buy` | `package_id` within a valid buy not found                                    | `adcpError('PACKAGE_NOT_FOUND', { field: 'package_id' })`               |
 
 ```
 // Success — revision, confirmed_at, and valid_actions are auto-set:
@@ -759,7 +777,11 @@ productRepo.upsert(merged.product_id, merged);
 **2. `bridgeFromTestControllerStore`** — wires your seeded `Map` into `get_products` responses automatically. Sandbox requests see seeded + handler products merged (with seeded winning collisions); production traffic (no sandbox marker, or resolved non-sandbox account) skips the bridge entirely.
 
 ```ts
-import { createAdcpServerFromPlatform, bridgeFromTestControllerStore, DEFAULT_REPORTING_CAPABILITIES } from '@adcp/sdk/server';
+import {
+  createAdcpServerFromPlatform,
+  bridgeFromTestControllerStore,
+  DEFAULT_REPORTING_CAPABILITIES,
+} from '@adcp/sdk/server';
 
 const seedStore = new Map<string, unknown>();
 
@@ -843,27 +865,270 @@ For production test controllers with persisted-session state (Postgres/Redis/JSO
 
 Key SDK pieces you'll import from `@adcp/sdk`: `CONTROLLER_SCENARIOS`, `enforceMapCap`, `SESSION_ENTRY_CAP`, `handleTestControllerRequest`, `toMcpResponse`, `TOOL_INPUT_SHAPE`.
 
+### Opting into `upstream_traffic` (anti-façade contract)
+
+Storyboards on `audience-sync`, `sales-social`, `signal-marketplace`, and any specialism with a real upstream platform may declare `check: upstream_traffic` validations (per spec PR adcontextprotocol/adcp#3816). The runner queries your `comply_test_controller`'s `query_upstream_traffic` scenario after each step and asserts your adapter actually called the upstream platform with the storyboard-supplied identifiers — distinguishing a real adapter from one that returns shape-valid AdCP responses without touching upstream.
+
+**Prereq:** you've already wired `comply_test_controller` per [§ Compliance Testing](#compliance-testing-required-for-deterministic_testing-storyboard) above. The recorder plugs into the existing controller's scenario dispatch — it doesn't stand up a new tool. If you skipped that section, go back and finish it before continuing here.
+
+**Opt-in is voluntary** — adopters who don't advertise `query_upstream_traffic` in `list_scenarios` grade the check `not_applicable`. But adopters who advertise and observe zero calls grade `failed` (the façade signal). Since the storyboards exist to verify your adapter does what it claims, opting in is the load-bearing way to claim the specialism.
+
+#### Two traffic surfaces — don't conflate them
+
+The SDK has two anti-façade-traffic patterns. They're complementary, not alternatives:
+
+```
+buyer-agent / runner
+        │
+        │  AdCP wire
+        ▼
+  ┌──────────────┐         outbound HTTP            ┌──────────────────┐
+  │   adopter    │ ────────────────────────────►   │     upstream     │
+  │   adapter    │     (recorder.wrapFetch here)    │   platform / mock │
+  └──────────────┘                                   └──────────────────┘
+        │                                                    │
+        │  comply_test_controller.query_upstream_traffic     │  GET /_debug/traffic
+        │  (recorder.query() here)                           │  (mock-server only)
+        ▼                                                    ▼
+   runner verifies                                    matrix harness verifies
+   adopter's outbound                                 mock received inbound
+   calls + payloads                                   route hits
+```
+
+- **Adopter-side `query_upstream_traffic`** (this section): full request payloads with JSONPath assertions, per-principal scoping. Required when the runner can't reach upstream (production sandbox, real platform). The recorder records adapter outbound calls.
+- **Mock-side `/_debug/traffic`** (`src/lib/mock-server/*/server.ts`): per-route hit counts on the mock platform itself. Used by the matrix harness which has direct access to the mock. Anonymous, no payload detail.
+
+Don't try to use one for the other. The recorder is an adapter-side concern; mocks expose `_debug/traffic` because they ARE the upstream and have nothing to record outbound.
+
+#### What the runner asserts (and what it can't catch)
+
+Per spec PR adcontextprotocol/adcp#3816, the runner's `upstream_traffic` validator on each storyboard step:
+
+1. Queries `comply_test_controller.query_upstream_traffic` with `since_timestamp = step request start − 250ms`, scoped to the calling principal.
+2. Filters `recorded_calls[]` by the optional `endpoint_pattern` glob.
+3. Checks `min_count` (default 1) — adopters who advertise the scenario but observe zero calls grade `failed` here.
+4. Checks each `payload_must_contain` entry's JSONPath against at least one matching call's `payload`. Non-JSON payloads fall back to substring matching for `match: present`; `equals` / `contains_any` against non-JSON grade `not_applicable`.
+5. Checks `identifier_paths` — extracts every value at each path from the storyboard's `sample_request` and asserts ALL resolved values appear at any depth in some matched call's payload. The recorder records what your adapter sent; the runner matches against what the storyboard sent. Forward identifiers as-received (don't transform them mid-flight, or your recorded payloads won't match).
+
+What the recorder CAN'T catch on its own: a thoughtful façade can call `recorder.record()` synthetically with fabricated payloads, or replay-attack with hardcoded recorded*calls, or wrap fetch but never invoke it. The load-bearing anti-façade defense is the storyboard's `identifier_paths` matching against payloads only a real adapter integration would produce. The recorder is the \_surfacing primitive*; the storyboards are where the contract is enforced. Treat opt-in honestly.
+
+#### Wire-up — the four steps
+
+```ts
+import { createUpstreamRecorder, toQueryUpstreamTrafficResponse } from '@adcp/sdk/upstream-recorder';
+import { registerTestController } from '@adcp/sdk/server';
+
+// ─── 1. Boot the recorder (sandbox-only)
+const recorder = createUpstreamRecorder({
+  enabled: process.env.NODE_ENV !== 'production',
+  // strict: true during integration tests — calls outside runWithPrincipal
+  // throw UpstreamRecorderScopeError instead of silently dropping. Surfaces
+  // the unwrapped call site as a stack trace, not a mystery zero-result.
+  strict: process.env.ADCP_RECORDER_STRICT === '1',
+});
+
+// ─── 2. Wrap your HTTP layer (one-time at boot, replaces step 2 if you don't use fetch — see below)
+const recordedFetch = recorder.wrapFetch(globalThis.fetch);
+
+// ─── 3. Scope every outbound call inside your AdCP handler to the resolving principal
+async function syncAudiences(req, ctx) {
+  await recorder.runWithPrincipal(resolvePrincipal(ctx), async () => {
+    await recordedFetch('https://platform.example/v1/audience/upload', {
+      /* ... */
+    });
+  });
+}
+
+/**
+ * The same string MUST be returned at record-time (here) and at
+ * query-time (step 4). Mismatch returns zero — that's the spec's
+ * security floor (cross-tenant isolation), not a bug.
+ *
+ *   - OAuth client_credentials sellers: return the resolved `client_id`.
+ *   - Session-token sellers: return `ctx.account.id`.
+ *   - Anonymous / public sandbox: a stable per-session identifier
+ *     (literal "anonymous" collides across tenants and defeats isolation).
+ */
+function resolvePrincipal(ctx) {
+  return ctx.account.id; // adjust per your auth layer
+}
+
+// ─── 4. Add `queryUpstreamTraffic` as a method on your existing TestControllerStore
+// (this is an entry in the SAME store you registered above for force/seed/simulate
+// scenarios — NOT a separate handler. registerTestController auto-advertises
+// `query_upstream_traffic` in list_scenarios when this method is present).
+registerTestController(adcpServer, {
+  // ... your existing force_*, seed_*, simulate_* methods ...
+
+  queryUpstreamTraffic: async params =>
+    toQueryUpstreamTrafficResponse(
+      recorder.query({
+        principal: resolvePrincipal(ctxFromInput(params)), // same resolver as step 3
+        sinceTimestamp: params.since_timestamp,
+        endpointPattern: params.endpoint_pattern,
+        limit: params.limit,
+      })
+    ),
+});
+```
+
+#### Multi-tenant adopters: factory shape with per-request principal resolution
+
+The wire-up above hardcodes `RECORDER_PRINCIPAL` because the example uses static-API-key auth (one principal for the whole process). Multi-tenant adopters — OAuth `client_credentials` sellers, session-token sellers, anyone whose `comply_test_controller` request can come from different tenants — MUST resolve the principal **per request** so cross-tenant isolation actually holds. Use `registerTestController`'s factory shape, which runs a fresh `createStore` per request with access to the controller's input:
+
+```ts
+import { CONTROLLER_SCENARIOS } from '@adcp/sdk/server';
+
+registerTestController(adcpServer, {
+  // Static capability list — answered without invoking createStore so
+  // list_scenarios pings don't pay a session-rehydration cost.
+  scenarios: [
+    CONTROLLER_SCENARIOS.FORCE_CREATIVE_STATUS,
+    // ... your existing canonical scenarios ...
+    'query_upstream_traffic', // extension scenario, advertised verbatim
+  ],
+  createStore: async input => {
+    // input is the parsed comply_test_controller request — { scenario,
+    // params, context, ext, account } as the buyer sent it. Resolve the
+    // calling principal from your auth layer here.
+    const principal = await resolvePrincipal(input);
+
+    return {
+      // ... your existing force/seed/simulate methods ...
+
+      queryUpstreamTraffic: async params =>
+        toQueryUpstreamTrafficResponse(
+          recorder.query({
+            principal,
+            sinceTimestamp: params.since_timestamp,
+            endpointPattern: params.endpoint_pattern,
+            limit: params.limit,
+          })
+        ),
+    };
+  },
+});
+```
+
+The `resolvePrincipal(input)` resolver is where adopter auth-layer choice lives:
+
+```ts
+async function resolvePrincipal(input: Record<string, unknown>): Promise<string> {
+  // OAuth client_credentials: derive from your token-introspection cache,
+  // keyed off the bearer the request arrived with. The same principal
+  // string MUST be returned by your handler-side `runWithPrincipal(p, fn)`
+  // wrapper — keep both call sites pointing at one resolver.
+  const oauth = await loadOAuthSession(input);
+  if (oauth) return oauth.client_id;
+
+  // Session-token sellers: resolve account from the session id and use
+  // its stable account.id.
+  const session = (input.context as { session_id?: string })?.session_id;
+  if (session) {
+    const acct = await accountFromSession(session);
+    return acct.id;
+  }
+
+  // Public-sandbox adopters serving anonymous traffic: a stable
+  // per-session identifier you mint at session start. The literal
+  // string "anonymous" collides across tenants — don't use it.
+  throw new Error('No auth context available; cannot scope upstream-traffic query');
+}
+```
+
+On the AdCP-handler side, call the **same** `resolvePrincipal` from `runWithPrincipal`. The `ctx` an AdCP handler receives carries the same auth shape your controller-side `input` does (often `ctx.account`, sometimes `ctx.authInfo` for the raw transport layer). Wrap a thin shim:
+
+```ts
+async function syncAudiences(req, ctx) {
+  const principal = await resolvePrincipal(adcpCtxToControllerInput(ctx));
+  await recorder.runWithPrincipal(principal, async () => {
+    await fetch('https://platform.example/v1/audience/upload', {
+      /* ... */
+    });
+  });
+}
+```
+
+If the two call sites pick the principal differently — for example, controller-side resolves from `input.account.operator` but handler-side uses `ctx.account.id` directly — your storyboard runs grade `failed` with `matched_count: 0` and the diagnostic looks identical to a façade. Use one resolver, call it from both ends.
+
+#### Adopters not on `fetch`
+
+`recorder.wrapFetch` covers most adapters. If you use `axios` / `got` / native `node:http`, **replace step 2** with a per-client interceptor + manual `recorder.record()` (don't combine with `wrapFetch` — pick one):
+
+```ts
+// Axios — interceptor on the response side so we have the status code
+axiosInstance.interceptors.response.use(
+  resp => {
+    recorder.record({
+      method: resp.config.method?.toUpperCase() ?? 'GET',
+      url: resp.config.url ?? '',
+      content_type: resp.config.headers['content-type'] ?? '',
+      headers: resp.config.headers,
+      payload: resp.config.data,
+      status_code: resp.status,
+    });
+    return resp;
+  },
+  err => {
+    /* still record on error — same shape, omit status_code */ throw err;
+  }
+);
+
+// got — afterResponse hook
+got.extend({
+  hooks: {
+    afterResponse: [
+      response => {
+        recorder.record({
+          method: response.request.options.method,
+          url: response.request.requestUrl.toString(),
+          content_type: response.request.options.headers['content-type'] ?? '',
+          headers: response.request.options.headers,
+          payload: response.request.options.body,
+          status_code: response.statusCode,
+        });
+        return response;
+      },
+    ],
+  },
+});
+```
+
+`runWithPrincipal` (step 3) still applies — adapters not on fetch still need to scope their handler bodies so the recorder knows which principal each call belongs to.
+
+#### Debugging "my storyboard says zero calls but I see them in my logs"
+
+Three checks, in order:
+
+1. **`recorder.debug()` from inside your handler.** Returns `{ enabled, bufferSize, bufferedEntries, principals, lastRecordedAt, activePrincipal, strict }`. Verify `enabled: true`, `bufferedEntries > 0`, and that `activePrincipal` matches what your controller handler will pass at query time. Mismatch is the most common adopter bug — a typo or stale-cache resolver that returns a different string at record vs query time silently returns `[]`.
+2. **`strict: true`** during integration test runs. Calls outside `runWithPrincipal` throw `UpstreamRecorderScopeError` instead of silently dropping. Surfaces unwrapped call sites as stack traces.
+3. **`onError` hook** for production-style observability — fires on classifier throws, URL parse failures, payload-build failures, and unscoped records. Wire to your logger.
+
+`enabled: false` returns a no-op recorder for production builds — zero per-call overhead. See `@adcp/sdk/upstream-recorder`'s module-level docs for the full surface (`strict`, `debug()`, `onError`, `redactPattern`, `maxPayloadBytes`, `purpose` classifier, `bufferSize` / `ttlMs` tuning).
+
+**Worked reference adapter**: [`examples/hello_signals_adapter_marketplace.ts`](../../examples/hello_signals_adapter_marketplace.ts) wires the recorder end-to-end against the SDK's `signal-marketplace` mock. CI gates that example via `test/examples/hello-signals-adapter-marketplace.test.js` — type-checks under strictest tsc, runs the storyboard with zero failed steps, asserts every expected upstream route was hit. Fork the example and replace `UpstreamClient` with your real backend.
+
 ## SDK Quick Reference
 
-| SDK piece                                                                 | Usage                                                                          |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| SDK piece                                                                 | Usage                                                                                                                                                                                |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `createAdcpServerFromPlatform(platform, opts)`                            | Build a server from a typed `DecisioningPlatform` — compile-time specialism enforcement, ctx_metadata round-trip, idempotency-principal synthesis, status mappers, webhook auto-emit |
-| `createAdcpServer(config)` *(legacy)*                                     | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`                                                                                       |
-| `serve(() => createAdcpServerFromPlatform(platform, opts))`               | Start HTTP server on `:3001/mcp`                                               |
-| `ctx.store`                                                               | State store in every handler — `get`, `put`, `patch`, `delete`, `list`         |
-| `InMemoryStateStore`                                                      | Default state store (dev/testing)                                              |
-| `PostgresStateStore`                                                      | Production state store (shared across instances)                               |
-| `DEFAULT_REPORTING_CAPABILITIES`                                          | Use as `reporting_capabilities: DEFAULT_REPORTING_CAPABILITIES` on products    |
-| `checkGovernance(options)`                                                | Call governance agent before financial commits                                 |
-| `governanceDeniedError(result)`                                           | Convert governance denial to GOVERNANCE_DENIED error                           |
-| `mediaBuyResponse(data)`                                                  | Auto-applied for `createMediaBuy` (sets revision, confirmed_at, valid_actions) |
-| `adcpError(code, { message })`                                            | Structured error (e.g., `BUDGET_TOO_LOW`, `PRODUCT_NOT_FOUND`)                 |
-| `registerTestController(server, store \| { scenarios, createStore })`     | Add `comply_test_controller`. Plain store or per-request factory.              |
-| `TestControllerError(code, message)`                                      | Typed error from store methods                                                 |
-| `handleTestControllerRequest(store, input)`                               | Low-level dispatch for custom MCP wrappers                                     |
-| `toMcpResponse(response)` / `TOOL_INPUT_SHAPE`                            | MCP envelope + Zod input schema for custom wrappers                            |
-| `enforceMapCap(map, key, label, cap?)`                                    | Reject net-new keys once a session Map hits `SESSION_ENTRY_CAP` (1000)         |
-| `expectControllerError(result, code)` / `expectControllerSuccess(result)` | Unit-test assertions — narrow responses to error or success arms               |
+| `createAdcpServer(config)` _(legacy)_                                     | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`                                                                                      |
+| `serve(() => createAdcpServerFromPlatform(platform, opts))`               | Start HTTP server on `:3001/mcp`                                                                                                                                                     |
+| `ctx.store`                                                               | State store in every handler — `get`, `put`, `patch`, `delete`, `list`                                                                                                               |
+| `InMemoryStateStore`                                                      | Default state store (dev/testing)                                                                                                                                                    |
+| `PostgresStateStore`                                                      | Production state store (shared across instances)                                                                                                                                     |
+| `DEFAULT_REPORTING_CAPABILITIES`                                          | Use as `reporting_capabilities: DEFAULT_REPORTING_CAPABILITIES` on products                                                                                                          |
+| `checkGovernance(options)`                                                | Call governance agent before financial commits                                                                                                                                       |
+| `governanceDeniedError(result)`                                           | Convert governance denial to GOVERNANCE_DENIED error                                                                                                                                 |
+| `mediaBuyResponse(data)`                                                  | Auto-applied for `createMediaBuy` (sets revision, confirmed_at, valid_actions)                                                                                                       |
+| `adcpError(code, { message })`                                            | Structured error (e.g., `BUDGET_TOO_LOW`, `PRODUCT_NOT_FOUND`)                                                                                                                       |
+| `registerTestController(server, store \| { scenarios, createStore })`     | Add `comply_test_controller`. Plain store or per-request factory.                                                                                                                    |
+| `TestControllerError(code, message)`                                      | Typed error from store methods                                                                                                                                                       |
+| `handleTestControllerRequest(store, input)`                               | Low-level dispatch for custom MCP wrappers                                                                                                                                           |
+| `toMcpResponse(response)` / `TOOL_INPUT_SHAPE`                            | MCP envelope + Zod input schema for custom wrappers                                                                                                                                  |
+| `enforceMapCap(map, key, label, cap?)`                                    | Reject net-new keys once a session Map hits `SESSION_ENTRY_CAP` (1000)                                                                                                               |
+| `expectControllerError(result, code)` / `expectControllerSuccess(result)` | Unit-test assertions — narrow responses to error or success arms                                                                                                                     |
 
 Response builders (`productsResponse`, `mediaBuyResponse`, `deliveryResponse`, etc.) are auto-applied by the framework — you return the data, the framework wraps it. You only need to call them directly for tools without a dedicated builder.
 
@@ -1055,8 +1320,9 @@ class MySeller implements DecisioningPlatform<{}, MySellerMeta> {
         status = 'paused';
       } else if (
         status === 'pending_creatives' &&
-        (patch.packages ?? []).some((p: { creative_assignments?: unknown[] }) =>
-          (p.creative_assignments ?? []).length > 0)
+        (patch.packages ?? []).some(
+          (p: { creative_assignments?: unknown[] }) => (p.creative_assignments ?? []).length > 0
+        )
       ) {
         const startTime = existing.start_time ? new Date(existing.start_time as string) : null;
         status = startTime && startTime > new Date() ? 'pending_start' : 'active';
@@ -1515,7 +1781,7 @@ Common failure decoder:
 | Using `createTaskCapableServer` + `server.tool()`          | Use `createAdcpServerFromPlatform(platform, opts)` — handles schemas, response builders, capabilities, ctx_metadata round-trip, idempotency-principal synthesis                       |
 | Calling `createAdcpServer` directly in new code            | Reach for `createAdcpServerFromPlatform` first; `createAdcpServer` lives at `@adcp/sdk/server/legacy/v5` for mid-migration / escape-hatch use only                                    |
 | Using module-level Maps for state                          | Use `ctx.store` — persists across HTTP requests, swappable for postgres                                                                                                               |
-| Return raw JSON without response builders                  | The framework auto-applies response builders — just return the data                                                                                                                  |
+| Return raw JSON without response builders                  | The framework auto-applies response builders — just return the data                                                                                                                   |
 | Missing `brand`/`operator` in sync_accounts response       | Echo them back from the request — they're required                                                                                                                                    |
 | sync_governance returns wrong shape                        | Must include `status: 'synced'` and `governance_agents` array                                                                                                                         |
 | `sandbox: false` on mock data                              | Buyers may treat mock data as real                                                                                                                                                    |

package/skills/build-seller-agent/specialisms/sales-broadcast-tv.md

@@ -4,6 +4,8 @@ Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this f
 
 Storyboard: `media_buy_broadcast_seller`. Broadcast has four protocol surfaces not used in digital.
 
+**Forecast surface**: `'reach_freq'` or `'package'`. Broadcast plans aren't quoted in spend curves — buyers want unique reach and frequency at a planned weight (GRPs), or a fully-priced package. Project your reach/freq tool (Nielsen, etc.) onto `Product.forecast` points where each point's `metrics` includes `reach_unique`, `frequency_avg`, `grps`, `spend`, and a `package: { spots, dayparts }` breakdown. Use `'package'` when the seller quotes a fixed bundle of spots; use `'reach_freq'` when the buyer is exploring weight levels. See [Delivery Forecasts § CTV with GRP Demographics](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#ctv-with-grp-demographics) for the canonical worked example.
+
 **Pricing** — unit-based (cost per spot). Until a `pricing_model: 'unit'` lands, express as CPM with a very high `fixed_price` that represents the cost per thousand spots equivalent, or use a custom pricing option ID and clarify in `description`.
 
 **Agency estimate number** — top-level on `create_media_buy`. Echo it on the response:

package/skills/build-seller-agent/specialisms/sales-guaranteed.md

@@ -2,6 +2,10 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-guaranteed`.
 
+**Fork target**: `examples/hello_seller_adapter_guaranteed.ts` is the worked, passing reference adapter for this specialism. It demonstrates the IO-signing handoff via `ctx.handoffToTask(fn)`, the `SalesCorePlatform & SalesIngestionPlatform` field-annotation pattern, and structured `MEDIA_BUY_NOT_FOUND` / `PACKAGE_NOT_FOUND` / `TERMS_REJECTED` error shapes. Replace the `// SWAP:` markers with calls to your real ad-server backend.
+
+**Forecast surface**: `'availability'`. Guaranteed sellers don't quote spend curves — they confirm reserved inventory against a targeting + dates request. `Product.forecast` should be a single point with `metrics.impressions` / `metrics.audience_size` populated and `metrics.spend` expressing the seller's quoted cost; budget is omitted. Set `valid_until` to within 24 hours so buyers refresh their view. See [Delivery Forecasts § Availability Forecast](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#availability-forecast) for the canonical worked example.
+
 Storyboard: `sales_guaranteed`. `create_media_buy` has **three return shapes**. Route on request signals FIRST — the specialism's name is about IO signing, but the baseline `media_buy_seller` storyboard exercises all three in sequence.
 
 | Request signal                                                         | Return                                                                                                                  | Why                                                                                                     |
@@ -64,3 +68,17 @@ When the task completes, emit the final `create_media_buy` result (carrying `med
 Declare `requires_io_approval` in your `capabilities.features` for this path. For deterministic compliance testing, implement `forceTaskStatus` (not `forceMediaBuyStatus`) in your `TestControllerStore` to drive the task from `submitted → completed` without waiting for a human.
 
 **Governance denial (`GOVERNANCE_DENIED`).** Baseline `media_buy_seller/governance_denied*` scenarios exercise governance refusal. For sellers that compose with a governance agent, call `checkGovernance(...)` from `@adcp/sdk/server` at the top of `create_media_buy`. If the governance agent returns denial, surface with `governanceDeniedError(result)` so the error code is `GOVERNANCE_DENIED` and context echoes. Sellers that don't compose with governance will see these scenarios fail with `INVALID_REQUEST` — expected until upstream gates the scenarios behind a composition-claim specialism (tracked at adcontextprotocol/adcp#2521).
+
+### Forecast (`Product.forecast`)
+
+Drive `Product.forecast` from a per-query upstream call so the buyer sees deltas across targeting, dates, and budget. Static seed-data `availability` blobs are placeholder; real GAM/FreeWheel/Operative integrations spend most of their API time here. The mock-server exposes the upstream-shape used by the worked adapter — see [`../../../src/lib/mock-server/sales-guaranteed/openapi.yaml`](../../../src/lib/mock-server/sales-guaranteed/openapi.yaml):
+
+| Mock endpoint                                                              | Returns                                              | When                                                       |
+| -------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| `GET /v1/products?targeting=&flight_start=&flight_end=&budget=`            | catalog + inline `forecast` per product              | single round-trip during `getProducts`                     |
+| `POST /v1/forecast` (`{product_id, targeting?, flight_dates?, budget?}`)   | `DeliveryForecast` (availability or spend)           | per-product on demand (cheaper backends)                   |
+| `POST /v1/availability` (`{items: [...], dry_run: true}`)                  | per-item forecast + tier_pricing + cross-item conflicts | pre-flight a multi-LI proposal                          |
+
+The structured fields the buyer passes live on `req.filters` (`start_date`, `end_date`, `budget_range`) — `brief` is the free-text natural-language string per `GetProductsRequest`, not a structured payload. The worked `getProducts` projection lives in [`examples/hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts).
+
+**Cross-item supply contention is upstream-only.** `POST /v1/availability` mirrors GAM's `getCompetitiveForecast` — items are evaluated in order and earlier reservations reduce supply visible to later ones. AdCP `DeliveryForecast` is per-product, not per-package-set; adapters collapse the upstream contention model down to one `Product.forecast` per product. Multi-LI competitive math lives in the buyer's proposal logic, not the wire shape.

package/skills/build-seller-agent/specialisms/sales-non-guaranteed.md

@@ -2,36 +2,16 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-non-guaranteed`.
 
-Storyboard: `media_buy_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
+Storyboard: `sales_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
 
-Packages on `create_media_buy` carry `bid_price`. Validate it against the product's `floor_price`:
+**Fork target**: [`examples/hello_seller_adapter_non_guaranteed.ts`](../../../examples/hello_seller_adapter_non_guaranteed.ts) is the worked, passing reference adapter for this specialism. CI gates strict tsc + storyboard pass + upstream-traffic façade.
 
-```typescript
-createMediaBuy: async (params, ctx) => {
-  for (const pkg of params.packages ?? []) {
-    const product = PRODUCTS.find((p) => p.product_id === pkg.product_id);
-    const floor = product?.pricing_options[0].floor_price;
-    if (floor && pkg.bid_price != null && pkg.bid_price < floor) {
-      return adcpError('INVALID_REQUEST', {
-        message: `bid_price ${pkg.bid_price} below floor_price ${floor}`,
-      });
-    }
-  }
-  return {
-    media_buy_id: `mb_${randomUUID()}`,
-    status: 'active' as const,   // instant — no IO
-    packages: /* ... */,
-  };
-},
+The adapter demonstrates the auction-mode deltas vs `sales-guaranteed`:
 
-updateMediaBuy: async (params, ctx) => {
-  const existing = await ctx.store.get('media_buys', params.media_buy_id);
-  if (!existing) return adcpError('NOT_FOUND', { message: `Media buy ${params.media_buy_id} not found` });
-  // Apply bid/budget updates from params.packages
-  const updated = { ...existing, packages: /* merged */ };
-  await ctx.store.put('media_buys', params.media_buy_id, updated);
-  return updated;
-},
-```
+- **Sync confirmation** — `createMediaBuy` returns `media_buy_id` immediately with `status: 'active'` (or `pending_creatives` until creatives attach). No `ctx.handoffToTask`, no IO poll, no task envelope. Auction inventory clears at request time.
+- **Floor pricing** — `pricing_options[].fixed_price` projected from upstream `min_cpm`; `min_spend` and `target_cpm` flow through to the wire when the upstream sets them. Reject `bid_price` below `floor_price` with `INVALID_REQUEST`.
+- **Spend-only forecast** — `forecast_range_unit: 'spend'`; no `availability` unit because non-guaranteed inventory isn't pre-committed. See [Delivery Forecasts § Budget Curve](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#budget-curve) for the wire shape.
+- **Pacing propagation** — `even` / `asap` / `front_loaded` forwarded to upstream order; reflected in delivery curve. Validate raw input — reject typos rather than silently passing them through.
+- **`update_media_buy`** — bid/budget changes apply in-flight without re-issuing the order. `valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`; the framework auto-populates this when `status: 'active'`.
 
-`valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`. The framework auto-populates this when `createMediaBuy`/`updateMediaBuy` return with `status: 'active'`.
+Auction mode is the deletion-fork of the guaranteed sibling. If your backend has HITL approval, fork [`hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts) instead. Replace the `// SWAP:` markers with calls to your real backend.