@adcp/sdk 15.8.0 → 15.9.0

package/dist/lib/core/SingleAgentClient.js

@@ -82,6 +82,7 @@ var import_v2_5 = require('../adapters/legacy/v2-5/index.js');
 var import_property_policy = require('../media-buy/property-policy.js');
 var import_targeting_helpers = require('../server/targeting-helpers.js');
 var import_creative_delivery = require('../v2/projection/creative-delivery.js');
+var import_legacy_routes = require('../v2/projection/legacy-routes.js');
 var import_catalog_snapshot = require('../v2/projection/catalog-snapshot.js');
 var import_augment_response = require('../v2/projection/augment-response.js');
 var import_legacy_metadata = require('../v2/projection/legacy-metadata.js');
@@ -940,6 +941,7 @@ class SingleAgentClient {
         ...this.config.accountRegistryOptions,
         provisionOwnsDispatchBoundary: true,
         maxEntries: this.config.accountRegistryMaxEntries,
+        evictAtCapacity: () => !this.accountRegistryOptedIn(),
         normalizeOptions: async (options, taskOptions) => {
           if (options.billing) return options;
           const caps = await this.getCapabilities(taskOptions);
@@ -978,24 +980,65 @@ class SingleAgentClient {
       }
     };
   }
+  usesStableAccountIds(capabilities) {
+    if (capabilities._synthetic) return false;
+    return capabilities.account?.stableAccountId === true || (0, import_adcp_version_config.isAdcpVersionAtLeast)(this.config.wireAdcpVersion ?? this.resolvedAdcpVersion, "4.0.0") && ((0, import_adcp_version_config.isAdcpVersionAtLeast)(capabilities.servedVersion, "4.0.0") || !capabilities.servedVersion && capabilities.supportedVersions?.some((version) => (0, import_adcp_version_config.isAdcpVersionAtLeast)(version, "4.0.0")) === true);
+  }
+  accountWireReference(account, accountId, capabilities) {
+    if ("account_id" in account || this.config.accountReferenceMode === "natural-key" || !this.usesStableAccountIds(capabilities))
+      return account;
+    if (!accountId)
+      throw new import_errors3.AccountSetupRequiredError(
+        "The seller declares stable account IDs but did not return an account_id. Reconcile with syncAccounts."
+      );
+    return { account_id: accountId };
+  }
   async applyAccountPolicy(task, params, options) {
     const policy = this.config.accountPolicy ?? "off";
     const ref = params?.account ?? (typeof params?.account_id === "string" ? { account_id: params.account_id } : void 0);
-    if (policy === "off" || options?.skipAccountValidation || options?.preserveGovernedPayload || !ref || task === "list_accounts")
+    if (options?.skipAccountValidation || options?.preserveGovernedPayload || task === "list_accounts" || task === "sync_accounts")
+      return params;
+    if (!ref) {
+      if (policy === "strict" && ["get_products", "list_products"].includes(task) && this.usesStableAccountIds(await this.getCapabilities(options)))
+        throw new import_errors3.AccountNotProvisionedError(void 0, task);
       return params;
+    }
+    if (policy === "off" && !this._accounts) return params;
     if (typeof ref !== "object" || ref === null || !("account_id" in ref) && (typeof ref.brand?.domain !== "string" || typeof ref.operator !== "string"))
       return params;
-    const known = await this.getAccountRegistry().get(ref);
+    const registry = this.getAccountRegistry();
+    let known = await registry.get(ref);
+    let capabilities;
+    if (known && !["unknown", "provisioning", "failed_provisioning"].includes(known.status) && !("account_id" in ref) && this.config.accountReferenceMode !== "natural-key") {
+      const scope = this.accountScope();
+      capabilities = await this.getCapabilities(options);
+      if (scope !== this.accountScope()) throw new import_errors3.AccountNotProvisionedError(ref, task);
+      known = await registry.get(ref);
+      if (scope !== this.accountScope()) throw new import_errors3.AccountNotProvisionedError(ref, task);
+    }
     if (known && !["unknown", "provisioning", "failed_provisioning"].includes(known.status)) {
-      if (["create_media_buy", "buy_products", "accept_proposal", "activate_signal", "acquire_rights"].includes(task) && known.status !== "active") {
+      const commitsSpend = [
+        "create_media_buy",
+        "buy_products",
+        "accept_proposal",
+        "activate_signal",
+        "acquire_rights"
+      ].includes(task);
+      const allowedStatuses = task === "sync_creatives" ? ["active", "payment_required"] : ["active"];
+      if (policy !== "off" && (commitsSpend || task === "sync_creatives") && !allowedStatuses.includes(known.status)) {
         if (known.status === "pending_approval") throw new import_errors3.AccountPendingApprovalError(ref, known.account_id);
         if (known.status === "payment_required") throw new import_errors3.AccountPaymentRequiredError();
         throw new import_errors3.AccountSetupRequiredError(
           `Account status is ${known.status}. Refresh it with client.accounts.applyStatusChange or complete seller setup.`
         );
       }
+      if (capabilities) {
+        const account2 = this.accountWireReference(ref, known.account_id, capabilities);
+        if (account2 !== ref) return { ...params, account: account2 };
+      }
       return params;
     }
+    if (policy === "off") return params;
     if (policy === "strict" || ![
       "get_products",
       "list_products",
@@ -1322,7 +1365,6 @@ class SingleAgentClient {
           format_option_id: option.format_option_id
         } : { scope: "product", format_option_id: option.format_option_id };
         const refs = (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option);
-        if (refs.length === 0) continue;
         const declared = declaredOptions ? declaredOptions.get(product.product_id)?.some((declaredRef) => this.sameCanonicalOptionRef(declaredRef, ref)) : (0, import_legacy_metadata.sellerDeclaredFormatOption)(option);
         if (declared !== void 0) (0, import_legacy_metadata.rememberSellerDeclaredFormatOption)(option, declared);
         this.rememberCanonicalLegacyRoute(this.canonicalLegacyRouteKey(account, product.product_id, ref), {
@@ -1331,13 +1373,7 @@ class SingleAgentClient {
           productId: product.product_id,
           optionRef: ref,
           refs,
-          ...declared === false ? {
-            undeclaredSelector: {
-              format_kind: typeof option.format_kind === "string" ? option.format_kind : "",
-              ...option.params !== void 0 && { params: structuredClone(option.params) },
-              ...(typeof option.format_kind !== "string" || option.format_kind === "custom" || option.format_shape !== void 0 || option.format_schema !== void 0) && { unrepresentable: true }
-            }
-          } : {}
+          ...declared === false ? { undeclaredSelector: (0, import_legacy_routes.undeclaredFormatOptionSelector)(option) } : {}
         });
       }
     }
@@ -1371,28 +1407,39 @@ class SingleAgentClient {
     return declared;
   }
   /**
-   * The direct selector for an option this client derived from the seller's
-   * legacy `format_ids`. Without a product id, every remembered route for the
-   * option must agree that the seller did not declare it.
+   * What this client's own discovery recorded about an option's origin.
+   * Without a product id, every remembered route for the option must agree
+   * that the seller did not declare it.
    */
-  undeclaredFormatOptionSelector(account, ref, productId) {
+  cachedFormatOptionOrigin(account, ref, productId) {
+    const originOf = (route) => route.undeclaredSelector ? { seller_declared: false, selector: route.undeclaredSelector } : { seller_declared: true };
     if (productId !== void 0) {
       const route = this.routeForOption(account, productId, ref);
-      return route?.kind === "product" ? route.undeclaredSelector : void 0;
+      return route?.kind === "product" ? originOf(route) : void 0;
     }
     const accountScope = this.canonicalAccountScope(account);
     const routes = [...this.canonicalLegacyRoutes.values()].filter(
       (route) => route.kind === "product" && (route.accountScope === accountScope || route.accountScope === "none") && this.sameCanonicalOptionRef(route.optionRef, ref)
     );
-    if (routes.length === 0 || routes.some((route) => route.undeclaredSelector === void 0)) return void 0;
-    return routes[0].undeclaredSelector;
+    if (routes.length === 0) return void 0;
+    return originOf(routes.find((route) => route.undeclaredSelector === void 0) ?? routes[0]);
   }
-  projectUndeclaredFormatOptions(request, operation, wireMode, account) {
+  /**
+   * The direct selector for an option the seller did not declare, from the
+   * first source that knows the option's origin: the per-call resolver, this
+   * client's discovery, then the configured resolver. Resolvers carry origin
+   * only when built from persisted routes.
+   */
+  undeclaredSelectorFor(account, ref, productId, override) {
+    const origin = (0, import_legacy_routes.formatOptionOriginFromRoutes)(override, ref, productId) ?? this.cachedFormatOptionOrigin(account, ref, productId) ?? (0, import_legacy_routes.formatOptionOriginFromRoutes)(this.config.canonicalFormatLegacyResolver, ref, productId);
+    return origin && !origin.seller_declared ? origin.selector : void 0;
+  }
+  projectUndeclaredFormatOptions(request, operation, wireMode, account, override) {
     if (wireMode !== "canonical") return request;
     return (0, import_creative_delivery.projectUndeclaredFormatOptionSelectors)(
       request,
       operation,
-      (ref, productId) => this.undeclaredFormatOptionSelector(account, ref, productId)
+      (ref, productId) => this.undeclaredSelectorFor(account, ref, productId, override)
     );
   }
   rememberCanonicalProductRoutesForCompletion(taskType, data, legacyFormatConverter, account) {
@@ -1490,7 +1537,7 @@ class SingleAgentClient {
     const resolved = [];
     for (const ref of optionRefs) {
       const route = this.routeForOption(account, productId, ref);
-      if (!route) return void 0;
+      if (!route || route.refs.length === 0) return void 0;
       resolved.push(...route.refs.map((value) => ({ ...value })));
     }
     return resolved;
@@ -4733,7 +4780,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         ),
         "create_media_buy",
         wireMode,
-        wireParams.account
+        wireParams.account,
+        canonicalFormatLegacyResolver
       ),
       inputHandler,
       taskOptions,
@@ -4819,7 +4867,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         ),
         "update_media_buy",
         wireMode,
-        params.account
+        params.account,
+        canonicalFormatLegacyResolver
       ),
       inputHandler,
       taskOptions,
@@ -4915,7 +4964,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ),
       "sync_creatives",
       wireMode,
-      params.account
+      params.account,
+      canonicalFormatLegacyResolver
     );
     return this.executeAndHandle(
       "sync_creatives",
@@ -5344,11 +5394,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       options
     );
   }
-  /**
-   * Resolve an account for the authenticated caller. Explicit-account sellers
-   * are discovered with list_accounts; implicit-account sellers are registered
-   * with sync_accounts and addressed by their natural key.
-   */
   async resolveAccount(hints = {}, options, onTaskResult) {
     return (0, import_task_deadline.withTaskDeadline)(snapshotTaskOptions(options), async (effectiveOptions) => {
       const capabilities = await this.getCapabilities(effectiveOptions);
@@ -5359,6 +5404,14 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           "The seller did not provide an account contract. Probe get_adcp_capabilities or pass an account reference explicitly."
         );
       }
+      const resolved = (account2, accountId) => {
+        const reference = this.accountWireReference(account2, accountId, capabilities);
+        return hints.includeDetails ? {
+          reference,
+          ...accountId && { account_id: accountId },
+          ...!("account_id" in account2) && { naturalKey: structuredClone(account2) }
+        } : reference;
+      };
       if (capabilities.account.requireOperatorAuth) {
         const accounts = [];
         const seenCursors = /* @__PURE__ */ new Set();
@@ -5378,7 +5431,10 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             throw new Error("list_accounts did not return a completed account list.");
           }
           accounts.push(...result.data.accounts);
-          if (!result.data.pagination?.has_more) return (0, import_account_resolution.selectListedAccount)(accounts, hints);
+          if (!result.data.pagination?.has_more) {
+            const selected = (0, import_account_resolution.selectListedAccount)(accounts, hints);
+            return resolved(selected, "account_id" in selected ? selected.account_id : void 0);
+          }
           const nextCursor = result.data.pagination.cursor;
           if (!nextCursor || seenCursors.has(nextCursor)) break;
           seenCursors.add(nextCursor);
@@ -5447,6 +5503,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         );
       }
       if (!this.accountRegistryOptedIn()) {
+        const registry = this.usesStableAccountIds(capabilities) ? this.getAccountRegistry() : void 0;
+        const registryScope = registry ? this.accountScope() : void 0;
+        const observationEpoch = registry?.captureObservation();
         const result = await this.syncAccounts(
           {
             accounts: [
@@ -5465,20 +5524,62 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data) || !Array.isArray(result.data.accounts)) {
           throw new Error("sync_accounts did not return a completed account result.");
         }
-        const syncedRow = result.data.accounts.find(
+        if (registry) {
+          if (registryScope !== this.accountScope())
+            throw new import_errors3.AccountRequiredError(
+              "implicit",
+              "resolveAccount",
+              "Caller credentials changed during provisioning."
+            );
+          await registry.observeSync([account], result.data.accounts, false, observationEpoch);
+          if (registryScope !== this.accountScope())
+            throw new import_errors3.AccountRequiredError(
+              "implicit",
+              "resolveAccount",
+              "Caller credentials changed during provisioning."
+            );
+        }
+        const matchingRows = result.data.accounts.filter(
           (row) => row.brand?.domain === hints.brand.domain && row.operator === hints.operator && (!hints.brand.brand_id || row.brand.brand_id === hints.brand.brand_id) && (0, import_account_resolution.sameCountrySet)(hints.brand.countries, row.brand.countries) && (!hints.operatorUnit || row.operator_unit?.id === hints.operatorUnit.id) && (!hints.currency || row.currency === hints.currency) && (!hints.timezone || row.timezone === hints.timezone) && (row.sandbox === void 0 || row.sandbox === true === (hints.sandbox === true))
         );
-        if (syncedRow?.status === "pending_approval") {
-          throw new import_errors3.AccountPendingApprovalError(account, syncedRow.account_id);
-        }
-        if (!syncedRow || syncedRow.action === "failed" || syncedRow.status !== "active") {
+        if (registry && matchingRows.length > 1)
+          throw new import_errors3.AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "sync_accounts returned ambiguous rows for the requested account."
+          );
+        const syncedRow = matchingRows[0];
+        if (!syncedRow || syncedRow.action === "failed") {
           throw new import_errors3.AccountRequiredError(
             "implicit",
             "resolveAccount",
             "sync_accounts did not establish an active account for the requested brand and operator."
           );
         }
-        return account;
+        let current = registry ? await registry.get(account) : syncedRow;
+        if (registry && registryScope !== this.accountScope())
+          throw new import_errors3.AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "Caller credentials changed during provisioning."
+          );
+        if (registry && !current && registry.captureObservation() === observationEpoch) {
+          current = syncedRow;
+        }
+        if (current && current.account_id !== syncedRow.account_id && registry?.captureObservation() === observationEpoch)
+          throw new import_errors3.AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "The seller account binding changed during resolution. Resolve the account again."
+          );
+        if (current?.status === "pending_approval") throw new import_errors3.AccountPendingApprovalError(account, current.account_id);
+        if (current?.status !== "active")
+          throw new import_errors3.AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "sync_accounts did not establish an active account for the requested brand and operator."
+          );
+        return resolved(account, current.account_id);
       }
       let synced;
       try {
@@ -5500,7 +5601,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       if (synced.status === "pending_approval") throw new import_errors3.AccountPendingApprovalError(account, synced.account_id);
       if (synced.status !== "active")
         throw new import_errors3.AccountRequiredError("implicit", "resolveAccount", "The account is not active.");
-      return account;
+      return resolved(account, synced.account_id);
     });
   }
   /**

package/dist/lib/core/SingleAgentClient.mjs

@@ -142,7 +142,10 @@ import {
   UnsupportedBuyingModeError
 } from "../errors/index.mjs";
 import { BuyerAccountRegistry } from "./buyer-account-registry.mjs";
-import { sameCountrySet, selectListedAccount } from "./account-resolution.mjs";
+import {
+  sameCountrySet,
+  selectListedAccount
+} from "./account-resolution.mjs";
 import { normalizeRequestParams } from "../utils/request-normalizer.mjs";
 import { globalAsyncLocalStorage } from "../utils/global-async-local-storage.mjs";
 import { validateUserAgent } from "../utils/validate-user-agent.mjs";
@@ -163,6 +166,10 @@ import {
   resolveCreativeFormatWireMode,
   stripLegacyCreativeIdentity
 } from "../v2/projection/creative-delivery.mjs";
+import {
+  formatOptionOriginFromRoutes,
+  undeclaredFormatOptionSelector
+} from "../v2/projection/legacy-routes.mjs";
 import {
   legacyFormatConverterFromCatalogSnapshots
 } from "../v2/projection/catalog-snapshot.mjs";
@@ -1018,6 +1025,7 @@ class SingleAgentClient {
         ...this.config.accountRegistryOptions,
         provisionOwnsDispatchBoundary: true,
         maxEntries: this.config.accountRegistryMaxEntries,
+        evictAtCapacity: () => !this.accountRegistryOptedIn(),
         normalizeOptions: async (options, taskOptions) => {
           if (options.billing) return options;
           const caps = await this.getCapabilities(taskOptions);
@@ -1056,24 +1064,65 @@ class SingleAgentClient {
       }
     };
   }
+  usesStableAccountIds(capabilities) {
+    if (capabilities._synthetic) return false;
+    return capabilities.account?.stableAccountId === true || isAdcpVersionAtLeast(this.config.wireAdcpVersion ?? this.resolvedAdcpVersion, "4.0.0") && (isAdcpVersionAtLeast(capabilities.servedVersion, "4.0.0") || !capabilities.servedVersion && capabilities.supportedVersions?.some((version) => isAdcpVersionAtLeast(version, "4.0.0")) === true);
+  }
+  accountWireReference(account, accountId, capabilities) {
+    if ("account_id" in account || this.config.accountReferenceMode === "natural-key" || !this.usesStableAccountIds(capabilities))
+      return account;
+    if (!accountId)
+      throw new AccountSetupRequiredError(
+        "The seller declares stable account IDs but did not return an account_id. Reconcile with syncAccounts."
+      );
+    return { account_id: accountId };
+  }
   async applyAccountPolicy(task, params, options) {
     const policy = this.config.accountPolicy ?? "off";
     const ref = params?.account ?? (typeof params?.account_id === "string" ? { account_id: params.account_id } : void 0);
-    if (policy === "off" || options?.skipAccountValidation || options?.preserveGovernedPayload || !ref || task === "list_accounts")
+    if (options?.skipAccountValidation || options?.preserveGovernedPayload || task === "list_accounts" || task === "sync_accounts")
       return params;
+    if (!ref) {
+      if (policy === "strict" && ["get_products", "list_products"].includes(task) && this.usesStableAccountIds(await this.getCapabilities(options)))
+        throw new AccountNotProvisionedError(void 0, task);
+      return params;
+    }
+    if (policy === "off" && !this._accounts) return params;
     if (typeof ref !== "object" || ref === null || !("account_id" in ref) && (typeof ref.brand?.domain !== "string" || typeof ref.operator !== "string"))
       return params;
-    const known = await this.getAccountRegistry().get(ref);
+    const registry = this.getAccountRegistry();
+    let known = await registry.get(ref);
+    let capabilities;
+    if (known && !["unknown", "provisioning", "failed_provisioning"].includes(known.status) && !("account_id" in ref) && this.config.accountReferenceMode !== "natural-key") {
+      const scope = this.accountScope();
+      capabilities = await this.getCapabilities(options);
+      if (scope !== this.accountScope()) throw new AccountNotProvisionedError(ref, task);
+      known = await registry.get(ref);
+      if (scope !== this.accountScope()) throw new AccountNotProvisionedError(ref, task);
+    }
     if (known && !["unknown", "provisioning", "failed_provisioning"].includes(known.status)) {
-      if (["create_media_buy", "buy_products", "accept_proposal", "activate_signal", "acquire_rights"].includes(task) && known.status !== "active") {
+      const commitsSpend = [
+        "create_media_buy",
+        "buy_products",
+        "accept_proposal",
+        "activate_signal",
+        "acquire_rights"
+      ].includes(task);
+      const allowedStatuses = task === "sync_creatives" ? ["active", "payment_required"] : ["active"];
+      if (policy !== "off" && (commitsSpend || task === "sync_creatives") && !allowedStatuses.includes(known.status)) {
         if (known.status === "pending_approval") throw new AccountPendingApprovalError(ref, known.account_id);
         if (known.status === "payment_required") throw new AccountPaymentRequiredError();
         throw new AccountSetupRequiredError(
           `Account status is ${known.status}. Refresh it with client.accounts.applyStatusChange or complete seller setup.`
         );
       }
+      if (capabilities) {
+        const account2 = this.accountWireReference(ref, known.account_id, capabilities);
+        if (account2 !== ref) return { ...params, account: account2 };
+      }
       return params;
     }
+    if (policy === "off") return params;
     if (policy === "strict" || ![
       "get_products",
       "list_products",
@@ -1400,7 +1449,6 @@ class SingleAgentClient {
           format_option_id: option.format_option_id
         } : { scope: "product", format_option_id: option.format_option_id };
         const refs = legacyFormatRefsForDeclaration(option);
-        if (refs.length === 0) continue;
         const declared = declaredOptions ? declaredOptions.get(product.product_id)?.some((declaredRef) => this.sameCanonicalOptionRef(declaredRef, ref)) : sellerDeclaredFormatOption(option);
         if (declared !== void 0) rememberSellerDeclaredFormatOption(option, declared);
         this.rememberCanonicalLegacyRoute(this.canonicalLegacyRouteKey(account, product.product_id, ref), {
@@ -1409,13 +1457,7 @@ class SingleAgentClient {
           productId: product.product_id,
           optionRef: ref,
           refs,
-          ...declared === false ? {
-            undeclaredSelector: {
-              format_kind: typeof option.format_kind === "string" ? option.format_kind : "",
-              ...option.params !== void 0 && { params: structuredClone(option.params) },
-              ...(typeof option.format_kind !== "string" || option.format_kind === "custom" || option.format_shape !== void 0 || option.format_schema !== void 0) && { unrepresentable: true }
-            }
-          } : {}
+          ...declared === false ? { undeclaredSelector: undeclaredFormatOptionSelector(option) } : {}
         });
       }
     }
@@ -1449,28 +1491,39 @@ class SingleAgentClient {
     return declared;
   }
   /**
-   * The direct selector for an option this client derived from the seller's
-   * legacy `format_ids`. Without a product id, every remembered route for the
-   * option must agree that the seller did not declare it.
+   * What this client's own discovery recorded about an option's origin.
+   * Without a product id, every remembered route for the option must agree
+   * that the seller did not declare it.
    */
-  undeclaredFormatOptionSelector(account, ref, productId) {
+  cachedFormatOptionOrigin(account, ref, productId) {
+    const originOf = (route) => route.undeclaredSelector ? { seller_declared: false, selector: route.undeclaredSelector } : { seller_declared: true };
     if (productId !== void 0) {
       const route = this.routeForOption(account, productId, ref);
-      return route?.kind === "product" ? route.undeclaredSelector : void 0;
+      return route?.kind === "product" ? originOf(route) : void 0;
     }
     const accountScope = this.canonicalAccountScope(account);
     const routes = [...this.canonicalLegacyRoutes.values()].filter(
       (route) => route.kind === "product" && (route.accountScope === accountScope || route.accountScope === "none") && this.sameCanonicalOptionRef(route.optionRef, ref)
     );
-    if (routes.length === 0 || routes.some((route) => route.undeclaredSelector === void 0)) return void 0;
-    return routes[0].undeclaredSelector;
+    if (routes.length === 0) return void 0;
+    return originOf(routes.find((route) => route.undeclaredSelector === void 0) ?? routes[0]);
+  }
+  /**
+   * The direct selector for an option the seller did not declare, from the
+   * first source that knows the option's origin: the per-call resolver, this
+   * client's discovery, then the configured resolver. Resolvers carry origin
+   * only when built from persisted routes.
+   */
+  undeclaredSelectorFor(account, ref, productId, override) {
+    const origin = formatOptionOriginFromRoutes(override, ref, productId) ?? this.cachedFormatOptionOrigin(account, ref, productId) ?? formatOptionOriginFromRoutes(this.config.canonicalFormatLegacyResolver, ref, productId);
+    return origin && !origin.seller_declared ? origin.selector : void 0;
   }
-  projectUndeclaredFormatOptions(request, operation, wireMode, account) {
+  projectUndeclaredFormatOptions(request, operation, wireMode, account, override) {
     if (wireMode !== "canonical") return request;
     return projectUndeclaredFormatOptionSelectors(
       request,
       operation,
-      (ref, productId) => this.undeclaredFormatOptionSelector(account, ref, productId)
+      (ref, productId) => this.undeclaredSelectorFor(account, ref, productId, override)
     );
   }
   rememberCanonicalProductRoutesForCompletion(taskType, data, legacyFormatConverter, account) {
@@ -1568,7 +1621,7 @@ class SingleAgentClient {
     const resolved = [];
     for (const ref of optionRefs) {
       const route = this.routeForOption(account, productId, ref);
-      if (!route) return void 0;
+      if (!route || route.refs.length === 0) return void 0;
       resolved.push(...route.refs.map((value) => ({ ...value })));
     }
     return resolved;
@@ -4811,7 +4864,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         ),
         "create_media_buy",
         wireMode,
-        wireParams.account
+        wireParams.account,
+        canonicalFormatLegacyResolver
       ),
       inputHandler,
       taskOptions,
@@ -4897,7 +4951,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         ),
         "update_media_buy",
         wireMode,
-        params.account
+        params.account,
+        canonicalFormatLegacyResolver
       ),
       inputHandler,
       taskOptions,
@@ -4993,7 +5048,8 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       ),
       "sync_creatives",
       wireMode,
-      params.account
+      params.account,
+      canonicalFormatLegacyResolver
     );
     return this.executeAndHandle(
       "sync_creatives",
@@ -5422,11 +5478,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       options
     );
   }
-  /**
-   * Resolve an account for the authenticated caller. Explicit-account sellers
-   * are discovered with list_accounts; implicit-account sellers are registered
-   * with sync_accounts and addressed by their natural key.
-   */
   async resolveAccount(hints = {}, options, onTaskResult) {
     return withTaskDeadline(snapshotTaskOptions(options), async (effectiveOptions) => {
       const capabilities = await this.getCapabilities(effectiveOptions);
@@ -5437,6 +5488,14 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
           "The seller did not provide an account contract. Probe get_adcp_capabilities or pass an account reference explicitly."
         );
       }
+      const resolved = (account2, accountId) => {
+        const reference = this.accountWireReference(account2, accountId, capabilities);
+        return hints.includeDetails ? {
+          reference,
+          ...accountId && { account_id: accountId },
+          ...!("account_id" in account2) && { naturalKey: structuredClone(account2) }
+        } : reference;
+      };
       if (capabilities.account.requireOperatorAuth) {
         const accounts = [];
         const seenCursors = /* @__PURE__ */ new Set();
@@ -5456,7 +5515,10 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             throw new Error("list_accounts did not return a completed account list.");
           }
           accounts.push(...result.data.accounts);
-          if (!result.data.pagination?.has_more) return selectListedAccount(accounts, hints);
+          if (!result.data.pagination?.has_more) {
+            const selected = selectListedAccount(accounts, hints);
+            return resolved(selected, "account_id" in selected ? selected.account_id : void 0);
+          }
           const nextCursor = result.data.pagination.cursor;
           if (!nextCursor || seenCursors.has(nextCursor)) break;
           seenCursors.add(nextCursor);
@@ -5525,6 +5587,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         );
       }
       if (!this.accountRegistryOptedIn()) {
+        const registry = this.usesStableAccountIds(capabilities) ? this.getAccountRegistry() : void 0;
+        const registryScope = registry ? this.accountScope() : void 0;
+        const observationEpoch = registry?.captureObservation();
         const result = await this.syncAccounts(
           {
             accounts: [
@@ -5543,20 +5608,62 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data) || !Array.isArray(result.data.accounts)) {
           throw new Error("sync_accounts did not return a completed account result.");
         }
-        const syncedRow = result.data.accounts.find(
+        if (registry) {
+          if (registryScope !== this.accountScope())
+            throw new AccountRequiredError(
+              "implicit",
+              "resolveAccount",
+              "Caller credentials changed during provisioning."
+            );
+          await registry.observeSync([account], result.data.accounts, false, observationEpoch);
+          if (registryScope !== this.accountScope())
+            throw new AccountRequiredError(
+              "implicit",
+              "resolveAccount",
+              "Caller credentials changed during provisioning."
+            );
+        }
+        const matchingRows = result.data.accounts.filter(
           (row) => row.brand?.domain === hints.brand.domain && row.operator === hints.operator && (!hints.brand.brand_id || row.brand.brand_id === hints.brand.brand_id) && sameCountrySet(hints.brand.countries, row.brand.countries) && (!hints.operatorUnit || row.operator_unit?.id === hints.operatorUnit.id) && (!hints.currency || row.currency === hints.currency) && (!hints.timezone || row.timezone === hints.timezone) && (row.sandbox === void 0 || row.sandbox === true === (hints.sandbox === true))
         );
-        if (syncedRow?.status === "pending_approval") {
-          throw new AccountPendingApprovalError(account, syncedRow.account_id);
-        }
-        if (!syncedRow || syncedRow.action === "failed" || syncedRow.status !== "active") {
+        if (registry && matchingRows.length > 1)
+          throw new AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "sync_accounts returned ambiguous rows for the requested account."
+          );
+        const syncedRow = matchingRows[0];
+        if (!syncedRow || syncedRow.action === "failed") {
           throw new AccountRequiredError(
             "implicit",
             "resolveAccount",
             "sync_accounts did not establish an active account for the requested brand and operator."
           );
         }
-        return account;
+        let current = registry ? await registry.get(account) : syncedRow;
+        if (registry && registryScope !== this.accountScope())
+          throw new AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "Caller credentials changed during provisioning."
+          );
+        if (registry && !current && registry.captureObservation() === observationEpoch) {
+          current = syncedRow;
+        }
+        if (current && current.account_id !== syncedRow.account_id && registry?.captureObservation() === observationEpoch)
+          throw new AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "The seller account binding changed during resolution. Resolve the account again."
+          );
+        if (current?.status === "pending_approval") throw new AccountPendingApprovalError(account, current.account_id);
+        if (current?.status !== "active")
+          throw new AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "sync_accounts did not establish an active account for the requested brand and operator."
+          );
+        return resolved(account, current.account_id);
       }
       let synced;
       try {
@@ -5578,7 +5685,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       if (synced.status === "pending_approval") throw new AccountPendingApprovalError(account, synced.account_id);
       if (synced.status !== "active")
         throw new AccountRequiredError("implicit", "resolveAccount", "The account is not active.");
-      return account;
+      return resolved(account, synced.account_id);
     });
   }
   /**