@porulle/plugin-channel-connector 0.48.1 → 0.49.0

package/dist/service.js

@@ -364,6 +364,131 @@ function redactStore(store) {
         updatedAt: store.updatedAt,
     };
 }
+/**
+ * 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;
+function imageOrder(a, b) {
+    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) {
+    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 = [];
+    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 };
+}
+/** Streams a response and refuses mid-stream past `cap`; a lying `content-length` cannot get around it. */
+async function fetchBounded(url, cap) {
+    let 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 = [];
+    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) {
+    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 {
     db;
     services;
@@ -713,7 +838,15 @@ export class ChannelConnectorService {
     }
     async upsertOptionAxes(entityId, item, actor) {
         const optionValueIds = new Map();
-        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 = 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);
@@ -721,18 +854,37 @@ export class ChannelConnectorService {
                 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 existingValues = await this.db.select().from(optionValues).where(eq(optionValues.optionTypeId, 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({ id: optionValues.id, value: optionValues.value, displayValue: optionValues.displayValue, sortOrder: optionValues.sortOrder })
+                .from(optionValues)
+                .where(eq(optionValues.optionTypeId, optionType.id));
             const valueIds = new Map();
             for (const [valueIndex, sourceValue] of sourceType.values.entries()) {
                 let optionValue = existingValues.find((row) => row.value === sourceValue.value);
@@ -740,17 +892,22 @@ export class ChannelConnectorService {
                     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);
@@ -762,10 +919,52 @@ export class ChannelConnectorService {
         let repaired = 0;
         let changed = false;
         const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), 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 !== null);
+        const existingOptionValues = new Map();
+        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 = {};
@@ -786,18 +985,38 @@ export class ChannelConnectorService {
                 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.`);
@@ -808,8 +1027,7 @@ export class ChannelConnectorService {
                 const desiredOptionValueIds = Object.entries(sourceVariant.optionValues ?? {})
                     .map(([name, value]) => optionValueIds.get(name)?.get(value))
                     .filter((optionValueId) => 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));
@@ -817,6 +1035,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) {
@@ -835,16 +1056,57 @@ export class ChannelConnectorService {
                 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.
+     */
+    taxonomyCache = null;
+    async taxonomyFor(orgId) {
+        // 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;
+    }
     async applyTaxonomy(orgId, entityId, item, actor, warnings) {
-        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") {
@@ -865,7 +1127,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) {
@@ -882,7 +1144,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) {
@@ -1688,6 +1950,206 @@ 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, storeId, cursor) {
+        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, 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, storeId, items, actor) {
+        const failures = [];
+        const warnings = [];
+        const entityByExternalId = new Map();
+        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 = [];
+        const editor = [];
+        const seen = new Set();
+        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 = [];
+        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", 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", externalId: variant.externalId, entityId, variantId, syncHash: hash(variant), lastSyncedAt: now }];
+                    }),
+                ])).onConflictDoNothing();
+            }
+        }
+        const media = await this.importHeroes(orgId, createdItems, actor);
+        const entityIds = [];
+        const emitted = new Set();
+        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,
+        });
+    }
+    async importHeroes(orgId, createdItems, actor) {
+        const mediaFailures = [];
+        const deferredMedia = [];
+        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();
+        for (const asset of existingAssets) {
+            const urlHash = asset.metadata?.channelImageUrlHash;
+            if (typeof urlHash === "string")
+                assetByUrlHash.set(urlHash, asset.id);
+        }
+        const outcomes = [];
+        const resolveHero = async ({ item, entityId, variantIds, hero }) => {
+            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, detail) => {
+                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", 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, storeId, actor, options) {
         const store = await this.getStoreRecord(orgId, storeId);
         if (!store || store.status !== "connected") {
@@ -2089,6 +2551,10 @@ export class ChannelConnectorService {
     async convergeCatalogItems(orgId, storeId, items, actor, force = false, dryRun = false) {
         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;