@adcp/sdk 14.0.0 → 14.2.0

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

@@ -0,0 +1,578 @@
+import { isDeepStrictEqual } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { accountReferenceKey } from "./account-key.mjs";
+import { sameCountrySet } from "./account-resolution.mjs";
+import { adcpErrorToTypedError, AccountNotFoundError, AccountSetupRequiredError } from "../errors/index.mjs";
+import { isAbortOrTimeoutError, MAX_TIMER_DELAY_MS, throwIfAborted, withAbortSignal } from "../protocols/abort.mjs";
+import { withTaskDeadline } from "./task-deadline.mjs";
+import { isValidIdempotencyKey } from "../utils/idempotency.mjs";
+function setupTerms(options) {
+  const stable = (value) => Array.isArray(value) ? value.map(stable) : value && typeof value === "object" ? Object.fromEntries(
+    Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, stable(item)])
+  ) : value;
+  return Object.fromEntries(
+    Object.entries(options).filter(([key]) => key !== "idempotencyKey").map(([key, value]) => [
+      key,
+      createHash("sha256").update(JSON.stringify(stable(value))).digest("hex")
+    ])
+  );
+}
+function isDefinitiveRejection(result) {
+  return Boolean(
+    result.adcpError && !result.adcpError.synthetic && !result.adcpError.code.startsWith("IDEMPOTENCY_") && ["terminal", "correctable"].includes(result.adcpError.recovery ?? "")
+  );
+}
+class BuyerAccountRegistry {
+  constructor(scope, provision, storage, repair, registryOptions = {}) {
+    this.scope = scope;
+    this.provision = provision;
+    this.storage = storage;
+    this.repair = repair;
+    this.registryOptions = registryOptions;
+    this.maxEntries = registryOptions.maxEntries ?? 1e4;
+    this.normalizeOptions = registryOptions.normalizeOptions;
+    if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries < 2)
+      throw new Error("Account registry maxEntries must be an integer >= 2.");
+  }
+  scope;
+  provision;
+  storage;
+  repair;
+  registryOptions;
+  entries = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  writes = Promise.resolve();
+  repairs = /* @__PURE__ */ new Map();
+  repairWaiters = /* @__PURE__ */ new Map();
+  invalidatedHandles = /* @__PURE__ */ new Set();
+  observationEpoch = 0;
+  observationFloor = 0;
+  statusEpochs = /* @__PURE__ */ new Map();
+  maxEntries;
+  normalizeOptions;
+  key(account, scope = this.scope()) {
+    return `${scope}:${accountReferenceKey(account)}`;
+  }
+  /** Capture before a seller request; observations older than a status repair are ignored. */
+  captureObservation() {
+    return this.observationEpoch;
+  }
+  observationIsCurrent(accountId, epoch, scope) {
+    return epoch === void 0 || epoch >= this.observationFloor && (!accountId || (this.statusEpochs.get(this.key({ account_id: accountId }, scope)) ?? 0) <= epoch);
+  }
+  remember(key, entry) {
+    if (!this.entries.has(key) && this.entries.size >= this.maxEntries) {
+      if (!this.storage)
+        throw new AccountSetupRequiredError(
+          "Account registry capacity reached; configure durable storage or increase maxEntries."
+        );
+      this.entries.delete(this.entries.keys().next().value);
+    }
+    this.entries.set(key, structuredClone(entry));
+  }
+  async get(account) {
+    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 (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))
+      throw new Error("CAS account storage must return a positive integer revision.");
+    if (entry) this.remember(key, entry);
+    if (entry?.account_id && this.invalidatedHandles.has(this.key({ account_id: entry.account_id })))
+      return { ...structuredClone(entry), status: "unknown" };
+    return entry ? structuredClone(entry) : void 0;
+  }
+  async ensure(account, options = {}, taskOptions, onTaskResult) {
+    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}`);
+    account = structuredClone(account);
+    if (this.normalizeOptions) options = await this.normalizeOptions(structuredClone(options), taskOptions);
+    options = structuredClone(Object.fromEntries(Object.entries(options).filter(([, value]) => value !== void 0)));
+    if (options.idempotencyKey !== void 0 && !isValidIdempotencyKey(options.idempotencyKey))
+      throw new TypeError("idempotencyKey must match [A-Za-z0-9_.:-]{16,255}.");
+    const scope = this.scope();
+    const key = this.key(account, scope);
+    const current = await this.get(account);
+    throwIfAborted(taskOptions?.signal);
+    if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
+    const shared = this.pending.get(key);
+    const wait = (promise) => withTaskDeadline(
+      taskOptions,
+      (options2) => withAbortSignal([options2.signal], void 0, () => promise.then((entry2) => structuredClone(entry2)))
+    );
+    if (shared) {
+      if (!isDeepStrictEqual(shared.options, options))
+        throw new AccountSetupRequiredError(
+          "Provisioning is already in progress with different billing terms or idempotency keys."
+        );
+      const entry2 = await wait(shared.promise);
+      if (shared.result) onTaskResult?.(shared.result);
+      return entry2;
+    }
+    const terms = setupTerms(options);
+    if (current?.status === "failed_provisioning" && current.setupTerms && !isDeepStrictEqual(current.setupTerms, terms))
+      throw new AccountSetupRequiredError(
+        "The pending account was provisioned with different billing terms. Call syncAccounts explicitly to change terms."
+      );
+    if (current && current.status !== "failed_provisioning") {
+      if (Object.entries(terms ?? {}).some(
+        ([name, value]) => current.setupTerms?.[name] !== void 0 && current.setupTerms[name] !== value
+      ))
+        throw new AccountSetupRequiredError(
+          "The account was provisioned with different billing terms. Call syncAccounts explicitly to change terms."
+        );
+      if (current.status !== "active" && current.account_id && this.repair) {
+        try {
+          await this.repairStatus(current.account_id, taskOptions, false);
+        } catch (error) {
+          throwIfAborted(taskOptions?.signal);
+          if (isAbortOrTimeoutError(error)) throw error;
+          if (scope !== this.scope())
+            throw new AccountNotFoundError("Caller credentials changed during reconciliation.");
+          return current;
+        }
+        const refreshed = await this.get(account) ?? current;
+        if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during reconciliation.");
+        if (refreshed.status === "unknown")
+          throw new AccountNotFoundError(
+            "The seller no longer lists this account. Call syncAccounts explicitly to reestablish it."
+          );
+        return refreshed;
+      }
+      if (current.status === "unknown")
+        throw new AccountNotFoundError(
+          "Reconcile this account with listAccounts or explicitly reestablish it with syncAccounts."
+        );
+      if (current.status === "provisioning" && current.dispatch)
+        throw new AccountSetupRequiredError(
+          `Provisioning is claimed or in doubt in durable storage.${current.pendingTaskId ? ` Recover task ${current.pendingTaskId}.` : ""} Reconcile the recorded idempotency key and observeSync before retrying.`
+        );
+      if (current.status === "provisioning" && current.pendingTaskId)
+        throw new AccountSetupRequiredError(
+          `Reconcile pending sync_accounts task ${current.pendingTaskId} and observe its completed account rows before provisioning again.`
+        );
+      if (current.status !== "pending_approval" || current.account_id) return current;
+      if (!current.setupTerms || !isDeepStrictEqual(current.setupTerms, terms))
+        throw new AccountSetupRequiredError(
+          "Provide the original billing options to refresh a legacy account without a handle, or call syncAccounts explicitly."
+        );
+    }
+    const requiredEntries = current ? 1 : 2;
+    if (!this.storage && this.entries.size + this.pending.size * 2 + requiredEntries > this.maxEntries) {
+      throw new AccountSetupRequiredError(
+        "Account registry capacity reached; configure durable storage or increase maxEntries."
+      );
+    }
+    const pending = { promise: void 0, options: structuredClone(options) };
+    let callbackFailed = false;
+    let callbackError;
+    const notify = (result) => {
+      try {
+        onTaskResult?.(result);
+      } catch (error) {
+        callbackFailed = true;
+        callbackError = error;
+      }
+    };
+    const operationOptions = { ...taskOptions, signal: void 0, timeout: void 0 };
+    const observationEpoch = this.captureObservation();
+    const idempotencyKey = options.idempotencyKey ?? randomUUID();
+    const dispatch = { storageKey: key, account: structuredClone(account), idempotencyKey };
+    let claimRevision;
+    let dispatched = false;
+    const releaseClaim = async () => {
+      if (!this.storage?.compareAndSet || claimRevision === void 0) return;
+      const latest = await this.storage.get(key);
+      if (latest?.revision !== claimRevision || latest.dispatch?.idempotencyKey !== idempotencyKey) return;
+      await this.write({ ...latest, status: "failed_provisioning", dispatch: void 0 }, scope);
+    };
+    const beforeDispatch = async () => {
+      if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed before dispatch.");
+      if (this.storage?.compareAndSet) {
+        await this.write(
+          {
+            account,
+            status: "provisioning",
+            setupTerms: terms,
+            revision: current?.revision,
+            dispatch: { idempotencyKey, startedAt: (/* @__PURE__ */ new Date()).toISOString() }
+          },
+          scope
+        );
+        claimRevision = (current?.revision ?? 0) + 1;
+      }
+      await this.registryOptions.onDispatchStart?.(structuredClone(dispatch));
+      if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed before dispatch.");
+      dispatched = true;
+    };
+    const request = (async () => {
+      try {
+        if (!this.registryOptions.provisionOwnsDispatchBoundary) await beforeDispatch();
+        return await this.provision(structuredClone(account), pending.options, operationOptions, {
+          idempotencyKey,
+          beforeDispatch,
+          requireIdempotencyKey: Boolean(
+            options.idempotencyKey || this.storage?.compareAndSet || this.registryOptions.onDispatchStart || this.registryOptions.onResult
+          )
+        });
+      } catch (error) {
+        if (!dispatched) await releaseClaim();
+        throw error;
+      }
+    })().then(async (initial) => {
+      let result = initial;
+      pending.result = result;
+      if (dispatched) await this.registryOptions.onResult?.({ ...structuredClone(dispatch), result });
+      notify(result);
+      if (this.key(account) !== key) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
+      if (!result.success) {
+        if (!dispatched || isDefinitiveRejection(result)) await releaseClaim();
+        throw adcpErrorToTypedError(result.adcpError ?? { code: "ACCOUNT_NOT_FOUND", message: result.error }) ?? new Error(result.error);
+      }
+      if (result.status !== "completed") {
+        const provisional = {
+          account: structuredClone(account),
+          status: "provisioning",
+          setupTerms: current?.setupTerms ?? terms,
+          ...(result.metadata.serverTaskId ?? result.metadata.taskId) && {
+            pendingTaskId: result.metadata.serverTaskId ?? result.metadata.taskId
+          }
+        };
+        await this.enqueue(async () => {
+          const latest = await this.get(account);
+          if (this.storage?.compareAndSet ? latest?.revision === claimRevision && latest?.dispatch?.idempotencyKey === idempotencyKey : !latest || latest.status === "failed_provisioning" || latest.status === current?.status && latest.account_id === current?.account_id) {
+            await this.write({ ...provisional, revision: latest?.revision, dispatch: latest?.dispatch }, scope);
+            if (claimRevision !== void 0) claimRevision = (latest?.revision ?? 0) + 1;
+          }
+        });
+        if (!result.submitted) return provisional;
+        result = await result.submitted.waitForCompletion();
+        pending.result = result;
+        await this.registryOptions.onResult?.({ ...structuredClone(dispatch), result });
+        notify(result);
+        if (!result.success) {
+          if (this.storage?.compareAndSet) {
+            if (isDefinitiveRejection(result)) await releaseClaim();
+          } else {
+            await this.enqueue(async () => {
+              const latest = await this.get(account);
+              if (!latest || latest.status === "provisioning")
+                await this.write(
+                  {
+                    account: structuredClone(account),
+                    status: "failed_provisioning",
+                    setupTerms: current?.setupTerms ?? terms
+                  },
+                  scope
+                );
+            });
+          }
+          throw adcpErrorToTypedError(result.adcpError ?? { code: "ACCOUNT_SETUP_REQUIRED", message: result.error }) ?? new Error(result.error);
+        }
+      }
+      if (this.key(account) !== key) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
+      if (result.status !== "completed" || !result.data || !("accounts" in result.data))
+        throw new AccountSetupRequiredError(
+          "sync_accounts has not completed; observe its completion before provisioning again."
+        );
+      await this.observeSync([account], result.data.accounts, false, observationEpoch, claimRevision);
+      const entry2 = await this.get(account);
+      if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
+      if (!entry2 || entry2.status === "provisioning" || entry2.status === "failed_provisioning") {
+        if (this.storage?.compareAndSet) await releaseClaim();
+        else
+          await this.enqueue(async () => {
+            const latest = await this.get(account);
+            if (!latest || ["provisioning", "failed_provisioning"].includes(latest.status))
+              await this.write(
+                { account, status: "failed_provisioning", setupTerms: current?.setupTerms ?? terms },
+                scope
+              );
+          });
+        const failed = result.data.accounts.find((row) => row.action === "failed");
+        const error = failed?.errors?.[0];
+        throw (error && adcpErrorToTypedError(error)) ?? new AccountNotFoundError("sync_accounts did not establish the requested account.");
+      }
+      if (claimRevision !== void 0 && entry2.revision !== claimRevision + 1) return entry2;
+      let settled = entry2;
+      await this.enqueue(async () => {
+        const latest = await this.get(account);
+        if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
+        if (!latest) throw new AccountNotFoundError("The provisioned account is no longer registered.");
+        settled = latest;
+        if (latest.account_id !== entry2.account_id || this.storage?.compareAndSet && latest.revision !== entry2.revision)
+          return;
+        settled = { ...latest, setupTerms: setupTerms(options) };
+        await this.write(settled, scope);
+        settled = await this.get(account) ?? settled;
+        if (settled.account_id && !("account_id" in account)) {
+          const idEntry = await this.get({ account_id: settled.account_id });
+          if (scope !== this.scope()) throw new AccountNotFoundError("Caller credentials changed during provisioning.");
+          if (idEntry) await this.write({ ...idEntry, setupTerms: settled.setupTerms }, scope);
+        }
+      });
+      return settled;
+    });
+    pending.promise = request;
+    this.pending.set(key, pending);
+    const cleanup = () => {
+      if (this.pending.get(key) === pending) this.pending.delete(key);
+    };
+    void request.then(cleanup, cleanup);
+    const entry = await wait(request);
+    if (callbackFailed) throw callbackError;
+    return entry;
+  }
+  async write(entry, scope, isCurrent = () => true) {
+    if (!isCurrent()) return;
+    const key = this.key(entry.account, scope);
+    if (this.storage?.compareAndSet) {
+      const revision = entry.revision;
+      entry = { ...entry, revision: (revision ?? 0) + 1 };
+      if (!await this.storage.compareAndSet(key, revision, structuredClone(entry)))
+        throw new AccountSetupRequiredError("Account storage revision changed. Reload and reconcile before retrying.");
+    } else {
+      await this.storage?.set(key, structuredClone(entry));
+    }
+    if (scope === this.scope()) this.remember(key, entry);
+  }
+  async record(ref, row, scope, preserveTerms = false, isCurrent = () => true, expectedRevision) {
+    const entry = {
+      account: structuredClone(ref),
+      status: row.status,
+      ...row.account_id && { account_id: row.account_id }
+    };
+    const prior = await this.get(ref);
+    if (expectedRevision !== void 0 && prior?.revision !== expectedRevision) return;
+    if (scope !== this.scope() || !isCurrent()) return;
+    const idRef = row.account_id && !("account_id" in ref) ? { account_id: row.account_id } : void 0;
+    const priorId = idRef ? await this.get(idRef) : void 0;
+    if (scope !== this.scope() || !isCurrent()) return;
+    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 (!("account_id" in ref) && prior?.account_id && prior.account_id !== row.account_id) {
+      const oldId = await this.get({ account_id: prior.account_id });
+      if (scope !== this.scope() || !isCurrent()) return;
+      if (oldId?.aliases) {
+        await this.write(
+          { ...oldId, aliases: oldId.aliases.filter((alias) => accountReferenceKey(alias) !== accountReferenceKey(ref)) },
+          scope,
+          isCurrent
+        );
+      }
+    }
+    entry.revision = prior?.revision;
+    if (preserveTerms && prior?.setupTerms) entry.setupTerms = prior.setupTerms;
+    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
+    );
+  }
+  enqueue(run) {
+    const next = this.writes.then(run);
+    this.writes = next.catch(() => {
+    });
+    return next;
+  }
+  async observeSync(refs, rows, dryRun = false, observationEpoch, expectedRevision) {
+    if (dryRun) return;
+    const scope = this.scope();
+    return this.enqueue(async () => {
+      if (scope !== this.scope()) return;
+      for (const ref of refs) {
+        const candidates = rows.filter((value) => {
+          if (!value || typeof value !== "object") return false;
+          const row2 = value;
+          if ("account_id" in ref) return row2.account_id === ref.account_id;
+          return row2.brand?.domain === ref.brand.domain && row2.operator === ref.operator && (!ref.brand.brand_id || row2.brand.brand_id === ref.brand.brand_id) && sameCountrySet(ref.brand.countries, row2.brand.countries) && (!ref.operator_unit || row2.operator_unit?.id === ref.operator_unit.id) && (!ref.currency || row2.currency === ref.currency) && (!ref.timezone || row2.timezone === ref.timezone) && (row2.sandbox === void 0 || row2.sandbox === true === (ref.sandbox === true));
+        });
+        if (candidates.length !== 1) continue;
+        let row = candidates[0];
+        if (row.action === "failed" || typeof row.status !== "string") continue;
+        const prior = await this.get(ref);
+        if (scope !== this.scope()) return;
+        let rowEpoch = observationEpoch;
+        let repairedBinding = false;
+        if (!this.observationIsCurrent(row.account_id, rowEpoch, scope)) {
+          if (!row.account_id || prior?.account_id && prior.account_id !== row.account_id) continue;
+          const captured = this.captureObservation();
+          const authoritative = await this.get({ account_id: row.account_id });
+          if (scope !== this.scope()) return;
+          row = {
+            ...row,
+            status: captured === this.captureObservation() ? authoritative?.status ?? "unknown" : "unknown"
+          };
+          rowEpoch = this.captureObservation();
+          repairedBinding = true;
+        }
+        const isCurrent = () => scope === this.scope() && this.observationIsCurrent(row.account_id, rowEpoch, scope);
+        await this.record(ref, row, scope, false, isCurrent, expectedRevision);
+        if (!isCurrent() || repairedBinding) continue;
+        for (const id of [row.account_id])
+          if (id) {
+            const key = this.key({ account_id: id }, scope);
+            this.repairs.delete(key);
+            this.invalidatedHandles.delete(key);
+          }
+      }
+    });
+  }
+  async reconcileId(accountId, status, scope, isCurrent = () => true) {
+    if (scope !== this.scope() || !isCurrent()) return;
+    const idRef = { account_id: accountId };
+    const indexed = await this.get(idRef);
+    if (scope !== this.scope() || !isCurrent()) return;
+    const aliases = new Map((indexed?.aliases ?? []).map((ref) => [accountReferenceKey(ref), ref]));
+    for (const [key, entry] of this.entries) {
+      if (key === this.key(entry.account, scope) && entry.account_id === accountId && !("account_id" in entry.account)) {
+        aliases.set(accountReferenceKey(entry.account), entry.account);
+      }
+    }
+    for (const ref of aliases.values()) {
+      const prior = await this.get(ref);
+      if (scope !== this.scope() || !isCurrent()) return;
+      if (!prior || prior.account_id !== accountId) {
+        aliases.delete(accountReferenceKey(ref));
+        continue;
+      }
+      await this.write({ ...prior, account: ref, account_id: accountId, status }, scope, isCurrent);
+    }
+    if (scope !== this.scope() || !isCurrent()) return;
+    if (indexed || aliases.size)
+      await this.write(
+        { ...indexed, account: idRef, account_id: accountId, status, aliases: [...aliases.values()] },
+        scope,
+        isCurrent
+      );
+  }
+  async observeList(rows, queriedAccountId, observationEpoch) {
+    const scope = this.scope();
+    return this.observeListAtScope(rows, queriedAccountId, scope, void 0, observationEpoch);
+  }
+  async observeListAtScope(rows, queriedAccountId, scope, isCurrent, observationEpoch) {
+    return this.enqueue(async () => {
+      if (scope !== this.scope() || isCurrent && !isCurrent()) return;
+      if (!this.observationIsCurrent(queriedAccountId, observationEpoch, scope)) return;
+      let foundQuery = false;
+      for (const value of rows) {
+        if (!value || typeof value !== "object") continue;
+        const row = value;
+        if (typeof row.account_id !== "string" || typeof row.status !== "string") continue;
+        if (!this.observationIsCurrent(row.account_id, observationEpoch, scope)) continue;
+        const current = () => scope === this.scope() && (!isCurrent || isCurrent()) && this.observationIsCurrent(row.account_id, observationEpoch, scope);
+        if (row.account_id === queriedAccountId) foundQuery = true;
+        await this.reconcileId(row.account_id, row.status, scope, current);
+        await this.record({ account_id: row.account_id }, row, scope, true, current);
+        if (row.brand?.domain && row.operator) {
+          const ref = {
+            brand: row.brand,
+            operator: row.operator,
+            ...row.operator_unit && { operator_unit: row.operator_unit },
+            ...row.currency && { currency: row.currency },
+            ...row.timezone && { timezone: row.timezone },
+            ...row.sandbox !== void 0 && { sandbox: row.sandbox }
+          };
+          const prior = await this.get(ref);
+          if (scope !== this.scope()) return;
+          if (!prior?.account_id || prior.account_id === row.account_id)
+            await this.record(ref, row, scope, true, current);
+        }
+        if (!isCurrent && current()) {
+          const key = this.key({ account_id: row.account_id }, scope);
+          this.repairs.delete(key);
+          this.invalidatedHandles.delete(key);
+        }
+      }
+      if (queriedAccountId && !foundQuery) {
+        const current = () => scope === this.scope() && (!isCurrent || isCurrent()) && this.observationIsCurrent(queriedAccountId, observationEpoch, scope);
+        await this.reconcileId(queriedAccountId, "unknown", scope, current);
+        if (!isCurrent && current()) {
+          const key = this.key({ account_id: queriedAccountId }, scope);
+          this.repairs.delete(key);
+          this.invalidatedHandles.delete(key);
+        }
+      }
+    });
+  }
+  /** After verifying account.status_changed, repair aliases by handle from the authoritative seller. */
+  async applyStatusChange(notification, options) {
+    return this.repairStatus(notification.account_id, options, true);
+  }
+  async repairStatus(accountId, options, invalidate) {
+    throwIfAborted(options?.signal);
+    const key = this.key({ account_id: accountId });
+    let operation = !invalidate ? this.repairWaiters.get(key) : void 0;
+    if (!operation) {
+      operation = this.runRepair(accountId, { ...options, signal: void 0, timeout: void 0 }, invalidate);
+      this.repairWaiters.set(key, operation);
+      const cleanup = () => {
+        if (this.repairWaiters.get(key) === operation) this.repairWaiters.delete(key);
+      };
+      void operation.then(cleanup, cleanup);
+    }
+    const wait = (promise) => withTaskDeadline(options, (taskOptions) => withAbortSignal([taskOptions.signal], void 0, () => promise));
+    await wait(operation);
+    let newer = this.repairWaiters.get(key);
+    while (newer && newer !== operation) {
+      operation = newer;
+      await wait(operation);
+      newer = this.repairWaiters.get(key);
+    }
+  }
+  async runRepair(accountId, options, invalidate) {
+    if (!this.repair) throw new Error("Account registry requires a list_accounts repair callback.");
+    const scope = this.scope();
+    const key = this.key({ account_id: accountId }, scope);
+    const token = {};
+    this.statusEpochs.delete(key);
+    this.statusEpochs.set(key, ++this.observationEpoch);
+    if (this.statusEpochs.size > this.maxEntries) {
+      const oldestKey = this.statusEpochs.keys().next().value;
+      this.observationFloor = this.statusEpochs.get(oldestKey);
+      this.statusEpochs.delete(oldestKey);
+    }
+    this.repairs.set(key, token);
+    if (invalidate) this.invalidatedHandles.add(key);
+    let invalidationPersisted = !invalidate;
+    try {
+      if (invalidate) {
+        await this.enqueue(() => this.reconcileId(accountId, "unknown", scope, () => this.repairs.get(key) === token));
+        invalidationPersisted = true;
+      }
+      const rows = (await this.repair(accountId, options)).filter(
+        (row) => row !== null && typeof row === "object" && row.account_id === accountId
+      );
+      await this.observeListAtScope(rows, accountId, scope, () => this.repairs.get(key) === token);
+    } finally {
+      if (this.repairs.get(key) === token) {
+        this.repairs.delete(key);
+        if (invalidationPersisted) this.invalidatedHandles.delete(key);
+      }
+    }
+  }
+}
+export {
+  BuyerAccountRegistry
+};

package/dist/lib/core/product-cache.d.mts

@@ -0,0 +1,18 @@
+import type { TaskResult } from './ConversationTypes.mjs';
+export interface ProductCacheOptions {
+    maxEntries?: number;
+    publicTtl?: number;
+    accountTtl?: number;
+}
+/** Cache response scope and both feed tokens together. Account overlays never share entries. */
+export declare class ProductCache {
+    private options;
+    private entries;
+    constructor(options?: ProductCacheOptions);
+    private key;
+    read<T>(scope: string, params: Record<string, unknown>, allowExpired?: boolean): TaskResult<T> | undefined;
+    conditionalParams(scope: string, params: Record<string, unknown>): Record<string, unknown>;
+    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>): TaskResult<T>;
+    clear(): void;
+}
+export declare function createProductCache(options?: ProductCacheOptions): ProductCache;

package/dist/lib/core/product-cache.d.ts

@@ -0,0 +1,18 @@
+import type { TaskResult } from './ConversationTypes';
+export interface ProductCacheOptions {
+    maxEntries?: number;
+    publicTtl?: number;
+    accountTtl?: number;
+}
+/** Cache response scope and both feed tokens together. Account overlays never share entries. */
+export declare class ProductCache {
+    private options;
+    private entries;
+    constructor(options?: ProductCacheOptions);
+    private key;
+    read<T>(scope: string, params: Record<string, unknown>, allowExpired?: boolean): TaskResult<T> | undefined;
+    conditionalParams(scope: string, params: Record<string, unknown>): Record<string, unknown>;
+    write<T>(scope: string, params: Record<string, unknown>, result: TaskResult<T>, conditionalSnapshot?: TaskResult<T>): TaskResult<T>;
+    clear(): void;
+}
+export declare function createProductCache(options?: ProductCacheOptions): ProductCache;