@porulle/plugin-channel-connector 0.48.0 → 0.49.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,
@@ -891,6 +900,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 +1483,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 +1581,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 +1646,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 +1686,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 +1694,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 +1714,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 +1780,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 +1800,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 +1815,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) {
@@ -2427,6 +2747,229 @@ 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 slugs = [...new Set(items.map((item) => item.slug))];
+    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 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 || orphanSlugs.has(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> }> = [];
+    if (fresh.length > 0) {
+      const report = await this.catalog.importProducts(fresh.map(toImportProduct), { sourceStoreId: storeId, errorPolicy: "reject-failed-rows" }, actor);
+      if (!report.ok) return PluginErr(report.error.message, report.error.code);
+      for (const [index, row] of report.value.rows.entries()) {
+        const item = fresh[index];
+        if (!item) continue;
+        if (row.status === "failed") {
+          failures.push({ externalId: row.ref, error: `${row.code}: ${row.error}` });
+          continue;
+        }
+        warnings.push(...row.warnings);
+        entityByExternalId.set(item.externalId, row.entityId);
+        createdItems.push({ item, entityId: row.entityId, variantIds: row.variantIds });
+      }
+      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 +3469,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;