@porulle/plugin-channel-connector 0.48.1 → 0.50.0

package/src/service.ts

@@ -23,8 +23,12 @@ import type {
   PluginResult,
   PluginTxFn,
   CatalogWriteContext,
+  ImportProduct,
+  ImportProductsOptions,
+  ImportProductsReport,
   TxContext,
 } from "@porulle/core";
+import type { ChannelCatalogImage } from "@porulle/core";
 import { isValidFieldPath, requireUserId } from "@porulle/core";
 import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
@@ -523,6 +527,11 @@ interface CatalogService {
     actor: Actor | null,
   ): Promise<{ ok: true; value: undefined } | { ok: false; error: { message: string } }>;
   seedImportedFieldOwnership(entityId: string, storeId: string, fieldPaths: FieldPath[]): Promise<{ ok: true; value: undefined } | { ok: false; error: { message: string } }>;
+  importProducts(
+    page: ImportProduct[],
+    options: ImportProductsOptions,
+    actor: Actor,
+  ): Promise<ServiceResult<ImportProductsReport>>;
   createOptionType(
     input: { entityId: string; name: string; values?: string[] },
     actor: Actor,
@@ -627,6 +636,39 @@ function hash(value: unknown): string {
   return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
+/**
+ * The suffix a store's product takes when its handle is already another store's slug: the first
+ * label of the store domain (`kelly-felder.myshopify.com` → `kelly-felder`), slugified.
+ */
+export function storeSlugSuffix(storeDomain: string): string {
+  const label = storeDomain.trim().toLowerCase().split(".")[0] ?? "";
+  return label.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+const SLUG_CONFLICT = /sellable_entities_org_slug_unique|Entity with slug .+ already exists|Slug ".+" already exists/;
+
+/**
+ * Whether a create or update lost a slug to another writer — core's pre-check message, or the
+ * unique index itself, which a driver error can carry several `cause`s deep.
+ */
+export function isSlugConflict(error: unknown): boolean {
+  let cursor: unknown = error;
+  for (let depth = 0; depth < 5; depth += 1) {
+    if (typeof cursor === "string") return SLUG_CONFLICT.test(cursor);
+    if (typeof cursor !== "object" || cursor === null) return false;
+    if ("constraint" in cursor && cursor.constraint === "sellable_entities_org_slug_unique") return true;
+    if ("message" in cursor && typeof cursor.message === "string" && SLUG_CONFLICT.test(cursor.message)) return true;
+    cursor = "cause" in cursor ? cursor.cause : undefined;
+  }
+  return false;
+}
+
+function errorMessage(error: unknown): string {
+  if (typeof error === "string") return error;
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") return error.message;
+  return String(error);
+}
+
 /** Mid-import map rows carry this until convergence finishes; must not equal any real remote hash. */
 const PENDING_ENTITY_MAP_SYNC_HASH = "";
 
@@ -891,6 +933,167 @@ function redactStore(store: ConnectedStore): PublicConnectedStore {
   };
 }
 
+/**
+ * A hero is streamed inside the page's own invocation, so it is bounded: a 30 MB TIFF a merchant
+ * uploaded by mistake must not buffer into a 128 MiB isolate. Anything larger is reported, not
+ * stored, and the product still lands — the index reads text first and media later.
+ */
+export const HERO_IMAGE_BYTE_CAP = 1024 * 1024;
+
+export type CatalogMediaFailureReason = "too-large" | "download-failed" | "unsupported" | "storage";
+
+export interface CatalogMediaFailure {
+  externalId: string;
+  imageExternalId?: string;
+  url: string;
+  reason: CatalogMediaFailureReason;
+  detail: string;
+}
+
+/** Media the page did NOT fetch: the first photo of each variant the hero does not show. */
+export interface CatalogDeferredMedia {
+  externalId: string;
+  entityId: string;
+  images: ChannelCatalogImage[];
+}
+
+export interface CatalogPageConvergence extends Record<string, unknown> {
+  created: number;
+  unchanged: number;
+  updated: number;
+  /** Input order, failures excluded, no duplicates — the page message is rebuilt from this. */
+  entityIds: string[];
+  failures: CatalogConvergenceFailure[];
+  heroesImported: number;
+  mediaFailures: CatalogMediaFailure[];
+  deferredMedia: CatalogDeferredMedia[];
+  warnings: string[];
+}
+
+export interface ImportImageSelection {
+  hero: ChannelCatalogImage | null;
+  /** In variant order; one image per variant the hero does not cover; no url twice. */
+  perVariant: ChannelCatalogImage[];
+}
+
+function imageOrder(a: ChannelCatalogImage, b: ChannelCatalogImage): number {
+  return (a.sortOrder ?? 0) - (b.sortOrder ?? 0);
+}
+
+/**
+ * Ruling 2026-09-22: import the hero plus the FIRST photo of each other variant, nothing more.
+ * A "blue long dress" query must be able to show the blue variant, and a fourth photo of the red
+ * one adds nothing the index can use. Variants are read off the images' own variant references,
+ * so a connector that lists images against variants it does not enumerate still gets one each.
+ */
+export function selectImportImages(item: ChannelCatalogItem): ImportImageSelection {
+  const images = [...(item.images ?? [])].sort(imageOrder);
+  const hero = images.find((image) => image.role === "primary") ?? images[0] ?? null;
+  if (!hero) return { hero: null, perVariant: [] };
+  const covered = new Set(hero.variantExternalIds ?? []);
+  const usedUrls = new Set([hero.url]);
+  const perVariant: ChannelCatalogImage[] = [];
+  const variantRefs = [...new Set(images.flatMap((image) => image.variantExternalIds ?? []))];
+  for (const ref of variantRefs) {
+    if (covered.has(ref)) continue;
+    const image = images.find((candidate) => candidate.variantExternalIds?.includes(ref) && !usedUrls.has(candidate.url));
+    for (const shown of image?.variantExternalIds ?? []) covered.add(shown);
+    covered.add(ref);
+    if (!image) continue;
+    usedUrls.add(image.url);
+    perVariant.push(image);
+  }
+  return { hero, perVariant };
+}
+
+type BoundedFetch =
+  | { ok: true; bytes: Uint8Array<ArrayBuffer>; contentType: string }
+  | { ok: false; reason: CatalogMediaFailureReason; detail: string };
+
+/** Streams a response and refuses mid-stream past `cap`; a lying `content-length` cannot get around it. */
+async function fetchBounded(url: string, cap: number): Promise<BoundedFetch> {
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    return { ok: false, reason: "download-failed", detail: error instanceof Error ? error.message : "download failed" };
+  }
+  if (!response.ok) return { ok: false, reason: "download-failed", detail: `download returned ${response.status}` };
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > cap) return { ok: false, reason: "too-large", detail: `content-length ${declared} exceeds ${cap}` };
+  const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim() || "image/jpeg";
+  const reader = response.body?.getReader();
+  if (!reader) {
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > cap) return { ok: false, reason: "too-large", detail: `${buffer.byteLength} bytes exceeds ${cap}` };
+    return { ok: true, bytes: new Uint8Array(buffer), contentType };
+  }
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > cap) {
+      await reader.cancel();
+      return { ok: false, reason: "too-large", detail: `stream exceeded ${cap} bytes` };
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { ok: true, bytes, contentType };
+}
+
+function toImportProduct(item: ChannelCatalogItem): ImportProduct {
+  const attributes = item.attributes?.length
+    ? item.attributes
+    : [{ locale: "en", title: item.title, ...(item.description !== undefined ? { description: item.description } : {}) }];
+  return {
+    ref: item.externalId,
+    slug: item.slug,
+    ...(item.status !== undefined ? { status: item.status, isVisible: item.status === "active" } : {}),
+    metadata: mergeMetadata(undefined, item.metadata ?? {}),
+    attributes: attributes.map((attribute) => ({
+      locale: attribute.locale,
+      title: attribute.title,
+      ...(attribute.subtitle !== undefined ? { subtitle: attribute.subtitle } : {}),
+      ...(attribute.description !== undefined ? { description: attribute.description } : {}),
+      ...(attribute.richDescription !== undefined ? { richDescription: attribute.richDescription } : {}),
+      ...(attribute.seoTitle !== undefined ? { seoTitle: attribute.seoTitle } : {}),
+      ...(attribute.seoDescription !== undefined ? { seoDescription: attribute.seoDescription } : {}),
+    })),
+    ...(item.options !== undefined ? {
+      options: item.options.map((option) => ({
+        name: option.name,
+        displayName: option.displayName,
+        ...(option.sortOrder !== undefined ? { sortOrder: option.sortOrder } : {}),
+        values: option.values.map((value) => ({
+          value: value.value,
+          displayValue: value.displayValue,
+          ...(value.sortOrder !== undefined ? { sortOrder: value.sortOrder } : {}),
+        })),
+      })),
+    } : {}),
+    variants: item.variants.map((variant) => ({
+      ref: variant.externalId,
+      ...(variant.sku !== undefined ? { sku: variant.sku } : {}),
+      ...(variant.barcode !== undefined ? { barcode: variant.barcode } : {}),
+      ...(variant.optionValues !== undefined ? { options: variant.optionValues } : {}),
+      ...(variant.prices !== undefined ? { prices: variant.prices } : {}),
+      ...(variant.metadata !== undefined ? { metadata: variant.metadata } : {}),
+    })),
+    ...(item.tags !== undefined ? { tags: item.tags } : {}),
+    ...(item.brand !== undefined ? { brand: item.brand } : {}),
+    ...(item.categories !== undefined ? { categories: item.categories } : {}),
+    ownedFieldPaths: importedFieldPaths(item),
+  };
+}
+
 export class ChannelConnectorService {
   private readonly connectors = new Map<string, ChannelConnector>();
   private readonly transact: PluginTxFn;
@@ -1313,41 +1516,77 @@ export class ChannelConnectorService {
     actor: Actor,
   ): Promise<PluginResult<{ value: Map<string, Map<string, string>>; changed: boolean }>> {
     const optionValueIds = new Map<string, Map<string, string>>();
-    const existingTypes = await this.db.select().from(optionTypes).where(eq(optionTypes.entityId, entityId));
+    // PROJECTED, not `select()`. Three reasons, and the third is the one that saves statements:
+    // the row's other columns are never read; a projection types the locally-constructed row below
+    // without a cast; and carrying `displayName`/`sortOrder` is what lets the update be SKIPPED when
+    // they already hold. A re-import that changes nothing is the common case for a sync, and it used
+    // to issue one UPDATE per option type and one per option value regardless.
+    const existingTypes: { id: string; name: string; displayName: string | null; sortOrder: number | null }[] =
+      await this.db
+        .select({ id: optionTypes.id, name: optionTypes.name, displayName: optionTypes.displayName, sortOrder: optionTypes.sortOrder })
+        .from(optionTypes)
+        .where(eq(optionTypes.entityId, entityId));
     let changed = false;
     for (const [typeIndex, sourceType] of (item.options ?? []).entries()) {
       let optionType = existingTypes.find((row) => row.name === sourceType.name);
       if (!optionType) {
         const created = await this.catalog.createOptionType({ entityId, name: sourceType.name, values: [] }, actor);
         if (!created.ok) return PluginErr(created.error.message);
-        const [createdType] = await this.db.select().from(optionTypes).where(eq(optionTypes.id, created.value.id));
-        if (!createdType) return PluginErr(`Option type "${sourceType.name}" was not persisted.`);
-        optionType = createdType;
+        // The created row is CONSTRUCTED rather than read back: `createOptionType` returns the id and
+        // the name is what we just sent.
+        //
+        // The two nulls are DELIBERATE PLACEHOLDERS, not a claim about the database. `createOptionType`
+        // actually persists `displayName: input.name, sortOrder: 0` (core entity-service.ts:595) and
+        // `display_name` is NOT NULL (core catalog/schema.ts:307) — so a fresh row never holds null.
+        // Constructing nulls here makes the comparison below unequal on any input, which is what forces
+        // the update that writes the caller's real `displayName`/`sortOrder` over those defaults.
+        optionType = { id: created.value.id, name: sourceType.name, displayName: null, sortOrder: null };
         existingTypes.push(optionType);
         changed = true;
       }
-      await this.db.update(optionTypes).set({
-        displayName: sourceType.displayName,
-        sortOrder: sourceType.sortOrder ?? typeIndex,
-      }).where(eq(optionTypes.id, optionType.id));
+      const desiredTypeSort = sourceType.sortOrder ?? typeIndex;
+      // `?? null` NORMALISES, and it is load-bearing rather than tidy. The stored value is `null` or a
+      // string; a connector that omits `displayName` sends `undefined`, and `null !== undefined` is
+      // true — so without this every such connector issued one UPDATE per option type on every sync
+      // and the conditional bought it nothing. Latent on today's corpus, whose connector always sends
+      // both fields.
+      const desiredTypeDisplay = sourceType.displayName ?? null;
+      if (optionType.displayName !== desiredTypeDisplay || optionType.sortOrder !== desiredTypeSort) {
+        await this.db.update(optionTypes).set({
+          displayName: sourceType.displayName,
+          sortOrder: desiredTypeSort,
+        }).where(eq(optionTypes.id, optionType.id));
+        optionType.displayName = desiredTypeDisplay;
+        optionType.sortOrder = desiredTypeSort;
+      }
 
-      const existingValues = await this.db.select().from(optionValues).where(eq(optionValues.optionTypeId, optionType.id));
+      const existingValues: { id: string; value: string; displayValue: string | null; sortOrder: number | null }[] =
+        await this.db
+          .select({ id: optionValues.id, value: optionValues.value, displayValue: optionValues.displayValue, sortOrder: optionValues.sortOrder })
+          .from(optionValues)
+          .where(eq(optionValues.optionTypeId, optionType.id));
       const valueIds = new Map<string, string>();
       for (const [valueIndex, sourceValue] of sourceType.values.entries()) {
         let optionValue = existingValues.find((row) => row.value === sourceValue.value);
         if (!optionValue) {
           const created = await this.catalog.createOptionValue({ optionTypeId: optionType.id, value: sourceValue.value }, actor);
           if (!created.ok) return PluginErr(created.error.message);
-          const [createdValue] = await this.db.select().from(optionValues).where(eq(optionValues.id, created.value.id));
-          if (!createdValue) return PluginErr(`Option value "${sourceValue.value}" was not persisted.`);
-          optionValue = createdValue;
+          // Same placeholder reasoning as the option type above: core persists `displayValue: input.value,
+          // sortOrder: 0` (entity-service.ts:615), and the nulls force the update that overwrites them.
+          optionValue = { id: created.value.id, value: sourceValue.value, displayValue: null, sortOrder: null };
           existingValues.push(optionValue);
           changed = true;
         }
-        await this.db.update(optionValues).set({
-          displayValue: sourceValue.displayValue,
-          sortOrder: sourceValue.sortOrder ?? valueIndex,
-        }).where(eq(optionValues.id, optionValue.id));
+        const desiredValueSort = sourceValue.sortOrder ?? valueIndex;
+        const desiredValueDisplay = sourceValue.displayValue ?? null;
+        if (optionValue.displayValue !== desiredValueDisplay || optionValue.sortOrder !== desiredValueSort) {
+          await this.db.update(optionValues).set({
+            displayValue: sourceValue.displayValue,
+            sortOrder: desiredValueSort,
+          }).where(eq(optionValues.id, optionValue.id));
+          optionValue.displayValue = desiredValueDisplay;
+          optionValue.sortOrder = desiredValueSort;
+        }
         valueIds.set(sourceValue.value, optionValue.id);
       }
       optionValueIds.set(sourceType.name, valueIds);
@@ -1375,10 +1614,52 @@ export class ChannelConnectorService {
       eq(channelEntityMap.kind, "variant"),
       eq(channelEntityMap.entityId, entityId),
     ));
+    // ONE read of the existing option-value rows for every already-mapped variant, instead of one
+    // per variant inside the loop. Measured on the deployed Worker at 17.0 calls per product, which
+    // is one per offer on a catalogue averaging 13 offers per product. A variant CREATED below is
+    // absent from this map and correctly reads as empty: its rows are written in this same pass.
+    const mappedVariantIds = mappings
+      .map((row) => row.variantId)
+      .filter((variantId): variantId is string => variantId !== null);
+    const existingOptionValues = new Map<string, string[]>();
+    if (mappedVariantIds.length > 0) {
+      const rows = await this.db
+        .select({ variantId: variantOptionValues.variantId, optionValueId: variantOptionValues.optionValueId })
+        .from(variantOptionValues)
+        .where(inArray(variantOptionValues.variantId, mappedVariantIds));
+      for (const row of rows) {
+        const list = existingOptionValues.get(row.variantId) ?? [];
+        list.push(row.optionValueId);
+        existingOptionValues.set(row.variantId, list);
+      }
+    }
     for (const sourceVariant of item.variants) {
       const fullSourceVariant = fullItem.variants.find((variant) => variant.externalId === sourceVariant.externalId) ?? sourceVariant;
       let mapping = mappings.find((row) => row.externalId === sourceVariant.externalId);
       let variantId = mapping?.variantId;
+      // ADOPT BEFORE CREATE. A variant-kind mapping row whose `variantId` is null has lost its link
+      // — the key survived, the target did not. Creating a replacement is what the loop used to do,
+      // and it cannot work: the orphaned variant still holds the sku, so `variants_native_org_sku_unique`
+      // refuses the insert and the item fails on this and every later sync. The row can never heal.
+      //
+      // `sku` is the store's own natural key for a variant, so re-resolving by it is what restores
+      // the link the null destroyed. Scoped to this entity because a sku is unique per organization
+      // and adopting another entity's variant would be worse than failing.
+      if (mapping && !variantId && sourceVariant.sku) {
+        const [adopted] = await this.db
+          .select({ id: variants.id })
+          .from(variants)
+          .where(and(eq(variants.entityId, entityId), eq(variants.sku, sourceVariant.sku)))
+          .limit(1);
+        if (adopted) {
+          variantId = adopted.id;
+          // Write the link back, or the row stays broken and every later sync pays this lookup again.
+          await this.db.update(channelEntityMap)
+            .set({ variantId })
+            .where(eq(channelEntityMap.id, mapping.id));
+          mapping.variantId = variantId;
+        }
+      }
       const createdVariant = !variantId;
       if (!variantId) {
         const options: Record<string, string> = {};
@@ -1398,17 +1679,36 @@ export class ChannelConnectorService {
         }, actor);
         if (!created.ok) return PluginErr(created.error.message);
         variantId = created.value.id;
-        const [createdMapping] = await this.db.insert(channelEntityMap).values({
-          organizationId: orgId,
-          storeId,
-          kind: "variant",
-          externalId: sourceVariant.externalId,
-          entityId,
-          variantId,
-          syncHash: hash(fullSourceVariant),
-        }).returning();
-        mapping = createdMapping;
-        if (mapping) mappings.push(mapping);
+        if (mapping) {
+          // REPAIR IN PLACE. `variantId` is nullable because this table also holds `kind: "entity"`
+          // rows, which legitimately have none — but a VARIANT row with a null `variantId` is a
+          // broken invariant, not a state to work around. The row already occupies
+          // `channel_entity_map_store_kind_external_unique` on (store, kind, externalId), so the
+          // insert below would raise a unique violation and fail the whole item. Updating the row
+          // we already hold is the only shape that converges.
+          await this.db.update(channelEntityMap).set({
+            entityId,
+            variantId,
+            syncHash: hash(fullSourceVariant),
+          }).where(eq(channelEntityMap.id, mapping.id));
+          mapping.entityId = entityId;
+          mapping.variantId = variantId;
+          mapping.syncHash = hash(fullSourceVariant);
+        } else {
+          const [createdMapping] = await this.db.insert(channelEntityMap).values({
+            organizationId: orgId,
+            storeId,
+            kind: "variant",
+            externalId: sourceVariant.externalId,
+            entityId,
+            variantId,
+            syncHash: hash(fullSourceVariant),
+          }).returning();
+          mapping = createdMapping;
+          // Pushed so a payload repeating this externalId resolves the row it just created rather
+          // than creating a second variant for it.
+          if (mapping) mappings.push(mapping);
+        }
       }
       if (!variantId) {
         warnings.push(`Skipped variant "${sourceVariant.externalId}": no local variant mapping exists.`);
@@ -1419,8 +1719,7 @@ export class ChannelConnectorService {
         const desiredOptionValueIds = Object.entries(sourceVariant.optionValues ?? {})
           .map(([name, value]) => optionValueIds.get(name)?.get(value))
           .filter((optionValueId): optionValueId is string => optionValueId !== undefined);
-        const currentOptionValues = await this.db.select().from(variantOptionValues).where(eq(variantOptionValues.variantId, variantId));
-        const currentIds = currentOptionValues.map((row) => row.optionValueId).sort();
+        const currentIds = [...(existingOptionValues.get(variantId) ?? [])].sort();
         const desiredIds = [...new Set(desiredOptionValueIds)].sort();
         if (currentIds.length !== desiredIds.length || currentIds.some((id, index) => id !== desiredIds[index])) {
           await this.db.delete(variantOptionValues).where(eq(variantOptionValues.variantId, variantId));
@@ -1428,6 +1727,9 @@ export class ChannelConnectorService {
             await this.db.insert(variantOptionValues).values(desiredIds.map((optionValueId) => ({ variantId, optionValueId }))).onConflictDoNothing();
             repaired += 1;
           }
+          // The map is the read model for this pass; a payload repeating an externalId must not see
+          // the pre-fetched state after this write.
+          existingOptionValues.set(variantId, [...desiredIds]);
           changed = true;
         }
         if (createdVariant && desiredIds.length > 0) {
@@ -1445,15 +1747,65 @@ export class ChannelConnectorService {
         }, actor);
         if (!priced.ok) return PluginErr(priced.error.message);
       }
-      if (mapping) {
+      // Was UNCONDITIONAL: one UPDATE per variant on every import, including a re-sync where the
+      // variant is byte-identical. `mapping.syncHash` is already in hand from the select above, so
+      // the comparison is free and the write disappears on an unchanged variant — which is the
+      // ordinary case for a store that syncs repeatedly.
+      const nextSyncHash = hash(fullSourceVariant);
+      if (mapping && mapping.syncHash !== nextSyncHash) {
         await this.db.update(channelEntityMap).set({
-          syncHash: hash(fullSourceVariant),
+          syncHash: nextSyncHash,
         }).where(eq(channelEntityMap.id, mapping.id));
+        mapping.syncHash = nextSyncHash;
       }
     }
     return Ok({ value: variantIds, repaired, changed });
   }
 
+  /**
+   * The organization's categories, brands and tags, read ONCE per converge run instead of once per
+   * product.
+   *
+   * `applyTaxonomy` takes an `entityId` and is called unconditionally for every item, and each of
+   * its three lookups was a whole-table read filtered by `organization_id`. Measured on the deployed
+   * Worker: 1.0 call per product per class, three classes, every product — an organization's whole
+   * category list re-read for each of twenty products in a batch that cannot have changed it.
+   *
+   * Rows created DURING the run are appended by the callers below, exactly as they were appended to
+   * the per-product arrays before, so an item that introduces a category is still seen by the next
+   * item. The cache is cleared at the top of `convergeCatalogItems`, so its lifetime is one converge
+   * rather than the lifetime of the service.
+   *
+   * The staleness window widens from one product to one batch: a category created by ANOTHER process
+   * mid-batch is not seen here. That was already true within a product — these lists were always a
+   * snapshot — and the create paths below go through `this.catalog`, which refuses a duplicate slug
+   * rather than writing one. So the failure mode is unchanged in kind and wider in window, which is
+   * the trade this comment exists to state rather than hide.
+   */
+  private taxonomyCache: {
+    orgId: string;
+    categories: (typeof categories.$inferSelect)[];
+    brands: (typeof brands.$inferSelect)[];
+    tags: (typeof tags.$inferSelect)[];
+  } | null = null;
+
+  private async taxonomyFor(orgId: string): Promise<{
+    categories: (typeof categories.$inferSelect)[];
+    brands: (typeof brands.$inferSelect)[];
+    tags: (typeof tags.$inferSelect)[];
+  }> {
+    // Keyed on orgId as well as presence: one service instance serving two organizations must not
+    // hand the second one the first one's taxonomy.
+    if (this.taxonomyCache?.orgId === orgId) return this.taxonomyCache;
+    const [categoryRows, brandRows, tagRows] = await Promise.all([
+      this.db.select().from(categories).where(eq(categories.organizationId, orgId)),
+      this.db.select().from(brands).where(eq(brands.organizationId, orgId)),
+      this.db.select().from(tags).where(eq(tags.organizationId, orgId)),
+    ]);
+    this.taxonomyCache = { orgId, categories: categoryRows, brands: brandRows, tags: tagRows };
+    return this.taxonomyCache;
+  }
+
   private async applyTaxonomy(
     orgId: string,
     entityId: string,
@@ -1461,7 +1813,8 @@ export class ChannelConnectorService {
     actor: Actor,
     warnings: string[],
   ): Promise<PluginResult<void>> {
-    const categoryRows = await this.db.select().from(categories).where(eq(categories.organizationId, orgId));
+    const taxonomy = await this.taxonomyFor(orgId);
+    const categoryRows = taxonomy.categories;
     for (const slug of new Set(item.categories ?? [])) {
       let category = categoryRows.find((row) => row.slug === slug);
       if (category?.status === "archived") {
@@ -1480,7 +1833,7 @@ export class ChannelConnectorService {
       if (!linked.ok) return PluginErr(linked.error.message);
     }
 
-    const brandRows = await this.db.select().from(brands).where(eq(brands.organizationId, orgId));
+    const brandRows = taxonomy.brands;
     if (item.brand) {
       let brand = brandRows.find((row) => row.slug === item.brand);
       if (!brand) {
@@ -1495,7 +1848,7 @@ export class ChannelConnectorService {
       if (!linked.ok) return PluginErr(linked.error.message);
     }
 
-    const tagRows = await this.db.select().from(tags).where(eq(tags.organizationId, orgId));
+    const tagRows = taxonomy.tags;
     for (const slug of new Set(item.tags ?? [])) {
       let tag = tagRows.find((row) => row.slug === slug);
       if (!tag) {
@@ -1730,6 +2083,65 @@ export class ChannelConnectorService {
     return rows[0] as ConnectedStore | undefined;
   }
 
+  /**
+   * The slug each wanted handle takes for THIS store. Slugs stay unique across the organization —
+   * the storefront resolves `/:idOrSlug` org-wide — but one platform organization holds many
+   * merchants, and two of them may sell the same handle.
+   *
+   * A handle's FAMILY for a store is, in order: the bare handle, `<handle>-<store suffix>`, and
+   * `<handle>-<store suffix>-<store id prefix>`. The last is unique per store, so a third store with
+   * the same domain label still gets a slug of its own. A new product takes the first member no
+   * other store holds. An existing product whose slug is already in its handle's family KEEPS it
+   * (see `slugToKeep`): a slug, once assigned, is a shared link and is never recomputed.
+   */
+  private async resolveStoreSlugs(
+    orgId: string,
+    storeId: string,
+    handles: readonly string[],
+  ): Promise<Map<string, { slug: string; family: string[] }>> {
+    const wanted = [...new Set(handles)];
+    const resolved = new Map<string, { slug: string; family: string[] }>();
+    if (wanted.length === 0) return resolved;
+    const suffix = await this.storeSlugSuffixFor(orgId, storeId);
+    const idPart = storeId.replace(/[^a-z0-9]/gi, "").slice(0, 8).toLowerCase();
+    const familyOf = (handle: string): string[] => suffix
+      ? [handle, `${handle}-${suffix}`, `${handle}-${suffix}-${idPart}`]
+      : [handle, `${handle}-${idPart}`];
+    const families = new Map(wanted.map((handle) => [handle, familyOf(handle)]));
+    const owners = await this.db.select({ slug: sellableEntities.slug, sourceStoreId: sellableEntities.sourceStoreId })
+      .from(sellableEntities)
+      .where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.slug, [...families.values()].flat())));
+    // Only ANOTHER STORE's product moves this one to a qualified slug. A product a person made in
+    // Merchant Center (no source store) holding the handle stays a loud slug conflict, as before.
+    const heldElsewhere = new Set(owners.filter((row) => row.sourceStoreId !== null && row.sourceStoreId !== storeId).map((row) => row.slug));
+    for (const [handle, family] of families) {
+      // Every member held by another store is only reachable through a hand-made slug; the last
+      // member is then used anyway and the create fails loudly on the unique index.
+      const slug = family.find((candidate) => !heldElsewhere.has(candidate)) ?? family[family.length - 1] ?? handle;
+      resolved.set(handle, { slug, family });
+    }
+    return resolved;
+  }
+
+  // ponytail: cached for the service instance's lifetime (one task invocation), so a batched import
+  // reads the store once. A store whose domain changes mid-invocation keeps the old suffix until the
+  // next one — a new slug family only, never a rename of a slug already assigned.
+  private readonly slugSuffixByStore = new Map<string, string>();
+
+  private async storeSlugSuffixFor(orgId: string, storeId: string): Promise<string> {
+    const cached = this.slugSuffixByStore.get(storeId);
+    if (cached !== undefined) return cached;
+    const suffix = storeSlugSuffix((await this.getStoreRecord(orgId, storeId))?.storeDomain ?? "");
+    this.slugSuffixByStore.set(storeId, suffix);
+    return suffix;
+  }
+
+  /** The slug an existing product converges to: its current one while that is still in the family
+   *  of the handle the store sends, so a slug is never recomputed out from under a shared link. */
+  private slugToKeep(currentSlug: string, resolved: { slug: string; family: string[] }): string {
+    return resolved.family.includes(currentSlug) ? currentSlug : resolved.slug;
+  }
+
   async getStoreByDomain(shopDomain: string): Promise<ConnectedStore | undefined> {
     const rows = await this.db
       .select()
@@ -2427,6 +2839,258 @@ export class ChannelConnectorService {
     }));
   }
 
+  /**
+   * One page from the connector, nothing written. The host lands the page durably (R2 + its
+   * ledger) and hands it to `convergeCatalogPage` from a queue consumer; the two halves are
+   * separate so a consumer retry never re-fetches the merchant's API.
+   */
+  async fetchCatalogPage(
+    orgId: string,
+    storeId: string,
+    cursor: string | null,
+  ): Promise<PluginResult<{ items: ChannelCatalogItem[]; nextCursor: string | null }>> {
+    const store = await this.getStoreRecord(orgId, storeId);
+    if (!store || store.status !== "connected") return PluginErr("Connected store not found.", "NOT_FOUND");
+    const connector = this.connectors.get(store.provider);
+    if (!connector) return PluginErr(`No connector registered for provider "${store.provider}".`);
+    const page = await connector.importCatalog(store as ChannelStore, cursor ?? undefined);
+    if (!page.ok) return PluginErr(page.error.message);
+    return Ok({ items: page.value.items, nextCursor: page.value.nextCursor ?? null });
+  }
+
+  /**
+   * Converges a page: items this store has never mapped take the import fast path
+   * (`catalog.importProducts`, one transaction, multi-row writes); items already mapped and
+   * unchanged cost nothing; items mapped-but-changed, and orphans (an entity of this store with
+   * the item's slug but no map row), take the editor path, which owns ownership and conflicts.
+   *
+   * Media: only each new item's hero is fetched here, streamed under `HERO_IMAGE_BYTE_CAP`, and
+   * linked at entity level as `primary` plus to the variants it shows. The first photo of every
+   * other variant comes back in `deferredMedia` for the host to land later.
+   */
+  async convergeCatalogPage(
+    orgId: string,
+    storeId: string,
+    items: ChannelCatalogItem[],
+    actor: Actor,
+  ): Promise<PluginResult<CatalogPageConvergence>> {
+    const failures: CatalogConvergenceFailure[] = [];
+    const warnings: string[] = [];
+    const entityByExternalId = new Map<string, string>();
+    let unchanged = 0;
+    let updated = 0;
+
+    const externalIds = [...new Set(items.map((item) => item.externalId))];
+    const mappings = externalIds.length === 0 ? [] : await this.db.select().from(channelEntityMap).where(and(
+      eq(channelEntityMap.organizationId, orgId),
+      eq(channelEntityMap.storeId, storeId),
+      eq(channelEntityMap.kind, "entity"),
+      inArray(channelEntityMap.externalId, externalIds),
+    ));
+    const mappingByExternalId = new Map(mappings.map((row) => [row.externalId, row]));
+    const slugFor = await this.resolveStoreSlugs(orgId, storeId, items.map((item) => item.slug));
+    const slugs = [...new Set([...slugFor.values()].flatMap((resolved) => resolved.family))];
+    const orphans = slugs.length === 0 ? [] : await this.db.select({ slug: sellableEntities.slug }).from(sellableEntities).where(and(
+      eq(sellableEntities.organizationId, orgId),
+      eq(sellableEntities.sourceStoreId, storeId),
+      inArray(sellableEntities.slug, slugs),
+    ));
+    const orphanSlugs = new Set(orphans.map((row) => row.slug));
+    const isOrphan = (handle: string): boolean => (slugFor.get(handle)?.family ?? [handle]).some((slug) => orphanSlugs.has(slug));
+
+    const fresh: ChannelCatalogItem[] = [];
+    const editor: ChannelCatalogItem[] = [];
+    const seen = new Set<string>();
+    for (const item of items) {
+      if (seen.has(item.externalId)) {
+        failures.push({ externalId: item.externalId, error: "duplicate-in-page: this externalId appears twice in the page." });
+        continue;
+      }
+      seen.add(item.externalId);
+      const mapping = mappingByExternalId.get(item.externalId);
+      if (mapping && mapping.syncHash === hash(item)) {
+        entityByExternalId.set(item.externalId, mapping.entityId);
+        unchanged += 1;
+      } else if (mapping || isOrphan(item.slug)) {
+        editor.push(item);
+      } else {
+        fresh.push(item);
+      }
+    }
+
+    if (editor.length > 0) {
+      const result = await this.convergeCatalogItems(orgId, storeId, editor, actor);
+      if (!result.ok) return result;
+      failures.push(...result.value.failures);
+      warnings.push(...result.value.warnings);
+      const failedIds = new Set(result.value.failures.map((failure) => failure.externalId));
+      const survivors = editor.filter((item) => !failedIds.has(item.externalId));
+      survivors.forEach((item, index) => {
+        const entityId = result.value.entityIds[index];
+        if (entityId !== undefined) entityByExternalId.set(item.externalId, entityId);
+      });
+      updated += survivors.length;
+    }
+
+    const createdItems: Array<{ item: ChannelCatalogItem; entityId: string; variantIds: Record<string, string> }> = [];
+    // Two stores onboarding at once can both resolve a handle as free and then both create it. The
+    // loser's collision is transient: re-resolve those items once (the winner is now visible, so they
+    // take the store-qualified slug) and try again. A second collision is reported as the item's.
+    let pending = fresh;
+    for (let attempt = 0; pending.length > 0; attempt += 1) {
+      // The slug is resolved on the import row only: the map row's hash stays the hash of the item
+      // as the store sent it, so the next page still reads it as unchanged.
+      const report = await this.catalog.importProducts(
+        pending.map((item) => toImportProduct({ ...item, slug: slugFor.get(item.slug)?.slug ?? item.slug })),
+        { sourceStoreId: storeId, errorPolicy: "reject-failed-rows" },
+        actor,
+      );
+      if (!report.ok) return PluginErr(report.error.message, report.error.code);
+      const collided: Array<{ item: ChannelCatalogItem; failure: CatalogConvergenceFailure }> = [];
+      for (const [index, row] of report.value.rows.entries()) {
+        const item = pending[index];
+        if (!item) continue;
+        if (row.status === "failed") {
+          const failure = { externalId: row.ref, error: `${row.code}: ${row.error}` };
+          const lostSlug = row.code === "slug-conflict" || (row.code === "conflict" && isSlugConflict(row.error));
+          if (attempt === 0 && lostSlug) collided.push({ item, failure });
+          else failures.push(failure);
+          continue;
+        }
+        warnings.push(...row.warnings);
+        entityByExternalId.set(item.externalId, row.entityId);
+        createdItems.push({ item, entityId: row.entityId, variantIds: row.variantIds });
+      }
+      pending = [];
+      if (collided.length > 0) {
+        const again = await this.resolveStoreSlugs(orgId, storeId, collided.map(({ item }) => item.slug));
+        for (const { item, failure } of collided) {
+          const before = slugFor.get(item.slug)?.slug ?? item.slug;
+          const after = again.get(item.slug);
+          // Retry only when another STORE took the handle: a slug held by a product made in
+          // Merchant Center resolves to the same slug again, and stays the loud conflict it was.
+          if (after === undefined || after.slug === before) { failures.push(failure); continue; }
+          slugFor.set(item.slug, after);
+          pending.push(item);
+        }
+      }
+    }
+    if (createdItems.length > 0) {
+      const now = new Date();
+      await this.db.insert(channelEntityMap).values(createdItems.flatMap(({ item, entityId, variantIds }) => [
+        { organizationId: orgId, storeId, kind: "entity" as const, externalId: item.externalId, entityId, syncHash: hash(item), lastSyncedAt: now },
+        ...item.variants.flatMap((variant) => {
+          const variantId = variantIds[variant.externalId];
+          return variantId === undefined ? [] : [{ organizationId: orgId, storeId, kind: "variant" as const, externalId: variant.externalId, entityId, variantId, syncHash: hash(variant), lastSyncedAt: now }];
+        }),
+      ])).onConflictDoNothing();
+    }
+
+    const media = await this.importHeroes(orgId, createdItems, actor);
+    const entityIds: string[] = [];
+    const emitted = new Set<string>();
+    for (const item of items) {
+      const entityId = entityByExternalId.get(item.externalId);
+      if (entityId === undefined || emitted.has(entityId)) continue;
+      emitted.add(entityId);
+      entityIds.push(entityId);
+    }
+    return Ok({
+      created: createdItems.length,
+      unchanged,
+      updated,
+      entityIds,
+      failures,
+      heroesImported: media.heroesImported,
+      mediaFailures: media.mediaFailures,
+      deferredMedia: media.deferredMedia,
+      warnings,
+    });
+  }
+
+  private async importHeroes(
+    orgId: string,
+    createdItems: Array<{ item: ChannelCatalogItem; entityId: string; variantIds: Record<string, string> }>,
+    actor: Actor,
+  ): Promise<Pick<CatalogPageConvergence, "heroesImported" | "mediaFailures" | "deferredMedia">> {
+    const mediaFailures: CatalogMediaFailure[] = [];
+    const deferredMedia: CatalogDeferredMedia[] = [];
+    const selections = createdItems.flatMap(({ item, entityId, variantIds }) => {
+      const selection = selectImportImages(item);
+      if (selection.perVariant.length > 0) deferredMedia.push({ externalId: item.externalId, entityId, images: selection.perVariant });
+      return selection.hero ? [{ item, entityId, variantIds, hero: selection.hero }] : [];
+    });
+    if (selections.length === 0) return { heroesImported: 0, mediaFailures, deferredMedia };
+
+    // One read for every hero the page might already hold (a re-import after the map was lost).
+    const urlHashes = [...new Set(selections.map(({ hero }) => hash(hero.url)))];
+    const existingAssets = await this.db.select({ id: mediaAssets.id, metadata: mediaAssets.metadata }).from(mediaAssets).where(and(
+      eq(mediaAssets.organizationId, orgId),
+      inArray(sql`${mediaAssets.metadata}->>'channelImageUrlHash'`, urlHashes),
+    ));
+    const assetByUrlHash = new Map<string, string>();
+    for (const asset of existingAssets) {
+      const urlHash = asset.metadata?.channelImageUrlHash;
+      if (typeof urlHash === "string") assetByUrlHash.set(urlHash, asset.id);
+    }
+
+    type HeroOutcome = { entityId: string; mediaAssetId: string; hero: ChannelCatalogImage; variantIds: Record<string, string>; imported: boolean };
+    const outcomes: HeroOutcome[] = [];
+    const resolveHero = async ({ item, entityId, variantIds, hero }: (typeof selections)[number]): Promise<void> => {
+      const urlHash = hash(hero.url);
+      const existing = assetByUrlHash.get(urlHash);
+      if (existing !== undefined) {
+        outcomes.push({ entityId, mediaAssetId: existing, hero, variantIds, imported: false });
+        return;
+      }
+      const fetched = await fetchBounded(hero.url, HERO_IMAGE_BYTE_CAP);
+      const failure = (reason: CatalogMediaFailureReason, detail: string): void => {
+        mediaFailures.push({ externalId: item.externalId, ...(hero.externalId !== undefined ? { imageExternalId: hero.externalId } : {}), url: hero.url, reason, detail });
+      };
+      if (!fetched.ok) {
+        failure(fetched.reason, fetched.detail);
+        return;
+      }
+      const extension = fetched.contentType.split("/", 2)[1] ?? "jpg";
+      const uploaded = await this.media.upload({
+        filename: `${hero.externalId ?? urlHash}.${extension}`,
+        contentType: fetched.contentType,
+        data: fetched.bytes.buffer,
+        ...(hero.alt !== undefined ? { alt: hero.alt } : {}),
+        metadata: { channelImageUrlHash: urlHash, ...(hero.externalId !== undefined ? { channelImageExternalId: hero.externalId } : {}) },
+        origin: "imported",
+      }, actor);
+      if (!uploaded.ok) {
+        failure(uploaded.error.code === "VALIDATION_FAILED" ? "unsupported" : "storage", uploaded.error.message);
+        return;
+      }
+      assetByUrlHash.set(urlHash, uploaded.value.id);
+      outcomes.push({ entityId, mediaAssetId: uploaded.value.id, hero, variantIds, imported: true });
+    };
+    // Six outbound connections per Worker invocation, two per image (download + storage put).
+    const MAX_IN_FLIGHT = 3;
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(MAX_IN_FLIGHT, selections.length) }, async () => {
+      for (;;) {
+        const selection = selections[next];
+        next += 1;
+        if (selection === undefined) return;
+        await resolveHero(selection);
+      }
+    }));
+
+    if (outcomes.length > 0) {
+      await this.db.insert(entityMedia).values(outcomes.flatMap(({ entityId, mediaAssetId, hero, variantIds }) => [
+        { entityId, mediaAssetId, role: "primary" as const, sortOrder: hero.sortOrder ?? 0 },
+        ...(hero.variantExternalIds ?? []).flatMap((externalId) => {
+          const variantId = variantIds[externalId];
+          return variantId === undefined ? [] : [{ entityId, variantId, mediaAssetId, role: hero.role, sortOrder: hero.sortOrder ?? 0 }];
+        }),
+      ])).onConflictDoNothing();
+    }
+    return { heroesImported: outcomes.filter((outcome) => outcome.imported).length, mediaFailures, deferredMedia };
+  }
+
   async importCatalog(
     orgId: string,
     storeId: string,
@@ -2926,6 +3590,10 @@ export class ChannelConnectorService {
     dryRun = false,
   ): Promise<PluginResult<CatalogConvergenceStats>> {
     if (dryRun) return this.estimateCatalogItems(orgId, storeId, items);
+    // One converge, one taxonomy snapshot. Cleared HERE rather than left to the service's lifetime:
+    // the instance can outlive a batch on a warm isolate, and a taxonomy cached across batches would
+    // go stale in a way nothing reports.
+    this.taxonomyCache = null;
     let imported = 0;
     let converged = 0;
     let entitiesTouched = 0;
@@ -2939,6 +3607,8 @@ export class ChannelConnectorService {
     const failures: CatalogConvergenceFailure[] = [];
     const entityIds: string[] = [];
     const committed = new Set<string>();
+    // One resolution for the whole batch, not two round trips per changed product.
+    const slugFor = await this.resolveStoreSlugs(orgId, storeId, items.map((item) => item.slug));
     for (const item of items) {
       consumed += 1;
       try {
@@ -2975,43 +3645,61 @@ export class ChannelConnectorService {
           existingEntity = entity;
         }
       }
+      let resolvedSlug = slugFor.get(item.slug) ?? { slug: item.slug, family: [item.slug] };
+      // A slug lost to a concurrent writer (another store onboarding the same handle) is transient:
+      // re-resolve once, and the winner being visible now moves this item to its qualified slug.
+      const reresolveSlug = async (): Promise<void> => {
+        resolvedSlug = (await this.resolveStoreSlugs(orgId, storeId, [item.slug])).get(item.slug) ?? resolvedSlug;
+        slugFor.set(item.slug, resolvedSlug);
+      };
       if (entityId === undefined) {
         const [orphan] = await this.db.select().from(sellableEntities).where(and(
           eq(sellableEntities.organizationId, orgId),
           eq(sellableEntities.sourceStoreId, storeId),
-          eq(sellableEntities.slug, item.slug),
-        ));
+          inArray(sellableEntities.slug, resolvedSlug.family),
+        )).limit(1);
         if (orphan) {
           entityId = orphan.id;
           existingEntity = orphan;
           adoptedOrphan = true;
         } else {
           const status = item.status;
-          try {
-            entityId = await this.transact(async (tx) => {
-              const txContext = createTxContext(tx, { actor });
-              const created = await this.catalog.create({
-                type: "product",
-                slug: item.slug,
-                sourceStoreId: storeId,
-                metadata: mergeMetadata(undefined, item.metadata ?? {}),
-                ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
-              }, actor, txContext);
-              if (!created.ok) throw new Error(created.error.message);
-              await tx.insert(channelEntityMap).values({
-                organizationId: orgId,
-                storeId,
-                kind: "entity",
-                externalId: item.externalId,
-                entityId: created.value.id,
-                syncHash: PENDING_ENTITY_MAP_SYNC_HASH,
-                heldFieldPaths: [],
-                forcedPushFieldPaths: [],
-              });
-              return created.value.id;
+          const createEntity = (slug: string): Promise<string> => this.transact(async (tx) => {
+            const txContext = createTxContext(tx, { actor });
+            const created = await this.catalog.create({
+              type: "product",
+              slug,
+              sourceStoreId: storeId,
+              metadata: mergeMetadata(undefined, item.metadata ?? {}),
+              ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
+            }, actor, txContext);
+            if (!created.ok) throw new Error(created.error.message);
+            await tx.insert(channelEntityMap).values({
+              organizationId: orgId,
+              storeId,
+              kind: "entity",
+              externalId: item.externalId,
+              entityId: created.value.id,
+              syncHash: PENDING_ENTITY_MAP_SYNC_HASH,
+              heldFieldPaths: [],
+              forcedPushFieldPaths: [],
             });
-          } catch (error) {
-            failures.push({ externalId: item.externalId, error: error instanceof Error ? error.message : "Failed to create catalog entity." });
+            return created.value.id;
+          });
+          let createError: unknown;
+          for (let attempt = 0; attempt < 2 && entityId === undefined; attempt += 1) {
+            try {
+              entityId = await createEntity(resolvedSlug.slug);
+            } catch (error) {
+              createError = error;
+              if (attempt > 0 || !isSlugConflict(error)) break;
+              const before = resolvedSlug.slug;
+              await reresolveSlug();
+              if (resolvedSlug.slug === before) break;
+            }
+          }
+          if (entityId === undefined) {
+            failures.push({ externalId: item.externalId, error: createError instanceof Error ? createError.message : "Failed to create catalog entity." });
             continue;
           }
           isNew = true;
@@ -3071,8 +3759,9 @@ export class ChannelConnectorService {
           status?: string;
           isVisible?: boolean;
         } = {};
-        if (ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && existingEntity.slug !== writable.slug) {
-          updateInput.slug = writable.slug;
+        const keptSlug = this.slugToKeep(existingEntity.slug, resolvedSlug);
+        if (ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && existingEntity.slug !== keptSlug) {
+          updateInput.slug = keptSlug;
         }
         if (hash(remoteMetadata) !== hash(existingEntity.metadata ?? {})) updateInput.metadata = remoteMetadata;
         if (remoteStatus !== undefined && !blockedPaths.has("entity.status") && remoteStatus !== existingEntity.status) {
@@ -3083,10 +3772,25 @@ export class ChannelConnectorService {
           ? Object.keys(updateInput).length > 0
           : remoteChanged || existingEntity.status === "archived";
         if (shouldUpdate) {
-          converged += 1;
           if (Object.keys(updateInput).length > 0) {
-            const updated = await this.catalog.update(entityMapping.entityId, updateInput, actor, CHANNEL_CONVERGENCE_CTX);
-            if (!updated.ok) { failures.push({ externalId: item.externalId, error: updated.error.message }); continue; }
+            const mappedEntityId = entityMapping.entityId;
+            const update = async (): Promise<unknown> => {
+              try {
+                const updated = await this.catalog.update(mappedEntityId, updateInput, actor, CHANNEL_CONVERGENCE_CTX);
+                return updated.ok ? undefined : updated.error;
+              } catch (error) {
+                return error;
+              }
+            };
+            let updateError = await update();
+            if (updateError !== undefined && updateInput.slug !== undefined && isSlugConflict(updateError)) {
+              await reresolveSlug();
+              const retrySlug = this.slugToKeep(existingEntity.slug, resolvedSlug);
+              if (retrySlug === existingEntity.slug) delete updateInput.slug;
+              else updateInput.slug = retrySlug;
+              updateError = Object.keys(updateInput).length > 0 ? await update() : undefined;
+            }
+            if (updateError !== undefined) { failures.push({ externalId: item.externalId, error: errorMessage(updateError) }); continue; }
             entityTouched = true;
           }
         }
@@ -3107,7 +3811,9 @@ export class ChannelConnectorService {
         !heldSharedPaths.includes("options") && owners.get("options") !== "platform",
         item,
       );
-      if (!variantIds.ok) return variantIds;
+      // A variant the store's own data makes unwritable (a sku another of its products holds) is
+      // that item's failure, reported with its error — not a page error the caller would retry.
+      if (!variantIds.ok) { failures.push({ externalId: item.externalId, error: variantIds.error }); continue; }
       const taxonomy = await this.applyTaxonomy(orgId, entityId, writable, actor, warnings);
       if (!taxonomy.ok) return taxonomy;
       const media = await this.applyMedia(orgId, entityId, writable, variantIds.value.value, actor, warnings, owners);
@@ -3118,6 +3824,9 @@ export class ChannelConnectorService {
       skipped.push(...media.value.skipped.map((fieldPath) => ({ entityId, fieldPath })));
       entityTouched = entityTouched || optionAxes.value.changed || variantIds.value.changed || media.value.changed || attributes.value.changed;
       if (entityTouched) entitiesTouched += 1;
+      // Counted from what was written, not from the stored hash: a hash that moved while the
+      // product did not (a blanked map row, a change in how an item serialises) is not drift.
+      if (entityTouched && entityMapping && !isNew) converged += 1;
 
       if (entityTouched) {
         const revision = await this.catalog.recordEntityRevision(entityId, actor, "import");
@@ -3253,11 +3962,13 @@ export class ChannelConnectorService {
       const mapping = mappings.find((entry) => entry.externalId === level.externalId);
       if (!mapping) continue;
       const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-      if (current?.quantityOnHand === level.available) continue;
+      // Stock cannot sit below zero here, so negative remote stock compares as the zero it is stored as.
+      const quantity = Math.max(0, level.available);
+      if (current?.quantityOnHand === quantity) continue;
       const result = await inventoryService.setAbsolute({
         entityId: mapping.entityId,
         ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
-        quantity: level.available,
+        quantity,
         reason: `Inventory reconciliation from ${store.provider}`,
       }, actor);
       if (!result.ok) return PluginErr(result.error?.message ?? "Inventory reconciliation failed.");
@@ -3496,11 +4207,13 @@ export class ChannelConnectorService {
       const mapping = mappings.find((entry) => entry.externalId === level.externalId);
       if (!mapping) continue;
       const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-      if (current?.quantityOnHand === level.available) continue;
+      // Stock cannot sit below zero here, so negative remote stock compares as the zero it is stored as.
+      const quantity = Math.max(0, level.available);
+      if (current?.quantityOnHand === quantity) continue;
       const result = await inventoryService.setAbsolute({
         entityId: mapping.entityId,
         ...(mapping.variantId ? { variantId: mapping.variantId } : {}),
-        quantity: level.available,
+        quantity,
         reason: `Inventory sync from ${store.provider}`,
       }, actor);
       if (!result.ok) return PluginErr(result.error?.message ?? "Inventory sync failed.");
@@ -3780,8 +4493,10 @@ export class ChannelConnectorService {
       status?: string;
       isVisible?: boolean;
     } = {};
-    if (fieldPaths.includes("entity.slug") && ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && entity.slug !== writable.slug) {
-      updateInput.slug = writable.slug;
+    if (fieldPaths.includes("entity.slug") && ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && typeof writable.slug === "string") {
+      const resolved = (await this.resolveStoreSlugs(orgId, storeId, [writable.slug])).get(writable.slug);
+      const slug = resolved ? this.slugToKeep(entity.slug, resolved) : writable.slug;
+      if (entity.slug !== slug) updateInput.slug = slug;
     }
     if (Object.keys(writable.metadata ?? {}).length > 0) {
       const remoteEntityMetadata = mergeMetadata(entity.metadata, writable.metadata ?? {});