@adcp/sdk 8.1.0-beta.13 → 8.1.0-beta.14

package/examples/README.md

@@ -4,22 +4,23 @@ This directory contains practical examples of how to use the `@adcp/sdk` library
 
 ## Building an AdCP agent — fork-target reference adapters
 
-Pick the example whose AdCP role and specialism most closely match what you're building, fork the file, replace the `// SWAP:` markers, and follow the `FORK CHECKLIST` block at the top of each adapter for the unmarked but load-bearing constants. Each adapter is paired with a three-gate CI test (strict tsc / storyboard / upstream-traffic) so a regression in your fork fails CI before it ships.
-
-| If you're claiming…                                              | Fork                                   | Then…                                                                                                                                                                                                                     |
-| ---------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `signal-marketplace` / `signal-owned`                            | `hello_signals_adapter_marketplace.ts` | as-is for marketplace; `signal-owned` adopters drop the marketplace-specific tax/rev-share fields                                                                                                                         |
-| `creative-template`                                              | `hello_creative_adapter_template.ts`   | as-is — single-tenant; production adopters add per-tenant workspace binding (see SWAP markers)                                                                                                                            |
-| `creative-generative`                                            | `hello_creative_adapter_template.ts`   | replace template-driven `buildCreative` with brief-driven generation; keep the `previewCreative` shape                                                                                                                    |
-| `creative-ad-server`                                             | `hello_creative_adapter_ad_server.ts`  | as-is — covers the stateful library + tag generation + macro substitution + delivery reporting flow                                                                                                                       |
+Pick the example whose AdCP role and specialism most closely matches what you're building, fork it, replace the `// SWAP:` markers, and follow the `FORK CHECKLIST` block for the unmarked but load-bearing constants. The `hello_*_adapter_*` examples are paired with the three-gate CI test (strict tsc / storyboard / upstream-traffic) where a matching mock server exists; examples without one are called out below with the narrower runtime coverage they currently have. `proxy-seller-snap/` is a lighter bridge-pattern fork target: it proves seed-bridge wiring and must be paired with your live-OAuth sandbox runner for upstream health.
+
+| If you're claiming…                                              | Fork                                     | Then…                                                                                                                                                                                                                     |
+| ---------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `signal-marketplace` / `signal-owned`                            | `hello_signals_adapter_marketplace.ts`   | as-is for marketplace; `signal-owned` adopters drop the marketplace-specific tax/rev-share fields                                                                                                                         |
+| `creative-template`                                              | `hello_creative_adapter_template.ts`     | as-is — single-tenant; production adopters add per-tenant workspace binding (see SWAP markers)                                                                                                                            |
+| `creative-generative`                                            | `hello_creative_adapter_template.ts`     | replace template-driven `buildCreative` with brief-driven generation; keep the `previewCreative` shape                                                                                                                    |
+| `creative-ad-server`                                             | `hello_creative_adapter_ad_server.ts`    | as-is — covers the stateful library + tag generation + macro substitution + delivery reporting flow                                                                                                                       |
 | `sales-non-guaranteed`                                           | `hello_seller_adapter_non_guaranteed.ts` | as-is — covers sync confirmation, floor pricing, spend-only forecast, pacing propagation                                                                                                                                  |
-| `sales-guaranteed`                                               | `hello_seller_adapter_guaranteed.ts`   | as-is — covers the HITL flow                                                                                                                                                                                              |
-| `sales-broadcast-tv`                                             | `hello_seller_adapter_guaranteed.ts`   | replace `audience_targeting` with broadcast-DMA targeting; replace `Product.channels` with `linear_tv`                                                                                                                    |
-| `sales-streaming-tv`                                             | `hello_seller_adapter_guaranteed.ts`   | adjust `Product.channels` to `ctv`                                                                                                                                                                                        |
-| `sales-social`                                                   | `hello_seller_adapter_social.ts`       | as-is                                                                                                                                                                                                                     |
-| `sales-catalog-driven`                                           | `hello_seller_adapter_social.ts`       | promote `syncCatalogs` to a real catalog ingestion + `getProducts` reads from the catalog                                                                                                                                 |
-| `audience-sync`                                                  | `hello_seller_adapter_social.ts`       | strip everything except `syncAudiences` + `pollAudienceStatuses`; this is the standalone audience-sync seller pattern                                                                                                     |
-| `governance-spend-authority` / `property-lists` / `brand-rights` | `hello_seller_adapter_multi_tenant.ts` | as-is — multi-specialism + multi-tenant agency / holdco shape; closes adcp-client#1332 (governance) and adcp-client#1334 (brand-rights). Single-specialism adopters fork the relevant handler block out of the same file. |
+| `sales-guaranteed`                                               | `hello_seller_adapter_guaranteed.ts`     | as-is — covers the HITL flow                                                                                                                                                                                              |
+| `sales-broadcast-tv`                                             | `hello_seller_adapter_guaranteed.ts`     | replace `audience_targeting` with broadcast-DMA targeting; replace `Product.channels` with `linear_tv`                                                                                                                    |
+| `sales-streaming-tv`                                             | `hello_seller_adapter_guaranteed.ts`     | adjust `Product.channels` to `ctv`                                                                                                                                                                                        |
+| `sales-social`                                                   | `hello_seller_adapter_social.ts`         | as-is                                                                                                                                                                                                                     |
+| Proxy-shaped seller / DSP / walled garden                        | `proxy-seller-snap/`                     | start here when reads proxy an upstream platform API and storyboard seeds need `TestControllerBridge` to appear in sandbox reads                                                                                          |
+| `sales-catalog-driven`                                           | `hello_seller_adapter_social.ts`         | promote `syncCatalogs` to a real catalog ingestion + `getProducts` reads from the catalog                                                                                                                                 |
+| `audience-sync`                                                  | `hello_seller_adapter_social.ts`         | strip everything except `syncAudiences` + `pollAudienceStatuses`; this is the standalone audience-sync seller pattern                                                                                                     |
+| `governance-spend-authority` / `property-lists` / `brand-rights` | `hello_seller_adapter_multi_tenant.ts`   | as-is — multi-specialism + multi-tenant agency / holdco shape; closes adcp-client#1332 (governance) and adcp-client#1334 (brand-rights). Single-specialism adopters fork the relevant handler block out of the same file. |
 
 Naming convention: `hello_<role>_adapter_<specialism>.ts` where `<role>` is the AdCP protocol layer (`seller` for `media-buy`, `creative` for `creative`, `signals` for `signals`, `governance` for `governance`, `brand` for `brand`). `<specialism>` strips the role-implied prefix (so `creative-template` → `_template`, `sales-guaranteed` → `_guaranteed`). The multi-tenant holdco adapter sits outside this convention because it spans multiple roles (governance + brand-rights + property-lists) — naming follows the deployment shape rather than a single role.
 
@@ -39,6 +40,16 @@ Real platforms typically claim more than one specialism. Claim a specialism only
 
 > Each specialism runs its own compliance storyboard independently — no joint multi-specialism storyboard exists yet. For cross-protocol bundles (e.g. DSP-side seller spans `media-buy` + `signals`), run each protocol's storyboard separately.
 
+## AdCP 3.1 commercial-state model
+
+Keep three axes separate when forking a Hello agent:
+
+- `capabilities.account.supported_billing` is the seller-wide wire capability. Set `capabilities.supportedBillings` on decisioning-platform examples when the seller accepts `operator`, `agent`, or `advertiser` billing at all.
+- `BuyerAgentRegistry` is the per-caller commercial relationship. `hello_signals_adapter_marketplace.ts`, `hello_seller_adapter_social.ts`, and `hello_seller_adapter_multi_tenant.ts` show the durable buyer-agent identity seam; `ctx.agent` is the trusted record for status, sandbox-only reach, tenant routing, and billing gates.
+- `fixtures.buyer_agents[]` plus `seed_buyer_agent` is the compliance setup path. The signals Hello agent wires a test-only overlay so a 3.1 storyboard can vary Addie's `status`, `sandbox_only`, or `billing_capabilities` without inventing a special bearer-token prefix. Production agents should back this with their onboarding ledger and invalidate the registry cache after mutation.
+
+The framework resolves buyer agents, status-gates them, and enforces `sync_accounts.billing` against both seller-wide `supportedBillings` and the resolved `ctx.agent.billing_capabilities`. The social Hello agent includes a buyer-agent ledger so the framework can exercise the per-agent billing gate; do not fork a separate bearer-token prefix or unscoped test-only shortcut.
+
 ## Examples
 
 ### Basic Usage
@@ -50,7 +61,7 @@ Real platforms typically claim more than one specialism. Claim a specialism only
 
 ### Multi-specialism + multi-tenant (account-routed)
 
-`hello_seller_adapter_multi_tenant.ts` demonstrates the **account-routed** multi-tenant model: one server hosts `governance-spend-authority`, `property-lists`, and `brand-rights` for two distinct tenants whose data never crosses. The agency / holdco hub shape. Two resolution paths:
+`hello_seller_adapter_multi_tenant.ts` demonstrates the **account-routed** multi-tenant model: one server hosts `governance-spend-authority`, `property-lists`, and `brand-rights` for two distinct tenants whose data never crosses. The agency / holdco hub shape. It has strict typecheck coverage plus a direct MCP runtime test for buyer-agent-derived no-account tenant routing; full storyboard/façade gates will land once governance / brand-rights mock servers exist. Two resolution paths:
 
 - Tools that carry `account` (governance, property-lists, sync_accounts, sync_governance) → `accounts.resolve(ref)` reads `ref.operator` and routes to the matching tenant. Same buyer credential can hit different tenants by varying `account.operator`.
 - Tools without `account` (`get_brand_identity`, `get_rights`) → `accounts.resolve(undefined, ctx)` reads the resolved buyer agent's home tenant from `ctx.agent`. Different credentials → different views of the catalog without any account field on the wire.
@@ -68,6 +79,8 @@ Start with `createComplyController` (`comply-controller-seller.ts`). Switch to `
 
 Both wire `comply_test_controller`, both auto-emit the `capabilities.compliance_testing.scenarios` block, both sit on the same primitives. Pick by state shape, not by perceived helper tier.
 
+For proxy-shaped sellers where reads go to an upstream platform API, start with **`proxy-seller-snap/`**. It shows the seed bridge pattern: `comply_test_controller` writes storyboard fixtures into a session store, production read handlers call the Snap-shaped client, and `bridgeFromSessionStore` merges seeded products, creatives, and governance lists into sandbox responses after the handler succeeds.
+
 Run `npm run typecheck:examples` to validate both examples against the built `dist/`.
 
 ### Running Examples

package/examples/hello_creative_adapter_ad_server.ts

@@ -378,17 +378,23 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
   };
 
   accounts: AccountStore<NetworkMeta> = {
-    resolve: async ref => {
+    resolve: async (ref, ctx) => {
       // No-account tools (`previewCreative`, `listCreativeFormats`) hand
       // `undefined` to resolve. Return the default-listing network so
-      // the format catalog query has tenant context.
+      // the format catalog query has tenant context. This worked example
+      // uses the same auth-derived path for the conformance runner's
+      // controller discovery, so authenticated ref-less calls are stamped
+      // sandbox. Production sellers replace this with a real principal →
+      // account lookup and only stamp sandbox for sandbox tenants.
       if (!ref) {
+        if (!ctx?.authInfo) return null;
         const network = await upstream.lookupNetwork(KNOWN_PUBLISHERS[0] ?? 'creative-network.example');
         if (!network) return null;
         return {
           id: network.network_code,
           name: network.display_name,
           status: 'active',
+          mode: 'sandbox',
           brand: { domain: network.adcp_publisher },
           ctx_metadata: { network_code: network.network_code, publisher_domain: network.adcp_publisher },
         };

package/examples/hello_seller_adapter_guaranteed.ts

@@ -104,8 +104,8 @@ const ADCP_AUTH_TOKEN = process.env['ADCP_AUTH_TOKEN'] ?? 'sk_harness_do_not_use
 // (adcp#4028). The runner authenticates with this bearer to probe the
 // seller's live-mode denial path. The resolver below stamps
 // `mode: 'live'` on the matching principal so the framework gate inside
-// `createAdcpServerFromPlatform` refuses `comply_test_controller`
-// dispatch with FORBIDDEN. Test-kit value pinned by
+// `createAdcpServerFromPlatform` hides `comply_test_controller` from that
+// principal. Test-kit value pinned by
 // `compliance/cache/<ver>/test-kits/acme-outdoor-live.yaml`.
 //
 // ⚠️ This bearer is published in the open-source SDK and in the public
@@ -528,6 +528,10 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
     specialisms: ['sales-guaranteed'] as const,
     channels: ['olv', 'ctv', 'display'] as const,
     pricingModels: ['cpm'] as const,
+    // Storyboard account setup uses operator-billed settlement. Declare it
+    // explicitly so the framework-level sync_accounts commercial gate admits
+    // rows before this adapter resolves them to upstream network codes.
+    supportedBillings: ['operator', 'agent'] as const,
     supportsProposals: false,
     config: {},
     // Declares the comply_test_controller surface so the conformance
@@ -571,24 +575,27 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
         //   (1) the cascade-scenario sandbox arm below, keyed by
         //       `ref.sandbox === true` and stamped with `mode: 'sandbox'`
         //       and a `${SANDBOX_ID_PREFIX}${network_code}` id.
-        //   (2) the production path below, keyed by `ref.brand.domain`
+        //   (2) the conformance principal path here, keyed by auth and
+        //       stamped with `mode: 'sandbox'` but using the bare
+        //       `network_code` id so tasks/get polls match direct-buy tasks.
+        //   (3) the production path below, keyed by `ref.brand.domain`
         //       and stamped with the bare `network_code` id (no mode).
         // The compliance runner exercises path (2) for the
         // sales_guaranteed HITL flow (no `sandbox: true` on the create
         // step's account), so the auth-derived ref-less fallback
-        // returns the matching production account here. Production
-        // sellers key this off `ctx.authInfo.credential.key_id` /
-        // `client_id` against a real tenant store.
+        // returns the matching account id with sandbox principal mode here.
+        // Production sellers key this off `ctx.authInfo.credential.key_id`
+        // / `client_id` against a real tenant store.
         const publisherDomain = 'acmeoutdoor.example';
         const network = await upstream.lookupNetwork(publisherDomain);
         if (!network) return null;
         // Live-mode probe principal (comply_controller_mode_gate
         // storyboard) — stamp `mode: 'live'` so the framework gate inside
-        // `createAdcpServerFromPlatform` refuses `comply_test_controller`
-        // dispatch with FORBIDDEN. The probe never reaches a mutating
-        // dispatch path; the live-mode caller is denied before scenario
-        // execution. Production sellers source `mode` from their tenant
-        // store, not from the principal name.
+        // `createAdcpServerFromPlatform` hides `comply_test_controller`
+        // from that principal. The probe never reaches a mutating dispatch
+        // path; the live-mode caller is denied before scenario execution.
+        // Production sellers source `mode` from their tenant store, not
+        // from the principal name.
         //
         // Detection: ResolvedAuthInfo doesn't surface the principal name
         // directly (the framework propagates AuthPrincipal.principal as
@@ -602,7 +609,7 @@ class SalesGuaranteedAdapter implements DecisioningPlatform<Record<string, never
           name: network.display_name,
           status: 'active',
           brand: { domain: network.adcp_publisher },
-          ...(isLiveModeProbe ? { mode: 'live' as const } : {}),
+          mode: isLiveModeProbe ? 'live' : 'sandbox',
           ctx_metadata: {
             network_code: network.network_code,
             publisher_domain: network.adcp_publisher,
@@ -1246,10 +1253,11 @@ serve(
       // `createAdcpServerFromPlatform` resolves the calling principal
       // through `accounts.resolve` and admits only when the resolved
       // account's `mode` is `'sandbox'` or `'mock'` (per `Account.mode`
-      // in AdCP 6.7+). The synthesis branch in `accounts.resolve` above
-      // stamps `mode: 'sandbox'` on cascade-scenario refs; production
-      // refs flow through the live path with the field unset (default
-      // `'live'`), so the framework gate refuses dispatch for them.
+      // in AdCP 6.7+). The auth-derived conformance branch and the
+      // cascade-scenario ref branch in `accounts.resolve` above stamp
+      // `mode: 'sandbox'`; production refs flow through the live path with
+      // the field unset (default `'live'`), so the framework gate hides the
+      // controller for them.
       // See `docs/proposals/lifecycle-state-and-sandbox-authority.md`.
       complyTest: {
         seed: {
@@ -1306,8 +1314,8 @@ serve(
         [ADCP_AUTH_TOKEN]: { principal: 'compliance-runner' },
         // Live-mode probe principal — see comply_controller_mode_gate
         // storyboard. The resolver below stamps `mode: 'live'` when this
-        // bearer is presented; the framework gate then refuses
-        // comply_test_controller dispatch with FORBIDDEN.
+        // bearer is presented; the framework gate then hides
+        // comply_test_controller from that principal.
         [ADCP_LIVE_MODE_AUTH_TOKEN]: { principal: LIVE_MODE_PROBE_PRINCIPAL },
       },
     }),

package/examples/hello_seller_adapter_multi_tenant.ts

@@ -486,12 +486,12 @@ class MultiTenantAdapter implements DecisioningPlatform<Record<string, never>, T
         operator,
         ...(r?.brand?.domain && { brand: { domain: r.brand.domain } }),
         ctx_metadata: { tenant_id: tenant.id, display_name: tenant.display_name },
-        // SWAP: read sandbox flag from your backing store. Defaults to false
-        // — production adopters route reads/writes to a sandbox backend on
-        // this flag, so an unset wire field MUST NOT silently land in
-        // sandbox. Buyers who want sandbox set `account.sandbox = true`
-        // explicitly.
-        sandbox: r?.sandbox ?? false,
+        // SWAP: read sandbox flag from your backing store. Account-routed
+        // calls default false unless the buyer explicitly sets
+        // `account.sandbox = true`. No-account demo calls synthesize an
+        // auth-derived account for local sandbox buyer credentials, so keep
+        // that branch sandboxed.
+        sandbox: r ? (r.sandbox ?? false) : true,
       };
     },
     upsertRow: (tenant, ref, _ctx) => {

package/examples/hello_seller_adapter_social.ts

@@ -12,10 +12,12 @@
  *   3. Replace `audience_targeting` and `conversion_tracking` capability
  *      declarations with the identifier types / event types your platform
  *      actually accepts.
- *   4. Replace the `m.uids[i]` → `external_id_sha256` projection in
+ *   4. Replace `ONBOARDING_LEDGER` and `SELLER_SUPPORTED_BILLING` with your
+ *      buyer-agent onboarding/commercial-state source of truth.
+ *   5. Replace the `m.uids[i]` → `external_id_sha256` projection in
  *      `logEvent` with your CAPI's specific UID-to-field mapping.
- *   5. Replace `eventSourceMap` with persistent storage (DB / cache).
- *   6. Validate: `node --test test/examples/hello-seller-adapter-social.test.js`
+ *   6. Replace `eventSourceMap` with persistent storage (DB / cache).
+ *   7. Validate: `node --test test/examples/hello-seller-adapter-social.test.js`
  *
  * Demo:
  *   npx @adcp/sdk@latest mock-server sales-social --port 4350
@@ -36,6 +38,7 @@ import {
   createUpstreamHttpClient,
   memoryBackend,
   AdcpError,
+  BuyerAgentRegistry,
   defineSalesPlatform,
   defineAudiencePlatform,
   assertNoExampleTlds,
@@ -47,6 +50,8 @@ import {
   type SyncAudiencesRow,
   type SyncCreativesRow,
   type SyncAccountsResultRow,
+  type BuyerAgent,
+  type BuyerAgentBillingMode,
 } from '@adcp/sdk/server';
 import type {
   SyncCatalogsSuccess,
@@ -54,6 +59,7 @@ import type {
   SyncEventSourcesSuccess,
   GetAccountFinancialsSuccess,
 } from '@adcp/sdk/types';
+import { createHash } from 'node:crypto';
 
 const UPSTREAM_URL = process.env['UPSTREAM_URL'] ?? 'http://127.0.0.1:4350';
 const UPSTREAM_CLIENT_ID = process.env['UPSTREAM_OAUTH_CLIENT_ID'] ?? 'walled_garden_test_client_001';
@@ -61,6 +67,34 @@ const UPSTREAM_CLIENT_SECRET =
   process.env['UPSTREAM_OAUTH_CLIENT_SECRET'] ?? 'walled_garden_test_secret_do_not_use_in_prod';
 const PORT = Number(process.env['PORT'] ?? 3003);
 const ADCP_AUTH_TOKEN = process.env['ADCP_AUTH_TOKEN'] ?? 'sk_harness_do_not_use_in_prod';
+const SELLER_SUPPORTED_BILLING = ['operator', 'agent'] as const satisfies readonly BuyerAgentBillingMode[];
+
+function hashApiKey(token: string): string {
+  return createHash('sha256').update(token).digest('hex').slice(0, 32);
+}
+
+const ONBOARDING_LEDGER = new Map<string, BuyerAgent>([
+  [
+    hashApiKey(ADCP_AUTH_TOKEN),
+    {
+      agent_url: 'https://addie.example.com',
+      display_name: 'Addie (storyboard runner)',
+      status: 'active',
+      billing_capabilities: new Set(['operator']),
+      sandbox_only: true,
+    },
+  ],
+]);
+
+const agentRegistry = BuyerAgentRegistry.cached(
+  BuyerAgentRegistry.bearerOnly({
+    resolveByCredential: async credential => {
+      if (credential.kind !== 'api_key') return null;
+      return ONBOARDING_LEDGER.get(credential.key_id) ?? null;
+    },
+  }),
+  { ttlSeconds: 60 }
+);
 
 // ---------------------------------------------------------------------------
 // OAuth token cache — SWAP for production.
@@ -366,9 +400,12 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
       supported_event_types: ['purchase' as const, 'add_to_cart' as const, 'page_view' as const, 'lead' as const],
       supported_action_sources: ['website' as const, 'app' as const],
     },
+    supportedBillings: SELLER_SUPPORTED_BILLING,
     config: {},
   };
 
+  agentRegistry = agentRegistry;
+
   accounts: AccountStore<AdvertiserMeta> = {
     /** Translate AdCP `account.brand.domain` → upstream `advertiser_id`.
      *  The mock's discovery endpoint is /_lookup/advertiser; production
@@ -407,6 +444,7 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
         status: 'active',
         ...(operator !== undefined && { operator }),
         brand: { domain: upstreamAdv.adcp_advertiser },
+        sandbox: ref === undefined || !('sandbox' in ref) || ref.sandbox === true,
         ctx_metadata: {
           advertiser_id: upstreamAdv.advertiser_id,
           advertiser_domain: upstreamAdv.adcp_advertiser,
@@ -439,7 +477,7 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
      *  advertiser seats out-of-band — this is a discovery/echo, not a
      *  provisioning call. Per the storyboard, list_accounts is the
      *  canonical alternative (declared via `provides_state_for`). */
-    upsert: async refs => {
+    upsert: async (refs, ctx) => {
       const out: SyncAccountsResultRow[] = [];
       for (const ref of refs) {
         // sync_accounts always carries the brand+operator arm (the buyer is
@@ -468,6 +506,42 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
           });
           continue;
         }
+        const requestedBilling = (ref as { billing?: BuyerAgentBillingMode }).billing ?? 'operator';
+        if (!(SELLER_SUPPORTED_BILLING as readonly BuyerAgentBillingMode[]).includes(requestedBilling)) {
+          out.push({
+            brand: { domain },
+            operator,
+            action: 'failed',
+            status: 'rejected',
+            errors: [
+              {
+                code: 'BILLING_NOT_SUPPORTED',
+                message: `Billing '${requestedBilling}' is not supported by this seller.`,
+                details: {
+                  scope: 'capability',
+                  supported_billing: [...SELLER_SUPPORTED_BILLING],
+                },
+              } as unknown as { code: string; message: string },
+            ],
+          });
+          continue;
+        }
+        if (ctx?.agent && !ctx.agent.billing_capabilities.has(requestedBilling)) {
+          out.push({
+            brand: { domain },
+            operator,
+            action: 'failed',
+            status: 'rejected',
+            errors: [
+              {
+                code: 'BILLING_NOT_PERMITTED_FOR_AGENT',
+                message: `Billing '${requestedBilling}' is not permitted for this buyer agent.`,
+                details: { rejected_billing: requestedBilling, suggested_billing: 'operator' },
+              } as unknown as { code: string; message: string },
+            ],
+          });
+          continue;
+        }
         const adv = await upstream.lookupAdvertiser(domain);
         if (!adv) {
           out.push({
@@ -486,6 +560,8 @@ class SalesSocialAdapter implements DecisioningPlatform<Record<string, never>, A
           operator,
           action: 'unchanged',
           status: 'active',
+          billing: requestedBilling,
+          sandbox: (ref as { sandbox?: boolean }).sandbox ?? true,
         });
       }
       return out;

package/examples/hello_si_adapter_brand.ts

@@ -1,18 +1,15 @@
 /**
  * hello_si_adapter_brand — worked starting point for an AdCP Sponsored
- * Intelligence agent (protocol `sponsored_intelligence`) that wraps an
+ * Intelligence agent (`sponsored-intelligence` specialism / protocol) that wraps an
  * upstream brand-agent platform via HTTP.
  *
  * Fork this. Replace `upstream` with calls to your real backend
  * (Salesforce Agentforce, OpenAI Assistants brand mode, custom brand
  * chat). The AdCP-facing platform methods stay the same.
  *
- * **Status**: SI is a *protocol* in AdCP 3.0, not a specialism. Spec change
- * to add it to `AdCPSpecialism` is tracked at adcontextprotocol/adcp#3961
- * for 3.1. Until then the SDK dispatches off the
- * `platform.sponsoredIntelligence` field's presence — which auto-derives
- * `'sponsored_intelligence'` into the wire-side `supported_protocols`
- * via `detectProtocols`.
+ * **Status**: SI is an AdCP 3.1 specialism. The SDK still dispatches off the
+ * `platform.sponsoredIntelligence` field's presence, and that field also
+ * auto-derives the wire-side `supported_protocols` entry via `detectProtocols`.
  *
  * FORK CHECKLIST
  *   1. Replace every `// SWAP:` marker with calls to your backend.
@@ -368,11 +365,10 @@ interface SiBrandMeta {
   [key: string]: unknown;
 }
 
-// SI isn't yet a specialism (adcp#3961). The platform field's presence
-// is the declaration; framework auto-derives 'sponsored_intelligence'
-// into supported_protocols from the four SI tools getting registered.
-// Build with `definePlatform` so the empty-`specialisms[]` flows through
-// `RequiredPlatformsFor`'s `[S] extends [never]` short-circuit cleanly.
+// SI is a 3.1 specialism and a protocol-bundle surface. The platform field
+// supplies the four SI tools; claiming `specialisms: ['sponsored-intelligence']`
+// below lets the framework validate the field and auto-derive
+// 'sponsored_intelligence' into wire-side supported_protocols.
 
 const accounts: AccountStore<SiBrandMeta> = {
   resolve: async ref => {
@@ -453,14 +449,7 @@ const sponsoredIntelligence = defineSponsoredIntelligencePlatform<SiBrandMeta>({
       ...(matching ? { matching_products: matching } : {}),
       total_matching: offering.total_matching,
     };
-    // Top-level `offering_id` mirror. The canonical AdCP wire location is
-    // `offering.offering_id` (above), but the `si_baseline` compliance
-    // storyboard captures with `path: 'offering_id'` (top-level). The
-    // schema allows `additionalProperties: true` at the response root so
-    // the mirror is permitted at the wire layer; the generated TS type
-    // doesn't model extra properties, so widen via cast. Drop once the
-    // storyboard path is corrected to `offering.offering_id` upstream.
-    return Object.assign({}, response, { offering_id: offering.offering_id }) as SIGetOfferingResponse;
+    return response;
   },
 
   initiateSession: async (req: SIInitiateSessionRequest, ctx): Promise<SIInitiateSessionResponse> => {
@@ -552,7 +541,7 @@ const sponsoredIntelligence = defineSponsoredIntelligencePlatform<SiBrandMeta>({
 // ---------------------------------------------------------------------------
 
 const platform = definePlatform<Record<string, never>, SiBrandMeta>({
-  capabilities: { specialisms: [] as const, config: {} },
+  capabilities: { specialisms: ['sponsored-intelligence'] as const, config: {} },
   accounts,
   sponsoredIntelligence,
 });