@porulle/plugin-channel-connector 0.55.0 → 0.57.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
+export { channelSyncHash } from "./service.js";
 export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";

package/dist/index.js

@@ -3,11 +3,12 @@ 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 { channelSyncHash } from "./service.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";
@@ -290,6 +291,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

@@ -236,6 +236,8 @@ export interface CatalogPushPreviewResult {
 }
 export declare function canExportTransition(from: ExportState, to: ExportState): boolean;
 export declare function canCatalogPushTransition(from: CatalogPushState, to: CatalogPushState): boolean;
+/** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+export declare function channelSyncHash(value: unknown): string;
 /**
  * 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.
@@ -368,6 +370,11 @@ export declare class ChannelConnectorService {
      * 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;
@@ -466,6 +473,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,11 +1,11 @@
 import { createHash } from "node:crypto";
-import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createTxContext, createSystemActor, linkFieldPaths, writeEntityLinks, } 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, inventoryLevels, mediaAssets, optionTypes, optionValues, orderLineItems, orders, prices, sellableAttributes, sellableCustomFields, sellableEntities, sellableEntityRevisions, entityFieldDefinitions, tags, variants, variantOptionValues, } from "@porulle/core/schema";
+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, channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.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,
@@ -123,9 +123,30 @@ const catalogPushTransitions = {
 export function canCatalogPushTransition(from, to) {
     return catalogPushTransitions[from].includes(to);
 }
-function hash(value) {
-    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/**
+ * JSON with every object's keys sorted, recursively — the one form every hash here is taken over.
+ *
+ * The sync hash was `sha256(JSON.stringify(item))`, and JSON.stringify writes keys in insertion
+ * order. The host's page consumer rebuilds each landed item in its own key order while reconcile
+ * hashes the adapter's objects in theirs, so the fast path and reconcile hashed the SAME content
+ * differently and reconcile re-converged every freshly imported product. Content, not key order,
+ * is what a hash here must answer. `undefined` values are dropped exactly as JSON.stringify drops
+ * them; array order is kept (it carries meaning: images, variants, options).
+ */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map((entry) => (entry === undefined ? "null" : canonicalJson(entry))).join(",")}]`;
+    if (value !== null && typeof value === "object" && !(value instanceof Date)) {
+        const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
 }
+/** THE sync hash: every path that records or compares a `channel_entity_map.sync_hash` uses this. */
+export function channelSyncHash(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+const hash = channelSyncHash;
 /**
  * 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.
@@ -1339,10 +1360,14 @@ export class ChannelConnectorService {
         // with the entity's version bump; a link that already exists writes nothing there.
         const taxonomy = await this.taxonomyFor(orgId);
         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;
             }
@@ -1354,6 +1379,7 @@ export class ChannelConnectorService {
                 categoryRows.push(category);
             }
             links.categories.push({ entityId, categoryId: category.id, sortOrder: 0 });
+            listed.add(`category:${category.id}`);
         }
         const brandRows = taxonomy.brands;
         if (item.brand) {
@@ -1367,6 +1393,7 @@ export class ChannelConnectorService {
                 brandRows.push(brand);
             }
             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 ?? [])) {
@@ -1379,8 +1406,9 @@ export class ChannelConnectorService {
                 tagRows.push(tag);
             }
             links.tags.push({ entityId, tagId: tag.id });
+            listed.add(`tag:${tag.id}`);
         }
-        return Ok(links);
+        return Ok({ ...links, listed });
     }
     /**
      * Writes one item's planned links and versions the entity for them, in ONE transaction: the
@@ -1391,12 +1419,36 @@ export class ChannelConnectorService {
      * 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, entityId, planned, previousRoles, isNew, actor) {
+    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 paths = new Set(linkFieldPaths(written).get(entityId));
+                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)
@@ -2375,6 +2427,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 = [];
@@ -2871,6 +2932,47 @@ 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) {
+        // Nothing listed, nothing to claim: no query. Otherwise one select per converge call (a batch),
+        // never one per product.
+        if (!items.some((item) => (item.tags?.length ?? 0) > 0 || (item.categories?.length ?? 0) > 0 || item.brand !== undefined))
+            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);
@@ -2896,6 +2998,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 {
@@ -3096,7 +3199,8 @@ export class ChannelConnectorService {
                 const media = await this.applyMedia(orgId, entityId, writable, variantIds.value.value, actor, warnings, owners);
                 if (!media.ok)
                     return media;
-                const links = await this.commitEntityLinks(orgId, entityId, { ...taxonomy.value, ...media.value.links }, media.value.previousRoles, isNew, actor);
+                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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,15 +19,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.55.0"
+    "@porulle/core": "0.57.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"

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   channelCatalogPushes,
   channelCatalogConflicts,
   channelCatalogConflictEvents,
+  channelEntityLinks,
   channelEntityMap,
   channelExportEvents,
   channelOrderExports,
@@ -54,6 +55,7 @@ type ChannelRouteContext = {
 };
 
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
+export { channelSyncHash } from "./service.js";
 export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";
@@ -453,6 +455,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",
   {