@adcp/sdk 16.4.0 → 16.6.0

package/dist/lib/server/decisioning/account.mjs

@@ -1,4 +1,6 @@
 import { projectReportingDeliveryConfigStates } from "../reporting-delivery-config.mjs";
+import { isPre32AdcpVersion } from "../../utils/adcp-version-config.mjs";
+import { projectAccountResponseIdentityFields } from "../account-response-identity.mjs";
 const ACCOUNT_AUTHORIZATION_WIRE_KEYS = [
   "allowed_tasks",
   "field_scopes",
@@ -19,6 +21,30 @@ class AccountNotFoundError extends Error {
     super(message);
   }
 }
+const SYNC_ACCOUNT_PASSTHROUGH_KEYS = [
+  "account_id",
+  "brand",
+  "operator",
+  "revision",
+  "currency",
+  "timezone",
+  "name",
+  "action",
+  "status",
+  "billing",
+  "account_scope",
+  "setup",
+  "rate_card",
+  "payment_terms",
+  "credit_limit",
+  "errors",
+  "warnings",
+  "sandbox"
+];
+const SYNC_ACCOUNTS_RESULT_KEY_COVERAGE = {};
+void SYNC_ACCOUNTS_RESULT_KEY_COVERAGE;
+const SYNC_ACCOUNTS_PROJECTION_KEY_COVERAGE = {};
+void SYNC_ACCOUNTS_PROJECTION_KEY_COVERAGE;
 function toWireAccount(account) {
   const wire = {
     account_id: account.id,
@@ -75,23 +101,22 @@ function projectAccountAuthorization(authorization) {
   if (authorization.read_only !== void 0) projected.read_only = authorization.read_only;
   return projected;
 }
-function toWireSyncAccountRow(row) {
+function toWireSyncAccountRow(row, servedAdcpVersion) {
+  const modernAnchor = !isPre32AdcpVersion(servedAdcpVersion);
+  const identity = projectAccountResponseIdentityFields(modernAnchor ? row : { ...row, account: void 0 });
   const wire = {
-    brand: row.brand,
-    operator: row.operator,
     action: row.action,
-    status: row.status
+    ...identity
   };
-  if (row.account_id !== void 0) wire.account_id = row.account_id;
-  if (row.name !== void 0) wire.name = row.name;
-  if (row.billing !== void 0) wire.billing = row.billing;
+  const source = row;
+  function copyField(key) {
+    if (modernAnchor && identity.account !== void 0 && (key === "brand" || key === "operator")) return;
+    const value = source[key];
+    if (value !== void 0) wire[key] = value;
+  }
+  for (const key of SYNC_ACCOUNT_PASSTHROUGH_KEYS) copyField(key);
   const projectedEntity = projectBillingEntity(row.billing_entity);
   if (projectedEntity !== void 0) wire.billing_entity = projectedEntity;
-  if (row.account_scope !== void 0) wire.account_scope = row.account_scope;
-  if (row.setup !== void 0) wire.setup = row.setup;
-  if (row.rate_card !== void 0) wire.rate_card = row.rate_card;
-  if (row.payment_terms !== void 0) wire.payment_terms = row.payment_terms;
-  if (row.credit_limit !== void 0) wire.credit_limit = row.credit_limit;
   if (row.notification_configs !== void 0) {
     wire.notification_configs = row.notification_configs.map(projectNotificationConfig);
   }
@@ -103,9 +128,6 @@ function toWireSyncAccountRow(row) {
       row.authorization
     );
   }
-  if (row.errors !== void 0) wire.errors = row.errors;
-  if (row.warnings !== void 0) wire.warnings = row.warnings;
-  if (row.sandbox !== void 0) wire.sandbox = row.sandbox;
   return wire;
 }
 function projectNotificationConfig(config) {

package/dist/lib/server/decisioning/runtime/from-platform.d.mts

@@ -362,10 +362,10 @@ export interface CreateAdcpServerFromPlatformOptions<TAccount = unknown> extends
     ctxMetadata?: CtxMetadataStore;
     /**
      * Opinionated media-buy store that satisfies the seller spec contract for
-     * `targeting_overlay` echo: persist `packages[].targeting_overlay` from
-     * `create_media_buy`, echo it on `get_media_buys`, deep-merge across
-     * `update_media_buy` without dropping prior `property_list` /
-     * `collection_list` references.
+     * creation context and targeting echo: persist buy/package `context` and
+     * `packages[].targeting_overlay` from `create_media_buy`, then fill missing
+     * fields on `get_media_buys`. Targeting updates preserve creation context
+     * and prior `property_list` / `collection_list` references.
      *
      * Wire to honor the
      * `schemas/cache/<v>/media-buy/get-media-buys-response.json` contract
@@ -373,7 +373,7 @@ export interface CreateAdcpServerFromPlatformOptions<TAccount = unknown> extends
      * `property-lists` / `collection-lists` MUST echo the persisted refs;
      * `mediaBuyStore` is the framework-side way to do it.
      *
-     * Backed by any `AdcpStateStore` — `InMemoryStateStore` for dev,
+     * Backed by any `AdcpStateStore`: `InMemoryStateStore` for dev,
      * `PostgresStateStore` for production. Failures are logged and swallowed
      * (auto-echo MUST NOT break a successful seller response).
      *

package/dist/lib/server/decisioning/runtime/from-platform.d.ts

@@ -362,10 +362,10 @@ export interface CreateAdcpServerFromPlatformOptions<TAccount = unknown> extends
     ctxMetadata?: CtxMetadataStore;
     /**
      * Opinionated media-buy store that satisfies the seller spec contract for
-     * `targeting_overlay` echo: persist `packages[].targeting_overlay` from
-     * `create_media_buy`, echo it on `get_media_buys`, deep-merge across
-     * `update_media_buy` without dropping prior `property_list` /
-     * `collection_list` references.
+     * creation context and targeting echo: persist buy/package `context` and
+     * `packages[].targeting_overlay` from `create_media_buy`, then fill missing
+     * fields on `get_media_buys`. Targeting updates preserve creation context
+     * and prior `property_list` / `collection_list` references.
      *
      * Wire to honor the
      * `schemas/cache/<v>/media-buy/get-media-buys-response.json` contract
@@ -373,7 +373,7 @@ export interface CreateAdcpServerFromPlatformOptions<TAccount = unknown> extends
      * `property-lists` / `collection-lists` MUST echo the persisted refs;
      * `mediaBuyStore` is the framework-side way to do it.
      *
-     * Backed by any `AdcpStateStore` — `InMemoryStateStore` for dev,
+     * Backed by any `AdcpStateStore`: `InMemoryStateStore` for dev,
      * `PostgresStateStore` for production. Failures are logged and swallowed
      * (auto-echo MUST NOT break a successful seller response).
      *

package/dist/lib/server/decisioning/runtime/from-platform.js

@@ -3267,7 +3267,7 @@ async function autoStoreResources(store, accountId, kind, resources, idField, lo
     );
   }
 }
-async function persistTargetingOverlayFromCreate(store, accountId, request, result, logger) {
+async function persistMediaBuyFromCreate(store, accountId, request, result, logger) {
   if (!store || !accountId) return;
   if (result == null || typeof result !== "object") return;
   try {
@@ -3290,7 +3290,7 @@ async function persistTargetingOverlayFromUpdate(store, accountId, mediaBuyId, p
     logger.warn(`[adcp/decisioning] mediaBuyStore.mergeFromUpdate failed: ${msg}`);
   }
 }
-async function backfillTargetingOverlay(store, accountId, result, logger) {
+async function backfillMediaBuyState(store, accountId, result, logger) {
   if (!store || !accountId) return;
   if (result == null || typeof result !== "object") return;
   try {
@@ -4064,7 +4064,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
               },
               result,
               async (r) => {
-                await persistTargetingOverlayFromCreate(mediaBuyStore, reqCtx.account?.id, params, r, logger);
+                await persistMediaBuyFromCreate(mediaBuyStore, reqCtx.account?.id, params, r, logger);
                 return asSemanticServerResponseForWire(
                   r,
                   "create_media_buy",
@@ -4352,7 +4352,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
               canonicalFormatLegacyResolver,
               responseWireMode
             );
-            await backfillTargetingOverlay(mediaBuyStore, reqCtx.account?.id, wireResult, logger);
+            await backfillMediaBuyState(mediaBuyStore, reqCtx.account?.id, wireResult, logger);
             return wireResult;
           },
           (r) => r
@@ -5494,7 +5494,7 @@ function buildAccountHandlers(platform, ctxFor, logger = DEFAULT_FRAMEWORK_LOGGE
           if (policy.failedRows.size === 0) {
             return {
               ...dryRun && { dry_run: true },
-              accounts: rows.map(import_account.toWireSyncAccountRow)
+              accounts: rows.map((row) => (0, import_account.toWireSyncAccountRow)(row, resolveCtx.servedAdcpVersion))
             };
           }
           const combined = [];
@@ -5510,7 +5510,7 @@ function buildAccountHandlers(platform, ctxFor, logger = DEFAULT_FRAMEWORK_LOGGE
           }
           return {
             ...dryRun && { dry_run: true },
-            accounts: combined.map(import_account.toWireSyncAccountRow)
+            accounts: combined.map((row) => (0, import_account.toWireSyncAccountRow)(row, resolveCtx.servedAdcpVersion))
           };
         }
       );

package/dist/lib/server/decisioning/runtime/from-platform.mjs

@@ -3299,7 +3299,7 @@ async function autoStoreResources(store, accountId, kind, resources, idField, lo
     );
   }
 }
-async function persistTargetingOverlayFromCreate(store, accountId, request, result, logger) {
+async function persistMediaBuyFromCreate(store, accountId, request, result, logger) {
   if (!store || !accountId) return;
   if (result == null || typeof result !== "object") return;
   try {
@@ -3322,7 +3322,7 @@ async function persistTargetingOverlayFromUpdate(store, accountId, mediaBuyId, p
     logger.warn(`[adcp/decisioning] mediaBuyStore.mergeFromUpdate failed: ${msg}`);
   }
 }
-async function backfillTargetingOverlay(store, accountId, result, logger) {
+async function backfillMediaBuyState(store, accountId, result, logger) {
   if (!store || !accountId) return;
   if (result == null || typeof result !== "object") return;
   try {
@@ -4096,7 +4096,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
               },
               result,
               async (r) => {
-                await persistTargetingOverlayFromCreate(mediaBuyStore, reqCtx.account?.id, params, r, logger);
+                await persistMediaBuyFromCreate(mediaBuyStore, reqCtx.account?.id, params, r, logger);
                 return asSemanticServerResponseForWire(
                   r,
                   "create_media_buy",
@@ -4384,7 +4384,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
               canonicalFormatLegacyResolver,
               responseWireMode
             );
-            await backfillTargetingOverlay(mediaBuyStore, reqCtx.account?.id, wireResult, logger);
+            await backfillMediaBuyState(mediaBuyStore, reqCtx.account?.id, wireResult, logger);
             return wireResult;
           },
           (r) => r
@@ -5526,7 +5526,7 @@ function buildAccountHandlers(platform, ctxFor, logger = DEFAULT_FRAMEWORK_LOGGE
           if (policy.failedRows.size === 0) {
             return {
               ...dryRun && { dry_run: true },
-              accounts: rows.map(toWireSyncAccountRow)
+              accounts: rows.map((row) => toWireSyncAccountRow(row, resolveCtx.servedAdcpVersion))
             };
           }
           const combined = [];
@@ -5542,7 +5542,7 @@ function buildAccountHandlers(platform, ctxFor, logger = DEFAULT_FRAMEWORK_LOGGE
           }
           return {
             ...dryRun && { dry_run: true },
-            accounts: combined.map(toWireSyncAccountRow)
+            accounts: combined.map((row) => toWireSyncAccountRow(row, resolveCtx.servedAdcpVersion))
           };
         }
       );

package/dist/lib/server/index.d.mts

@@ -32,7 +32,7 @@ export { applyTargetingInput, hasTargetingClears, resolveTargetingInput } from '
 export type { ResolvedTargetingInput, TargetingInputFor } from '../media-buy/targeting-input.mjs';
 export type { CreateTargetingInput, UpdateTargetingInput } from '../types/index.mjs';
 export type { MediaBuyStore, CreateMediaBuyStoreOptions, CreateMediaBuyInputForStore, CreateMediaBuyResultForStore, UpdateMediaBuyInputForStore, GetMediaBuysResultForStore, } from './media-buy-store.mjs';
-export { MEDIA_BUY_TRANSITIONS, CREATIVE_ASSET_TRANSITIONS, isLegalMediaBuyTransition, isLegalCreativeTransition, assertMediaBuyTransition, assertCreativeTransition, } from './state-machine.mjs';
+export { MEDIA_BUY_TRANSITIONS, getMediaBuyTransitions, CREATIVE_ASSET_TRANSITIONS, isLegalMediaBuyTransition, isLegalCreativeTransition, assertMediaBuyTransition, assertCreativeTransition, } from './state-machine.mjs';
 export { getAccountMode, isSandboxOrMockAccount, assertSandboxAccount } from './account-mode.mjs';
 export type { AccountMode } from './account-mode.mjs';
 export { taskToolResponse, registerAdcpTaskTool, createTaskCapableServer, InMemoryTaskStore, isTerminal, } from './tasks.mjs';

package/dist/lib/server/index.d.ts

@@ -32,7 +32,7 @@ export { applyTargetingInput, hasTargetingClears, resolveTargetingInput } from '
 export type { ResolvedTargetingInput, TargetingInputFor } from '../media-buy/targeting-input';
 export type { CreateTargetingInput, UpdateTargetingInput } from '../types';
 export type { MediaBuyStore, CreateMediaBuyStoreOptions, CreateMediaBuyInputForStore, CreateMediaBuyResultForStore, UpdateMediaBuyInputForStore, GetMediaBuysResultForStore, } from './media-buy-store';
-export { MEDIA_BUY_TRANSITIONS, CREATIVE_ASSET_TRANSITIONS, isLegalMediaBuyTransition, isLegalCreativeTransition, assertMediaBuyTransition, assertCreativeTransition, } from './state-machine';
+export { MEDIA_BUY_TRANSITIONS, getMediaBuyTransitions, CREATIVE_ASSET_TRANSITIONS, isLegalMediaBuyTransition, isLegalCreativeTransition, assertMediaBuyTransition, assertCreativeTransition, } from './state-machine';
 export { getAccountMode, isSandboxOrMockAccount, assertSandboxAccount } from './account-mode';
 export type { AccountMode } from './account-mode';
 export { taskToolResponse, registerAdcpTaskTool, createTaskCapableServer, InMemoryTaskStore, isTerminal, } from './tasks';

package/dist/lib/server/index.js

@@ -157,6 +157,7 @@ __export(server_exports, {
   getIdempotencyMigration: () => import_idempotency.getIdempotencyMigration,
   getKeyedAccountMigration: () => import_keyed_account_backend.getKeyedAccountMigration,
   getMcpTasksMigration: () => import_postgres_task_store.getMcpTasksMigration,
+  getMediaBuyTransitions: () => import_state_machine.getMediaBuyTransitions,
   getNotificationSubscriptionMigration: () => import_notification_subscriptions.getNotificationSubscriptionMigration,
   getServeRequestContext: () => import_auth.getServeRequestContext,
   getWebhookDeliveryMigration: () => import_webhook_delivery.getWebhookDeliveryMigration,
@@ -498,6 +499,7 @@ var import_property_lists = require('./property-lists.js');
   getIdempotencyMigration,
   getKeyedAccountMigration,
   getMcpTasksMigration,
+  getMediaBuyTransitions,
   getNotificationSubscriptionMigration,
   getServeRequestContext,
   getWebhookDeliveryMigration,

package/dist/lib/server/index.mjs

@@ -59,6 +59,7 @@ import { createMediaBuyStore, DEFAULT_MEDIA_BUY_STORE_COLLECTION } from "./media
 import { applyTargetingInput, hasTargetingClears, resolveTargetingInput } from "../media-buy/targeting-input.mjs";
 import {
   MEDIA_BUY_TRANSITIONS,
+  getMediaBuyTransitions,
   CREATIVE_ASSET_TRANSITIONS,
   isLegalMediaBuyTransition,
   isLegalCreativeTransition,
@@ -444,6 +445,7 @@ export {
   getIdempotencyMigration,
   getKeyedAccountMigration,
   getMcpTasksMigration,
+  getMediaBuyTransitions,
   getNotificationSubscriptionMigration,
   getServeRequestContext,
   getWebhookDeliveryMigration,

package/dist/lib/server/media-buy-action-resolver.d.mts

@@ -32,6 +32,9 @@ export interface SellerActionResolutionOptions {
     /** Noncommercial metadata authority is explicit, never fabricated as a proposal term. */
     metadata?: {
         update_name?: SellerActionDecision;
+        /** Seller-owned scope identifies packages which have never been enabled
+         * for serving. Aggregate buy status cannot establish that fact. */
+        update_creative_start_policy?: SellerActionDecision;
     };
     now?: number;
 }

package/dist/lib/server/media-buy-action-resolver.d.ts

@@ -32,6 +32,9 @@ export interface SellerActionResolutionOptions {
     /** Noncommercial metadata authority is explicit, never fabricated as a proposal term. */
     metadata?: {
         update_name?: SellerActionDecision;
+        /** Seller-owned scope identifies packages which have never been enabled
+         * for serving. Aggregate buy status cannot establish that fact. */
+        update_creative_start_policy?: SellerActionDecision;
     };
     now?: number;
 }

package/dist/lib/server/media-buy-action-resolver.js

@@ -246,6 +246,38 @@ const mediaBuyActionResolver = {
           }
         );
     }
+    const startup = input.metadata?.update_creative_start_policy;
+    if (startup) {
+      const scope = Array.isArray(startup.applicable_package_ids) ? startup.applicable_package_ids : void 0;
+      const entry = {
+        action: "update_creative_start_policy",
+        mode: "self_serve",
+        task: startup.task ?? "control_media_buy",
+        ...scope && { applicable_package_ids: [...scope] },
+        ...startup.sla && { sla: structuredClone(startup.sla) }
+      };
+      const request = scope ? { packages: scope.map((package_id) => ({ package_id, start_requires_all_creatives_approved: false })) } : void 0;
+      const result = (0, import_action_assessment.assessActionAvailability)(
+        { ...input.buy, available_actions: [entry] },
+        entry.action,
+        {
+          adcpVersion: input.adcpVersion ?? import_version.ADCP_VERSION,
+          request
+        }
+      );
+      if (input.wireVersion !== "3.1" && startup.authorization === true && startup.governance === true && startup.policy === true && result.status === "available_now")
+        available_actions.push(entry);
+      else
+        unavailable.push(
+          result.status === "currently_unavailable" ? result : {
+            status: "currently_unavailable",
+            action: "update_creative_start_policy",
+            reason: "condition_unresolved",
+            certainty: "unknown",
+            message: "Explicit seller startup gates and a supported wire projection must admit this action."
+          }
+        );
+    }
     return {
       available_actions,
       unavailable,

package/dist/lib/server/media-buy-action-resolver.mjs

@@ -235,6 +235,38 @@ const mediaBuyActionResolver = {
           }
         );
     }
+    const startup = input.metadata?.update_creative_start_policy;
+    if (startup) {
+      const scope = Array.isArray(startup.applicable_package_ids) ? startup.applicable_package_ids : void 0;
+      const entry = {
+        action: "update_creative_start_policy",
+        mode: "self_serve",
+        task: startup.task ?? "control_media_buy",
+        ...scope && { applicable_package_ids: [...scope] },
+        ...startup.sla && { sla: structuredClone(startup.sla) }
+      };
+      const request = scope ? { packages: scope.map((package_id) => ({ package_id, start_requires_all_creatives_approved: false })) } : void 0;
+      const result = assessActionAvailability(
+        { ...input.buy, available_actions: [entry] },
+        entry.action,
+        {
+          adcpVersion: input.adcpVersion ?? ADCP_VERSION,
+          request
+        }
+      );
+      if (input.wireVersion !== "3.1" && startup.authorization === true && startup.governance === true && startup.policy === true && result.status === "available_now")
+        available_actions.push(entry);
+      else
+        unavailable.push(
+          result.status === "currently_unavailable" ? result : {
+            status: "currently_unavailable",
+            action: "update_creative_start_policy",
+            reason: "condition_unresolved",
+            certainty: "unknown",
+            message: "Explicit seller startup gates and a supported wire projection must admit this action."
+          }
+        );
+    }
     return {
       available_actions,
       unavailable,

package/dist/lib/server/media-buy-store.d.mts

@@ -1,7 +1,8 @@
 /**
  * Opinionated media-buy store that satisfies the seller's spec contract:
- * persist `packages[].targeting_overlay` from `create_media_buy`, echo it on
- * `get_media_buys`, and deep-merge updates without dropping prior
+ * persist creation context and `packages[].targeting_overlay` from
+ * `create_media_buy`, echo them on `get_media_buys`, and merge targeting
+ * updates without dropping creation context or prior
  * `property_list` / `collection_list` references.
  *
  * Per `schemas/cache/<v>/media-buy/get-media-buys-response.json` the seller
@@ -12,7 +13,7 @@
  * by hand.
  *
  * Adopters opt in by passing `mediaBuyStore` to
- * `createAdcpServerFromPlatform`. Backed by any `AdcpStateStore` —
+ * `createAdcpServerFromPlatform`. Backed by any `AdcpStateStore`:
  * `InMemoryStateStore` for development, `PostgresStateStore` for
  * production.
  *
@@ -41,9 +42,13 @@ export declare const DEFAULT_MEDIA_BUY_STORE_COLLECTION = "media_buys_targeting"
  * request to the full generated type just to thread it through.
  */
 export interface CreateMediaBuyInputForStore {
+    /** Opaque creation context, persisted verbatim for resource readback. */
+    context?: Record<string, unknown>;
     packages?: Array<{
         package_id?: string;
         buyer_ref?: string;
+        product_id?: string;
+        context?: Record<string, unknown>;
         /**
          * Request-shaped Targeting Input: individual dimensions may be `null` to
          * suppress a configured-product or product default (AdCP 3.2, DR-0020).
@@ -58,9 +63,12 @@ export interface CreateMediaBuyInputForStore {
  */
 export interface CreateMediaBuyResultForStore {
     media_buy_id: string;
+    context?: Record<string, unknown>;
     packages?: Array<{
         package_id?: string;
         buyer_ref?: string;
+        product_id?: string;
+        context?: Record<string, unknown>;
         targeting_overlay?: TargetingOverlay;
     }>;
 }
@@ -89,18 +97,23 @@ export interface UpdateMediaBuyInputForStore {
 export interface GetMediaBuysResultForStore {
     media_buys?: Array<{
         media_buy_id?: string;
+        context?: Record<string, unknown>;
         packages?: Array<{
             package_id?: string;
+            context?: Record<string, unknown>;
             targeting_overlay?: TargetingOverlay;
         }>;
     }>;
 }
 export interface MediaBuyStore {
     /**
-     * Persist `packages[].targeting_overlay` from a successful
-     * `create_media_buy`. Joins the request's per-package targeting
+     * Persist buy/package creation context and `packages[].targeting_overlay`
+     * from a successful `create_media_buy`. Joins the request's per-package targeting
      * overlay with the response's seller-assigned `package_id` (or
-     * `buyer_ref` when the request used buyer-supplied refs).
+     * `buyer_ref` when the request used buyer-supplied refs). Context uses
+     * unambiguous package identities, then positional alignment only when
+     * package counts agree and echoed identities do not contradict it.
+     * Existing creation context is retained on repeated persistence calls.
      */
     persistFromCreate(accountId: string, request: CreateMediaBuyInputForStore, result: CreateMediaBuyResultForStore): Promise<void>;
     /**
@@ -112,21 +125,22 @@ export interface MediaBuyStore {
      * - field present and `null` → clear (drop the field)
      *
      * A patch that clears the last surviving dimension drops the package's
-     * tracked overlay entirely, so `backfill` stops echoing one — a cleared
+     * tracked overlay entirely, so `backfill` stops echoing one. A cleared
      * dimension is absent from effective readback rather than present as `null`.
      *
      * `new_packages` from the patch are persisted as fresh entries when
      * they declare `targeting_overlay`. Entries that omit it are
-     * intentionally NOT tracked — this store is overlay-only, and a
-     * later patch can still seed an overlay onto the package_id when
-     * one becomes relevant.
+     * not tracked. Updates preserve creation context and do not capture
+     * context for packages added after creation.
      */
     mergeFromUpdate(accountId: string, mediaBuyId: string, patch: UpdateMediaBuyInputForStore): Promise<void>;
     /**
-     * Fill in missing `packages[].targeting_overlay` on the seller's
+     * Fill in missing buy/package creation context and
+     * `packages[].targeting_overlay` on the seller's
      * `get_media_buys` response from the persisted store. **Mutates the
      * response in place** (and returns it for fluent chaining). Packages
-     * the seller already echoed are left untouched.
+     * the seller already echoed are left untouched. The top-level response
+     * context belongs to the read request and is never changed.
      */
     backfill<T extends GetMediaBuysResultForStore>(accountId: string, result: T): Promise<T>;
 }

package/dist/lib/server/media-buy-store.d.ts

@@ -1,7 +1,8 @@
 /**
  * Opinionated media-buy store that satisfies the seller's spec contract:
- * persist `packages[].targeting_overlay` from `create_media_buy`, echo it on
- * `get_media_buys`, and deep-merge updates without dropping prior
+ * persist creation context and `packages[].targeting_overlay` from
+ * `create_media_buy`, echo them on `get_media_buys`, and merge targeting
+ * updates without dropping creation context or prior
  * `property_list` / `collection_list` references.
  *
  * Per `schemas/cache/<v>/media-buy/get-media-buys-response.json` the seller
@@ -12,7 +13,7 @@
  * by hand.
  *
  * Adopters opt in by passing `mediaBuyStore` to
- * `createAdcpServerFromPlatform`. Backed by any `AdcpStateStore` —
+ * `createAdcpServerFromPlatform`. Backed by any `AdcpStateStore`:
  * `InMemoryStateStore` for development, `PostgresStateStore` for
  * production.
  *
@@ -41,9 +42,13 @@ export declare const DEFAULT_MEDIA_BUY_STORE_COLLECTION = "media_buys_targeting"
  * request to the full generated type just to thread it through.
  */
 export interface CreateMediaBuyInputForStore {
+    /** Opaque creation context, persisted verbatim for resource readback. */
+    context?: Record<string, unknown>;
     packages?: Array<{
         package_id?: string;
         buyer_ref?: string;
+        product_id?: string;
+        context?: Record<string, unknown>;
         /**
          * Request-shaped Targeting Input: individual dimensions may be `null` to
          * suppress a configured-product or product default (AdCP 3.2, DR-0020).
@@ -58,9 +63,12 @@ export interface CreateMediaBuyInputForStore {
  */
 export interface CreateMediaBuyResultForStore {
     media_buy_id: string;
+    context?: Record<string, unknown>;
     packages?: Array<{
         package_id?: string;
         buyer_ref?: string;
+        product_id?: string;
+        context?: Record<string, unknown>;
         targeting_overlay?: TargetingOverlay;
     }>;
 }
@@ -89,18 +97,23 @@ export interface UpdateMediaBuyInputForStore {
 export interface GetMediaBuysResultForStore {
     media_buys?: Array<{
         media_buy_id?: string;
+        context?: Record<string, unknown>;
         packages?: Array<{
             package_id?: string;
+            context?: Record<string, unknown>;
             targeting_overlay?: TargetingOverlay;
         }>;
     }>;
 }
 export interface MediaBuyStore {
     /**
-     * Persist `packages[].targeting_overlay` from a successful
-     * `create_media_buy`. Joins the request's per-package targeting
+     * Persist buy/package creation context and `packages[].targeting_overlay`
+     * from a successful `create_media_buy`. Joins the request's per-package targeting
      * overlay with the response's seller-assigned `package_id` (or
-     * `buyer_ref` when the request used buyer-supplied refs).
+     * `buyer_ref` when the request used buyer-supplied refs). Context uses
+     * unambiguous package identities, then positional alignment only when
+     * package counts agree and echoed identities do not contradict it.
+     * Existing creation context is retained on repeated persistence calls.
      */
     persistFromCreate(accountId: string, request: CreateMediaBuyInputForStore, result: CreateMediaBuyResultForStore): Promise<void>;
     /**
@@ -112,21 +125,22 @@ export interface MediaBuyStore {
      * - field present and `null` → clear (drop the field)
      *
      * A patch that clears the last surviving dimension drops the package's
-     * tracked overlay entirely, so `backfill` stops echoing one — a cleared
+     * tracked overlay entirely, so `backfill` stops echoing one. A cleared
      * dimension is absent from effective readback rather than present as `null`.
      *
      * `new_packages` from the patch are persisted as fresh entries when
      * they declare `targeting_overlay`. Entries that omit it are
-     * intentionally NOT tracked — this store is overlay-only, and a
-     * later patch can still seed an overlay onto the package_id when
-     * one becomes relevant.
+     * not tracked. Updates preserve creation context and do not capture
+     * context for packages added after creation.
      */
     mergeFromUpdate(accountId: string, mediaBuyId: string, patch: UpdateMediaBuyInputForStore): Promise<void>;
     /**
-     * Fill in missing `packages[].targeting_overlay` on the seller's
+     * Fill in missing buy/package creation context and
+     * `packages[].targeting_overlay` on the seller's
      * `get_media_buys` response from the persisted store. **Mutates the
      * response in place** (and returns it for fluent chaining). Packages
-     * the seller already echoed are left untouched.
+     * the seller already echoed are left untouched. The top-level response
+     * context belongs to the read request and is never changed.
      */
     backfill<T extends GetMediaBuysResultForStore>(accountId: string, result: T): Promise<T>;
 }