@porulle/plugin-channel-connector 0.48.1 → 0.50.0

package/dist/service.js

@@ -125,6 +125,41 @@ export function canCatalogPushTransition(from, to) {
 function hash(value) {
     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) {
+    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) {
+    let cursor = 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) {
+    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 = "";
 export const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS = 15 * 60 * 1000;
@@ -364,6 +399,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 +873,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 +889,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 +927,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 +954,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 +1020,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 +1062,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 +1070,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 +1091,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 +1162,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 +1179,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) {
@@ -1088,6 +1385,59 @@ export class ChannelConnectorService {
             .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, id)));
         return rows[0];
     }
+    /**
+     * 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.
+     */
+    async resolveStoreSlugs(orgId, storeId, handles) {
+        const wanted = [...new Set(handles)];
+        const resolved = new Map();
+        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) => 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.
+    slugSuffixByStore = new Map();
+    async storeSlugSuffixFor(orgId, storeId) {
+        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. */
+    slugToKeep(currentSlug, resolved) {
+        return resolved.family.includes(currentSlug) ? currentSlug : resolved.slug;
+    }
     async getStoreByDomain(shopDomain) {
         const rows = await this.db
             .select()
@@ -1688,6 +2038,236 @@ 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 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) => (slugFor.get(handle)?.family ?? [handle]).some((slug) => orphanSlugs.has(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 || 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 = [];
+        // 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 = [];
+            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", 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 +2669,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;
@@ -2102,6 +2686,8 @@ export class ChannelConnectorService {
         const failures = [];
         const entityIds = [];
         const committed = new Set();
+        // 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 {
@@ -2127,8 +2713,15 @@ 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 () => {
+                    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)));
+                    const [orphan] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.sourceStoreId, storeId), inArray(sellableEntities.slug, resolvedSlug.family))).limit(1);
                     if (orphan) {
                         entityId = orphan.id;
                         existingEntity = orphan;
@@ -2136,33 +2729,46 @@ export class ChannelConnectorService {
                     }
                     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) => 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: [],
                             });
+                            return created.value.id;
+                        });
+                        let createError;
+                        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;
+                            }
                         }
-                        catch (error) {
-                            failures.push({ externalId: item.externalId, error: error instanceof Error ? error.message : "Failed to create catalog entity." });
+                        if (entityId === undefined) {
+                            failures.push({ externalId: item.externalId, error: createError instanceof Error ? createError.message : "Failed to create catalog entity." });
                             continue;
                         }
                         isNew = true;
@@ -2214,8 +2820,9 @@ export class ChannelConnectorService {
                         ? writable.status ?? (existingEntity.status === "archived" ? "active" : undefined)
                         : undefined;
                     const updateInput = {};
-                    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;
@@ -2227,11 +2834,29 @@ 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 });
+                            const mappedEntityId = entityMapping.entityId;
+                            const update = async () => {
+                                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;
@@ -2245,8 +2870,12 @@ export class ChannelConnectorService {
                 if (!attributes.ok)
                     return attributes;
                 const variantIds = await this.upsertVariants(orgId, storeId, entityId, writable, optionAxes.value.value, actor, warnings, !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;
@@ -2260,6 +2889,10 @@ export class ChannelConnectorService {
                 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");
                     if (!revision.ok) {
@@ -2382,12 +3015,14 @@ export class ChannelConnectorService {
             if (!mapping)
                 continue;
             const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-            if (current?.quantityOnHand === level.available)
+            // 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)
@@ -2594,12 +3229,14 @@ export class ChannelConnectorService {
             if (!mapping)
                 continue;
             const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
-            if (current?.quantityOnHand === level.available)
+            // 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)
@@ -2866,8 +3503,11 @@ export class ChannelConnectorService {
         const warnings = conflicts.map((conflict) => `Held shared field conflict for entity "${conflict.entityId}", store "${conflict.storeId}", field "${conflict.fieldPath}" (local ${conflict.localValueSummary}, remote ${conflict.remoteValueSummary}).`);
         const writable = held.writable;
         const updateInput = {};
-        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 ?? {});