@porulle/plugin-channel-connector 0.54.0 → 0.56.0

package/src/deletion-policy.ts

@@ -0,0 +1,30 @@
+/**
+ * THE deletion policy for a store's mapped products that a fetch no longer lists — one home for
+ * the rule, shared by `reconcile()` and the app's import finalize barrier.
+ *
+ * A fetch that succeeded is not a fetch that was complete: a merchant API hiccup, pagination that
+ * stopped early, or an auth scope change returns fewer products than the store has, and archiving
+ * "everything absent" then wipes the store. Found on the sim, 2026-09-24. So the plan REFUSES:
+ *  - an empty fetch over a store that has mapped products;
+ *  - more absent products than max(ABSENT_ARCHIVE_FLOOR, floor(ABSENT_ARCHIVE_FRACTION × mapped)).
+ * A refusal archives nothing; the caller surfaces the reason for a person to look at.
+ */
+export const ABSENT_ARCHIVE_FLOOR = 5;
+export const ABSENT_ARCHIVE_FRACTION = 0.2;
+
+export type AbsentArchivePlan = { archive: string[] } | { refused: string };
+
+export function planAbsentArchives(mappedExternalIds: Iterable<string>, presentExternalIds: Iterable<string>): AbsentArchivePlan {
+  const mapped = [...new Set(mappedExternalIds)];
+  const present = new Set(presentExternalIds);
+  const absent = mapped.filter((externalId) => !present.has(externalId));
+  if (absent.length === 0) return { archive: [] };
+  if (present.size === 0) {
+    return { refused: `The fetch listed no products while ${mapped.length} are mapped; refusing to archive them.` };
+  }
+  const bound = Math.max(ABSENT_ARCHIVE_FLOOR, Math.floor(ABSENT_ARCHIVE_FRACTION * mapped.length));
+  if (absent.length > bound) {
+    return { refused: `${absent.length} of ${mapped.length} mapped products are absent from the fetch, above the bound of ${bound}; refusing to archive them.` };
+  }
+  return { archive: absent };
+}

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   channelCatalogPushes,
   channelCatalogConflicts,
   channelCatalogConflictEvents,
+  channelEntityLinks,
   channelEntityMap,
   channelExportEvents,
   channelOrderExports,
@@ -53,6 +54,8 @@ type ChannelRouteContext = {
   raw?: unknown;
 };
 
+export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
+export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";
 export {
@@ -451,6 +454,7 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
     schema: () => ({
       connectedStores,
       channelEntityMap,
+      channelEntityLinks,
       channelCatalogPushes,
       channelCatalogPushEvents,
       channelCatalogConflicts,

package/src/schema.ts

@@ -72,6 +72,26 @@ export const channelEntityMap = pgTable(
   }),
 );
 
+/**
+ * The category, brand and tag links a store's converge CREATED on an entity — link provenance, per
+ * store, the way `channel_entity_map` records the variants a store owns. A converge removes a link
+ * the store dropped only when the link is on record here: a link the merchant added (or another
+ * store did) has no row for this store and is never this store's to take away.
+ */
+export const channelEntityLinks = pgTable(
+  "channel_entity_links",
+  {
+    organizationId: text("organization_id").notNull(),
+    storeId: uuid("store_id").references(() => connectedStores.id, { onDelete: "cascade" }).notNull(),
+    entityId: uuid("entity_id").references(() => sellableEntities.id, { onDelete: "cascade" }).notNull(),
+    kind: text("kind", { enum: ["category", "brand", "tag"] }).notNull(),
+    targetId: uuid("target_id").notNull(),
+  },
+  (table) => ({
+    linkUnique: uniqueIndex("channel_entity_links_store_entity_kind_target_unique").on(table.storeId, table.entityId, table.kind, table.targetId),
+  }),
+);
+
 export const channelCatalogConflicts = pgTable(
   "channel_catalog_conflicts",
   {

package/src/service.ts

@@ -6,9 +6,13 @@ import {
   PluginErr,
   createTxContext,
   createSystemActor,
+  linkFieldPaths,
+  removeEntityLinks,
+  writeEntityLinks,
 } from "@porulle/core";
 import type {
   Actor,
+  EntityLinkRows,
   ChannelCatalogItem,
   ChannelConnector,
   ChannelOrderSlice,
@@ -33,15 +37,15 @@ import { isValidFieldPath, requireUserId } from "@porulle/core";
 import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
 import { CHANNEL_CONVERGENCE_CTX } from "./catalog-push-trigger.js";
-import { and, desc, eq, inArray, isNull, lte, or, sql } from "@porulle/core/drizzle";
+import { and, desc, eq, inArray, isNull, lte, or, sql, type SQL } from "@porulle/core/drizzle";
 import {
   brands,
   categories,
   customerAddresses,
   customers,
-  entityMedia,
   entityBrands,
   entityCategories,
+  entityMedia,
   entityTags,
   inventoryLevels,
   mediaAssets,
@@ -60,11 +64,13 @@ import {
   variantOptionValues,
 } from "@porulle/core/schema";
 import type { SellableEntityRevisionSnapshot } from "@porulle/core/schema";
+import { planAbsentArchives } from "./deletion-policy.js";
 import {
   channelCatalogPushEvents,
   channelCatalogPushes,
   channelCatalogConflicts,
   channelCatalogConflictEvents,
+  channelEntityLinks,
   channelEntityMap,
   channelExportEvents,
   channelOrderExports,
@@ -164,6 +170,8 @@ export interface ReconcileReport extends Record<string, unknown> {
   inventoryUpdated: number;
   openConflicts: number;
   driftAlert: boolean;
+  /** Why this reconcile archived nothing although mapped products were absent (`planAbsentArchives`). */
+  refused?: string;
   skipped?: CatalogFieldSkip[];
   conflicts?: CatalogFieldConflict[];
   warnings?: string[];
@@ -517,6 +525,8 @@ interface CatalogService {
     actor: Actor,
     ctx?: CatalogWriteContext,
   ): Promise<{ ok: true; value: undefined } | { ok: false; error: { message: string } }>;
+  /** Moves the entity's updated_at and fires catalog.afterUpdate for a change to related rows. */
+  notifyEntityChanged(entityId: string, changedFieldPaths: readonly string[], actor: Actor | null, ctx?: TxContext<PluginDb>): Promise<void>;
   recordEntityRevision(
     entityId: string,
     actor: Actor,
@@ -581,16 +591,6 @@ interface MediaService {
     },
     actor: Actor,
   ): Promise<ServiceResult<{ id: string; url: string }>>;
-  attachToEntity(
-    input: {
-      entityId: string;
-      mediaAssetId: string;
-      role: "primary" | "gallery" | "thumbnail" | "video" | "document";
-      variantId?: string;
-      sortOrder?: number;
-    },
-    actor: Actor,
-  ): Promise<ServiceResult<undefined>>;
   listEntityMedia(
     entityId: string,
     opts?: { variantId?: string; orgId?: string },
@@ -1127,6 +1127,9 @@ function toImportProduct(item: ChannelCatalogItem): ImportProduct {
   };
 }
 
+/** One item's link writes, planned before the transaction that commits them (`commitEntityLinks`). */
+type PlannedLinks = { [K in keyof EntityLinkRows]-?: Array<NonNullable<EntityLinkRows[K]>[number]> };
+
 export class ChannelConnectorService {
   private readonly connectors = new Map<string, ChannelConnector>();
   private readonly transact: PluginTxFn;
@@ -2050,19 +2053,20 @@ export class ChannelConnectorService {
     item: ChannelCatalogItem,
     actor: Actor,
     warnings: string[],
-  ): Promise<PluginResult<{ changed: boolean }>> {
+  ): Promise<PluginResult<Pick<PlannedLinks, "categories" | "brands" | "tags"> & { listed: Set<string> }>> {
+    // Resolves (creating where missing) the category, brand and tag rows the item names, and PLANS
+    // the entity's links to them. The links are written by `commitEntityLinks`, in one transaction
+    // with the entity's version bump; a link that already exists writes nothing there.
     const taxonomy = await this.taxonomyFor(orgId);
-    // The links this entity already has, read only for the classes the item names. A link already
-    // there is not re-written, and a link that is added is what reports the taxonomy as changed.
-    const linkedCategories = new Set((item.categories ?? []).length === 0 ? [] : (await this.db
-      .select({ id: entityCategories.categoryId }).from(entityCategories).where(eq(entityCategories.entityId, entityId))).map((row) => row.id));
-    const linkedBrands = new Set(!item.brand ? [] : (await this.db
-      .select({ id: entityBrands.brandId }).from(entityBrands).where(eq(entityBrands.entityId, entityId))).map((row) => row.id));
-    let changed = false;
+    const links: Pick<PlannedLinks, "categories" | "brands" | "tags"> = { categories: [], brands: [], tags: [] };
+    // Every link the item names, as `${kind}:${id}` — including an archived category it names but
+    // is not linked to again, so a link the store still lists is never read as dropped.
+    const listed = new Set<string>();
     const categoryRows = taxonomy.categories;
     for (const slug of new Set(item.categories ?? [])) {
       let category = categoryRows.find((row) => row.slug === slug);
       if (category?.status === "archived") {
+        listed.add(`category:${category.id}`);
         warnings.push(`Skipped archived category "${slug}".`);
         continue;
       }
@@ -2077,10 +2081,8 @@ export class ChannelConnectorService {
         category = created.value;
         categoryRows.push(category);
       }
-      if (linkedCategories.has(category.id)) continue;
-      const linked = await this.catalog.addToCategory(entityId, category.id, actor);
-      if (!linked.ok) return PluginErr(linked.error.message);
-      changed = true;
+      links.categories.push({ entityId, categoryId: category.id, sortOrder: 0 });
+      listed.add(`category:${category.id}`);
     }
 
     const brandRows = taxonomy.brands;
@@ -2098,11 +2100,8 @@ export class ChannelConnectorService {
         brand = created.value;
         brandRows.push(brand);
       }
-      if (!linkedBrands.has(brand.id)) {
-        const linked = await this.catalog.addToBrand(entityId, brand.id, actor);
-        if (!linked.ok) return PluginErr(linked.error.message);
-        changed = true;
-      }
+      links.brands.push({ entityId, brandId: brand.id, sortOrder: 0 });
+      listed.add(`brand:${brand.id}`);
     }
 
     const tagRows = taxonomy.tags;
@@ -2117,10 +2116,77 @@ export class ChannelConnectorService {
         if (!tag) return PluginErr(`Tag "${slug}" was not persisted.`);
         tagRows.push(tag);
       }
-      const added = await this.db.insert(entityTags).values({ entityId, tagId: tag.id }).onConflictDoNothing().returning({ tagId: entityTags.tagId });
-      if (added.length > 0) changed = true;
+      links.tags.push({ entityId, tagId: tag.id });
+      listed.add(`tag:${tag.id}`);
+    }
+    return Ok({ ...links, listed });
+  }
+
+  /**
+   * Writes one item's planned links and versions the entity for them, in ONE transaction: the
+   * entity's `updated_at` moves with the links or not at all, and `catalog.afterUpdate` fires once
+   * for the item with every link path that really changed (`["categories","tags"]`), not once per
+   * link. Returns those paths; empty means nothing changed.
+   *
+   * An entity CREATED by this converge is not versioned for its links: its creation already put it
+   * in front of every consumer, so a bump here would re-project a product in the same breath as its
+   * first projection — the cold-import cost this rule exists to avoid.
+   *
+   * It also REMOVES the category, brand and tag links the store no longer lists — only those on
+   * record in `channel_entity_links` as this store's, so a link the merchant added survives. Rows
+   * this converge inserts go on record; a product imported before provenance existed is claimed by
+   * `claimUnrecordedLinks` at the top of the converge.
+   */
+  private async commitEntityLinks(
+    orgId: string,
+    storeId: string,
+    entityId: string,
+    planned: PlannedLinks,
+    listed: Set<string>,
+    previousRoles: Map<string, string>,
+    isNew: boolean,
+    actor: Actor,
+  ): Promise<PluginResult<string[]>> {
+    try {
+      return Ok(await this.transact(async (tx) => {
+        const written = await writeEntityLinks(tx, orgId, planned);
+        const owned = isNew ? [] : await tx.select({ kind: channelEntityLinks.kind, targetId: channelEntityLinks.targetId }).from(channelEntityLinks)
+          .where(and(eq(channelEntityLinks.storeId, storeId), eq(channelEntityLinks.entityId, entityId)));
+        const dropped = owned.filter((row) => !listed.has(`${row.kind}:${row.targetId}`));
+        const removed = await removeEntityLinks(tx, orgId, {
+          categories: dropped.filter((row) => row.kind === "category").map((row) => ({ entityId, categoryId: row.targetId })),
+          brands: dropped.filter((row) => row.kind === "brand").map((row) => ({ entityId, brandId: row.targetId })),
+          tags: dropped.filter((row) => row.kind === "tag").map((row) => ({ entityId, tagId: row.targetId })),
+        });
+        if (dropped.length > 0) {
+          await tx.delete(channelEntityLinks).where(and(
+            eq(channelEntityLinks.storeId, storeId),
+            eq(channelEntityLinks.entityId, entityId),
+            or(...dropped.map((row) => and(eq(channelEntityLinks.kind, row.kind), eq(channelEntityLinks.targetId, row.targetId)))),
+          ));
+        }
+        const record = [
+          ...written.categories.map((row) => ({ kind: "category" as const, targetId: row.categoryId })),
+          ...written.brands.map((row) => ({ kind: "brand" as const, targetId: row.brandId })),
+          ...written.tags.map((row) => ({ kind: "tag" as const, targetId: row.tagId })),
+        ];
+        if (record.length > 0) {
+          await tx.insert(channelEntityLinks).values(record.map((row) => ({ organizationId: orgId, storeId, entityId, ...row }))).onConflictDoNothing();
+        }
+        const paths = new Set([...(linkFieldPaths(written).get(entityId) ?? []), ...(linkFieldPaths(removed).get(entityId) ?? [])]);
+        for (const row of written.placed) {
+          const previous = previousRoles.get(`${row.mediaAssetId}:${row.variantId}`);
+          if (previous !== undefined) paths.add(`media.${previous}`);
+        }
+        const changed = [...paths].sort();
+        if (changed.length > 0 && !isNew) {
+          await this.catalog.notifyEntityChanged(entityId, changed, actor, createTxContext(tx, { actor }));
+        }
+        return changed;
+      }));
+    } catch (error) {
+      return PluginErr(error instanceof Error ? error.message : "Failed to write the entity's links.");
     }
-    return Ok({ changed });
   }
 
   private async applyMedia(
@@ -2131,7 +2197,15 @@ export class ChannelConnectorService {
     actor: Actor,
     warnings: string[],
     owners: Map<FieldPath, FieldOwner>,
-  ): Promise<PluginResult<{ imported: number; changed: boolean; skipped: FieldPath[] }>> {
+  ): Promise<PluginResult<{
+    imported: number;
+    uploaded: boolean;
+    skipped: FieldPath[];
+    links: Pick<PlannedLinks, "media" | "mediaPlacements">;
+    /** The role a re-placed link held before, keyed `${mediaAssetId}:${variantId}` — its path changes too. */
+    previousRoles: Map<string, string>;
+  }>> {
+    // Uploads what is missing and PLANS the entity's media links; `commitEntityLinks` writes them.
     const images = item.images ?? [];
     const externalIds = [...new Set(images.map((image) => image.externalId).filter((id): id is string => id != null))];
     const urlHashes = [...new Set(images.map((image) => hash(image.url)))];
@@ -2150,8 +2224,10 @@ export class ChannelConnectorService {
       ));
     const links = await this.db.select().from(entityMedia).where(eq(entityMedia.entityId, entityId));
     let imported = 0;
-    let changed = false;
+    let uploaded = false;
     const skipped: FieldPath[] = [];
+    const planned: Pick<PlannedLinks, "media" | "mediaPlacements"> = { media: [], mediaPlacements: [] };
+    const previousRoles = new Map<string, string>();
 
     // A Cloudflare Worker may hold at most six simultaneous outbound connections per
     // invocation, and one image costs two of them — the download and the storage put — so
@@ -2273,7 +2349,7 @@ export class ChannelConnectorService {
     for (const resolved of resolvedImages) {
       warnings.push(...resolved.imageWarnings);
       imported += resolved.imported;
-      if (resolved.imageChanged) changed = true;
+      if (resolved.imageChanged) uploaded = true;
     }
 
     for (const [imageIndex, image] of images.entries()) {
@@ -2302,24 +2378,12 @@ export class ChannelConnectorService {
             if (skipped.includes(currentRolePath) || skipped.includes(incomingRolePath)) continue;
           }
           if (existingLink.role !== image.role || existingLink.sortOrder !== (image.sortOrder ?? 0)) {
-            await this.db.update(entityMedia).set({ role: image.role, sortOrder: image.sortOrder ?? 0 }).where(and(
-              eq(entityMedia.entityId, entityId),
-              eq(entityMedia.mediaAssetId, mediaAssetId),
-              target.variantId === undefined ? isNull(entityMedia.variantId) : eq(entityMedia.variantId, target.variantId),
-            ));
-            changed = true;
+            planned.mediaPlacements.push({ entityId, variantId: target.variantId ?? null, mediaAssetId, role: image.role, sortOrder: image.sortOrder ?? 0 });
+            previousRoles.set(`${mediaAssetId}:${target.variantId ?? null}`, existingLink.role);
           }
           continue;
         }
-        const attached = await this.media.attachToEntity({
-          entityId,
-          mediaAssetId,
-          role: image.role,
-          sortOrder: image.sortOrder ?? 0,
-          ...(target.variantId !== undefined ? { variantId: target.variantId } : {}),
-        }, actor);
-        if (!attached.ok) return PluginErr(attached.error.message);
-        changed = true;
+        planned.media.push({ entityId, variantId: target.variantId ?? null, mediaAssetId, role: image.role, sortOrder: image.sortOrder ?? 0 });
         links.push({
           entityId,
           mediaAssetId,
@@ -2330,7 +2394,7 @@ export class ChannelConnectorService {
         });
       }
     }
-    return Ok({ imported, changed, skipped });
+    return Ok({ imported, uploaded, skipped, links: planned, previousRoles });
   }
 
   private async getStoreRecord(orgId: string, id: string): Promise<ConnectedStore | undefined> {
@@ -3232,6 +3296,15 @@ export class ChannelConnectorService {
           return variantId === undefined ? [] : [{ organizationId: orgId, storeId, kind: "variant" as const, externalId: variant.externalId, entityId, variantId, syncHash: hash(variant), lastSyncedAt: now }];
         }),
       ])).onConflictDoNothing();
+      // Every category / brand / tag link on an entity this page just created was written by this
+      // import, so all of it is this store's on record (`channel_entity_links`) — one statement.
+      const created = sql.join(createdItems.map(({ entityId }) => sql`${entityId}::uuid`), sql`, `);
+      await this.db.execute(sql`
+        insert into ${channelEntityLinks} (organization_id, store_id, entity_id, kind, target_id)
+        select ${orgId}, ${storeId}::uuid, entity_id, 'category', category_id from ${entityCategories} where entity_id in (${created})
+        union all select ${orgId}, ${storeId}::uuid, entity_id, 'brand', brand_id from ${entityBrands} where entity_id in (${created})
+        union all select ${orgId}, ${storeId}::uuid, entity_id, 'tag', tag_id from ${entityTags} where entity_id in (${created})
+        on conflict do nothing`);
     }
 
     const media = await this.importHeroes(orgId, createdItems, actor);
@@ -3328,13 +3401,13 @@ export class ChannelConnectorService {
     }));
 
     if (outcomes.length > 0) {
-      await this.db.insert(entityMedia).values(outcomes.flatMap(({ entityId, mediaAssetId, hero, variantIds }) => [
-        { entityId, mediaAssetId, role: "primary" as const, sortOrder: hero.sortOrder ?? 0 },
+      await writeEntityLinks(this.db, orgId, { media: outcomes.flatMap(({ entityId, mediaAssetId, hero, variantIds }) => [
+        { entityId, variantId: null, mediaAssetId, role: "primary" as const, sortOrder: hero.sortOrder ?? 0 },
         ...(hero.variantExternalIds ?? []).flatMap((externalId) => {
           const variantId = variantIds[externalId];
           return variantId === undefined ? [] : [{ entityId, variantId, mediaAssetId, role: hero.role, sortOrder: hero.sortOrder ?? 0 }];
         }),
-      ])).onConflictDoNothing();
+      ]) });
     }
     return { heroesImported: outcomes.filter((outcome) => outcome.imported).length, mediaFailures, deferredMedia };
   }
@@ -3829,6 +3902,52 @@ export class ChannelConnectorService {
     return Ok(stats);
   }
 
+  /**
+   * Link provenance for products imported before `channel_entity_links` existed: a mapped product
+   * of this batch with NOTHING on record for this store claims, once, the category / brand / tag
+   * links it has that the store lists NOW. Runs for unchanged items too — an unchanged item skips
+   * its converge, and the converge that follows may already be the drop, too late to claim.
+   *
+   * Its limit, stated rather than hidden: a link upstream had dropped BEFORE this claim was never
+   * the store's on record, so it stays (the stale set the old add-only converge left; repaired by a
+   * re-import, not by a heuristic delete). One select per batch; the claims only while unclaimed
+   * products remain.
+   */
+  private async claimUnrecordedLinks(orgId: string, storeId: string, items: ChannelCatalogItem[]): Promise<void> {
+    if (items.length === 0) return;
+    const unclaimed = await this.db.select({ externalId: channelEntityMap.externalId, entityId: channelEntityMap.entityId }).from(channelEntityMap).where(and(
+      eq(channelEntityMap.organizationId, orgId),
+      eq(channelEntityMap.storeId, storeId),
+      eq(channelEntityMap.kind, "entity"),
+      inArray(channelEntityMap.externalId, items.map((item) => item.externalId)),
+      sql`not exists (select 1 from ${channelEntityLinks} where ${channelEntityLinks.storeId} = ${channelEntityMap.storeId} and ${channelEntityLinks.entityId} = ${channelEntityMap.entityId})`,
+    ));
+    if (unclaimed.length === 0) return;
+    const entityOf = new Map(unclaimed.map((row) => [row.externalId, row.entityId]));
+    const listed = (pick: (item: ChannelCatalogItem) => readonly string[]) => items.flatMap((item) => {
+      const entityId = entityOf.get(item.externalId);
+      return entityId === undefined ? [] : [...new Set(pick(item))].map((slug) => sql`(${entityId}::uuid, ${slug}::text)`);
+    });
+    const claim = async (kind: "category" | "brand" | "tag", pairs: SQL[], link: SQL) => {
+      if (pairs.length === 0) return;
+      await this.db.execute(sql`
+        insert into ${channelEntityLinks} (organization_id, store_id, entity_id, kind, target_id)
+        select ${orgId}, ${storeId}::uuid, v.entity_id, ${kind}, t.id
+        from (values ${sql.join(pairs, sql`, `)}) as v(entity_id, slug)
+        ${link}
+        on conflict do nothing`);
+    };
+    await claim("category", listed((item) => item.categories ?? []),
+      sql`join ${categories} t on t.slug = v.slug and t.organization_id = ${orgId}
+        join ${entityCategories} l on l.entity_id = v.entity_id and l.category_id = t.id`);
+    await claim("brand", listed((item) => (item.brand ? [item.brand] : [])),
+      sql`join ${brands} t on t.slug = v.slug and t.organization_id = ${orgId}
+        join ${entityBrands} l on l.entity_id = v.entity_id and l.brand_id = t.id`);
+    await claim("tag", listed((item) => item.tags ?? []),
+      sql`join ${tags} t on t.slug = v.slug and t.organization_id = ${orgId}
+        join ${entityTags} l on l.entity_id = v.entity_id and l.tag_id = t.id`);
+  }
+
   private async convergeCatalogItems(
     orgId: string,
     storeId: string,
@@ -3860,6 +3979,7 @@ export class ChannelConnectorService {
     // Upstream SKU/barcode changes on already-mapped variants, for the whole batch at once, so that
     // variants exchanging SKUs across products in this batch land together.
     const identity = await this.applyUpstreamVariantIdentity(orgId, storeId, items);
+    await this.claimUnrecordedLinks(orgId, storeId, items);
     for (const item of items) {
       consumed += 1;
       try {
@@ -4073,11 +4193,14 @@ export class ChannelConnectorService {
       if (!taxonomy.ok) { failures.push({ externalId: item.externalId, error: taxonomy.error }); continue; }
       const media = await this.applyMedia(orgId, entityId, writable, variantIds.value.value, actor, warnings, owners);
       if (!media.ok) return media;
+      const { listed, ...taxonomyLinks } = taxonomy.value;
+      const links = await this.commitEntityLinks(orgId, storeId, entityId, { ...taxonomyLinks, ...media.value.links }, listed, media.value.previousRoles, isNew, actor);
+      if (!links.ok) { failures.push({ externalId: item.externalId, error: links.error }); continue; }
       attributesCreated += attributes.value.created;
       mediaImported += media.value.imported;
       variantsGivenOptionValues += variantIds.value.repaired;
       skipped.push(...media.value.skipped.map((fieldPath) => ({ entityId, fieldPath })));
-      entityTouched = entityTouched || optionAxes.value.changed || variantIds.value.changed || taxonomy.value.changed || media.value.changed || attributes.value.changed
+      entityTouched = entityTouched || optionAxes.value.changed || variantIds.value.changed || links.value.length > 0 || media.value.uploaded || attributes.value.changed
         || identity.written.has(item.externalId);
       const skuClashes = identity.clashes.get(item.externalId);
       if (skuClashes) {
@@ -4207,11 +4330,14 @@ export class ChannelConnectorService {
 
     const converged = await this.convergeCatalogItems(orgId, storeId, items, actor);
     if (!converged.ok) return converged;
-    const present = new Set(items.map((item) => item.externalId));
+    // Planned BEFORE anything is archived: an empty or truncated fetch is refused whole (see
+    // `planAbsentArchives`), and the refusal is reported, never half-applied.
+    const plan = planAbsentArchives(entityMappings.map((mapping) => mapping.externalId), items.map((item) => item.externalId));
+    const toArchive = new Set("archive" in plan ? plan.archive : []);
     let archived = 0;
     const skipped = [...converged.value.skipped];
     for (const mapping of entityMappings) {
-      if (present.has(mapping.externalId)) continue;
+      if (!toArchive.has(mapping.externalId)) continue;
       const [entity] = await this.db.select({ status: sellableEntities.status }).from(sellableEntities).where(and(
         eq(sellableEntities.organizationId, orgId),
         eq(sellableEntities.id, mapping.entityId),
@@ -4263,7 +4389,8 @@ export class ChannelConnectorService {
       archived,
       inventoryUpdated,
       openConflicts: openConflictRows.length,
-      driftAlert: converged.value.imported + converged.value.converged + archived > threshold,
+      driftAlert: "refused" in plan || converged.value.imported + converged.value.converged + archived > threshold,
+      ...("refused" in plan ? { refused: plan.refused } : {}),
       ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
       ...(converged.value.conflicts.length > 0 ? { conflicts: converged.value.conflicts } : {}),
       ...(converged.value.warnings.length > 0 ? { warnings: converged.value.warnings } : {}),