@adcp/sdk 15.8.1 → 15.9.0

package/dist/lib/core/account-resolution.d.mts

@@ -3,6 +3,12 @@ export type ListedAccount = ListAccountsResponse['accounts'][number];
 type NaturalAccountReference = Extract<AccountReference, {
     brand: unknown;
 }>;
+/** Account selection plus the seller handle, even when a legacy seller still needs the natural key. */
+export interface ResolveAccountResult {
+    reference: AccountReference;
+    account_id?: string;
+    naturalKey?: NaturalAccountReference;
+}
 export declare function sameCountrySet(expected?: readonly string[], actual?: readonly string[]): boolean;
 /** Hints for resolving a seller account against the caller's own credentials. */
 export interface ResolveAccountOptions {

package/dist/lib/core/account-resolution.d.ts

@@ -3,6 +3,12 @@ export type ListedAccount = ListAccountsResponse['accounts'][number];
 type NaturalAccountReference = Extract<AccountReference, {
     brand: unknown;
 }>;
+/** Account selection plus the seller handle, even when a legacy seller still needs the natural key. */
+export interface ResolveAccountResult {
+    reference: AccountReference;
+    account_id?: string;
+    naturalKey?: NaturalAccountReference;
+}
 export declare function sameCountrySet(expected?: readonly string[], actual?: readonly string[]): boolean;
 /** Hints for resolving a seller account against the caller's own credentials. */
 export interface ResolveAccountOptions {

package/dist/lib/core/buyer-account-registry.d.mts

@@ -29,6 +29,8 @@ export interface ProvisionedAccount {
 export interface BuyerAccountStorage {
     get(key: string): Promise<ProvisionedAccount | undefined>;
     set(key: string, account: ProvisionedAccount): Promise<void>;
+    /** Read the ID alias within this exact seller/caller scope, equivalent to get(scope + ':' + accountReferenceKey({ account_id })). */
+    getByAccountId?(accountId: string, scope: string): Promise<ProvisionedAccount | undefined>;
     /** Atomically insert (undefined revision) or replace. Store the supplied new revision. Required for multi-process safety. */
     compareAndSet?(key: string, expectedRevision: number | undefined, account: ProvisionedAccount): Promise<boolean>;
 }
@@ -68,6 +70,7 @@ export declare class BuyerAccountRegistry {
     private observationFloor;
     private statusEpochs;
     private readonly maxEntries;
+    private provisioningAccessed;
     private readonly normalizeOptions?;
     constructor(scope: () => string, provision: (key: AccountReference, options: EnsureAccountOptions, taskOptions?: TaskOptions, dispatch?: BuyerAccountProvisioningDispatch) => Promise<TaskResult<SyncAccountsResponse>>, storage?: BuyerAccountStorage | undefined, repair?: ((accountId: string, taskOptions?: TaskOptions) => Promise<readonly unknown[]>) | undefined, registryOptions?: BuyerAccountRegistryOptions);
     private key;
@@ -75,7 +78,10 @@ export declare class BuyerAccountRegistry {
     captureObservation(): number;
     private observationIsCurrent;
     private remember;
+    private canEvict;
     get(account: AccountReference): Promise<ProvisionedAccount | undefined>;
+    /** Lookup by seller-issued ID, partitioned by the registry's seller and caller. */
+    getByAccountId(accountId: string): Promise<ProvisionedAccount | undefined>;
     ensure(account: AccountReference, options?: EnsureAccountOptions, taskOptions?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<ProvisionedAccount>;
     private write;
     private record;

package/dist/lib/core/buyer-account-registry.d.ts

@@ -29,6 +29,8 @@ export interface ProvisionedAccount {
 export interface BuyerAccountStorage {
     get(key: string): Promise<ProvisionedAccount | undefined>;
     set(key: string, account: ProvisionedAccount): Promise<void>;
+    /** Read the ID alias within this exact seller/caller scope, equivalent to get(scope + ':' + accountReferenceKey({ account_id })). */
+    getByAccountId?(accountId: string, scope: string): Promise<ProvisionedAccount | undefined>;
     /** Atomically insert (undefined revision) or replace. Store the supplied new revision. Required for multi-process safety. */
     compareAndSet?(key: string, expectedRevision: number | undefined, account: ProvisionedAccount): Promise<boolean>;
 }
@@ -68,6 +70,7 @@ export declare class BuyerAccountRegistry {
     private observationFloor;
     private statusEpochs;
     private readonly maxEntries;
+    private provisioningAccessed;
     private readonly normalizeOptions?;
     constructor(scope: () => string, provision: (key: AccountReference, options: EnsureAccountOptions, taskOptions?: TaskOptions, dispatch?: BuyerAccountProvisioningDispatch) => Promise<TaskResult<SyncAccountsResponse>>, storage?: BuyerAccountStorage | undefined, repair?: ((accountId: string, taskOptions?: TaskOptions) => Promise<readonly unknown[]>) | undefined, registryOptions?: BuyerAccountRegistryOptions);
     private key;
@@ -75,7 +78,10 @@ export declare class BuyerAccountRegistry {
     captureObservation(): number;
     private observationIsCurrent;
     private remember;
+    private canEvict;
     get(account: AccountReference): Promise<ProvisionedAccount | undefined>;
+    /** Lookup by seller-issued ID, partitioned by the registry's seller and caller. */
+    getByAccountId(accountId: string): Promise<ProvisionedAccount | undefined>;
     ensure(account: AccountReference, options?: EnsureAccountOptions, taskOptions?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<ProvisionedAccount>;
     private write;
     private record;

package/dist/lib/core/buyer-account-registry.js

@@ -72,6 +72,7 @@ class BuyerAccountRegistry {
   observationFloor = 0;
   statusEpochs = /* @__PURE__ */ new Map();
   maxEntries;
+  provisioningAccessed = false;
   normalizeOptions;
   key(account, scope = this.scope()) {
     return `${scope}:${(0, import_account_key.accountReferenceKey)(account)}`;
@@ -85,21 +86,30 @@ class BuyerAccountRegistry {
   }
   remember(key, entry) {
     if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
-      if (!this.storage)
+      if (!this.storage && !this.canEvict())
         throw new import_errors.AccountSetupRequiredError(
           "Account registry capacity reached; configure durable storage or increase maxEntries."
         );
       this.entries.delete(this.entries.keys().next().value);
     }
+    this.entries.delete(key);
     this.entries.set(key, structuredClone(entry));
   }
+  canEvict() {
+    return !this.provisioningAccessed && this.registryOptions.evictAtCapacity?.() === true;
+  }
   async get(account) {
+    const scope = this.scope();
     const key = this.key(account);
     let entry = this.storage?.compareAndSet ? await this.storage.get(key) : this.entries.get(key);
     if (!entry && !this.storage?.compareAndSet) {
       const persisted = await this.storage?.get(key);
       entry = this.entries.get(key) ?? persisted;
     }
+    if (!entry && "account_id" in account && this.storage?.getByAccountId) {
+      const persisted = await this.storage.getByAccountId(account.account_id, scope);
+      entry = this.storage.compareAndSet ? persisted : this.entries.get(key) ?? persisted;
+    }
     if (key !== this.key(account) || entry && (0, import_account_key.accountReferenceKey)(entry.account) !== (0, import_account_key.accountReferenceKey)(account))
       return void 0;
     if (entry && this.storage?.compareAndSet && (!Number.isSafeInteger(entry.revision) || entry.revision < 1))
@@ -109,7 +119,12 @@ class BuyerAccountRegistry {
       return { ...structuredClone(entry), status: "unknown" };
     return entry ? structuredClone(entry) : void 0;
   }
+  /** Lookup by seller-issued ID, partitioned by the registry's seller and caller. */
+  async getByAccountId(accountId) {
+    return this.get({ account_id: accountId });
+  }
   async ensure(account, options = {}, taskOptions, onTaskResult) {
+    this.provisioningAccessed = true;
     (0, import_abort.throwIfAborted)(taskOptions?.signal);
     if (taskOptions?.timeout !== void 0 && (!Number.isFinite(taskOptions.timeout) || taskOptions.timeout < 0 || taskOptions.timeout > import_abort.MAX_TIMER_DELAY_MS))
       throw new RangeError(`timeout must be a finite non-negative number <= ${import_abort.MAX_TIMER_DELAY_MS}`);
@@ -379,8 +394,11 @@ class BuyerAccountRegistry {
     const aliases = new Map((priorId?.aliases ?? []).map((alias) => [(0, import_account_key.accountReferenceKey)(alias), alias]));
     if (idRef) {
       aliases.set((0, import_account_key.accountReferenceKey)(ref), structuredClone(ref));
-      if (aliases.size > this.maxEntries)
-        throw new import_errors.AccountSetupRequiredError("Account alias capacity reached; increase registry maxEntries.");
+      if (aliases.size > this.maxEntries) {
+        if (!this.canEvict())
+          throw new import_errors.AccountSetupRequiredError("Account alias capacity reached; increase registry maxEntries.");
+        aliases.delete(aliases.keys().next().value);
+      }
     }
     if (!("account_id" in ref) && prior?.account_id && prior.account_id !== row.account_id) {
       const oldId = await this.get({ account_id: prior.account_id });
@@ -398,20 +416,21 @@ class BuyerAccountRegistry {
     if ("account_id" in ref) {
       if (prior?.aliases) entry.aliases = prior.aliases;
     }
-    await this.write(entry, scope, isCurrent);
-    if (!idRef || scope !== this.scope() || !isCurrent()) return;
-    await this.write(
-      {
-        account: idRef,
-        revision: priorId?.revision,
-        account_id: row.account_id,
-        status: row.status,
-        aliases: [...aliases.values()],
-        ...preserveTerms && priorId?.setupTerms && { setupTerms: priorId.setupTerms }
-      },
-      scope,
-      isCurrent
-    );
+    if (idRef) {
+      await this.write(
+        {
+          account: idRef,
+          revision: priorId?.revision,
+          account_id: row.account_id,
+          status: row.status,
+          aliases: [...aliases.values()],
+          ...preserveTerms && priorId?.setupTerms && { setupTerms: priorId.setupTerms }
+        },
+        scope,
+        isCurrent
+      );
+    }
+    if (scope === this.scope() && isCurrent()) await this.write(entry, scope, isCurrent);
   }
   enqueue(run) {
     const next = this.writes.then(run);

package/dist/lib/core/buyer-account-registry.mjs

@@ -49,6 +49,7 @@ class BuyerAccountRegistry {
   observationFloor = 0;
   statusEpochs = /* @__PURE__ */ new Map();
   maxEntries;
+  provisioningAccessed = false;
   normalizeOptions;
   key(account, scope = this.scope()) {
     return `${scope}:${accountReferenceKey(account)}`;
@@ -62,21 +63,30 @@ class BuyerAccountRegistry {
   }
   remember(key, entry) {
     if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
-      if (!this.storage)
+      if (!this.storage && !this.canEvict())
         throw new AccountSetupRequiredError(
           "Account registry capacity reached; configure durable storage or increase maxEntries."
         );
       this.entries.delete(this.entries.keys().next().value);
     }
+    this.entries.delete(key);
     this.entries.set(key, structuredClone(entry));
   }
+  canEvict() {
+    return !this.provisioningAccessed && this.registryOptions.evictAtCapacity?.() === true;
+  }
   async get(account) {
+    const scope = this.scope();
     const key = this.key(account);
     let entry = this.storage?.compareAndSet ? await this.storage.get(key) : this.entries.get(key);
     if (!entry && !this.storage?.compareAndSet) {
       const persisted = await this.storage?.get(key);
       entry = this.entries.get(key) ?? persisted;
     }
+    if (!entry && "account_id" in account && this.storage?.getByAccountId) {
+      const persisted = await this.storage.getByAccountId(account.account_id, scope);
+      entry = this.storage.compareAndSet ? persisted : this.entries.get(key) ?? persisted;
+    }
     if (key !== this.key(account) || entry && accountReferenceKey(entry.account) !== accountReferenceKey(account))
       return void 0;
     if (entry && this.storage?.compareAndSet && (!Number.isSafeInteger(entry.revision) || entry.revision < 1))
@@ -86,7 +96,12 @@ class BuyerAccountRegistry {
       return { ...structuredClone(entry), status: "unknown" };
     return entry ? structuredClone(entry) : void 0;
   }
+  /** Lookup by seller-issued ID, partitioned by the registry's seller and caller. */
+  async getByAccountId(accountId) {
+    return this.get({ account_id: accountId });
+  }
   async ensure(account, options = {}, taskOptions, onTaskResult) {
+    this.provisioningAccessed = true;
     throwIfAborted(taskOptions?.signal);
     if (taskOptions?.timeout !== void 0 && (!Number.isFinite(taskOptions.timeout) || taskOptions.timeout < 0 || taskOptions.timeout > MAX_TIMER_DELAY_MS))
       throw new RangeError(`timeout must be a finite non-negative number <= ${MAX_TIMER_DELAY_MS}`);
@@ -356,8 +371,11 @@ class BuyerAccountRegistry {
     const aliases = new Map((priorId?.aliases ?? []).map((alias) => [accountReferenceKey(alias), alias]));
     if (idRef) {
       aliases.set(accountReferenceKey(ref), structuredClone(ref));
-      if (aliases.size > this.maxEntries)
-        throw new AccountSetupRequiredError("Account alias capacity reached; increase registry maxEntries.");
+      if (aliases.size > this.maxEntries) {
+        if (!this.canEvict())
+          throw new AccountSetupRequiredError("Account alias capacity reached; increase registry maxEntries.");
+        aliases.delete(aliases.keys().next().value);
+      }
     }
     if (!("account_id" in ref) && prior?.account_id && prior.account_id !== row.account_id) {
       const oldId = await this.get({ account_id: prior.account_id });
@@ -375,20 +393,21 @@ class BuyerAccountRegistry {
     if ("account_id" in ref) {
       if (prior?.aliases) entry.aliases = prior.aliases;
     }
-    await this.write(entry, scope, isCurrent);
-    if (!idRef || scope !== this.scope() || !isCurrent()) return;
-    await this.write(
-      {
-        account: idRef,
-        revision: priorId?.revision,
-        account_id: row.account_id,
-        status: row.status,
-        aliases: [...aliases.values()],
-        ...preserveTerms && priorId?.setupTerms && { setupTerms: priorId.setupTerms }
-      },
-      scope,
-      isCurrent
-    );
+    if (idRef) {
+      await this.write(
+        {
+          account: idRef,
+          revision: priorId?.revision,
+          account_id: row.account_id,
+          status: row.status,
+          aliases: [...aliases.values()],
+          ...preserveTerms && priorId?.setupTerms && { setupTerms: priorId.setupTerms }
+        },
+        scope,
+        isCurrent
+      );
+    }
+    if (scope === this.scope() && isCurrent()) await this.write(entry, scope, isCurrent);
   }
   enqueue(run) {
     const next = this.writes.then(run);

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

@@ -119,9 +119,9 @@ export declare class AccountPaymentRequiredError extends BuyerSetupError {
     constructor(message?: string);
 }
 export declare class AccountNotProvisionedError extends AccountNotFoundError {
-    readonly account: import('../types/index.mjs').AccountReference;
+    readonly account: import('../types/index.mjs').AccountReference | undefined;
     readonly taskName: string;
-    constructor(account: import('../types/index.mjs').AccountReference, taskName: string);
+    constructor(account: import('../types/index.mjs').AccountReference | undefined, taskName: string);
 }
 /**
  * Error thrown when protocol communication fails

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

@@ -119,9 +119,9 @@ export declare class AccountPaymentRequiredError extends BuyerSetupError {
     constructor(message?: string);
 }
 export declare class AccountNotProvisionedError extends AccountNotFoundError {
-    readonly account: import('../types').AccountReference;
+    readonly account: import('../types').AccountReference | undefined;
     readonly taskName: string;
-    constructor(account: import('../types').AccountReference, taskName: string);
+    constructor(account: import('../types').AccountReference | undefined, taskName: string);
 }
 /**
  * Error thrown when protocol communication fails

package/dist/lib/errors/index.js

@@ -157,7 +157,7 @@ class UnsupportedBuyingModeError extends ADCPError {
 class AccountRequiredError extends ADCPError {
   constructor(accountModel, taskName, reason) {
     super(
-      reason ?? `${taskName} requires an account for this ${accountModel}-account seller. ` + (accountModel === "explicit" ? "Call resolveAccount() to discover an account_id, then pass account: { account_id }." : "Call resolveAccount({ brand, operator }) to sync the account, then pass its natural key.")
+      reason ?? `${taskName} requires an account for this ${accountModel}-account seller. ` + (accountModel === "explicit" ? "Call resolveAccount() to discover an account_id, then pass account: { account_id }." : "Call resolveAccount({ brand, operator }) to sync the account, then pass the returned reference.")
     );
     this.accountModel = accountModel;
     this.taskName = taskName;
@@ -212,7 +212,9 @@ class AccountPaymentRequiredError extends BuyerSetupError {
 }
 class AccountNotProvisionedError extends AccountNotFoundError {
   constructor(account, taskName) {
-    super(`${taskName} requires an account provisioned at this seller. Call client.accounts.ensure first.`);
+    super(
+      account ? `${taskName} requires an account provisioned at this seller. Call client.accounts.ensure first.` : `${taskName} requires a provisioned account reference. Call client.accounts.ensure and pass the account reference.`
+    );
     this.account = account;
     this.taskName = taskName;
   }

package/dist/lib/errors/index.mjs

@@ -97,7 +97,7 @@ class UnsupportedBuyingModeError extends ADCPError {
 class AccountRequiredError extends ADCPError {
   constructor(accountModel, taskName, reason) {
     super(
-      reason ?? `${taskName} requires an account for this ${accountModel}-account seller. ` + (accountModel === "explicit" ? "Call resolveAccount() to discover an account_id, then pass account: { account_id }." : "Call resolveAccount({ brand, operator }) to sync the account, then pass its natural key.")
+      reason ?? `${taskName} requires an account for this ${accountModel}-account seller. ` + (accountModel === "explicit" ? "Call resolveAccount() to discover an account_id, then pass account: { account_id }." : "Call resolveAccount({ brand, operator }) to sync the account, then pass the returned reference.")
     );
     this.accountModel = accountModel;
     this.taskName = taskName;
@@ -152,7 +152,9 @@ class AccountPaymentRequiredError extends BuyerSetupError {
 }
 class AccountNotProvisionedError extends AccountNotFoundError {
   constructor(account, taskName) {
-    super(`${taskName} requires an account provisioned at this seller. Call client.accounts.ensure first.`);
+    super(
+      account ? `${taskName} requires an account provisioned at this seller. Call client.accounts.ensure first.` : `${taskName} requires a provisioned account reference. Call client.accounts.ensure and pass the account reference.`
+    );
     this.account = account;
     this.taskName = taskName;
   }

package/dist/lib/index.d.mts

@@ -226,7 +226,7 @@ export { previewCreative, singlePreviewCreativeResponse, batchPreviewCreativeRes
 export { mediaBuyDeliveryNotification, scheduledMediaBuyDeliveryNotification, finalMediaBuyDeliveryNotification, delayedMediaBuyDeliveryNotification, adjustedMediaBuyDeliveryNotification, windowUpdateMediaBuyDeliveryNotification, } from './utils/media-buy-delivery-notification-builders.mjs';
 export { buildSyntheticCapabilities, buildSyntheticV3Capabilities, parseCapabilitiesResponse, supportsV3, supportsProtocol, supportsPropertyListFiltering, supportsContentStandards, supportsSyncCreatives, supportsBuyingMode, requiresOperatorAuth, requiresAccountForProducts, supportsSandbox, supportsExperimentalFeature, resolveFeature, listDeclaredFeatures, MEDIA_BUY_TOOLS, SIGNALS_TOOLS, GOVERNANCE_TOOLS, CREATIVE_TOOLS, EVENT_TRACKING_TOOLS, ACCOUNT_TOOLS, PROTOCOL_TOOLS, BRAND_RIGHTS_TOOLS, TASK_FEATURE_MAP, } from './utils/capabilities.mjs';
 export type { AdcpCapabilities, AdcpMajorVersion, AdcpProtocol, AccountCapabilities, BuyingMode, MediaBuyFeatures, ToolInfo, FeatureName, } from './utils/capabilities.mjs';
-export type { ResolveAccountOptions, ListedAccount } from './core/account-resolution.mjs';
+export type { ResolveAccountOptions, ResolveAccountResult, ListedAccount } from './core/account-resolution.mjs';
 export { inlineCreativesForPackages, inlineCreativesForPackagesLegacy } from './utils/creative-delivery.mjs';
 export type { InlineCreativeAssignment, InlineCreativePackage, InlineCreativePackagePatch, InlineCreativesForPackagesOptions, InlineCreativesForPackagesLegacyOptions, LegacyInlineCreativePackage, } from './utils/creative-delivery.mjs';
 export { adaptPackageRequestForV2, adaptCreateMediaBuyRequestForV2, adaptUpdateMediaBuyRequestForV2, normalizePackageResponse, normalizeMediaBuyResponse, usesV2CreativeIds, usesV3CreativeAssignments, getCreativeIds, getCreativeAssignments, } from './utils/creative-adapter.mjs';

package/dist/lib/index.d.ts

@@ -226,7 +226,7 @@ export { previewCreative, singlePreviewCreativeResponse, batchPreviewCreativeRes
 export { mediaBuyDeliveryNotification, scheduledMediaBuyDeliveryNotification, finalMediaBuyDeliveryNotification, delayedMediaBuyDeliveryNotification, adjustedMediaBuyDeliveryNotification, windowUpdateMediaBuyDeliveryNotification, } from './utils/media-buy-delivery-notification-builders';
 export { buildSyntheticCapabilities, buildSyntheticV3Capabilities, parseCapabilitiesResponse, supportsV3, supportsProtocol, supportsPropertyListFiltering, supportsContentStandards, supportsSyncCreatives, supportsBuyingMode, requiresOperatorAuth, requiresAccountForProducts, supportsSandbox, supportsExperimentalFeature, resolveFeature, listDeclaredFeatures, MEDIA_BUY_TOOLS, SIGNALS_TOOLS, GOVERNANCE_TOOLS, CREATIVE_TOOLS, EVENT_TRACKING_TOOLS, ACCOUNT_TOOLS, PROTOCOL_TOOLS, BRAND_RIGHTS_TOOLS, TASK_FEATURE_MAP, } from './utils/capabilities';
 export type { AdcpCapabilities, AdcpMajorVersion, AdcpProtocol, AccountCapabilities, BuyingMode, MediaBuyFeatures, ToolInfo, FeatureName, } from './utils/capabilities';
-export type { ResolveAccountOptions, ListedAccount } from './core/account-resolution';
+export type { ResolveAccountOptions, ResolveAccountResult, ListedAccount } from './core/account-resolution';
 export { inlineCreativesForPackages, inlineCreativesForPackagesLegacy } from './utils/creative-delivery';
 export type { InlineCreativeAssignment, InlineCreativePackage, InlineCreativePackagePatch, InlineCreativesForPackagesOptions, InlineCreativesForPackagesLegacyOptions, LegacyInlineCreativePackage, } from './utils/creative-delivery';
 export { adaptPackageRequestForV2, adaptCreateMediaBuyRequestForV2, adaptUpdateMediaBuyRequestForV2, normalizePackageResponse, normalizeMediaBuyResponse, usesV2CreativeIds, usesV3CreativeAssignments, getCreativeIds, getCreativeAssignments, } from './utils/creative-adapter';

package/dist/lib/negotiation/commercial-terms-semantics.d.mts

@@ -1,5 +1,6 @@
 /**
- * Reviewed non-JSON-Schema semantics from the 3.2 beta.8 / rc.2 / rc.3 / rc.4 / rc.6 / rc.7 / 3.2.1 / 3.2.3 bundles.
+ * Reviewed non-JSON-Schema semantics from the 3.2 beta.8 / rc.2 / rc.3 / rc.4 / rc.6 / rc.7 / 3.2.1 / 3.2.3 /
+ * 3.2.4 bundles.
  * These are semantic contracts, NOT a binding-field allowlist: properties and
  * comparison always come from the selected runtime schema. Additions to these
  * annotations require a deliberate implementation/review instead of AJV silently

package/dist/lib/negotiation/commercial-terms-semantics.d.ts

@@ -1,5 +1,6 @@
 /**
- * Reviewed non-JSON-Schema semantics from the 3.2 beta.8 / rc.2 / rc.3 / rc.4 / rc.6 / rc.7 / 3.2.1 / 3.2.3 bundles.
+ * Reviewed non-JSON-Schema semantics from the 3.2 beta.8 / rc.2 / rc.3 / rc.4 / rc.6 / rc.7 / 3.2.1 / 3.2.3 /
+ * 3.2.4 bundles.
  * These are semantic contracts, NOT a binding-field allowlist: properties and
  * comparison always come from the selected runtime schema. Additions to these
  * annotations require a deliberate implementation/review instead of AJV silently

package/dist/lib/negotiation/commercial-terms-semantics.js

@@ -180,6 +180,17 @@ const COMMERCIAL_SEMANTIC_OVERRIDES_BY_RELEASE = {
         }
       }
     }
+  },
+  "3.2.4": {
+    "media-buy/product-purchase.json": {
+      verifier_constraints: {
+        accepted_snapshot_terms: "Inside canonical-proposal.commercial_terms, each purchase MUST carry resolved start_time and end_time and MUST preserve every applicable measurement term and performance standard. Omission of measurement_terms or performance_standards means the accepted offer declared none.",
+        pricing_identity: {
+          pricing_option_id: "equals_pricing.pricing_option_id_when_pricing_present",
+          on_violation: "reject_before_commitment"
+        }
+      }
+    }
   }
 };
 const REVIEWED_COMMERCIAL_ENUM_ANNOTATIONS = {

package/dist/lib/negotiation/commercial-terms-semantics.mjs

@@ -154,6 +154,17 @@ const COMMERCIAL_SEMANTIC_OVERRIDES_BY_RELEASE = {
         }
       }
     }
+  },
+  "3.2.4": {
+    "media-buy/product-purchase.json": {
+      verifier_constraints: {
+        accepted_snapshot_terms: "Inside canonical-proposal.commercial_terms, each purchase MUST carry resolved start_time and end_time and MUST preserve every applicable measurement term and performance standard. Omission of measurement_terms or performance_standards means the accepted offer declared none.",
+        pricing_identity: {
+          pricing_option_id: "equals_pricing.pricing_option_id_when_pricing_present",
+          on_violation: "reject_before_commitment"
+        }
+      }
+    }
   }
 };
 const REVIEWED_COMMERCIAL_ENUM_ANNOTATIONS = {

package/dist/lib/reporting/bigquery/index.d.mts

@@ -16,6 +16,8 @@ import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, R
  * BigQuery refuses to run twice. A failed load job is retried under a new
  * attempt suffix only after BigQuery reports that job finished with an error,
  * and each table keeps its own attempt count, so no batch lands twice.
+ * Concurrent runs claim one durable plan with compare-and-swap. Replays of
+ * that plan share job IDs; stale runs cannot change its attempts or cursor.
  */
 /** Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink. */
 export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
@@ -30,9 +32,12 @@ export interface ReportingBigQueryClientV1 {
         };
     };
     job(jobId: string, options?: {
+        projectId?: string;
         location?: string;
     }): {
         getMetadata(): Promise<unknown>;
+        /** Request cancellation. Optional so wrappers written before the sink used it still type-check. */
+        cancel?(): Promise<unknown>;
     };
     query(options: {
         query: string;
@@ -45,12 +50,25 @@ export interface ReportingWarehouseRowContextV1 {
 }
 export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     /** Ledger store with `changeFeed: true`. */
-    store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'saveFeedConsumerCursor' | 'getRevisionMetadata' | 'readRevisionRows'>;
+    store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'getRevisionMetadata' | 'readRevisionRows'> & {
+        /**
+         * The sink ignores the result, so wrappers written when this resolved
+         * `void` keep compiling.
+         */
+        saveFeedConsumerCursor(name: string, cursor: string, options?: {
+            refreshUnchanged?: boolean;
+        }): Promise<unknown>;
+    } & /** Needed only by `reset()`; custom store wrappers that predate it keep compiling. */ Partial<Pick<PostgresReportingLedgerStore, 'removeFeedConsumer'>>;
     /** PostgreSQL pool holding `REPORTING_WAREHOUSE_SINK_MIGRATION`. */
     db: Pick<ReportingPgPool, 'query'>;
     /** Host-constructed official BigQuery client. */
     bigquery: ReportingBigQueryClientV1;
-    /** Stable sink name; also the registered change-feed consumer name. */
+    /**
+     * Stable sink and consumer name. All replicas sharing it must use the same
+     * ledger database, feed scope, destination, location and row mapping. Use
+     * a new name when that configuration changes. Names must also be unique
+     * across independent ledgers sharing a BigQuery project.
+     */
     name: string;
     projectId?: string;
     datasetId: string;
@@ -69,19 +87,38 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
     /** Revisions per batch. Default 200. */
     maxRevisionsPerBatch?: number;
-    /** Job labels for cost attribution. */
+    /**
+     * @deprecated Has no effect, and the sink warns when it is set. The official
+     * client submits a local-file load by uploading a job resource whose
+     * `configuration.load` is built from the load options, and offers no way to
+     * set `configuration.labels`; BigQuery silently drops `labels` found inside
+     * `configuration.load`. For cost attribution, filter
+     * `INFORMATION_SCHEMA.JOBS` on `destination_table` or on the `adcp_rr_`
+     * job ID prefix instead.
+     */
     labels?: Readonly<Record<string, string>>;
     /**
-     * Deadline for one load (and its status check). Default 10 minutes. It is
-     * also sent as the job's `jobTimeoutMs`. A run that times out leaves its
-     * plan in place; the next run reuses the same job ID and waits for, or
-     * accepts, the job BigQuery is still running.
+     * Deadline for one load (and for each status check). Default 10 minutes.
+     * When a load exceeds it, the sink asks BigQuery to cancel that job by its
+     * deterministic ID (in `projectId` and `location`) and rejects, leaving the
+     * plan in place. The next run finds the cancelled job finished with an
+     * error, advances that table's attempt and rejects; the run after that
+     * loads under the new attempt. If the cancel has not taken effect yet the
+     * next run waits for the job. Each attempt doubles the load deadline (up to
+     * 6 hours), so a load that is slow but healthy converges; set this above
+     * your slowest expected load to avoid the cancelled attempts. A status
+     * check that times out is not cancelled. This is a client-side deadline:
+     * BigQuery's server-side `jobTimeoutMs` cannot be set on a local-file load
+     * through the official client, and cancellation is best effort.
      */
     loadTimeoutMilliseconds?: number;
 }
 export interface BigQueryReportingWarehouseSinkV1 {
     /**
-     * Load at most one batch. Resolves with what was loaded; `idle` when nothing new committed.
+     * Load at most one batch. Resolves with what was loaded; `idle` when no
+     * revision changes were selected. Idle ticks can advance past other feed changes.
+     * An overlapping run that loses its plan or cursor claim rejects. Retry
+     * `runOnce()` to resume the current durable plan or committed cursor.
      *
      * `missing` lists revision IDs the change feed announced that no longer
      * exist in the ledger because their period was retired before this batch
@@ -100,6 +137,33 @@ export interface BigQueryReportingWarehouseSinkV1 {
         rows: number;
         missing: string[];
     }>;
+    /**
+     * Clear the sink's saved state so the next `runOnce()` starts again from the
+     * oldest retained change, and unregister its feed consumer so the old
+     * checkpoint stops holding back retention. This is the way out of a sink
+     * that keeps rejecting with `CURSOR_EXPIRED`: a brand-new sink whose first
+     * read lost a startup race with pruning, or a sink that fell behind
+     * retention and has been resynchronized from current revisions. Stop every
+     * worker using this sink name first.
+     *
+     * It refuses while a batch plan is retained, because that batch's load jobs
+     * may already have succeeded; pass `discardRetainedPlan: true` once you have
+     * reconciled it against BigQuery. The warehouse is not touched: a sink that
+     * already loaded history will load the retained revisions again, so empty
+     * the destination tables first, or use a new sink name against new tables.
+     * Each reset starts a new job ID generation, so reloaded batches submit
+     * fresh BigQuery jobs instead of matching the finished jobs of the earlier
+     * history. Nothing holds change retention between `reset()` and the first
+     * committed batch. If `reset()` rejects after clearing the sink's state
+     * (the consumer could not be unregistered), call it again before restarting
+     * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
+     * Resolves with whether a saved sink state existed.
+     */
+    reset(options?: {
+        discardRetainedPlan?: boolean;
+    }): Promise<{
+        cleared: boolean;
+    }>;
     /** DDL for the default rows and revisions tables (partitioned and clustered). */
     readonly defaultTablesSql: string;
     /** DDL for the reference `current_rows` view. */
@@ -107,7 +171,7 @@ export interface BigQueryReportingWarehouseSinkV1 {
 }
 export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
 /** Deterministic load job ID for one planned change-feed range. */
-export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string): string;
+export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
 interface WarehouseTablesV1 {
     projectId?: string;
     datasetId: string;