@adcp/sdk 6.8.0 → 6.9.0

package/examples/hello_seller_adapter_non_guaranteed.ts

@@ -61,14 +61,17 @@ import {
   AdcpError,
   createMediaBuyStore,
   InMemoryStateStore,
+  assertMediaBuyTransition,
   type DecisioningPlatform,
   type SalesCorePlatform,
   type SalesIngestionPlatform,
   type AccountStore,
   type Account,
+  type AdcpMediaBuyStatus,
   type SyncCreativesRow,
   type SyncAccountsResultRow,
 } from '@adcp/sdk/server';
+import { FormatAsset } from '@adcp/sdk';
 import type {
   GetProductsRequest,
   GetProductsResponse,
@@ -440,6 +443,16 @@ function mapMediaBuyStatus(
 const adapterStatusOverrides = new Map<string, 'pending_start' | 'active'>();
 const overrideKey = (networkCode: string, orderId: string): string => `${networkCode}::${orderId}`;
 
+// Local pause / cancel tracker. The mock upstream models the create →
+// pending → active progression; pause and cancel are seller-side state-machine
+// concerns the spec's `core/state-machine.yaml` declares as terminal sinks
+// (canceled) or reversible (paused). Production sellers swap this Map for
+// a single durable lookup against their order DB and check
+// `MEDIA_BUY_TRANSITIONS` against the current status before issuing the
+// upstream PATCH. The local Map here exists only because the worked-example
+// mock doesn't model these states upstream.
+const localBuyStatus = new Map<string, 'paused' | 'canceled'>();
+
 class SalesNonGuaranteedAdapter implements DecisioningPlatform<Record<string, never>, NetworkMeta> {
   capabilities = {
     specialisms: ['sales-non-guaranteed'] as const,
@@ -735,10 +748,29 @@ class SalesNonGuaranteedAdapter implements DecisioningPlatform<Record<string, ne
       // → pending_start (or active if the flight already started). Production
       // backends would also persist the assignment to the upstream line item;
       // the worked example just advances the response state.
+      //
+      // State-machine enforcement for pause / cancel. The spec's
+      // `core/state-machine.yaml` declares `canceled` as a terminal sink and
+      // a re-cancel as illegal — `assertMediaBuyTransition` throws
+      // `NOT_CANCELLABLE` on `canceled → canceled`, which is the
+      // `media_buy_seller/invalid_transitions` storyboard's contract. The
+      // local Map covers the gap between upstream (which doesn't model these)
+      // and the spec; production sellers read the canonical transitions
+      // exported by `@adcp/sdk/server` against their own status column.
+      const local = localBuyStatus.get(overrideKey(networkCode, id));
       const baseStatus = mapMediaBuyStatus(existing.status);
-      let nextStatus: ReturnType<typeof mapMediaBuyStatus> =
-        adapterStatusOverrides.get(overrideKey(networkCode, id)) ?? baseStatus;
-      if (hasCreativeAssignment && nextStatus === 'pending_creatives') {
+      const currentStatus: AdcpMediaBuyStatus =
+        local ?? adapterStatusOverrides.get(overrideKey(networkCode, id)) ?? baseStatus;
+      let nextStatus: AdcpMediaBuyStatus = currentStatus;
+      if ((patch as { canceled?: boolean }).canceled === true) {
+        assertMediaBuyTransition(currentStatus, 'canceled');
+        nextStatus = 'canceled';
+        localBuyStatus.set(overrideKey(networkCode, id), nextStatus);
+      } else if ((patch as { paused?: boolean }).paused === true && currentStatus === 'active') {
+        assertMediaBuyTransition(currentStatus, 'paused');
+        nextStatus = 'paused';
+        localBuyStatus.set(overrideKey(networkCode, id), nextStatus);
+      } else if (hasCreativeAssignment && nextStatus === 'pending_creatives') {
         const flightStarted = existing.flight_start !== undefined && Date.parse(existing.flight_start) <= Date.now();
         nextStatus = flightStarted ? 'active' : 'pending_start';
         adapterStatusOverrides.set(overrideKey(networkCode, id), nextStatus);
@@ -906,27 +938,46 @@ class SalesNonGuaranteedAdapter implements DecisioningPlatform<Record<string, ne
       // formats endpoint (formats live inline on Product); production sellers
       // typically expose `/v1/formats` separately. SWAP: replace with your
       // backend's format catalog.
+      //
+      // Each format declares the input asset slots a buyer's `sync_creatives`
+      // creative_manifest MUST key its `assets` map against — per
+      // creative-manifest.json:14 ("Each key MUST match an asset_id from the
+      // format's assets array"). `required: true` slots reject creative
+      // submissions missing them at the manifest layer; `required: false`
+      // means the buyer MAY include the asset.
+      const displaySlots = [
+        FormatAsset.image({ asset_id: 'image', required: true }),
+        FormatAsset.url({ asset_id: 'click_url', required: true }),
+      ];
+      const videoSlots = [
+        FormatAsset.video({ asset_id: 'video', required: true }),
+        FormatAsset.url({ asset_id: 'click_url', required: true }),
+      ];
       return {
         formats: [
           {
             format_id: { agent_url: FORMAT_AGENT_URL, id: 'display_300x250' },
             name: 'Display 300x250 (medrec)',
             renders: [{ role: 'main', dimensions: { width: 300, height: 250, unit: 'px' } }],
+            assets: displaySlots,
           },
           {
             format_id: { agent_url: FORMAT_AGENT_URL, id: 'display_728x90' },
             name: 'Display 728x90 (leaderboard)',
             renders: [{ role: 'main', dimensions: { width: 728, height: 90, unit: 'px' } }],
+            assets: displaySlots,
           },
           {
             format_id: { agent_url: FORMAT_AGENT_URL, id: 'video_30s' },
             name: 'Video 30s outstream / instream',
             renders: [{ role: 'main', dimensions: { width: 1920, height: 1080, unit: 'px' } }],
+            assets: videoSlots,
           },
           {
             format_id: { agent_url: FORMAT_AGENT_URL, id: 'video_15s' },
             name: 'Video 15s',
             renders: [{ role: 'main', dimensions: { width: 1920, height: 1080, unit: 'px' } }],
+            assets: videoSlots,
           },
         ],
       };

package/examples/hello_seller_adapter_social.ts

@@ -185,7 +185,7 @@ const upstream = {
   // returns deterministic ranges keyed on (advertiser_id, targeting), so the
   // numbers are stable across runs but vary observably with targeting.
   // Surface this on AdCP wire as `SyncAudiencesRow.matched_count` /
-  // `effective_match_rate` (per `/schemas/3.0.5/core/audience.json`).
+  // `effective_match_rate` (per `/schemas/3.0.6/media-buy/sync-audiences-response.json`).
   async audienceReachEstimate(
     advertiserId: string,
     body: { targeting: Record<string, unknown> }

package/examples/hello_signals_adapter_marketplace.ts

@@ -28,7 +28,6 @@ import {
   AdcpError,
   BuyerAgentRegistry,
   defineSignalsPlatform,
-  registerTestController,
   type DecisioningPlatform,
   type SignalsPlatform,
   type AccountStore,
@@ -320,6 +319,13 @@ class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, nev
   capabilities = {
     specialisms: ['signal-marketplace'] as const,
     config: {},
+    // Declare `compliance_testing` so the framework projects the
+    // `comply_test_controller` capability + scenarios on
+    // `get_adcp_capabilities`. The `complyTest:` opts block on
+    // `createAdcpServerFromPlatform` (below) wires the adapters; the
+    // framework derives the `scenarios` list from which adapters are
+    // present.
+    compliance_testing: {},
   };
 
   /**
@@ -483,8 +489,8 @@ const platform = new SignalMarketplaceAdapter();
 const idempotencyStore = createIdempotencyStore({ backend: memoryBackend(), ttlSeconds: 86_400 });
 
 serve(
-  ({ taskStore }) => {
-    const adcpServer = createAdcpServerFromPlatform(platform, {
+  ({ taskStore }) =>
+    createAdcpServerFromPlatform(platform, {
       name: 'hello-signals-adapter-marketplace',
       version: '1.0.0',
       taskStore,
@@ -494,33 +500,32 @@ serve(
         const acct = ctx.account as Account<OperatorMeta> | undefined;
         return acct?.id ?? 'anonymous';
       },
-    });
-
-    // Register `comply_test_controller` with the recorder-backed
-    // `query_upstream_traffic` scenario. The runner queries this after
-    // each step that declares a `check: upstream_traffic` validation;
-    // adopters who don't advertise the scenario grade `not_applicable`.
-    //
-    // Sandbox-only — production builds 404 the controller entirely
-    // (gate via the `if (process.env.ADCP_SANDBOX === '1')` pattern from
-    // the SKILL). For this example adapter we always register since the
-    // example is itself a fixture for the matrix harness.
-    registerTestController(adcpServer, {
-      // Adapter resolves principal from auth context. The same string
-      // MUST be returned by both record-time (runWithPrincipal) and
-      // query-time — mismatch returns zero per cross-tenant isolation.
-      queryUpstreamTraffic: async params => {
-        const result = recorder.query({
-          principal: RECORDER_PRINCIPAL,
-          ...(params.since_timestamp !== undefined && { sinceTimestamp: params.since_timestamp }),
-          ...(params.endpoint_pattern !== undefined && { endpointPattern: params.endpoint_pattern }),
-          ...(params.limit !== undefined && { limit: params.limit }),
-        });
-        return toQueryUpstreamTrafficResponse(result);
+      // ─── TEST-ONLY: comply_test_controller wiring ──────────────────────
+      // DELETE THIS BLOCK BEFORE DEPLOYING. The conformance runner queries
+      // `query_upstream_traffic` after each step that declares a
+      // `check: upstream_traffic` validation; adopters who don't
+      // advertise the scenario grade `not_applicable`.
+      //
+      // No `sandboxGate` — the framework gate inside
+      // `createAdcpServerFromPlatform` resolves the calling principal
+      // through `accounts.resolve` and admits only when the resolved
+      // account's `mode` is `'sandbox'` or `'mock'` (per `Account.mode`,
+      // AdCP 6.7+). See `docs/proposals/lifecycle-state-and-sandbox-authority.md`.
+      complyTest: {
+        // Adapter resolves principal from auth context. The same string
+        // MUST be returned by both record-time (runWithPrincipal) and
+        // query-time — mismatch returns zero per cross-tenant isolation.
+        queryUpstreamTraffic: async params => {
+          const result = recorder.query({
+            principal: RECORDER_PRINCIPAL,
+            ...(params.since_timestamp !== undefined && { sinceTimestamp: params.since_timestamp }),
+            ...(params.endpoint_pattern !== undefined && { endpointPattern: params.endpoint_pattern }),
+            ...(params.limit !== undefined && { limit: params.limit }),
+          });
+          return toQueryUpstreamTrafficResponse(result);
+        },
       },
-    });
-    return adcpServer;
-  },
+    }),
   {
     port: PORT,
     authenticate: verifyApiKey({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -239,8 +239,7 @@
     "generate-zod-schemas": "tsx scripts/generate-zod-from-ts.ts && tsx scripts/generate-inline-enum-arrays.ts",
     "generate-wellknown-schemas": "tsx scripts/generate-wellknown-schemas.ts",
     "generate-agent-docs": "tsx scripts/generate-agent-docs.ts",
-    "compliance:agent-skill": "tsx scripts/manual-testing/agent-skill-storyboard.ts",
-    "compliance:skill-matrix": "tsx scripts/manual-testing/run-skill-matrix.ts",
+    "compliance:fork-matrix": "node --test --test-timeout=300000 'test/examples/hello-*.test.js'",
     "typecheck:skill-examples": "tsx scripts/typecheck-skill-examples.ts",
     "check:skill-sync": "tsx scripts/check-skill-sync.ts",
     "check:adopter-types": "tsx scripts/check-adopter-types.ts",
@@ -297,6 +296,7 @@
     "email": "bugs@adcontextprotocol.org"
   },
   "dependencies": {
+    "@types/ws": "^8.18.1",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "fast-check": "^3.23.2",
@@ -305,6 +305,7 @@
     "structured-headers": "^2.0.2",
     "tldts": "^7.0.29",
     "undici": "^6.25.0",
+    "ws": "^8.20.0",
     "yaml": "^2.7.1"
   },
   "peerDependencies": {
@@ -360,5 +361,5 @@
     },
     "minimatch": "^10.2.1"
   },
-  "adcp_version": "3.0.5"
+  "adcp_version": "3.0.6"
 }

package/skills/SHAPE-GOTCHAS.md

@@ -215,6 +215,24 @@ The `examples/hello_seller_adapter_social.ts` reference adapter codifies all thr
 
 ---
 
+## 7. `signal_type`: `marketplace` vs `owned` vs `custom`
+
+`signal_type` is the catalog-type discriminator on every `Signal` returned from `get_signals`. It's a closed enum (`marketplace | custom | owned` per `schemas/cache/3.0.6/enums/signal-catalog-type.json`) and adopters consistently mis-pick because the spec descriptions read like overlapping concepts.
+
+The spec definitions:
+
+| Value | Use when | Example adopter |
+| --- | --- | --- |
+| `marketplace` | Resold third-party segments. Provider's authorization is verifiable via their `adagents.json`. | LiveRamp marketplace; Oracle Data Cloud catalog; reseller of third-party panels |
+| `owned` | First-party segments derived from data the signal agent **directly owns**. | Retailer purchase data (Kroger 84.51°, Walmart Connect); publisher behavioral data (NYT subscribers); telco data |
+| `custom` | Agent-native segment built **on demand** from models, composites, or buyer inputs. Not attributable to a standing upstream provider. | Contextual classifier you train per-request; lookalike model output computed from a buyer's seed audience |
+
+**`owned` is the default for first-party data agents.** Most non-marketplace adopters mis-classify their segments as `custom` because the segment was "built" — but the test is provenance, not lifecycle. If you can point at a stable data-asset you own (a customer table, a pixel, a panel), it's `owned`. `custom` is reserved for segments that don't have a standing data asset behind them — the agent computed them per-call.
+
+**`marketplace` requires `data_provider_domain` to resolve.** Buyers fetch `https://{data_provider_domain}/adagents.json` to verify the provider's authorization. If you can't surface a verifiable provider domain (the segment is yours, or it's synthetic), the value isn't `marketplace`.
+
+---
+
 ## How to debug a "Field not found at path: …" error fast
 
 The validator's path naming is precise. When you see: