@adcp/sdk 6.6.0 → 6.8.0

package/dist/lib/server/decisioning/platform-helpers.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * Identity helpers for `createAdcpServerFromPlatform` adopters who build their
+ * platform as an object literal rather than a class.
+ *
+ * **The problem they solve:**
+ *
+ * `createAdcpServerFromPlatform<P extends DecisioningPlatform<any, any>>(platform: P)`
+ * infers `P` from the argument, which defeats TypeScript's contextual typing for
+ * method parameters inside nested object literals. Without an explicit type annotation,
+ * a handler like `syncEventSources: async (req, ctx) => {...}` gets `req: unknown`.
+ *
+ * These helpers force a concrete `DecisioningPlatform<TConfig, TCtxMeta>` (or
+ * per-specialism sub-interface) as the argument type, giving TypeScript the
+ * annotation it needs to flow types into nested method bodies:
+ *
+ * ```ts
+ * // Without helper — req: unknown
+ * createAdcpServerFromPlatform({
+ *   sales: { syncEventSources: async (req, ctx) => { req.event_sources } }
+ * }, opts);
+ *
+ * // With defineSalesPlatform — req: SyncEventSourcesRequest ✓
+ * createAdcpServerFromPlatform({
+ *   sales: defineSalesPlatform<MyMeta>({
+ *     syncEventSources: async (req, ctx) => { req.event_sources }
+ *   })
+ * }, opts);
+ * ```
+ *
+ * Alternatively, the class pattern with explicit property-type annotations achieves
+ * the same result without helpers:
+ *
+ * ```ts
+ * class MySeller implements DecisioningPlatform<Config, MyMeta> {
+ *   sales: SalesPlatform<MyMeta> = {
+ *     syncEventSources: async (req, ctx) => { req.event_sources } // req typed ✓
+ *   };
+ * }
+ * ```
+ *
+ * Use whichever pattern fits your codebase.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePlatform = definePlatform;
+exports.defineSalesPlatform = defineSalesPlatform;
+exports.defineSalesCorePlatform = defineSalesCorePlatform;
+exports.defineSalesIngestionPlatform = defineSalesIngestionPlatform;
+exports.defineAudiencePlatform = defineAudiencePlatform;
+exports.defineSignalsPlatform = defineSignalsPlatform;
+exports.defineSponsoredIntelligencePlatform = defineSponsoredIntelligencePlatform;
+exports.defineCreativeBuilderPlatform = defineCreativeBuilderPlatform;
+exports.defineCreativeAdServerPlatform = defineCreativeAdServerPlatform;
+exports.defineCampaignGovernancePlatform = defineCampaignGovernancePlatform;
+exports.defineContentStandardsPlatform = defineContentStandardsPlatform;
+exports.definePropertyListsPlatform = definePropertyListsPlatform;
+exports.defineCollectionListsPlatform = defineCollectionListsPlatform;
+exports.defineBrandRightsPlatform = defineBrandRightsPlatform;
+exports.definePlatformWithCompliance = definePlatformWithCompliance;
+/**
+ * Type-level identity for a full `DecisioningPlatform` object literal.
+ *
+ * Fixes TypeScript's contextual-typing gap when passing an object literal
+ * directly to `createAdcpServerFromPlatform`. Wrap your platform object with
+ * this helper to get typed `req` and `ctx` parameters in every handler body.
+ *
+ * @example
+ * ```ts
+ * import { createAdcpServerFromPlatform, definePlatform } from '@adcp/sdk/server';
+ *
+ * interface MyMeta { advertiserId: string }
+ *
+ * const server = createAdcpServerFromPlatform(
+ *   definePlatform<{ networkId: string }, MyMeta>({
+ *     capabilities: { specialisms: ['sales-non-guaranteed'], ... },
+ *     accounts: { resolve: async (ref) => ... },
+ *     sales: {
+ *       getProducts: async (req, ctx) => {
+ *         // req: GetProductsRequest ✓  ctx.account.ctx_metadata: MyMeta ✓
+ *       },
+ *     },
+ *   }),
+ *   { name: 'my-seller', version: '1.0.0' }
+ * );
+ * ```
+ */
+function definePlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `SalesPlatform` sub-object.
+ *
+ * Use this to type-annotate the `sales` property when building inline rather
+ * than with a class. Every handler method (`getProducts`, `createMediaBuy`,
+ * `syncEventSources`, etc.) gets its proper typed `req` parameter.
+ *
+ * @example
+ * ```ts
+ * import { createAdcpServerFromPlatform, defineSalesPlatform } from '@adcp/sdk/server';
+ *
+ * interface SocialMeta { advertiserId: string; pixelId: string }
+ *
+ * const server = createAdcpServerFromPlatform({
+ *   capabilities: { specialisms: ['sales-social', 'sales-non-guaranteed'], ... },
+ *   accounts: { resolve: async (ref) => ... },
+ *   sales: defineSalesPlatform<SocialMeta>({
+ *     getProducts: async (req, ctx) => { ... },
+ *     createMediaBuy: async (req, ctx) => { ... },
+ *     // req is fully typed throughout ✓
+ *     syncEventSources: async (req, ctx) => {
+ *       const sources = req.event_sources ?? [];  // no cast needed
+ *     },
+ *   }),
+ * }, { name: 'social-seller', version: '1.0.0' });
+ * ```
+ */
+function defineSalesPlatform(platform) {
+    // Identity helper — return type matches the input parameter type.
+    //
+    // **Post-#1341 caveat.** `SalesPlatform` methods are now optional
+    // individually, so this helper's return type is effectively all-optional
+    // even when the adopter passes all five core methods. Adopters claiming
+    // a sales specialism with `RequiredPlatformsFor<S>`-narrowed core methods
+    // (`sales-guaranteed`, `sales-non-guaranteed`, `sales-broadcast-tv`,
+    // `sales-catalog-driven`) need the closed shape on the way out — this
+    // helper doesn't preserve it. Two ways to keep the per-specialism type
+    // narrowing under #1341:
+    //
+    //   1. Drop `defineSalesPlatform` and write the platform field with an
+    //      explicit `: SalesCorePlatform<Meta> & SalesIngestionPlatform<Meta>`
+    //      annotation. The TS compiler flows the contextual type into the
+    //      literal and `RequiredPlatformsFor<S>` enforcement holds.
+    //   2. Use the new {@link defineSalesCorePlatform} for the core methods
+    //      and {@link defineSalesIngestionPlatform} for ingestion methods,
+    //      spreading both onto the `sales` field.
+    //
+    // Pure source-compat for adopters claiming `sales-social` (ingestion-only)
+    // who don't need the per-specialism core narrowing — the helper still
+    // pins TCtxMeta on the parameter so handler `ctx` is typed correctly.
+    return platform;
+}
+/**
+ * Type-level identity for the **core** sales surface — bidding +
+ * media-buy lifecycle (`getProducts`, `createMediaBuy`, `updateMediaBuy`,
+ * `getMediaBuyDelivery`, `getMediaBuys`). Use when claiming `sales-non-
+ * guaranteed` / `sales-guaranteed` / `sales-broadcast-tv` /
+ * `sales-catalog-driven` and you want compile-time enforcement of the
+ * lifecycle methods without dragging in optional ingestion methods.
+ *
+ * Pair with {@link defineSalesIngestionPlatform} when also implementing
+ * ingestion surfaces (sync_creatives, log_event, etc.) — spread the two
+ * onto the platform's `sales` field.
+ *
+ * @example
+ * ```ts
+ * sales: { ...defineSalesCorePlatform<MyMeta>({
+ *   getProducts: async (req, ctx) => { ... },
+ *   createMediaBuy: async (req, ctx) => { ... },
+ *   updateMediaBuy: async (id, patch, ctx) => { ... },
+ *   getMediaBuyDelivery: async (filter, ctx) => { ... },
+ *   getMediaBuys: async (req, ctx) => { ... },
+ * }) },
+ * ```
+ */
+function defineSalesCorePlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for the **ingestion** sales surface — sync surfaces
+ * (`syncCreatives`, `syncCatalogs`, `syncEventSources`, `logEvent`) +
+ * read/feedback (`listCreativeFormats`, `listCreatives`,
+ * `providePerformanceFeedback`). Walled-garden specialisms whose value
+ * surface is asset push (Meta CAPI, Snap CAPI, retail-media catalogs)
+ * use this without claiming the core media-buy lifecycle. Every method
+ * is optional individually — implement what your specialism's storyboard
+ * exercises.
+ *
+ * Use this when claiming `sales-social` (no `sales-non-guaranteed`)
+ * or composing `audience-sync` ingestion onto a non-media-buy seller.
+ * Adopters who also accept inbound media buys spread
+ * {@link defineSalesCorePlatform}'s output alongside.
+ *
+ * @example
+ * ```ts
+ * // Pure sales-social adopter — no media buys, just events + creatives.
+ * sales: defineSalesIngestionPlatform<SocialMeta>({
+ *   syncCreatives: async (creatives, ctx) => { ... },
+ *   syncEventSources: async (req, ctx) => { ... },
+ *   logEvent: async (req, ctx) => { ... },
+ * }),
+ * ```
+ */
+function defineSalesIngestionPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for an `AudiencePlatform` sub-object.
+ *
+ * Use when the `audiences` field is built inline. Ensures `audiences` and
+ * `audienceIds` parameters are typed rather than inferred as `unknown`.
+ *
+ * @example
+ * ```ts
+ * audiences: defineAudiencePlatform<SocialMeta>({
+ *   syncAudiences: async (audiences, ctx) => {
+ *     // audiences: Audience[] ✓  ctx.account.ctx_metadata: SocialMeta ✓
+ *   },
+ *   pollAudienceStatuses: async (audienceIds, ctx) => { ... },
+ * }),
+ * ```
+ */
+function defineAudiencePlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `SignalsPlatform` sub-object.
+ *
+ * @example
+ * ```ts
+ * signals: defineSignalsPlatform<SignalsMeta>({
+ *   getSignals: async (req, ctx) => { ... },
+ *   activateSignal: async (req, ctx) => { ... },
+ * }),
+ * ```
+ */
+function defineSignalsPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `SponsoredIntelligencePlatform` sub-object.
+ * SI is currently a *protocol* in AdCP 3.0, not a specialism — adopters
+ * declare SI by providing this field; the framework auto-derives
+ * `'sponsored_intelligence'` into the wire-side `supported_protocols`.
+ *
+ * @example
+ * ```ts
+ * sponsoredIntelligence: defineSponsoredIntelligencePlatform<BrandMeta>({
+ *   getOffering: async (req, ctx) => { ... },
+ *   initiateSession: async (req, ctx) => { ... },
+ *   sendMessage: async (req, ctx) => { ... },
+ *   terminateSession: async (req, ctx) => { ... },
+ * }),
+ * ```
+ */
+function defineSponsoredIntelligencePlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `CreativeBuilderPlatform` sub-object.
+ *
+ * @example
+ * ```ts
+ * creative: defineCreativeBuilderPlatform<CreativeMeta>({
+ *   buildCreative: async (req, ctx) => { ... },
+ * }),
+ * ```
+ */
+function defineCreativeBuilderPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `CreativeAdServerPlatform` sub-object.
+ */
+function defineCreativeAdServerPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `CampaignGovernancePlatform` sub-object.
+ */
+function defineCampaignGovernancePlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `ContentStandardsPlatform` sub-object.
+ */
+function defineContentStandardsPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `PropertyListsPlatform` sub-object.
+ */
+function definePropertyListsPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `CollectionListsPlatform` sub-object.
+ */
+function defineCollectionListsPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a `BrandRightsPlatform` sub-object.
+ */
+function defineBrandRightsPlatform(platform) {
+    return platform;
+}
+/**
+ * Type-level identity for a full `DecisioningPlatform` that wires
+ * `comply_test_controller`. Requires `capabilities.compliance_testing`
+ * to be present in the platform object, enforcing the cap/adapter
+ * pairing at compile time.
+ *
+ * When the returned platform is passed to `createAdcpServerFromPlatform`,
+ * `RequiredOptsFor<P>` resolves to require `complyTest` in opts — so
+ * both halves of the invariant are enforced without runtime-only feedback.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createAdcpServerFromPlatform,
+ *   definePlatformWithCompliance,
+ * } from '@adcp/sdk/server';
+ *
+ * const server = createAdcpServerFromPlatform(
+ *   definePlatformWithCompliance<Config, Meta>({
+ *     capabilities: {
+ *       specialisms: ['sales-guaranteed'],
+ *       compliance_testing: {}, // required by this helper ✓
+ *     },
+ *     accounts: { resolve: async (ref) => ... },
+ *     sales: { ... },
+ *   }),
+ *   {
+ *     name: 'my-seller',
+ *     version: '1.0.0',
+ *     complyTest: { seed: { product: ... } }, // required by RequiredOptsFor<P> ✓
+ *   }
+ * );
+ * ```
+ */
+function definePlatformWithCompliance(platform) {
+    return platform;
+}
+//# sourceMappingURL=platform-helpers.js.map

package/dist/lib/server/decisioning/platform-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-helpers.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/platform-helpers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;AA0CH,wCAIC;AA6BD,kDA0BC;AAyBD,0DAIC;AA2BD,oEAIC;AAkBD,wDAIC;AAaD,sDAIC;AAkBD,kFAIC;AAYD,sEAIC;AAKD,wEAIC;AAKD,4EAIC;AAKD,wEAIC;AAKD,kEAIC;AAKD,sEAIC;AAKD,8DAIC;AAoCD,oEAQC;AAjUD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,cAAc,CAC5B,QAAgD;IAEhD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,mBAAmB,CACjC,QAAiC;IAEjC,kEAAkE;IAClE,EAAE;IACF,kEAAkE;IAClE,yEAAyE;IACzE,wEAAwE;IACxE,0EAA0E;IAC1E,qEAAqE;IACrE,sEAAsE;IACtE,uEAAuE;IACvE,yBAAyB;IACzB,EAAE;IACF,uEAAuE;IACvE,2EAA2E;IAC3E,sEAAsE;IACtE,gEAAgE;IAChE,wEAAwE;IACxE,uEAAuE;IACvE,8CAA8C;IAC9C,EAAE;IACF,2EAA2E;IAC3E,sEAAsE;IACtE,sEAAsE;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,uBAAuB,CACrC,QAAqC;IAErC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,4BAA4B,CAC1C,QAA0C;IAE1C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,sBAAsB,CACpC,QAAoC;IAEpC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,qBAAqB,CACnC,QAAmC;IAEnC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,mCAAmC,CACjD,QAAiD;IAEjD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,6BAA6B,CAC3C,QAA2C;IAE3C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,8BAA8B,CAC5C,QAA4C;IAE5C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,gCAAgC,CAC9C,QAA8C;IAE9C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,8BAA8B,CAC5C,QAA4C;IAE5C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,2BAA2B,CACzC,QAAyC;IAEzC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,6BAA6B,CAC3C,QAA2C;IAE3C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAgB,yBAAyB,CACvC,QAAuC;IAEvC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,4BAA4B,CAC1C,QAEC;IAID,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/lib/server/decisioning/platform.d.ts

@@ -11,12 +11,15 @@
  */
 import type { DecisioningCapabilities, BrandCapabilities } from './capabilities';
 import type { Account, AccountStore } from './account';
+import type { BuyerAgentRegistry } from './buyer-agent';
+import type { SessionContext, OnInstructionsError, MaybePromise } from '../create-adcp-server';
 import type { StatusMappers } from './status-mappers';
-import type { SalesPlatform } from './specialisms/sales';
+import type { SalesPlatform, SalesCorePlatform, SalesIngestionPlatform } from './specialisms/sales';
 import type { CreativeBuilderPlatform } from './specialisms/creative';
 import type { CreativeAdServerPlatform } from './specialisms/creative-ad-server';
 import type { AudiencePlatform } from './specialisms/audiences';
 import type { SignalsPlatform } from './specialisms/signals';
+import type { SponsoredIntelligencePlatform } from './specialisms/sponsored-intelligence';
 import type { CampaignGovernancePlatform } from './specialisms/campaign-governance';
 import type { ContentStandardsPlatform } from './specialisms/content-standards';
 import type { BrandRightsPlatform } from './specialisms/brand-rights';
@@ -54,6 +57,63 @@ import type { AdCPSpecialism } from '../../types/tools.generated';
  * **What the platform owns**: the business decisions in each `SalesPlatform` /
  * `CreativeBuilderPlatform` / `AudiencePlatform` method. Nothing else.
  *
+ * ### Cross-specialism dispatch
+ *
+ * When one specialism handler needs to consult another (canonical case:
+ * `brandRights.acquireRights` calling `campaignGovernance.checkGovernance`
+ * before granting rights, against a buyer-registered governance binding),
+ * the framework does NOT thread a separate `ctx.platform.<specialism>`
+ * accessor on `RequestContext`. Two idiomatic patterns; pick by authoring
+ * style:
+ *
+ * **Pattern A — class instance + `this`** (canonical for holdco hubs;
+ * `examples/hello_seller_adapter_multi_tenant.ts` is the reference):
+ *
+ * ```ts
+ * class HoldcoAdapter implements DecisioningPlatform<Config, TenantMeta> {
+ *   campaignGovernance = defineCampaignGovernancePlatform<TenantMeta>({  });
+ *   brandRights = defineBrandRightsPlatform<TenantMeta>({
+ *     acquireRights: async (req, ctx) => {
+ *       const denial = await this.enforceGovernance(tenant, ctx, offering, req);
+ *       if (denial) return denial;
+ *
+ *     },
+ *   });
+ *   private async enforceGovernance(...) {
+ *     // calls this.campaignGovernance.checkGovernance(...)
+ *   }
+ * }
+ * ```
+ *
+ * **Pattern B — closure capture** (for adopters using `define<X>Platform({...})`
+ * factories standalone):
+ *
+ * ```ts
+ * const campaignGovernance = defineCampaignGovernancePlatform<TenantMeta>({ ... });
+ * const brandRights = defineBrandRightsPlatform<TenantMeta>({
+ *   acquireRights: async (req, ctx) => {
+ *     const govResp = await campaignGovernance.checkGovernance!(checkReq, ctx);
+ *
+ *   },
+ * });
+ * const platform: DecisioningPlatform<Config, TenantMeta> = {
+ *   capabilities: {  }, accounts: {  }, campaignGovernance, brandRights,
+ * };
+ * ```
+ *
+ * Both patterns forward the same `RequestContext` (resolved account, agent,
+ * authInfo), so tenant invariants hold transitively. Both bypass wire-side
+ * validation, idempotency dedup, and mutating-tool annotations — that's
+ * correct because you're inside the seller's code, not handling a buyer
+ * request, but it means an in-process `checkGovernance` won't be
+ * re-deduped if the originating tool is already idempotency-protected.
+ * Single-specialism adopters MUST NOT copy this short-circuit: without a
+ * co-resident sibling handler, dial out to the registered governance
+ * agent URL via the `@adcp/sdk` client instead.
+ *
+ * Full walkthrough with same-tenant invariant + production caveats:
+ * `skills/build-holdco-agent/SKILL.md` § Cross-specialism dispatch.
+ *
  * @template TConfig Platform-specific config typed at the call site.
  *                   Example: `class GAM implements DecisioningPlatform<{ networkId: string }>`.
  * @template TCtxMeta Shape of the platform's opaque ctx_metadata blob — typed
@@ -65,6 +125,66 @@ export interface DecisioningPlatform<TConfig = unknown, TCtxMeta = Record<string
     capabilities: DecisioningCapabilities<TConfig>;
     /** Account model + tenant resolution. */
     accounts: AccountStore<TCtxMeta>;
+    /**
+     * Server-level instructions surfaced on the MCP `initialize` response.
+     * Use to publish platform facts, decision policy, and trends that buying
+     * agents should read before issuing tool calls (e.g., "publisher-wide
+     * brand safety: alcohol disallowed", "carbon-aware pricing applies to
+     * display impressions only", "weekly cutoff Thursday 17:00 UTC").
+     *
+     * Two forms:
+     *
+     * 1. **Static string** — captured once at construction.
+     * 2. **Function** `(ctx: SessionContext) => MaybePromise<string | undefined>` —
+     *    re-evaluated each time `createAdcpServerFromPlatform` runs. Under the
+     *    canonical `serve({ reuseAgent: false })` flow that is per session, so the
+     *    closure can surface tenant-shaped prose (per-buyer brand manifests,
+     *    storefront-platform copy). `serve()` refuses `reuseAgent: true`
+     *    when this is a function — the function would only fire once for
+     *    the lifetime of the shared agent.
+     *
+     *    Async functions are supported: the framework calls the function at
+     *    construction and awaits the returned Promise during MCP `initialize`.
+     *    A rejected Promise is governed by `onInstructionsError`.
+     *
+     * MCP-only today. The A2A `AgentCard` analog is `description` (and
+     * per-skill `description`); threading platform.instructions into the
+     * agent-card builder is tracked separately so MCP and A2A buyers see
+     * the same prose.
+     *
+     * When set on the platform, takes precedence over any `instructions`
+     * supplied via `createAdcpServerFromPlatform` opts — same precedence as
+     * `agentRegistry`. Adopters with v5 escape-hatch wiring can keep using
+     * `opts.instructions`; v6 callers should declare it here.
+     *
+     * @see {@link OnInstructionsError} for `onInstructionsError` (default `'skip'`).
+     */
+    instructions?: string | ((ctx: SessionContext) => MaybePromise<string | undefined>);
+    /**
+     * Behavior when a function-form `instructions` callback throws.
+     * Defaults to `'skip'` — best-effort prose (brand manifests, marketing
+     * copy) should not kill the buyer's session on a registry fetch failure.
+     * Set `'fail'` for adopters whose instructions carry load-bearing policy.
+     *
+     * Threaded through to {@link createAdcpServer} unchanged.
+     */
+    onInstructionsError?: OnInstructionsError;
+    /**
+     * Buyer-agent identity registry — Phase 1 of #1269. Optional. When
+     * configured, framework calls `agentRegistry.resolve(authInfo)` once per
+     * request before `accounts.resolve` and threads the resolved record
+     * through `ctx.agent` to specialism handlers.
+     *
+     * Adopters construct via {@link BuyerAgentRegistry.signingOnly},
+     * {@link BuyerAgentRegistry.bearerOnly}, or {@link BuyerAgentRegistry.mixed}
+     * depending on their authentication posture. When omitted, `ctx.agent`
+     * is always undefined and the framework's request flow is unchanged.
+     *
+     * Phase 2 (#1292) wires framework-level billing-capability enforcement
+     * against `BuyerAgent.billing_capabilities` and emits the AdCP-3.1
+     * billing error codes. Phase 1 ships the surface and resolution only.
+     */
+    agentRegistry?: BuyerAgentRegistry;
     /**
      * Native-status mappers (account, mediaBuy, creative, plan).
      *
@@ -91,10 +211,19 @@ export interface DecisioningPlatform<TConfig = unknown, TCtxMeta = Record<string
     creative?: CreativeBuilderPlatform<TCtxMeta> | CreativeAdServerPlatform<TCtxMeta>;
     audiences?: AudiencePlatform<TCtxMeta>;
     signals?: SignalsPlatform<TCtxMeta>;
+    /** Sponsored Intelligence is currently a *protocol* in AdCP 3.0
+     * (`supported_protocols: ['sponsored_intelligence']`), not a specialism.
+     * Required IFF the agent declares the protocol — see
+     * `RequiredPlatformsForProtocols`. When AdCP 3.1 promotes SI to a
+     * specialism (adcontextprotocol/adcp#3961), specialism-keyed dispatch
+     * becomes additive without breaking this field. */
+    sponsoredIntelligence?: SponsoredIntelligencePlatform<TCtxMeta>;
+    /** @see DecisioningPlatform — § Cross-specialism dispatch (used as the canonical example: `brandRights.acquireRights` consulting `checkGovernance` before granting rights). */
     campaignGovernance?: CampaignGovernancePlatform<TCtxMeta>;
     contentStandards?: ContentStandardsPlatform<TCtxMeta>;
     propertyLists?: PropertyListsPlatform<TCtxMeta>;
     collectionLists?: CollectionListsPlatform<TCtxMeta>;
+    /** @see DecisioningPlatform — § Cross-specialism dispatch (`acquireRights` is the canonical caller into `campaignGovernance.checkGovernance`). */
     brandRights?: BrandRightsPlatform<TCtxMeta>;
 }
 /**
@@ -116,15 +245,21 @@ export interface DecisioningPlatform<TConfig = unknown, TCtxMeta = Record<string
  * resolve to an empty requirement — the framework's runtime check is the
  * fallback gate.
  */
-type SalesSpecialism = 'sales-non-guaranteed' | 'sales-guaranteed' | 'sales-broadcast-tv' | 'sales-social' | 'sales-catalog-driven' | 'sales-proposal-mode';
+type SalesCoreSpecialism = 'sales-non-guaranteed' | 'sales-guaranteed' | 'sales-broadcast-tv' | 'sales-catalog-driven';
+type SalesIngestionSpecialism = 'sales-social';
+type SalesProposalSpecialism = 'sales-proposal-mode';
 type SignalSpecialism = 'signal-marketplace' | 'signal-owned';
 type CampaignGovernanceSpecialism = 'governance-spend-authority' | 'governance-delivery-monitor';
-export type RequiredPlatformsFor<S extends AdCPSpecialism, TCtxMeta = any> = S extends 'creative-template' | 'creative-generative' ? {
+export type RequiredPlatformsFor<S extends AdCPSpecialism, TCtxMeta = any> = [S] extends [never] ? {} : S extends 'creative-template' | 'creative-generative' ? {
     creative: CreativeBuilderPlatform<TCtxMeta>;
 } : S extends 'creative-ad-server' ? {
     creative: CreativeAdServerPlatform<TCtxMeta>;
-} : S extends SalesSpecialism ? {
-    sales: SalesPlatform<TCtxMeta>;
+} : S extends SalesCoreSpecialism ? {
+    sales: SalesCorePlatform<TCtxMeta> & SalesIngestionPlatform<TCtxMeta>;
+} : S extends SalesIngestionSpecialism ? {
+    sales: SalesIngestionPlatform<TCtxMeta>;
+} : S extends SalesProposalSpecialism ? {
+    sales: Required<Pick<SalesPlatform<TCtxMeta>, 'getProducts'>> & SalesIngestionPlatform<TCtxMeta>;
 } : S extends 'audience-sync' ? {
     audiences: AudiencePlatform<TCtxMeta>;
 } : S extends SignalSpecialism ? {
@@ -139,21 +274,7 @@ export type RequiredPlatformsFor<S extends AdCPSpecialism, TCtxMeta = any> = S e
     contentStandards: ContentStandardsPlatform<TCtxMeta>;
 } : S extends 'brand-rights' ? {
     brandRights: BrandRightsPlatform<TCtxMeta>;
-} : Record<string, never>;
-/**
- * The framework's createAdcpServer<P> signature uses this intersection to
- * enforce capability claims at compile time. Sketch:
- *
- * ```ts
- * declare function createAdcpServer<P extends DecisioningPlatform>(config: {
- *   platform: P & RequiredPlatformsFor<P['capabilities']['specialisms'][number]>;
- * }): AdcpServer;
- * ```
- *
- * NOTE: The companion file is preview-only; the actual `createAdcpServer`
- * doesn't yet enforce this. Wiring lands in a follow-up PR with the
- * framework refactor.
- */
+} : {};
 /**
  * Compile-time mapping from a claimed specialism to the capability
  * blocks the framework requires on `DecisioningCapabilities`. Sister

package/dist/lib/server/decisioning/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxF,gFAAgF;IAChF,YAAY,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAE/C,yCAAyC;IACzC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEjC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,CACjB,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GACzB,uBAAuB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;IAMhF,KAAK,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAClF,SAAS,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IACpC,kBAAkB,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAC1D,gBAAgB,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IACtD,aAAa,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAChD,eAAe,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IACpD,WAAW,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CAI7C;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AAMH,KAAK,eAAe,GAChB,sBAAsB,GACtB,kBAAkB,GAClB,oBAAoB,GACpB,cAAc,GACd,sBAAsB,GACtB,qBAAqB,CAAC;AAI1B,KAAK,gBAAgB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AAM9D,KAAK,4BAA4B,GAAG,4BAA4B,GAAG,6BAA6B,CAAC;AAQjG,MAAM,MAAM,oBAAoB,CAC9B,CAAC,SAAS,cAAc,EAExB,QAAQ,GAAG,GAAG,IACZ,CAAC,SAAS,mBAAmB,GAAG,qBAAqB,GACrD;IAAE,QAAQ,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC/C,CAAC,SAAS,oBAAoB,GAC5B;IAAE,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAChD,CAAC,SAAS,eAAe,GACvB;IAAE,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;CAAE,GAClC,CAAC,SAAS,eAAe,GACvB;IAAE,SAAS,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;CAAE,GACzC,CAAC,SAAS,gBAAgB,GACxB;IAAE,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;CAAE,GACtC,CAAC,SAAS,4BAA4B,GACpC;IAAE,kBAAkB,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC5D,CAAC,SAAS,gBAAgB,GACxB;IAAE,aAAa,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAClD,CAAC,SAAS,kBAAkB,GAC1B;IAAE,eAAe,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAA;CAAE,GACtD,CAAC,SAAS,mBAAmB,GAC3B;IAAE,gBAAgB,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAA;CAAE,GACxD,CAAC,SAAS,cAAc,GACtB;IAAE,WAAW,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC9C,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,cAAc,IAAI,CAAC,SAAS,cAAc,GACpF;IAAE,YAAY,EAAE;QAAE,KAAK,EAAE,iBAAiB,CAAA;KAAE,CAAA;CAAE,GAC9C,EAAE,CAAC"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/platform.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/decisioning/platform.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/platform.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAmOH,0EAA0E;AAC1E,wEAAwE;AACxE,0EAA0E;AAC1E,sEAAsE;AACtE,iBAAiB"}
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/platform.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAsaH,0EAA0E;AAC1E,wEAAwE;AACxE,0EAA0E;AAC1E,sEAAsE;AACtE,iBAAiB"}