@porulle/plugin-channel-connector 0.54.0 → 0.56.0

package/dist/deletion-policy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare const ABSENT_ARCHIVE_FLOOR = 5;
+export declare const ABSENT_ARCHIVE_FRACTION = 0.2;
+export type AbsentArchivePlan = {
+    archive: string[];
+} | {
+    refused: string;
+};
+export declare function planAbsentArchives(mappedExternalIds: Iterable<string>, presentExternalIds: Iterable<string>): AbsentArchivePlan;

package/dist/deletion-policy.js

@@ -0,0 +1,28 @@
+/**
+ * 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 function planAbsentArchives(mappedExternalIds, presentExternalIds) {
+    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/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
+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 { ChannelConnectorService, HERO_IMAGE_BYTE_CAP, selectImportImages, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, isCatalogPushBreakerOpen, } from "./service.js";

package/dist/index.js

@@ -3,10 +3,11 @@ import { CommerceConflictError, CommerceInvalidTransitionError, CommerceNotFound
 import { z } from "@hono/zod-openapi";
 import { and, eq } from "@porulle/core/drizzle";
 import { processedWebhookEvents } from "@porulle/core/schema";
-import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
+import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, channelRefundEvents, channelRefundRequests, connectedStores, } from "./schema.js";
 import { ChannelConnectorService, catalogPushConcurrencyKey, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, } from "./service.js";
 import { buildHooks } from "./hooks.js";
 import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
+export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export { ChannelConnectorService, HERO_IMAGE_BYTE_CAP, selectImportImages, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, isCatalogPushBreakerOpen, } from "./service.js";
 export { isValidCatalogMappingFieldPath, matchFieldPath, mergeCatalogFieldMapping, normalizeCatalogFieldMapping, compareCatalogFieldMappingSpecificity, providerCatalogFieldMappingDefaults, selectCatalogFieldMapping, validateCatalogMappingRow, } from "./catalog-field-mapping.js";
@@ -289,6 +290,7 @@ export function channelConnectorPlugin(options = {}) {
         schema: () => ({
             connectedStores,
             channelEntityMap,
+            channelEntityLinks,
             channelCatalogPushes,
             channelCatalogPushEvents,
             channelCatalogConflicts,

package/dist/schema.d.ts

@@ -555,6 +555,104 @@ export declare const channelEntityMap: import("drizzle-orm/pg-core/table").PgTab
     };
     dialect: "pg";
 }>;
+/**
+ * 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 declare const channelEntityLinks: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "channel_entity_links";
+    schema: undefined;
+    columns: {
+        organizationId: import("@porulle/core/drizzle").PgColumn<{
+            name: "organization_id";
+            tableName: "channel_entity_links";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        storeId: import("@porulle/core/drizzle").PgColumn<{
+            name: "store_id";
+            tableName: "channel_entity_links";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        entityId: import("@porulle/core/drizzle").PgColumn<{
+            name: "entity_id";
+            tableName: "channel_entity_links";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        kind: import("@porulle/core/drizzle").PgColumn<{
+            name: "kind";
+            tableName: "channel_entity_links";
+            dataType: "string";
+            columnType: "PgText";
+            data: "brand" | "category" | "tag";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["category", "brand", "tag"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        targetId: import("@porulle/core/drizzle").PgColumn<{
+            name: "target_id";
+            tableName: "channel_entity_links";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export declare const channelCatalogConflicts: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
     name: "channel_catalog_conflicts";
     schema: undefined;

package/dist/schema.js

@@ -44,6 +44,21 @@ export const channelEntityMap = pgTable("channel_entity_map", {
     storeIdx: index("idx_channel_entity_map_store").on(table.storeId),
     externalUnique: uniqueIndex("channel_entity_map_store_kind_external_unique").on(table.storeId, table.kind, table.externalId),
 }));
+/**
+ * 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", {
     id: uuid("id").defaultRandom().primaryKey(),
     organizationId: text("organization_id").notNull(),

package/dist/service.d.ts

@@ -39,6 +39,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[];
@@ -357,6 +359,22 @@ export declare class ChannelConnectorService {
      */
     private createTaxonomyOrAdopt;
     private applyTaxonomy;
+    /**
+     * 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 commitEntityLinks;
     private applyMedia;
     private getStoreRecord;
     /**
@@ -453,6 +471,18 @@ export declare class ChannelConnectorService {
     private saveBackfillState;
     backfillCatalog(orgId: string, storeId: string, actor: Actor, options?: BackfillCatalogOptions): Promise<PluginResult<BackfillCatalogReport>>;
     private estimateCatalogItems;
+    /**
+     * 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 claimUnrecordedLinks;
     private convergeCatalogItems;
     reconcile(orgId: string, storeId: string, actor: Actor): Promise<PluginResult<ReconcileReport>>;
     getReconcileStatus(orgId: string, storeId: string): Promise<PluginResult<{

package/dist/service.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
-import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createTxContext, createSystemActor, } from "@porulle/core";
+import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createTxContext, createSystemActor, linkFieldPaths, removeEntityLinks, writeEntityLinks, } from "@porulle/core";
 import { isValidFieldPath, requireUserId } 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 { brands, categories, customerAddresses, customers, entityMedia, entityBrands, entityCategories, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
-import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.js";
+import { brands, categories, customerAddresses, customers, entityBrands, entityCategories, entityMedia, entityTags, inventoryLevels, mediaAssets, optionTypes, optionValues, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
+import { planAbsentArchives } from "./deletion-policy.js";
+import { channelCatalogPushEvents, channelCatalogPushes, channelCatalogConflicts, channelCatalogConflictEvents, channelEntityLinks, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.js";
 import { mergeCatalogFieldMapping, normalizeCatalogFieldMapping, selectCatalogFieldMapping, } from "./catalog-field-mapping.js";
 export const CATALOG_PUSH_BATCH_SIZES = {
     mock: 100,
@@ -1333,18 +1334,19 @@ export class ChannelConnectorService {
         return existing !== undefined ? Ok(existing) : PluginErr(`${label}: ${errorMessage(failure)}`);
     }
     async applyTaxonomy(orgId, entityId, item, actor, warnings) {
+        // 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 = { 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();
         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;
             }
@@ -1355,12 +1357,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;
         if (item.brand) {
@@ -1373,12 +1371,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;
         for (const slug of new Set(item.tags ?? [])) {
@@ -1390,13 +1384,68 @@ export class ChannelConnectorService {
                     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.
+     */
+    async commitEntityLinks(orgId, storeId, entityId, planned, listed, previousRoles, isNew, actor) {
+        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", targetId: row.categoryId })),
+                    ...written.brands.map((row) => ({ kind: "brand", targetId: row.brandId })),
+                    ...written.tags.map((row) => ({ kind: "tag", 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 });
     }
     async applyMedia(orgId, entityId, item, variantIds, actor, warnings, owners) {
+        // 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 != null))];
         const urlHashes = [...new Set(images.map((image) => hash(image.url)))];
@@ -1412,8 +1461,10 @@ export class ChannelConnectorService {
             : await this.db.select().from(mediaAssets).where(and(eq(mediaAssets.organizationId, orgId), or(...keyPredicates)));
         const links = await this.db.select().from(entityMedia).where(eq(entityMedia.entityId, entityId));
         let imported = 0;
-        let changed = false;
+        let uploaded = false;
         const skipped = [];
+        const planned = { media: [], mediaPlacements: [] };
+        const previousRoles = new Map();
         // 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
         // 6 / 2 = 3 images may be in flight. A fourth would queue behind the platform limit
@@ -1526,7 +1577,7 @@ export class ChannelConnectorService {
             warnings.push(...resolved.imageWarnings);
             imported += resolved.imported;
             if (resolved.imageChanged)
-                changed = true;
+                uploaded = true;
         }
         for (const [imageIndex, image] of images.entries()) {
             const mediaAssetId = resolvedImages[imageIndex]?.mediaAssetId;
@@ -1554,21 +1605,12 @@ export class ChannelConnectorService {
                             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,
@@ -1579,7 +1621,7 @@ export class ChannelConnectorService {
                 });
             }
         }
-        return Ok({ imported, changed, skipped });
+        return Ok({ imported, uploaded, skipped, links: planned, previousRoles });
     }
     async getStoreRecord(orgId, id) {
         const rows = await this.db
@@ -2364,6 +2406,15 @@ export class ChannelConnectorService {
                     return variantId === undefined ? [] : [{ organizationId: orgId, storeId, kind: "variant", 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);
         const entityIds = [];
@@ -2452,13 +2503,13 @@ export class ChannelConnectorService {
             }
         }));
         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();
+            await writeEntityLinks(this.db, orgId, { media: outcomes.flatMap(({ entityId, mediaAssetId, hero, variantIds }) => [
+                    { entityId, variantId: null, 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 }];
+                    }),
+                ]) });
         }
         return { heroesImported: outcomes.filter((outcome) => outcome.imported).length, mediaFailures, deferredMedia };
     }
@@ -2860,6 +2911,45 @@ 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.
+     */
+    async claimUnrecordedLinks(orgId, storeId, items) {
+        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) => 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, pairs, link) => {
+            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`);
+    }
     async convergeCatalogItems(orgId, storeId, items, actor, force = false, dryRun = false) {
         if (dryRun)
             return this.estimateCatalogItems(orgId, storeId, items);
@@ -2885,6 +2975,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 {
@@ -3085,11 +3176,17 @@ export class ChannelConnectorService {
                 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) {
@@ -3214,11 +3311,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))
+            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)));
             if (entity?.status !== "archived") {
@@ -3266,7 +3366,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 } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,15 +19,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.54.0"
+    "@porulle/core": "0.56.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/typescript-config": "0.1.0",
-    "@porulle/eslint-config": "0.1.0"
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"