@adcp/sdk 14.1.0 → 14.2.0

package/dist/lib/wholesale-feed-sync/sync.mjs

@@ -1,12 +1,21 @@
 import { EventEmitter } from "node:events";
 import { isDeepStrictEqual } from "node:util";
-import { randomUUID } from "node:crypto";
+import {
+  refreshWholesaleFeed,
+  InMemoryWholesaleFeedMirrorStore,
+  applyWholesaleFeedEvent,
+  diffWholesaleFeed
+} from "./mirror.mjs";
 import { assertLegacyWholesaleFeedRepresentation } from "./webhook-notification.mjs";
 const bootstrapReadFailures = /* @__PURE__ */ new WeakSet();
+function supersededRepairError() {
+  const error = new Error("WholesaleFeedSync: repair superseded repeatedly; retry webhook delivery.");
+  bootstrapReadFailures.add(error);
+  return error;
+}
 const DEFAULT_PROBE_INTERVAL_MS = 6e5;
 const DEFAULT_CAPABILITY_REFRESH_INTERVAL_MS = 864e5;
 const DEFAULT_PERSISTENCE_TIMEOUT_MS = 3e4;
-const DEFAULT_BOOTSTRAP_PAGE_LIMIT = 100;
 const VERSION_MISMATCH_RECOVERY_ATTEMPTS = 3;
 const VERSION_MISMATCH_RECOVERY_BACKOFF_MS = 5;
 class WholesaleFeedSync extends EventEmitter {
@@ -47,11 +56,10 @@ class WholesaleFeedSync extends EventEmitter {
   probeTimer = null;
   capabilityTimer = null;
   lifecycleEpoch = 0;
+  mirrorRevision = 0;
   /**
-   * Read-only view of the in-memory product index. The `mode` reflects the
-   * sync strategy for product events specifically — in mixed-capability
-   * agents (products-feed + signals-wholesale-only, or vice versa) this
-   * may differ from `signals.mode`.
+   * Product index view. `mode` identifies the product sync strategy and may
+   * differ from `signals.mode` for agents with mixed feed capabilities.
    */
   products = {
     list: () => [...this.productIndex.values()],
@@ -86,19 +94,12 @@ class WholesaleFeedSync extends EventEmitter {
     },
     _mode: "manual",
     /**
-     * `true` when the agent supports `discovery_mode: 'wholesale'` on
-     * `get_signals` (i.e., signals are browsable). When `false`, the
-     * agent only supports brief-mode discovery — `signals.list()` will
-     * be empty until adopters call into the agent with their own briefs.
+     * True when `get_signals` supports `discovery_mode: 'wholesale'`.
+     * Otherwise `list()` is empty; use client brief discovery instead.
      */
     queryable: true
   };
-  /**
-   * One-shot console warning when adopters call `signals.list()` or
-   * `signals.search()` against an agent that doesn't support wholesale
-   * signal enumeration. Without this, empty results read as "no signals
-   * match" rather than "the agent doesn't browse, only briefs."
-   */
+  // Warn once when empty signal results reflect missing wholesale support.
   warnIfSignalsNotQueryable() {
     if (this.signals.queryable || this.signalsQueryableWarned) return;
     if (this._state === "idle" || this._state === "bootstrapping") return;
@@ -124,14 +125,9 @@ class WholesaleFeedSync extends EventEmitter {
   }
   // ====== Lifecycle ======
   /**
-   * Probe the agent's capabilities, pick a sync mode, and bootstrap the
-   * in-memory replica via wholesale enumeration. In `'auto-poll'` mode
-   * starts the conditional wholesale-feed version probe loop.
-   *
-   * Safe to call repeatedly — concurrent calls await the in-flight
-   * bootstrap and return when it completes (no duplicate bootstrap, no
-   * silent drop). Sequential calls re-probe capabilities and re-bootstrap,
-   * equivalent to calling `refresh()` after a mode upgrade.
+   * Discover capabilities, bootstrap the mirror, and schedule auto-poll probes
+   * for versioned sellers. Concurrent calls share the bootstrap; sequential
+   * calls re-probe capabilities and refresh the mirror.
    */
   async start() {
     if (this.startPromise && this.startPromiseEpoch === this.lifecycleEpoch) return this.startPromise;
@@ -151,7 +147,7 @@ class WholesaleFeedSync extends EventEmitter {
     if (!await this.restorePersistedState(epoch)) return;
     if (!await this.resolveMode(epoch)) return;
     try {
-      await this.bootstrap({ epoch });
+      await this.bootstrapWithRetries({ epoch });
     } finally {
       if (this.isLifecycleCurrent(epoch)) {
         if (this._mode === "auto-poll") this.scheduleProbe(epoch);
@@ -175,6 +171,7 @@ class WholesaleFeedSync extends EventEmitter {
    */
   async reset() {
     this.stop();
+    ++this.mirrorRevision;
     this.productIndex.clear();
     this.signalIndex.clear();
     this.productWholesaleFeedVersion = void 0;
@@ -200,7 +197,7 @@ class WholesaleFeedSync extends EventEmitter {
   async refresh() {
     const epoch = this.lifecycleEpoch;
     this.emit("resyncing", { reason: "manual" });
-    await this.bootstrap({ emitDiffs: true, epoch, propagateFailure: true });
+    await this.bootstrapWithRetries({ emitDiffs: true, epoch, propagateFailure: true });
   }
   /**
    * Apply one legacy-view account-level wholesale feed webhook to the local mirror.
@@ -249,6 +246,11 @@ class WholesaleFeedSync extends EventEmitter {
       this.rememberLastWebhookEventId(event.event_id);
       throw err;
     }
+    if (!this._lastSyncedAt && event.event_type !== "wholesale_feed.bulk_change") {
+      if (!await this.recoverFromVersionMismatch(event, epoch)) return;
+      await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
+      return;
+    }
     if (webhook.previous_wholesale_feed_version && currentVersion && webhook.previous_wholesale_feed_version !== currentVersion) {
       if (!await this.recoverFromVersionMismatch(event, epoch)) return;
       await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
@@ -329,12 +331,24 @@ class WholesaleFeedSync extends EventEmitter {
     return true;
   }
   // ====== Private: bootstrap (wholesale enumeration) ======
+  async bootstrapWithRetries(options) {
+    for (let attempt = 0; attempt < VERSION_MISMATCH_RECOVERY_ATTEMPTS; attempt++) {
+      const revision = this.mirrorRevision;
+      if (await this.bootstrap({ ...options, conditional: attempt === 0 ? void 0 : false })) return;
+      if (!this.isLifecycleCurrent(options.epoch) || revision === this.mirrorRevision) return;
+    }
+    const error = new Error("WholesaleFeedSync: refresh superseded repeatedly; retry start or refresh.");
+    this.handleBootstrapFailure({ error });
+    throw error;
+  }
   async bootstrap(options = {}) {
     const epoch = options.epoch ?? this.lifecycleEpoch;
     if (!this.isLifecycleCurrent(epoch)) return false;
     this.setState("bootstrapping");
     const previousLastSyncedAt = this._lastSyncedAt;
+    const expectedRevision = this.mirrorRevision;
     let reportedFailure;
+    let committed = false;
     try {
       const previousProducts = new Map(this.productIndex);
       const previousSignals = new Map(this.signalIndex);
@@ -346,8 +360,12 @@ class WholesaleFeedSync extends EventEmitter {
       const refreshProducts = entities !== "signals";
       const refreshSignals = entities !== "products" && this.signals.queryable;
       if (refreshProducts) {
-        productResult = await this.bootstrapProducts(epoch);
+        productResult = await this.bootstrapProducts(epoch, options.conditional);
         if (productResult.cancelled) return false;
+        if (this.mirrorRevision !== expectedRevision) {
+          this.setState(this._lastSyncedAt ? "syncing" : "idle");
+          return false;
+        }
         if (productResult.failure) {
           const failure = productResult.failure;
           reportedFailure = failure.error;
@@ -361,8 +379,12 @@ class WholesaleFeedSync extends EventEmitter {
         }
       }
       if (refreshSignals) {
-        signalResult = await this.bootstrapSignals(epoch);
+        signalResult = await this.bootstrapSignals(epoch, options.conditional);
         if (signalResult.cancelled) return false;
+        if (this.mirrorRevision !== expectedRevision) {
+          this.setState(this._lastSyncedAt ? "syncing" : "idle");
+          return false;
+        }
         if (signalResult.failure) {
           const failure = signalResult.failure;
           reportedFailure = failure.error;
@@ -376,6 +398,12 @@ class WholesaleFeedSync extends EventEmitter {
         }
       }
       if (!this.isLifecycleCurrent(epoch)) return false;
+      if (this.mirrorRevision !== expectedRevision) {
+        this.setState(this._lastSyncedAt ? "syncing" : "idle");
+        return false;
+      }
+      ++this.mirrorRevision;
+      committed = true;
       if (refreshProducts && productResult) {
         this.commitProductMetadata(productResult.metadata);
         if (!productResult.unchanged) {
@@ -407,6 +435,7 @@ class WholesaleFeedSync extends EventEmitter {
       return true;
     } catch (err) {
       if (!this.isLifecycleCurrent(epoch)) return false;
+      if (!committed && this.mirrorRevision !== expectedRevision && err !== reportedFailure) return false;
       if (err === reportedFailure) throw err;
       this._lastSyncedAt = previousLastSyncedAt;
       this.setState(this._lastSyncedAt ? "degraded" : "error");
@@ -423,102 +452,74 @@ class WholesaleFeedSync extends EventEmitter {
     if (this.listenerCount("error") > 0) this.emit("error", failure);
     return false;
   }
-  /** Returns `true` when the seller short-circuited with `unchanged: true`. */
-  async bootstrapProducts(epoch) {
-    let cursor;
-    const into = /* @__PURE__ */ new Map();
-    let metadata = this.currentProductMetadata();
-    do {
-      const params = {
-        buying_mode: "wholesale",
-        pagination: { max_results: DEFAULT_BOOTSTRAP_PAGE_LIMIT, ...cursor && { cursor } },
-        ...this.account && { account: this.account }
-      };
-      if (!cursor && metadata.wholesaleFeedVersion && this._capabilities.wholesaleFeedVersioning) {
-        params.if_wholesale_feed_version = metadata.wholesaleFeedVersion;
-        if (metadata.pricingVersion) params.if_pricing_version = metadata.pricingVersion;
-      }
-      const result = await this.client.getProducts(params);
-      if (!this.isLifecycleCurrent(epoch)) return { cancelled: true, unchanged: false, items: into, metadata };
-      if (result.success === false || result.status !== void 0 && result.status !== "completed" && result.status !== "success") {
-        return {
-          cancelled: false,
-          unchanged: false,
-          items: into,
-          metadata,
-          failure: { error: new Error(result.error ?? "Product bootstrap failed"), adcpError: result.adcpError }
-        };
-      }
-      const body = result.data;
-      if (!body)
-        return {
-          cancelled: false,
-          unchanged: false,
-          items: into,
-          metadata,
-          failure: { error: new Error("Product bootstrap did not return a completed catalog") }
-        };
-      if (body.unchanged) {
-        metadata = mergeFeedMetadata(metadata, body);
-        return { cancelled: false, unchanged: true, items: into, metadata };
-      }
-      const products = Array.isArray(body.products) ? body.products : [];
-      for (const product of products) {
-        const id = product.product_id;
-        if (typeof id === "string") into.set(id, product);
-      }
-      metadata = mergeFeedMetadata(metadata, body);
-      cursor = body.pagination?.has_more ? body.pagination?.cursor : void 0;
-    } while (cursor);
-    return { cancelled: false, unchanged: false, items: into, metadata };
+  bootstrapProducts(epoch, conditional) {
+    return this.bootstrapFeed("product", epoch, conditional);
   }
-  async bootstrapSignals(epoch) {
-    let cursor;
-    const into = /* @__PURE__ */ new Map();
-    let metadata = this.currentSignalMetadata();
-    do {
-      const params = {
-        discovery_mode: "wholesale",
-        pagination: { max_results: DEFAULT_BOOTSTRAP_PAGE_LIMIT, ...cursor && { cursor } },
-        ...this.account && { account: this.account }
-      };
-      if (!cursor && metadata.wholesaleFeedVersion && this._capabilities.wholesaleFeedVersioning) {
-        params.if_wholesale_feed_version = metadata.wholesaleFeedVersion;
-        if (metadata.pricingVersion) params.if_pricing_version = metadata.pricingVersion;
-      }
-      const result = await this.client.getSignals(params);
-      if (!this.isLifecycleCurrent(epoch)) return { cancelled: true, unchanged: false, items: into, metadata };
-      if (result.success === false || result.status !== void 0 && result.status !== "completed" && result.status !== "success") {
-        return {
-          cancelled: false,
-          unchanged: false,
-          items: into,
-          metadata,
-          failure: { error: new Error(result.error ?? "Signal bootstrap failed"), adcpError: result.adcpError }
-        };
-      }
-      const body = result.data;
-      if (!body)
-        return {
-          cancelled: false,
-          unchanged: false,
-          items: into,
-          metadata,
-          failure: { error: new Error("Signal bootstrap did not return a completed catalog") }
-        };
-      if (body.unchanged) {
-        metadata = mergeFeedMetadata(metadata, body);
-        return { cancelled: false, unchanged: true, items: into, metadata };
+  bootstrapSignals(epoch, conditional) {
+    return this.bootstrapFeed("signal", epoch, conditional);
+  }
+  async bootstrapFeed(entity, epoch, conditional) {
+    const store = new InMemoryWholesaleFeedMirrorStore();
+    const scope = { agentUrl: "shell", accountKey: "shell", entity };
+    const metadata = entity === "product" ? this.currentProductMetadata() : this.currentSignalMetadata();
+    const previous = entity === "product" ? [...this.productIndex.values()] : [...this.signalIndex.values()];
+    store.restore(scope, { revision: 0, items: previous, ...metadata });
+    let readException;
+    const read = async (call) => {
+      try {
+        return await call();
+      } catch (cause) {
+        readException = cause instanceof Error ? cause : new Error(String(cause));
+        throw cause;
       }
-      const signals = Array.isArray(body.signals) ? body.signals : [];
-      for (const signal of signals) {
-        const id = signal.signal_agent_segment_id;
-        if (typeof id === "string") into.set(id, signal);
+    };
+    const outcome = await refreshWholesaleFeed({
+      client: {
+        getAdcpCapabilities: this.client.getAdcpCapabilities.bind(this.client),
+        getProducts: (params) => read(() => this.client.getProducts(params)),
+        getSignals: (params) => read(() => this.client.getSignals(params))
+      },
+      store,
+      scope,
+      account: this.account,
+      conditional: conditional ?? this._capabilities.wholesaleFeedVersioning,
+      isCurrent: () => this.isLifecycleCurrent(epoch)
+    });
+    if (outcome.outcome === "superseded") return { cancelled: true, unchanged: false, items: /* @__PURE__ */ new Map(), metadata };
+    if (outcome.outcome === "degraded") {
+      if (readException) throw readException;
+      return {
+        cancelled: false,
+        unchanged: false,
+        items: /* @__PURE__ */ new Map(),
+        metadata,
+        failure: {
+          error: new Error(
+            `${entity === "product" ? "Product" : "Signal"} bootstrap failed: ${outcome.cause.message}`,
+            {
+              cause: outcome.cause
+            }
+          ),
+          adcpError: outcome.error
+        }
+      };
+    }
+    const snapshot = outcome.snapshot;
+    return {
+      cancelled: false,
+      unchanged: outcome.outcome === "unchanged",
+      items: new Map(
+        snapshot.items.map((item) => [
+          entity === "product" ? item.product_id : item.signal_agent_segment_id,
+          item
+        ])
+      ),
+      metadata: {
+        wholesaleFeedVersion: snapshot.wholesaleFeedVersion,
+        pricingVersion: snapshot.pricingVersion,
+        cacheScope: snapshot.cacheScope
       }
-      metadata = mergeFeedMetadata(metadata, body);
-      cursor = body.pagination?.has_more ? body.pagination?.cursor : void 0;
-    } while (cursor);
-    return { cancelled: false, unchanged: false, items: into, metadata };
+    };
   }
   async recoverFromBulkChange(event, epoch = this.lifecycleEpoch) {
     this.emit("resyncing", { reason: "bulk_change" });
@@ -529,14 +530,22 @@ class WholesaleFeedSync extends EventEmitter {
       );
     }
     const entities = affected === "product" ? "products" : "signals";
-    return this.bootstrap({ emitDiffs: true, entities, epoch, propagateFailure: true });
+    for (let attempt = 0; attempt < VERSION_MISMATCH_RECOVERY_ATTEMPTS; attempt++) {
+      if (await this.bootstrap({ emitDiffs: true, entities, epoch, propagateFailure: true })) return true;
+      if (!this.isLifecycleCurrent(epoch)) return false;
+    }
+    throw supersededRepairError();
   }
   async recoverFromVersionMismatch(event, epoch = this.lifecycleEpoch) {
     this.emit("resyncing", { reason: "version_mismatch" });
     const beforeVersion = this.currentWholesaleFeedVersionForEvent(event);
     for (let attempt = 1; attempt <= VERSION_MISMATCH_RECOVERY_ATTEMPTS; attempt++) {
       const recovered = await this.bootstrap({ emitDiffs: true, epoch, propagateFailure: true });
-      if (!recovered) return false;
+      if (!recovered) {
+        if (!this.isLifecycleCurrent(epoch)) return false;
+        if (attempt === VERSION_MISMATCH_RECOVERY_ATTEMPTS) throw supersededRepairError();
+        continue;
+      }
       const afterVersion = this.currentWholesaleFeedVersionForEvent(event);
       if (afterVersion !== beforeVersion) return true;
       if (attempt < VERSION_MISMATCH_RECOVERY_ATTEMPTS) {
@@ -690,63 +699,16 @@ class WholesaleFeedSync extends EventEmitter {
     }
   }
   applyEvent(event) {
-    switch (event.event_type) {
-      case "product.created":
-      case "product.updated": {
-        const payload = event.payload;
-        if (typeof payload.product_id !== "string") return;
-        if (payload.product) {
-          this.productIndex.set(payload.product_id, payload.product);
-          return;
-        }
-        return;
-      }
-      case "product.priced": {
-        const payload = event.payload;
-        const existing = this.productIndex.get(payload.product_id);
-        if (existing && Array.isArray(payload.pricing_options)) {
-          this.productIndex.set(payload.product_id, {
-            ...existing,
-            pricing_options: payload.pricing_options
-          });
-        }
-        return;
-      }
-      case "product.removed": {
-        const payload = event.payload;
-        if (typeof payload.product_id === "string") this.productIndex.delete(payload.product_id);
-        return;
-      }
-      case "signal.created":
-      case "signal.updated": {
-        const payload = event.payload;
-        if (typeof payload.signal_agent_segment_id !== "string") return;
-        if (payload.signal) {
-          this.signalIndex.set(payload.signal_agent_segment_id, payload.signal);
-        }
-        return;
-      }
-      case "signal.priced": {
-        const payload = event.payload;
-        const existing = this.signalIndex.get(payload.signal_agent_segment_id);
-        if (existing && Array.isArray(payload.pricing_options)) {
-          this.signalIndex.set(payload.signal_agent_segment_id, {
-            ...existing,
-            pricing_options: payload.pricing_options
-          });
-        }
-        return;
-      }
-      case "signal.removed": {
-        const payload = event.payload;
-        if (typeof payload.signal_agent_segment_id === "string") {
-          this.signalIndex.delete(payload.signal_agent_segment_id);
-        }
-        return;
-      }
-      case "wholesale_feed.bulk_change":
-        return;
-    }
+    ++this.mirrorRevision;
+    const entity = event.event_type.startsWith("product.") ? "product" : "signal";
+    const items = applyWholesaleFeedEvent(
+      entity,
+      entity === "product" ? [...this.productIndex.values()] : [...this.signalIndex.values()],
+      event
+    );
+    if (!items) return;
+    if (entity === "product") this.productIndex = new Map(items.map((item) => [item.product_id, item]));
+    else this.signalIndex = new Map(items.map((item) => [item.signal_agent_segment_id, item]));
   }
   emitTypedEvent(event) {
     switch (event.event_type) {
@@ -780,107 +742,23 @@ class WholesaleFeedSync extends EventEmitter {
   }
   // ====== Private: diff emission (auto-poll / manual refresh) ======
   emitDiffs(previousProducts, previousSignals) {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const makeEvent = (event_type, entity_type, entity_id, payload) => ({
-      // crypto.randomUUID() emits a v4 UUID, NOT v7. Synthetic events
-      // are flagged via `synthetic: true` on the emit envelope so
-      // adopters writing event_ids to a dedupe table know not to
-      // treat the ID as seller-authored. Real webhook events carry the
-      // agent's authoritative event_id.
-      event_id: randomUUID(),
-      event_type,
-      entity_type,
-      entity_id,
-      created_at: now,
-      payload
-    });
-    const emit = (channel, event) => {
+    const events = [
+      ...diffWholesaleFeed(
+        "product",
+        [...previousProducts.values()],
+        [...this.productIndex.values()],
+        this.productCacheScope
+      ),
+      ...diffWholesaleFeed(
+        "signal",
+        [...previousSignals.values()],
+        [...this.signalIndex.values()],
+        this.signalCacheScope
+      )
+    ];
+    for (const event of events) {
       this.emit("event", { event, synthetic: true });
-      this.emit(channel, { event, synthetic: true });
-    };
-    for (const [id, product] of this.productIndex) {
-      const prev = previousProducts.get(id);
-      if (!prev) {
-        emit(
-          "product.created",
-          makeEvent("product.created", "product", id, {
-            product_id: id,
-            product,
-            applies_to: { scope: this.productCacheScope }
-          })
-        );
-      } else if (priceChanged(prev, product)) {
-        emit(
-          "product.priced",
-          makeEvent("product.priced", "product", id, {
-            product_id: id,
-            pricing_options: product.pricing_options ?? [],
-            applies_to: { scope: this.productCacheScope }
-          })
-        );
-      } else if (!isDeepStrictEqual(prev, product)) {
-        emit(
-          "product.updated",
-          makeEvent("product.updated", "product", id, {
-            product_id: id,
-            product,
-            applies_to: { scope: this.productCacheScope }
-          })
-        );
-      }
-    }
-    for (const [id] of previousProducts) {
-      if (!this.productIndex.has(id)) {
-        emit(
-          "product.removed",
-          makeEvent("product.removed", "product", id, {
-            product_id: id,
-            applies_to: { scope: this.productCacheScope }
-          })
-        );
-      }
-    }
-    for (const [id, signal] of this.signalIndex) {
-      const prev = previousSignals.get(id);
-      if (!prev) {
-        emit(
-          "signal.created",
-          makeEvent("signal.created", "signal", id, {
-            signal_agent_segment_id: id,
-            signal,
-            applies_to: { scope: this.signalCacheScope }
-          })
-        );
-      } else if (signalPriceChanged(prev, signal)) {
-        emit(
-          "signal.priced",
-          makeEvent("signal.priced", "signal", id, {
-            signal_agent_segment_id: id,
-            pricing_options: signal.pricing_options ?? [],
-            applies_to: { scope: this.signalCacheScope }
-          })
-        );
-      } else if (!isDeepStrictEqual(prev, signal)) {
-        emit(
-          "signal.updated",
-          makeEvent("signal.updated", "signal", id, {
-            signal_agent_segment_id: id,
-            signal,
-            applies_to: { scope: this.signalCacheScope }
-          })
-        );
-      }
-    }
-    for (const [id] of previousSignals) {
-      if (!this.signalIndex.has(id)) {
-        emit(
-          "signal.removed",
-          makeEvent("signal.removed", "signal", id, {
-            signal_agent_segment_id: id,
-            applies_to: { scope: this.signalCacheScope }
-          })
-        );
-      }
+      this.emit(event.event_type, { event, synthetic: true });
     }
   }
   // ====== Private: search ======
@@ -1057,16 +935,6 @@ function assertOptionalDate(value, field, invalid) {
 function parsePersistedDate(value) {
   return value === void 0 ? void 0 : new Date(value);
 }
-function priceChanged(prev, next) {
-  const a = prev.pricing_options;
-  const b = next.pricing_options;
-  return !isDeepStrictEqual(a, b);
-}
-function signalPriceChanged(prev, next) {
-  const a = prev.pricing_options;
-  const b = next.pricing_options;
-  return !isDeepStrictEqual(a, b);
-}
 function isUuidV7(value) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
 }
@@ -1076,13 +944,6 @@ function compareUuidV7(a, b) {
   const normalizedB = b.toLowerCase();
   return normalizedA === normalizedB ? 0 : normalizedA > normalizedB ? 1 : -1;
 }
-function mergeFeedMetadata(current, body) {
-  return {
-    wholesaleFeedVersion: typeof body.wholesale_feed_version === "string" ? body.wholesale_feed_version : current.wholesaleFeedVersion,
-    pricingVersion: typeof body.pricing_version === "string" ? body.pricing_version : current.pricingVersion,
-    cacheScope: body.cache_scope === "public" || body.cache_scope === "account" ? body.cache_scope : current.cacheScope
-  };
-}
 async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }

package/docs/README.md

@@ -25,6 +25,12 @@ Use the [buyer quick start](./guides/BUYER-QUICKSTART-3.2.md). For the complete
 tool and type inventory, use [llms.txt](./llms.txt) and the
 [type summary](./TYPE-SUMMARY.md).
 
+## Upgrade from SDK 14.0
+
+Use the [14.0-to-14.1 upgrade checklist](./migration-14.0-to-14.1.md) for
+required changes, opt-in features, and stricter signature verification. SDK
+14.1.0 continues to use AdCP 3.2.1 on the wire.
+
 ## Upgrade from SDK 13
 
 Start with the [release-bound upgrade worksheet](./migration-14.x-rc-worksheet.md),

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-04
-> @adcp/sdk v14.1.0
+> Generated at: 2026-10-05
+> @adcp/sdk v14.2.0
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/guides/BUYER-STORAGE.md

@@ -0,0 +1,3 @@
+# Buyer-owned storage and scheduling
+
+See the [adapter contracts and recovery guide](https://github.com/adcontextprotocol/adcp-client/blob/main/docs/development/BUYER-STORAGE.md) for timer-free catalog mirrors, CAS provisioning, dispatch hooks, and caller-owned replay keys.

package/docs/guides/FIRST-CALL-TO-A-SELLER.md

@@ -71,7 +71,9 @@ from authoritative `list_accounts`. The notification's status is not trusted as
 a snapshot, which avoids reordered deliveries overwriting current state.
 
 The registry is in memory by default. Set `accountStorage` to an adapter with
-`get(key)` and `set(key, entry)` for persistence. Keys partition by seller URI,
+`get(key)` and `set(key, entry)` for persistence. For multiple processes, add
+revision-checked `compareAndSet` writes and dispatch ledger hooks; see
+[buyer storage and scheduling](BUYER-STORAGE.md). Keys partition by seller URI,
 protocol, and caller scope. Client-credentials OAuth uses the stable client ID, token endpoint, scopes, and resource. Authorization-code OAuth pins this client's initial grant fingerprint, keeping distinct user grants apart while automatic refreshes preserve its partition. Create a new client when switching users. Other credential modes fingerprint credentials;
 for continuity across token rotations, supply `accountRegistryScope` from a
 trusted stable principal identifier. Never share that scope between tenants.