@adcp/sdk 17.0.0-beta.1 → 17.0.0-beta.3

package/dist/lib/server/decisioning/account.d.mts

@@ -633,11 +633,10 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * already run, and note the framework performs no such check for
      * `'explicit'` / `'implicit'`, where the entry key is buyer-declared.
      *
-     * **Rows must carry `brand` + `operator`** (`sync-accounts-response.json`
-     * requires them on every row, including `action: 'failed'`). Echo them from
-     * your own account record on settings-update results. If your upstream
-     * accounts have no expressible natural key, don't wire this method — see
-     * adcontextprotocol/adcp#7517.
+     * **Echo the selected release's identity anchor.** AdCP 3.2+ settings-update
+     * rows carry `account` instead of flat `brand` + `operator`; provisioning
+     * rows carry the natural key. Older releases require `brand` + `operator`
+     * on every row. Failed 3.2+ rows may omit an unknown lifecycle `status`.
      *
      * In AdCP 3.1 beta, adopters that need settings-update entries with
      * `notification_configs[]` can read the full wire body from `ctx.input`
@@ -890,18 +889,26 @@ export type AccountFilter = ListAccountsRequest;
  * returned rows — same MUST-NOT-LEAK rule the framework enforces on
  * `Account.authInfo`.
  */
-export interface SyncAccountsResultRow {
+interface SyncAccountsResultFields {
     account_id?: string;
-    brand: BrandReference;
-    operator: string;
+    /** Current canonical operator unit, distinct from the seller account ID. */
+    operator_unit?: SyncAccountsRow['operator_unit'];
+    /** Current persisted account revision, including during a dry-run preview. */
+    revision?: SyncAccountsRow['revision'];
+    /** Pending or rejected desired identity; canonical fields remain unchanged. */
+    identity_change?: SyncAccountsRow['identity_change'];
+    /** Non-persisted evaluation of an identity change requested in a dry run. */
+    identity_change_preview?: SyncAccountsRow['identity_change_preview'];
+    currency?: SyncAccountsRow['currency'];
+    timezone?: SyncAccountsRow['timezone'];
     /** Human-readable account name assigned by the seller. */
     name?: string;
-    action: 'created' | 'updated' | 'unchanged' | 'failed';
-    status: AdcpAccountStatus;
     /** Invoiced-to party. Echoes the request's `billing` after seller acceptance. */
     billing?: BillingParty;
     /** Business entity invoiced. `bank` is stripped on emit (write-only). */
     billing_entity?: BusinessEntity;
+    /** Request-only staging data. The entire field MUST NOT appear in responses. */
+    destination_billing_entity?: never;
     account_scope?: AccountScope;
     /** Setup payload for `pending_approval` accounts (URL/message/expiry). */
     setup?: WireAccount['setup'];
@@ -926,6 +933,25 @@ export interface SyncAccountsResultRow {
     warnings?: string[];
     sandbox?: boolean;
 }
+/**
+ * Provisioning results use the natural key; 3.2+ settings-update results use
+ * account instead. Only failed results can omit an unknown lifecycle status.
+ */
+export type SyncAccountsResultRow = SyncAccountsResultFields & ({
+    account: NonNullable<SyncAccountsRow['account']>;
+    brand?: never;
+    operator?: never;
+} | {
+    account?: never;
+    brand: BrandReference;
+    operator: string;
+}) & ({
+    action: 'failed';
+    status?: AdcpAccountStatus;
+} | {
+    action: 'created' | 'updated' | 'unchanged';
+    status: AdcpAccountStatus;
+});
 export type AdcpAccountStatus = 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
 /**
  * Project a framework `Account<TCtxMeta>` to the wire `Account` shape.

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

@@ -633,11 +633,10 @@ export interface AccountStore<TCtxMeta = Record<string, unknown>> {
      * already run, and note the framework performs no such check for
      * `'explicit'` / `'implicit'`, where the entry key is buyer-declared.
      *
-     * **Rows must carry `brand` + `operator`** (`sync-accounts-response.json`
-     * requires them on every row, including `action: 'failed'`). Echo them from
-     * your own account record on settings-update results. If your upstream
-     * accounts have no expressible natural key, don't wire this method — see
-     * adcontextprotocol/adcp#7517.
+     * **Echo the selected release's identity anchor.** AdCP 3.2+ settings-update
+     * rows carry `account` instead of flat `brand` + `operator`; provisioning
+     * rows carry the natural key. Older releases require `brand` + `operator`
+     * on every row. Failed 3.2+ rows may omit an unknown lifecycle `status`.
      *
      * In AdCP 3.1 beta, adopters that need settings-update entries with
      * `notification_configs[]` can read the full wire body from `ctx.input`
@@ -890,18 +889,26 @@ export type AccountFilter = ListAccountsRequest;
  * returned rows — same MUST-NOT-LEAK rule the framework enforces on
  * `Account.authInfo`.
  */
-export interface SyncAccountsResultRow {
+interface SyncAccountsResultFields {
     account_id?: string;
-    brand: BrandReference;
-    operator: string;
+    /** Current canonical operator unit, distinct from the seller account ID. */
+    operator_unit?: SyncAccountsRow['operator_unit'];
+    /** Current persisted account revision, including during a dry-run preview. */
+    revision?: SyncAccountsRow['revision'];
+    /** Pending or rejected desired identity; canonical fields remain unchanged. */
+    identity_change?: SyncAccountsRow['identity_change'];
+    /** Non-persisted evaluation of an identity change requested in a dry run. */
+    identity_change_preview?: SyncAccountsRow['identity_change_preview'];
+    currency?: SyncAccountsRow['currency'];
+    timezone?: SyncAccountsRow['timezone'];
     /** Human-readable account name assigned by the seller. */
     name?: string;
-    action: 'created' | 'updated' | 'unchanged' | 'failed';
-    status: AdcpAccountStatus;
     /** Invoiced-to party. Echoes the request's `billing` after seller acceptance. */
     billing?: BillingParty;
     /** Business entity invoiced. `bank` is stripped on emit (write-only). */
     billing_entity?: BusinessEntity;
+    /** Request-only staging data. The entire field MUST NOT appear in responses. */
+    destination_billing_entity?: never;
     account_scope?: AccountScope;
     /** Setup payload for `pending_approval` accounts (URL/message/expiry). */
     setup?: WireAccount['setup'];
@@ -926,6 +933,25 @@ export interface SyncAccountsResultRow {
     warnings?: string[];
     sandbox?: boolean;
 }
+/**
+ * Provisioning results use the natural key; 3.2+ settings-update results use
+ * account instead. Only failed results can omit an unknown lifecycle status.
+ */
+export type SyncAccountsResultRow = SyncAccountsResultFields & ({
+    account: NonNullable<SyncAccountsRow['account']>;
+    brand?: never;
+    operator?: never;
+} | {
+    account?: never;
+    brand: BrandReference;
+    operator: string;
+}) & ({
+    action: 'failed';
+    status?: AdcpAccountStatus;
+} | {
+    action: 'created' | 'updated' | 'unchanged';
+    status: AdcpAccountStatus;
+});
 export type AdcpAccountStatus = 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
 /**
  * Project a framework `Account<TCtxMeta>` to the wire `Account` shape.

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

@@ -30,6 +30,7 @@ __export(account_exports, {
 });
 module.exports = __toCommonJS(account_exports);
 var import_reporting_delivery_config = require('../reporting-delivery-config.js');
+var import_account_response_identity = require('../account-response-identity.js');
 const ACCOUNT_AUTHORIZATION_WIRE_KEYS = [
   "allowed_tasks",
   "field_scopes",
@@ -50,6 +51,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,
@@ -107,22 +132,19 @@ function projectAccountAuthorization(authorization) {
   return projected;
 }
 function toWireSyncAccountRow(row) {
+  const identity = (0, import_account_response_identity.projectAccountResponseIdentityFields)(row);
   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) {
+    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);
   }
@@ -134,9 +156,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/account.mjs

@@ -1,4 +1,5 @@
 import { projectReportingDeliveryConfigStates } from "../reporting-delivery-config.mjs";
+import { projectAccountResponseIdentityFields } from "../account-response-identity.mjs";
 const ACCOUNT_AUTHORIZATION_WIRE_KEYS = [
   "allowed_tasks",
   "field_scopes",
@@ -19,6 +20,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,
@@ -76,22 +101,19 @@ function projectAccountAuthorization(authorization) {
   return projected;
 }
 function toWireSyncAccountRow(row) {
+  const identity = projectAccountResponseIdentityFields(row);
   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) {
+    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 +125,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

@@ -3270,7 +3270,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 {
@@ -3293,7 +3293,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 {
@@ -4081,7 +4081,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",
@@ -4369,7 +4369,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

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

@@ -3302,7 +3302,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 {
@@ -3325,7 +3325,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 {
@@ -4113,7 +4113,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",
@@ -4401,7 +4401,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

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>;
 }