@porulle/plugin-channel-connector 0.10.8 → 0.13.0

package/dist/service.js

@@ -1,8 +1,53 @@
 import { createHash } from "node:crypto";
-import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createSystemActor, } from "@porulle/core";
-import { and, eq, inArray } from "@porulle/core/drizzle";
-import { customerAddresses, customers, inventoryLevels, orderLineItems, orders, sellableEntities } from "@porulle/core/schema";
-import { channelEntityMap, channelExportEvents, channelOrderExports, connectedStores, channelRefundEvents, channelRefundRequests, } from "./schema.js";
+import { CommerceInvalidTransitionError, CommerceValidationError, Ok, PluginErr, createTxContext, createSystemActor, } 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 } from "@porulle/core/drizzle";
+import { brands, categories, customerAddresses, customers, entityMedia, 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 { mergeCatalogFieldMapping, normalizeCatalogFieldMapping, selectCatalogFieldMapping, } from "./catalog-field-mapping.js";
+export const CATALOG_PUSH_BATCH_SIZES = {
+    mock: 100,
+    shopify: 50,
+    woocommerce: 100,
+};
+const DEFAULT_CATALOG_PUSH_BATCH_SIZE = 50;
+const CATALOG_PUSH_BREAKER_RETRY_MS = 60_000;
+export const CATALOG_PUSH_MAX_ATTEMPTS = 8;
+const CATALOG_PUSH_RETRY_BASE_MS = 60_000;
+const CATALOG_PUSH_RETRY_MAX_MS = 60 * 60 * 1000;
+export function catalogPushRetryDelayMs(attempts) {
+    const exponent = Math.max(0, attempts - 1);
+    return Math.min(CATALOG_PUSH_RETRY_BASE_MS * (2 ** exponent), CATALOG_PUSH_RETRY_MAX_MS);
+}
+export function catalogPushConcurrencyKey(input) {
+    const storeId = String(input.storeId);
+    const entityIds = input.entityIds;
+    if (Array.isArray(entityIds) && entityIds.length === 1) {
+        return `push:${String(entityIds[0])}:${storeId}`;
+    }
+    return `push-catalog:${storeId}`;
+}
+export function isCatalogPushBreakerOpen(breakerState) {
+    if (breakerState.open === true) {
+        const openUntil = breakerState.openUntil;
+        if (typeof openUntil === "string" && new Date(openUntil) <= new Date())
+            return false;
+        return true;
+    }
+    const catalogPush = breakerState.catalogPush;
+    if (!catalogPush || typeof catalogPush !== "object")
+        return false;
+    const state = catalogPush;
+    if (state.open !== true)
+        return false;
+    if (typeof state.openUntil === "string" && new Date(state.openUntil) <= new Date())
+        return false;
+    return true;
+}
+function catalogPushBatchSize(provider) {
+    return CATALOG_PUSH_BATCH_SIZES[provider] ?? DEFAULT_CATALOG_PUSH_BATCH_SIZE;
+}
 const exportTransitions = {
     pending: ["exported", "abandoned"],
     exported: ["confirmed", "failed", "abandoned"],
@@ -13,9 +58,218 @@ const exportTransitions = {
 export function canExportTransition(from, to) {
     return exportTransitions[from].includes(to);
 }
+// Catalog pushes recur; confirmed/failed rows re-arm through exported, and rows with nothing to push resolve directly.
+const catalogPushTransitions = {
+    pending: ["exported", "confirmed", "abandoned"],
+    exported: ["confirmed", "failed", "abandoned"],
+    confirmed: ["exported", "abandoned"],
+    failed: ["exported", "confirmed", "abandoned"],
+    abandoned: [],
+};
+export function canCatalogPushTransition(from, to) {
+    return catalogPushTransitions[from].includes(to);
+}
 function hash(value) {
     return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
+export const CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS = 15 * 60 * 1000;
+function normalizeCanonicalValue(value) {
+    if (typeof value === "string")
+        return value.replace(/\r\n?/g, "\n").replace(/\s+/g, " ").trim();
+    if (Array.isArray(value))
+        return value.map(normalizeCanonicalValue).sort((left, right) => (JSON.stringify(left) ?? "").localeCompare(JSON.stringify(right) ?? ""));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => [key, normalizeCanonicalValue(nested)]));
+    }
+    return value;
+}
+function normalizedValuesEqual(left, right) {
+    return JSON.stringify(normalizeCanonicalValue(left)) === JSON.stringify(normalizeCanonicalValue(right));
+}
+function snapshotCustomFieldValue(field) {
+    if (field.textValue !== null && field.textValue !== undefined)
+        return field.textValue;
+    if (field.numberValue !== null && field.numberValue !== undefined)
+        return field.numberValue;
+    if (field.booleanValue !== null && field.booleanValue !== undefined)
+        return field.booleanValue;
+    if (field.dateValue !== null && field.dateValue !== undefined)
+        return field.dateValue;
+    return field.jsonValue;
+}
+function snapshotFieldValue(snapshot, path) {
+    const [root, segment, field] = path.split(".");
+    if (root === "entity" && segment === "slug")
+        return { found: true, value: snapshot.entity.slug };
+    if (root === "entity" && segment === "status")
+        return { found: true, value: snapshot.entity.status };
+    if (root === "entity" && segment === "metadata") {
+        const metadata = snapshot.entity.metadata;
+        return {
+            found: true,
+            value: metadata && typeof metadata === "object" ? metadata[field ?? ""] : undefined,
+        };
+    }
+    if (root === "attributes" && segment && field) {
+        const attribute = snapshot.attributes.find((row) => row.locale === segment);
+        return { found: true, value: attribute?.[field] };
+    }
+    if (root === "customFields" && segment && field) {
+        const customField = snapshot.customFields.find((row) => row.fieldName === segment && row.locale === field && row.status === "approved");
+        return { found: true, value: customField ? snapshotCustomFieldValue(customField) : undefined };
+    }
+    if (root === "media" && segment) {
+        return {
+            found: true,
+            value: snapshot.media.filter((row) => row.role === segment).map((row) => row.mediaAssetId),
+        };
+    }
+    return { found: false, value: undefined };
+}
+function canonicalHash(externalId, fieldPaths, valueAtPath) {
+    const fields = fieldPaths.flatMap((fieldPath) => {
+        const value = valueAtPath(fieldPath);
+        return value === undefined ? [] : [{ fieldPath, value: normalizeCanonicalValue(value) }];
+    });
+    return hash({
+        externalId,
+        fields: fields.sort((left, right) => left.fieldPath.localeCompare(right.fieldPath)),
+    });
+}
+function outboundFieldPaths(item) {
+    const paths = new Set(item.fields.flatMap((field) => isValidFieldPath(field.fieldPath) ? [field.fieldPath] : []));
+    for (const image of item.images ?? [])
+        paths.add(`media.${image.role}`);
+    return [...paths].sort();
+}
+function pushFieldValue(item, fieldPath) {
+    if (fieldPath.startsWith("media.")) {
+        const role = fieldPath.slice("media.".length);
+        return (item.images ?? [])
+            .filter((image) => image.role === role)
+            .map((image) => ({ url: image.url, role: image.role }));
+    }
+    return item.fields.find((field) => field.fieldPath === fieldPath)?.value;
+}
+function canonicalOutboundHash(externalId, item, fieldPaths) {
+    return canonicalHash(externalId, fieldPaths, (fieldPath) => pushFieldValue(item, fieldPath));
+}
+function canonicalInboundHash(externalId, fieldPaths, remoteFieldValue) {
+    return canonicalHash(externalId, fieldPaths, remoteFieldValue);
+}
+function mergeMetadata(existing, remote) {
+    return { ...(existing ?? {}), ...remote };
+}
+const attributeFields = ["title", "subtitle", "description", "richDescription", "seoTitle", "seoDescription"];
+const pushImageRoles = ["primary", "gallery", "thumbnail", "video", "document"];
+function customFieldValue(field) {
+    switch (field.fieldType) {
+        case "text":
+        case "relation":
+        case "select":
+            return field.textValue;
+        case "number":
+            return field.numberValue;
+        case "boolean":
+            return field.booleanValue;
+        case "date":
+            return field.dateValue;
+        case "json":
+            return field.jsonValue;
+        default:
+            return null;
+    }
+}
+function pushCatalogIntent(fieldPath, target) {
+    if (fieldPath.startsWith("customFields.") && target === "attribute")
+        return "filterable";
+    if (fieldPath.startsWith("customFields.") || fieldPath.startsWith("entity.metadata."))
+        return "tag";
+    return "display";
+}
+function pushCatalogField(fieldPath, value, mapping) {
+    const segments = fieldPath.split(".");
+    const locale = fieldPath.startsWith("attributes.")
+        ? segments[1]
+        : fieldPath.startsWith("customFields.")
+            ? segments[2]
+            : undefined;
+    return {
+        fieldPath,
+        intent: pushCatalogIntent(fieldPath, mapping.target),
+        value,
+        ...(locale !== undefined ? { locale } : {}),
+        remoteKey: mapping.remoteKey,
+        target: mapping.target,
+    };
+}
+function pushCatalogImageRole(value) {
+    return pushImageRoles.find((role) => role === value);
+}
+function importedFieldPaths(item) {
+    const paths = new Set(["entity.slug"]);
+    if (item.status !== undefined)
+        paths.add("entity.status");
+    for (const key of Object.keys(item.metadata ?? {})) {
+        const path = `entity.metadata.${key}`;
+        if (isValidFieldPath(path))
+            paths.add(path);
+    }
+    const attributes = item.attributes?.length
+        ? item.attributes
+        : [{ locale: "en", title: item.title, ...(item.description !== undefined ? { description: item.description } : {}) }];
+    for (const attribute of attributes) {
+        for (const field of attributeFields) {
+            if (attribute[field] !== undefined)
+                paths.add(`attributes.${attribute.locale}.${field}`);
+        }
+    }
+    const customFields = item.customFields;
+    for (const [name, locales] of Object.entries(customFields ?? {})) {
+        if (!locales || typeof locales !== "object" || Array.isArray(locales))
+            continue;
+        for (const locale of Object.keys(locales)) {
+            const path = `customFields.${name}.${locale}`;
+            if (isValidFieldPath(path))
+                paths.add(path);
+        }
+    }
+    for (const image of item.images ?? [])
+        paths.add(`media.${image.role}`);
+    if (item.options?.length)
+        paths.add("options");
+    if (item.variants.some((variant) => variant.sku !== undefined))
+        paths.add("variants.sku");
+    if (item.variants.some((variant) => variant.barcode !== undefined))
+        paths.add("variants.barcode");
+    for (const currency of item.variants.flatMap((variant) => variant.prices ?? []).map((price) => price.currency)) {
+        const path = `prices.${currency}`;
+        if (isValidFieldPath(path))
+            paths.add(path);
+    }
+    return [...paths];
+}
+function summarizeValue(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        return String(value);
+    return serialized.length > 256 ? `${serialized.slice(0, 253)}...` : serialized;
+}
+function uniqueSkipped(skipped) {
+    const seen = new Set();
+    return skipped.filter((entry) => {
+        const key = `${entry.entityId}:${entry.fieldPath}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function ownerAllows(owners, path) {
+    return owners.get(path) !== "platform";
+}
 function stockFailure(line, reason) {
     return `Cannot checkout line "${line.title ?? line.entityId}": ${reason}.`;
 }
@@ -42,6 +296,8 @@ function redactStore(store) {
         credentials: "[REDACTED]",
         storeDomain: store.storeDomain,
         status: store.status,
+        catalogWriteEnabled: store.catalogWriteEnabled,
+        catalogFieldMapping: store.catalogFieldMapping,
         catalogCursor: store.catalogCursor,
         inventoryCursor: store.inventoryCursor,
         lastSyncAt: store.lastSyncAt,
@@ -79,6 +335,614 @@ export class ChannelConnectorService {
     get catalog() {
         return this.services.catalog;
     }
+    get media() {
+        return this.services.media;
+    }
+    get pricing() {
+        return this.services.pricing;
+    }
+    filterOwnedFields(item, owners) {
+        return this.filterOwnedFieldsAtPaths(item, owners, importedFieldPaths(item));
+    }
+    filterOwnedFieldsAtPaths(item, owners, fieldPaths) {
+        const populated = new Set(fieldPaths);
+        const skipped = fieldPaths.filter((path) => owners.get(path) === "platform");
+        const blocked = new Set(skipped);
+        const attributes = (item.attributes?.length
+            ? item.attributes
+            : [{ locale: "en", title: item.title, ...(item.description !== undefined ? { description: item.description } : {}) }])
+            .flatMap((attribute) => {
+            return [{
+                    locale: attribute.locale,
+                    title: attribute.title,
+                    ...Object.fromEntries(attributeFields.slice(1)
+                        .filter((field) => attribute[field] !== undefined
+                        && populated.has(`attributes.${attribute.locale}.${field}`)
+                        && !blocked.has(`attributes.${attribute.locale}.${field}`))
+                        .map((field) => [field, attribute[field]])),
+                }];
+        });
+        const writable = {
+            ...item,
+            attributes,
+            metadata: Object.fromEntries(Object.entries(item.metadata ?? {}).filter(([key]) => populated.has(`entity.metadata.${key}`) && !blocked.has(`entity.metadata.${key}`))),
+            ...(item.images !== undefined ? { images: item.images.filter((image) => populated.has(`media.${image.role}`) && !blocked.has(`media.${image.role}`)) } : {}),
+            ...(item.options !== undefined ? { options: blocked.has("options") ? [] : item.options } : {}),
+            variants: item.variants.map((variant) => ({
+                externalId: variant.externalId,
+                ...(variant.sku !== undefined && populated.has("variants.sku") && !blocked.has("variants.sku") ? { sku: variant.sku } : {}),
+                ...(variant.barcode !== undefined && populated.has("variants.barcode") && !blocked.has("variants.barcode") ? { barcode: variant.barcode } : {}),
+                ...(variant.metadata !== undefined ? { metadata: variant.metadata } : {}),
+                ...(variant.optionValues !== undefined && populated.has("options") && !blocked.has("options") ? { optionValues: variant.optionValues } : {}),
+                ...(variant.prices !== undefined
+                    ? { prices: variant.prices.filter((price) => populated.has(`prices.${price.currency}`) && !blocked.has(`prices.${price.currency}`)) }
+                    : {}),
+            })),
+        };
+        return { writable, skipped, conflicts: [] };
+    }
+    filterConflictingFields(item, conflicts) {
+        if (conflicts.length === 0)
+            return { writable: item, conflicts: [] };
+        const blocked = new Set(conflicts);
+        const attributes = (item.attributes ?? []).flatMap((attribute) => {
+            return [{
+                    locale: attribute.locale,
+                    title: attribute.title,
+                    ...Object.fromEntries(attributeFields.slice(1)
+                        .filter((field) => attribute[field] !== undefined && !blocked.has(`attributes.${attribute.locale}.${field}`))
+                        .map((field) => [field, attribute[field]])),
+                }];
+        });
+        return {
+            writable: {
+                ...item,
+                attributes,
+                metadata: Object.fromEntries(Object.entries(item.metadata ?? {}).filter(([key]) => !blocked.has(`entity.metadata.${key}`))),
+                ...(item.images !== undefined ? { images: item.images.filter((image) => !blocked.has(`media.${image.role}`)) } : {}),
+                ...(item.options !== undefined ? { options: blocked.has("options") ? [] : item.options } : {}),
+                variants: item.variants.map((variant) => ({
+                    externalId: variant.externalId,
+                    ...(variant.sku !== undefined && !blocked.has("variants.sku") ? { sku: variant.sku } : {}),
+                    ...(variant.barcode !== undefined && !blocked.has("variants.barcode") ? { barcode: variant.barcode } : {}),
+                    ...(variant.metadata !== undefined ? { metadata: variant.metadata } : {}),
+                    ...(variant.optionValues !== undefined && !blocked.has("options") ? { optionValues: variant.optionValues } : {}),
+                    ...(variant.prices !== undefined
+                        ? { prices: variant.prices.filter((price) => !blocked.has(`prices.${price.currency}`)) }
+                        : {}),
+                })),
+            },
+            conflicts,
+        };
+    }
+    remoteFieldValue(item, path) {
+        const [root, segment, field] = path.split(".");
+        if (root === "entity" && segment === "slug")
+            return item.slug;
+        if (root === "entity" && segment === "status")
+            return item.status;
+        if (root === "entity" && segment === "metadata")
+            return item.metadata?.[field ?? ""];
+        if (root === "customFields" && segment && field) {
+            const customFields = item.customFields;
+            const customField = customFields?.[segment];
+            if (customField && typeof customField === "object" && !Array.isArray(customField)) {
+                return customField[field];
+            }
+        }
+        if (root === "attributes" && segment && field) {
+            const attributes = item.attributes?.length
+                ? item.attributes
+                : [{ locale: "en", title: item.title, ...(item.description !== undefined ? { description: item.description } : {}) }];
+            const attribute = attributes.find((row) => row.locale === segment);
+            return attribute?.[field];
+        }
+        if (root === "media" && segment) {
+            return (item.images ?? [])
+                .filter((image) => image.role === segment)
+                .map((image) => ({ url: image.url, role: image.role }));
+        }
+        if (path === "options")
+            return item.options;
+        if (path === "variants.sku")
+            return item.variants.map((variant) => variant.sku);
+        if (path === "variants.barcode")
+            return item.variants.map((variant) => variant.barcode);
+        if (root === "prices" && segment)
+            return item.variants.flatMap((variant) => variant.prices ?? []).filter((price) => price.currency === segment);
+        return undefined;
+    }
+    isOutboundEcho(mapping, item) {
+        if (!mapping.outboundHash || !mapping.outboundPushedAt || mapping.outboundFieldPaths.length === 0)
+            return false;
+        const age = Date.now() - mapping.outboundPushedAt.getTime();
+        if (age < 0 || age > CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS)
+            return false;
+        const inboundHash = canonicalInboundHash(mapping.externalId, mapping.outboundFieldPaths, (fieldPath) => this.remoteFieldValue(item, fieldPath));
+        return inboundHash === mapping.outboundHash;
+    }
+    async localFieldValue(entityId, entity, path) {
+        const [root, segment, field] = path.split(".");
+        if (root === "entity" && segment === "slug")
+            return entity.slug;
+        if (root === "entity" && segment === "status")
+            return entity.status;
+        if (root === "entity" && segment === "metadata")
+            return entity.metadata?.[field ?? ""];
+        if (root === "attributes" && segment && field) {
+            const [attribute] = await this.db.select().from(sellableAttributes).where(and(eq(sellableAttributes.entityId, entityId), eq(sellableAttributes.locale, segment)));
+            const values = attribute
+                ? {
+                    title: attribute.title,
+                    subtitle: attribute.subtitle,
+                    description: attribute.description,
+                    richDescription: attribute.richDescription,
+                    seoTitle: attribute.seoTitle,
+                    seoDescription: attribute.seoDescription,
+                }
+                : {};
+            return values[field];
+        }
+        if (root === "customFields" && segment && field) {
+            const [customField] = await this.db.select().from(sellableCustomFields).where(and(eq(sellableCustomFields.entityId, entityId), eq(sellableCustomFields.fieldName, segment), eq(sellableCustomFields.locale, field), eq(sellableCustomFields.status, "approved")));
+            return customField ? customFieldValue(customField) : undefined;
+        }
+        if (root === "media" && segment) {
+            const links = await this.db.select({ id: entityMedia.mediaAssetId }).from(entityMedia).where(and(eq(entityMedia.entityId, entityId), eq(entityMedia.role, segment)));
+            return links.map((link) => link.id);
+        }
+        if (path === "options") {
+            const types = await this.db.select().from(optionTypes).where(eq(optionTypes.entityId, entityId));
+            const values = await Promise.all(types.map(async (type) => ({
+                name: type.name,
+                values: await this.db.select().from(optionValues).where(eq(optionValues.optionTypeId, type.id)),
+            })));
+            return values;
+        }
+        if (path === "variants.sku" || path === "variants.barcode") {
+            const rows = await this.db.select().from(variants).where(eq(variants.entityId, entityId));
+            return rows.map((variant) => path === "variants.sku" ? variant.sku : variant.barcode);
+        }
+        if (root === "prices" && segment) {
+            const rows = await this.db.select().from(prices).where(and(eq(prices.entityId, entityId), eq(prices.currency, segment)));
+            return rows.map((price) => ({ amount: price.amount, compareAtAmount: price.compareAtAmount }));
+        }
+        return undefined;
+    }
+    async lastSyncedSnapshot(entityId, lastSyncedAt) {
+        const [revision] = await this.db.select({ snapshot: sellableEntityRevisions.snapshot }).from(sellableEntityRevisions).where(and(eq(sellableEntityRevisions.entityId, entityId), lte(sellableEntityRevisions.createdAt, lastSyncedAt))).orderBy(desc(sellableEntityRevisions.createdAt)).limit(1);
+        return revision?.snapshot;
+    }
+    async detectSharedConflicts(entityId, storeId, entity, mapping, item, owners, fieldPaths = importedFieldPaths(item), remoteHash = hash(item), echo) {
+        if (!mapping || mapping.syncHash === remoteHash)
+            return { paths: [], conflicts: [] };
+        const revisions = await this.catalog.repository.findRevisionMarkers(entityId, mapping.lastSyncedAt);
+        const localChanged = revisions.some((revision) => revision.reason !== "import");
+        const paths = fieldPaths.filter((path) => owners.get(path) === "shared");
+        const openRows = await this.db.select({
+            fieldPath: channelCatalogConflicts.fieldPath,
+            storeValue: channelCatalogConflicts.storeValue,
+        }).from(channelCatalogConflicts).where(and(eq(channelCatalogConflicts.storeId, storeId), eq(channelCatalogConflicts.entityId, entityId), eq(channelCatalogConflicts.state, "open")));
+        if (!localChanged && openRows.length === 0)
+            return { paths: [], conflicts: [] };
+        const openByPath = new Map(openRows.map((row) => [row.fieldPath, row.storeValue]));
+        const baseline = await this.lastSyncedSnapshot(entityId, mapping.lastSyncedAt);
+        const changed = [];
+        for (const path of paths) {
+            const localValue = await this.localFieldValue(entityId, entity, path);
+            const remoteValue = this.remoteFieldValue(item, path);
+            let diverged = false;
+            if (echo) {
+                // The outbound hash certifies only the pushed paths; a shared path
+                // outside that set carrying a genuinely different remote value is a
+                // real store edit even inside an echo payload.
+                diverged = !echo.certifiedPaths.has(path) && !normalizedValuesEqual(remoteValue, localValue);
+            }
+            else if (openByPath.has(path)) {
+                diverged = !normalizedValuesEqual(remoteValue, openByPath.get(path));
+            }
+            else if (baseline) {
+                const baselineValue = snapshotFieldValue(baseline, path);
+                diverged = baselineValue.found
+                    && !normalizedValuesEqual(localValue, baselineValue.value)
+                    && !normalizedValuesEqual(remoteValue, baselineValue.value)
+                    && !normalizedValuesEqual(localValue, remoteValue);
+            }
+            else {
+                diverged = !normalizedValuesEqual(remoteValue, localValue);
+            }
+            if (diverged)
+                changed.push(path);
+        }
+        const conflicts = await Promise.all(changed.map(async (fieldPath) => {
+            const platformValue = await this.localFieldValue(entityId, entity, fieldPath);
+            const storeValue = this.remoteFieldValue(item, fieldPath);
+            return {
+                entityId,
+                storeId,
+                fieldPath,
+                platformValue: platformValue === undefined ? null : platformValue,
+                storeValue: storeValue === undefined ? null : storeValue,
+                localValueSummary: summarizeValue(platformValue),
+                remoteValueSummary: summarizeValue(storeValue),
+            };
+        }));
+        return { paths: changed, conflicts };
+    }
+    async persistCatalogConflicts(orgId, conflicts, changedBy) {
+        for (const conflict of conflicts) {
+            const [inserted] = await this.db.insert(channelCatalogConflicts).values({
+                organizationId: orgId,
+                storeId: conflict.storeId,
+                entityId: conflict.entityId,
+                fieldPath: conflict.fieldPath,
+                platformValue: conflict.platformValue,
+                storeValue: conflict.storeValue,
+            }).onConflictDoNothing().returning();
+            if (!inserted) {
+                const [existing] = await this.db.select({
+                    id: channelCatalogConflicts.id,
+                    storeValue: channelCatalogConflicts.storeValue,
+                    platformValue: channelCatalogConflicts.platformValue,
+                }).from(channelCatalogConflicts).where(and(eq(channelCatalogConflicts.organizationId, orgId), eq(channelCatalogConflicts.storeId, conflict.storeId), eq(channelCatalogConflicts.entityId, conflict.entityId), eq(channelCatalogConflicts.fieldPath, conflict.fieldPath), eq(channelCatalogConflicts.state, "open")));
+                const storeMoved = existing !== undefined && !normalizedValuesEqual(existing.storeValue, conflict.storeValue);
+                const platformMoved = existing !== undefined && !normalizedValuesEqual(existing.platformValue, conflict.platformValue);
+                if (existing && (storeMoved || platformMoved)) {
+                    await this.db.update(channelCatalogConflicts).set({
+                        storeValue: conflict.storeValue,
+                        platformValue: conflict.platformValue,
+                        updatedAt: new Date(),
+                    }).where(eq(channelCatalogConflicts.id, existing.id));
+                }
+                continue;
+            }
+            await this.db.insert(channelCatalogConflictEvents).values({
+                organizationId: orgId,
+                conflictId: inserted.id,
+                fromState: null,
+                toState: "open",
+                reason: "Shared catalog field changed on both sides.",
+                changedBy,
+            });
+        }
+        return Ok(undefined);
+    }
+    async setCatalogAttributes(entityId, item, actor, blockedPaths = new Set(), catalogCtx) {
+        const attributes = item.attributes ?? [{
+                locale: "en",
+                title: item.title,
+                ...(item.description !== undefined ? { description: item.description } : {}),
+            }];
+        const existing = await this.db.select().from(sellableAttributes).where(eq(sellableAttributes.entityId, entityId));
+        let created = 0;
+        let changed = false;
+        for (const attribute of attributes) {
+            const current = existing.find((row) => row.locale === attribute.locale);
+            const titlePath = `attributes.${attribute.locale}.title`;
+            if (!current && blockedPaths.has(titlePath))
+                continue;
+            const title = blockedPaths.has(titlePath) ? current?.title : attribute.title;
+            if (title === undefined)
+                continue;
+            const writeAttribute = {
+                title,
+                ...(attribute.subtitle !== undefined && !blockedPaths.has(`attributes.${attribute.locale}.subtitle`) ? { subtitle: attribute.subtitle } : current?.subtitle != null ? { subtitle: current.subtitle } : {}),
+                ...(attribute.description !== undefined && !blockedPaths.has(`attributes.${attribute.locale}.description`) ? { description: attribute.description } : current?.description != null ? { description: current.description } : {}),
+                ...(attribute.richDescription !== undefined && !blockedPaths.has(`attributes.${attribute.locale}.richDescription`) ? { richDescription: attribute.richDescription } : current?.richDescription != null ? { richDescription: current.richDescription } : {}),
+                ...(attribute.seoTitle !== undefined && !blockedPaths.has(`attributes.${attribute.locale}.seoTitle`) ? { seoTitle: attribute.seoTitle } : current?.seoTitle != null ? { seoTitle: current.seoTitle } : {}),
+                ...(attribute.seoDescription !== undefined && !blockedPaths.has(`attributes.${attribute.locale}.seoDescription`) ? { seoDescription: attribute.seoDescription } : current?.seoDescription != null ? { seoDescription: current.seoDescription } : {}),
+            };
+            if (!current) {
+                created += 1;
+                changed = true;
+            }
+            else if (attributeFields.some((field) => (current[field] == null ? null : current[field]) !== (writeAttribute[field] == null ? null : writeAttribute[field]))) {
+                changed = true;
+            }
+            const result = await this.catalog.setAttributes(entityId, attribute.locale, writeAttribute, actor, catalogCtx);
+            if (!result.ok)
+                return PluginErr(result.error.message);
+        }
+        return Ok({ created, changed });
+    }
+    async setCatalogAttributesIfWritable(entityId, item, actor, blockedPaths, catalogCtx) {
+        const attributes = item.attributes ?? [{
+                locale: "en",
+                title: item.title,
+                ...(item.description !== undefined ? { description: item.description } : {}),
+            }];
+        const writable = attributes.some((attribute) => attributeFields.some((field) => (attribute[field] !== undefined && !blockedPaths.has(`attributes.${attribute.locale}.${field}`))));
+        if (!writable)
+            return Ok({ created: 0, changed: false });
+        return this.setCatalogAttributes(entityId, item, actor, blockedPaths, catalogCtx);
+    }
+    async upsertOptionAxes(entityId, item, actor) {
+        const optionValueIds = new Map();
+        const existingTypes = await this.db.select().from(optionTypes).where(eq(optionTypes.entityId, entityId));
+        let changed = false;
+        for (const [typeIndex, sourceType] of (item.options ?? []).entries()) {
+            let optionType = existingTypes.find((row) => row.name === sourceType.name);
+            if (!optionType) {
+                const created = await this.catalog.createOptionType({ entityId, name: sourceType.name, values: [] }, actor);
+                if (!created.ok)
+                    return PluginErr(created.error.message);
+                const [createdType] = await this.db.select().from(optionTypes).where(eq(optionTypes.id, created.value.id));
+                if (!createdType)
+                    return PluginErr(`Option type "${sourceType.name}" was not persisted.`);
+                optionType = createdType;
+                existingTypes.push(optionType);
+                changed = true;
+            }
+            await this.db.update(optionTypes).set({
+                displayName: sourceType.displayName,
+                sortOrder: sourceType.sortOrder ?? typeIndex,
+            }).where(eq(optionTypes.id, optionType.id));
+            const existingValues = await this.db.select().from(optionValues).where(eq(optionValues.optionTypeId, optionType.id));
+            const valueIds = new Map();
+            for (const [valueIndex, sourceValue] of sourceType.values.entries()) {
+                let optionValue = existingValues.find((row) => row.value === sourceValue.value);
+                if (!optionValue) {
+                    const created = await this.catalog.createOptionValue({ optionTypeId: optionType.id, value: sourceValue.value }, actor);
+                    if (!created.ok)
+                        return PluginErr(created.error.message);
+                    const [createdValue] = await this.db.select().from(optionValues).where(eq(optionValues.id, created.value.id));
+                    if (!createdValue)
+                        return PluginErr(`Option value "${sourceValue.value}" was not persisted.`);
+                    optionValue = createdValue;
+                    existingValues.push(optionValue);
+                    changed = true;
+                }
+                await this.db.update(optionValues).set({
+                    displayValue: sourceValue.displayValue,
+                    sortOrder: sourceValue.sortOrder ?? valueIndex,
+                }).where(eq(optionValues.id, optionValue.id));
+                valueIds.set(sourceValue.value, optionValue.id);
+            }
+            optionValueIds.set(sourceType.name, valueIds);
+        }
+        return Ok({ value: optionValueIds, changed });
+    }
+    async upsertVariants(orgId, storeId, entityId, item, optionValueIds, actor, warnings, applyOptionValues, fullItem) {
+        const variantIds = new Map();
+        let repaired = 0;
+        let changed = false;
+        const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "variant"), eq(channelEntityMap.entityId, entityId)));
+        for (const sourceVariant of item.variants) {
+            const fullSourceVariant = fullItem.variants.find((variant) => variant.externalId === sourceVariant.externalId) ?? sourceVariant;
+            let mapping = mappings.find((row) => row.externalId === sourceVariant.externalId);
+            let variantId = mapping?.variantId;
+            const createdVariant = !variantId;
+            if (!variantId) {
+                const options = {};
+                for (const [name, value] of Object.entries(sourceVariant.optionValues ?? {})) {
+                    const optionValueId = optionValueIds.get(name)?.get(value);
+                    if (!optionValueId) {
+                        warnings.push(`Skipped unmapped option "${name}=${value}" on variant "${sourceVariant.externalId}".`);
+                        continue;
+                    }
+                    options[name] = value;
+                }
+                const created = await this.catalog.createVariant({
+                    entityId,
+                    options,
+                    ...(sourceVariant.sku !== undefined ? { sku: sourceVariant.sku } : {}),
+                    ...(sourceVariant.barcode !== undefined ? { barcode: sourceVariant.barcode } : {}),
+                }, actor);
+                if (!created.ok)
+                    return PluginErr(created.error.message);
+                variantId = created.value.id;
+                const [createdMapping] = await this.db.insert(channelEntityMap).values({
+                    organizationId: orgId,
+                    storeId,
+                    kind: "variant",
+                    externalId: sourceVariant.externalId,
+                    entityId,
+                    variantId,
+                    syncHash: hash(fullSourceVariant),
+                }).returning();
+                mapping = createdMapping;
+                if (mapping)
+                    mappings.push(mapping);
+            }
+            if (!variantId) {
+                warnings.push(`Skipped variant "${sourceVariant.externalId}": no local variant mapping exists.`);
+                continue;
+            }
+            variantIds.set(sourceVariant.externalId, variantId);
+            if (applyOptionValues) {
+                const desiredOptionValueIds = Object.entries(sourceVariant.optionValues ?? {})
+                    .map(([name, value]) => optionValueIds.get(name)?.get(value))
+                    .filter((optionValueId) => optionValueId !== undefined);
+                const currentOptionValues = await this.db.select().from(variantOptionValues).where(eq(variantOptionValues.variantId, variantId));
+                const currentIds = currentOptionValues.map((row) => row.optionValueId).sort();
+                const desiredIds = [...new Set(desiredOptionValueIds)].sort();
+                if (currentIds.length !== desiredIds.length || currentIds.some((id, index) => id !== desiredIds[index])) {
+                    await this.db.delete(variantOptionValues).where(eq(variantOptionValues.variantId, variantId));
+                    if (desiredIds.length > 0) {
+                        await this.db.insert(variantOptionValues).values(desiredIds.map((optionValueId) => ({ variantId, optionValueId }))).onConflictDoNothing();
+                        repaired += 1;
+                    }
+                    changed = true;
+                }
+                if (createdVariant && desiredIds.length > 0) {
+                    repaired += 1;
+                    changed = true;
+                }
+            }
+            for (const price of sourceVariant.prices ?? []) {
+                const priced = await this.pricing.setBasePrice({
+                    entityId,
+                    variantId,
+                    currency: price.currency,
+                    amount: price.amount,
+                    compareAtAmount: price.compareAtAmount ?? null,
+                }, actor);
+                if (!priced.ok)
+                    return PluginErr(priced.error.message);
+            }
+            if (mapping) {
+                await this.db.update(channelEntityMap).set({
+                    syncHash: hash(fullSourceVariant),
+                }).where(eq(channelEntityMap.id, mapping.id));
+            }
+        }
+        return Ok({ value: variantIds, repaired, changed });
+    }
+    async applyTaxonomy(orgId, entityId, item, actor, warnings) {
+        const categoryRows = await this.db.select().from(categories).where(eq(categories.organizationId, orgId));
+        for (const slug of new Set(item.categories ?? [])) {
+            let category = categoryRows.find((row) => row.slug === slug);
+            if (category?.status === "archived") {
+                warnings.push(`Skipped archived category "${slug}".`);
+                continue;
+            }
+            if (!category) {
+                const created = await this.catalog.createCategory({ slug }, actor);
+                if (!created.ok)
+                    return PluginErr(created.error.message);
+                const [createdCategory] = await this.db.select().from(categories).where(eq(categories.id, created.value.id));
+                if (!createdCategory)
+                    return PluginErr(`Category "${slug}" was not persisted.`);
+                category = createdCategory;
+                categoryRows.push(category);
+            }
+            const linked = await this.catalog.addToCategory(entityId, category.id, actor);
+            if (!linked.ok)
+                return PluginErr(linked.error.message);
+        }
+        const brandRows = await this.db.select().from(brands).where(eq(brands.organizationId, orgId));
+        if (item.brand) {
+            let brand = brandRows.find((row) => row.slug === item.brand);
+            if (!brand) {
+                const created = await this.catalog.createBrand({ slug: item.brand, displayName: item.brand }, actor);
+                if (!created.ok)
+                    return PluginErr(created.error.message);
+                const [createdBrand] = await this.db.select().from(brands).where(eq(brands.id, created.value.id));
+                if (!createdBrand)
+                    return PluginErr(`Brand "${item.brand}" was not persisted.`);
+                brand = createdBrand;
+                brandRows.push(brand);
+            }
+            const linked = await this.catalog.addToBrand(entityId, brand.id, actor);
+            if (!linked.ok)
+                return PluginErr(linked.error.message);
+        }
+        const tagRows = await this.db.select().from(tags).where(eq(tags.organizationId, orgId));
+        for (const slug of new Set(item.tags ?? [])) {
+            let tag = tagRows.find((row) => row.slug === slug);
+            if (!tag) {
+                const [createdTag] = await this.db.insert(tags).values({ organizationId: orgId, slug, displayName: slug }).onConflictDoNothing().returning();
+                tag = createdTag ?? (await this.db.select().from(tags).where(and(eq(tags.organizationId, orgId), eq(tags.slug, slug))))[0];
+                if (!tag)
+                    return PluginErr(`Tag "${slug}" was not persisted.`);
+                tagRows.push(tag);
+            }
+            await this.db.insert(entityTags).values({ entityId, tagId: tag.id }).onConflictDoNothing();
+        }
+        return Ok(undefined);
+    }
+    async applyMedia(orgId, entityId, item, variantIds, actor, warnings, owners) {
+        const assets = await this.db.select().from(mediaAssets).where(eq(mediaAssets.organizationId, orgId));
+        const links = await this.db.select().from(entityMedia).where(eq(entityMedia.entityId, entityId));
+        let imported = 0;
+        let changed = false;
+        const skipped = [];
+        for (const image of item.images ?? []) {
+            const urlHash = hash(image.url);
+            const asset = assets.find((row) => {
+                const metadata = row.metadata ?? {};
+                return (image.externalId != null && metadata.channelImageExternalId === image.externalId)
+                    || metadata.channelImageUrlHash === urlHash;
+            });
+            let mediaAssetId = asset?.id;
+            if (!mediaAssetId) {
+                let response;
+                try {
+                    response = await fetch(image.url);
+                }
+                catch (error) {
+                    warnings.push(`Skipped image "${image.externalId ?? image.url}": ${error instanceof Error ? error.message : "download failed"}.`);
+                    continue;
+                }
+                if (!response.ok) {
+                    warnings.push(`Skipped image "${image.externalId ?? image.url}": download returned ${response.status}.`);
+                    continue;
+                }
+                const contentType = response.headers.get("content-type")?.split(";", 1)[0] ?? "image/jpeg";
+                const extension = contentType.split("/", 2)[1] ?? "jpg";
+                const uploaded = await this.media.upload({
+                    filename: `${image.externalId ?? urlHash}.${extension}`,
+                    contentType,
+                    data: await response.arrayBuffer(),
+                    ...(image.alt !== undefined ? { alt: image.alt } : {}),
+                    metadata: {
+                        channelImageUrlHash: urlHash,
+                        ...(image.externalId !== undefined ? { channelImageExternalId: image.externalId } : {}),
+                    },
+                    origin: "imported",
+                }, actor);
+                if (!uploaded.ok) {
+                    warnings.push(`Skipped image "${image.externalId ?? image.url}": ${uploaded.error.code === "STORAGE_NOT_SUPPORTED" ? "storage adapter is not configured" : uploaded.error.message}.`);
+                    continue;
+                }
+                mediaAssetId = uploaded.value.id;
+                imported += 1;
+                changed = true;
+                const [createdAsset] = await this.db.select().from(mediaAssets).where(eq(mediaAssets.id, mediaAssetId));
+                if (createdAsset)
+                    assets.push(createdAsset);
+            }
+            if (!mediaAssetId)
+                continue;
+            const targets = image.variantExternalIds?.length
+                ? image.variantExternalIds.map((externalId) => ({ externalId, variantId: variantIds.get(externalId) }))
+                : [{ externalId: undefined, variantId: undefined }];
+            for (const target of targets) {
+                if (image.variantExternalIds?.length && !target.variantId) {
+                    warnings.push(`Skipped image "${image.externalId ?? image.url}" for unmapped variant "${target.externalId}".`);
+                    continue;
+                }
+                const existingLink = links.find((link) => link.mediaAssetId === mediaAssetId
+                    && (target.variantId === undefined ? link.variantId === null : link.variantId === target.variantId));
+                if (existingLink) {
+                    if (existingLink.role !== image.role) {
+                        const currentRolePath = `media.${existingLink.role}`;
+                        const incomingRolePath = `media.${image.role}`;
+                        for (const path of [currentRolePath, incomingRolePath]) {
+                            if (owners.get(path) === "platform" && !skipped.includes(path))
+                                skipped.push(path);
+                        }
+                        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;
+                    }
+                    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;
+                links.push({
+                    entityId,
+                    mediaAssetId,
+                    role: image.role,
+                    sortOrder: image.sortOrder ?? 0,
+                    variantId: target.variantId ?? null,
+                    createdAt: new Date(),
+                });
+            }
+        }
+        return Ok({ imported, changed, skipped });
+    }
     async getStoreRecord(orgId, id) {
         const rows = await this.db
             .select()
@@ -102,20 +966,458 @@ export class ChannelConnectorService {
             .where(eq(connectedStores.storeDomain, shopDomain));
         return rows;
     }
+    resolveCatalogFieldMapping(store, filterableCustomFields, warnings = []) {
+        return mergeCatalogFieldMapping(store.provider, store.catalogFieldMapping, filterableCustomFields, warnings);
+    }
+    async buildCatalogPushItems(orgId, storeId, entityIds, options = {}) {
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store || store.status !== "connected")
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        if (!store.catalogWriteEnabled)
+            return PluginErr("Catalog writes are disabled for this store.", "CATALOG_WRITE_DISABLED");
+        if (entityIds.length === 0)
+            return Ok({ items: [], skipped: [], warnings: [] });
+        const entities = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), inArray(sellableEntities.id, entityIds)));
+        const entityById = new Map(entities.map((entity) => [entity.id, entity]));
+        const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), inArray(channelEntityMap.entityId, entityIds)));
+        const mappingByEntity = new Map(mappings.map((mapping) => [mapping.entityId, mapping]));
+        const items = [];
+        const skipped = [];
+        const warnings = [];
+        const revisionEntityIds = [];
+        for (const entityId of entityIds) {
+            const entity = entityById.get(entityId);
+            if (!entity)
+                return PluginErr("Catalog entity not found.", "NOT_FOUND");
+            if (entity.status !== "active") {
+                skipped.push({ entityId, fieldPath: "entity.status", reason: "entity_not_active" });
+                continue;
+            }
+            const entityMapping = mappingByEntity.get(entity.id);
+            if (!entityMapping) {
+                skipped.push({ entityId, fieldPath: "entity", reason: "unmapped_entity" });
+                continue;
+            }
+            const owners = await this.catalog.resolveFieldOwners(entity.id, storeId);
+            const attributes = await this.db.select().from(sellableAttributes).where(eq(sellableAttributes.entityId, entity.id));
+            const customFields = await this.db.select().from(sellableCustomFields).where(and(eq(sellableCustomFields.entityId, entity.id), eq(sellableCustomFields.status, "approved")));
+            const customFieldNames = [...new Set(customFields.map((field) => field.fieldName))];
+            const definitions = customFieldNames.length > 0
+                ? await this.db.select({ name: entityFieldDefinitions.name, filterable: entityFieldDefinitions.filterable }).from(entityFieldDefinitions).where(and(eq(entityFieldDefinitions.organizationId, orgId), eq(entityFieldDefinitions.entityType, entity.type), inArray(entityFieldDefinitions.name, customFieldNames)))
+                : [];
+            const filterableCustomFields = Object.fromEntries(definitions.map((definition) => [
+                `customFields.${definition.name}.en`,
+                definition.filterable,
+            ]));
+            for (const field of customFields) {
+                filterableCustomFields[`customFields.${field.fieldName}.${field.locale}`] = definitions.find((definition) => definition.name === field.fieldName)?.filterable ?? false;
+            }
+            const fieldMapping = this.resolveCatalogFieldMapping(store, filterableCustomFields, warnings);
+            const heldPaths = new Set(entityMapping.heldFieldPaths ?? []);
+            const forcedPushPaths = new Set([
+                ...(entityMapping.forcedPushFieldPaths ?? []),
+                ...(options.forceFieldPaths?.[entity.id] ?? []),
+            ]);
+            const fields = [];
+            const appendField = (fieldPath, value) => {
+                if (value === undefined)
+                    return;
+                const owner = owners.get(fieldPath);
+                const mapping = selectCatalogFieldMapping(fieldMapping, fieldPath);
+                if (owner === "store") {
+                    skipped.push({
+                        entityId,
+                        fieldPath,
+                        reason: "store_owned",
+                        value,
+                        owner,
+                        ...(mapping ? { target: mapping.target, remoteKey: mapping.remoteKey } : {}),
+                    });
+                    return;
+                }
+                if (owner === undefined)
+                    return;
+                const forced = forcedPushPaths.has(fieldPath);
+                if (owner !== "platform" && !forced)
+                    return;
+                if (heldPaths.has(fieldPath)) {
+                    skipped.push({
+                        entityId,
+                        fieldPath,
+                        reason: "held",
+                        value,
+                        owner,
+                        ...(mapping ? { target: mapping.target, remoteKey: mapping.remoteKey } : {}),
+                    });
+                    return;
+                }
+                if (!mapping) {
+                    skipped.push({ entityId, fieldPath, reason: "no_mapping", value, owner });
+                    return;
+                }
+                fields.push(pushCatalogField(fieldPath, value, mapping));
+            };
+            for (const attribute of attributes) {
+                for (const field of attributeFields) {
+                    appendField(`attributes.${attribute.locale}.${field}`, attribute[field]);
+                }
+            }
+            for (const [key, value] of Object.entries(entity.metadata ?? {})) {
+                const fieldPath = `entity.metadata.${key}`;
+                if (isValidFieldPath(fieldPath))
+                    appendField(fieldPath, value);
+            }
+            for (const customField of customFields) {
+                const fieldPath = `customFields.${customField.fieldName}.${customField.locale}`;
+                if (isValidFieldPath(fieldPath))
+                    appendField(fieldPath, customFieldValue(customField));
+            }
+            const media = await this.media.listEntityMedia(entity.id, { orgId });
+            if (!media.ok)
+                return PluginErr(media.error.message);
+            const images = [];
+            for (const attached of media.value) {
+                const role = pushCatalogImageRole(attached.role);
+                if (!role)
+                    continue;
+                const fieldPath = `media.${role}`;
+                const owner = owners.get(fieldPath);
+                const mapping = selectCatalogFieldMapping(fieldMapping, fieldPath);
+                const imageValue = [{ url: attached.url, role }];
+                if (owner === "store") {
+                    skipped.push({
+                        entityId,
+                        fieldPath,
+                        reason: "store_owned",
+                        value: imageValue,
+                        owner,
+                        ...(mapping ? { target: mapping.target, remoteKey: mapping.remoteKey } : {}),
+                    });
+                    continue;
+                }
+                if (owner === undefined)
+                    continue;
+                const forced = forcedPushPaths.has(fieldPath);
+                if (owner !== "platform" && !forced)
+                    continue;
+                if (heldPaths.has(fieldPath)) {
+                    skipped.push({
+                        entityId,
+                        fieldPath,
+                        reason: "held",
+                        value: imageValue,
+                        owner,
+                        ...(mapping ? { target: mapping.target, remoteKey: mapping.remoteKey } : {}),
+                    });
+                    continue;
+                }
+                if (!mapping) {
+                    skipped.push({ entityId, fieldPath, reason: "no_mapping", value: imageValue, owner });
+                    continue;
+                }
+                images.push({
+                    fieldPath,
+                    target: mapping.target,
+                    remoteKey: mapping.remoteKey,
+                    url: attached.url,
+                    role,
+                    sortOrder: attached.sortOrder,
+                    ...(attached.alt !== null ? { alt: attached.alt } : {}),
+                });
+            }
+            fields.sort((left, right) => left.fieldPath.localeCompare(right.fieldPath));
+            const item = {
+                externalId: entityMapping.externalId,
+                fields,
+                ...(images.length > 0 ? { images } : {}),
+            };
+            items.push(item);
+            if (options.recordRevision === true)
+                revisionEntityIds.push(entity.id);
+        }
+        if (options.recordRevision === true && revisionEntityIds.length > 0) {
+            const actor = createSystemActor(orgId);
+            try {
+                await this.transact(async (tx) => {
+                    const txContext = createTxContext(tx, { actor });
+                    for (const entityId of revisionEntityIds) {
+                        const revision = await this.catalog.recordEntityRevision(entityId, actor, "push", txContext);
+                        if (!revision.ok)
+                            throw new Error(revision.error.message);
+                    }
+                });
+            }
+            catch (error) {
+                return PluginErr(error instanceof Error ? error.message : "Failed to record catalog push revisions.");
+            }
+        }
+        return Ok({ items, skipped, warnings: [...new Set(warnings)] });
+    }
+    async recordOutboundPush(orgId, storeId, outcomes, items, phase = "settle") {
+        const outcomeByExternalId = new Map(outcomes.map((outcome) => [outcome.externalId, outcome]));
+        const now = new Date();
+        for (const item of items) {
+            const outcome = outcomeByExternalId.get(item.externalId);
+            const mapping = await this.db.select({
+                id: channelEntityMap.id,
+                externalId: channelEntityMap.externalId,
+                forcedPushFieldPaths: channelEntityMap.forcedPushFieldPaths,
+            }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, item.externalId)));
+            if (!mapping[0])
+                continue;
+            if (outcome?.ok === true) {
+                const fieldPaths = outboundFieldPaths(item);
+                await this.db.update(channelEntityMap).set({
+                    outboundHash: canonicalOutboundHash(mapping[0].externalId, item, fieldPaths),
+                    outboundPushedAt: now,
+                    outboundFieldPaths: fieldPaths,
+                    // A force is an operator's conflict resolution. The write-ahead runs
+                    // before the connector is called and its outcomes are optimistic, so
+                    // consuming the force there would discard the resolution on a failed
+                    // push and the retry would silently omit the field.
+                    ...(phase === "settle"
+                        ? { forcedPushFieldPaths: (mapping[0].forcedPushFieldPaths ?? []).filter((path) => !fieldPaths.includes(path)) }
+                        : {}),
+                }).where(eq(channelEntityMap.id, mapping[0].id));
+            }
+            else {
+                await this.db.update(channelEntityMap).set({
+                    outboundHash: null,
+                    outboundPushedAt: null,
+                    outboundFieldPaths: [],
+                    syncHash: "",
+                }).where(eq(channelEntityMap.id, mapping[0].id));
+            }
+        }
+        return Ok(undefined);
+    }
+    async pushCatalogToStore(orgId, storeId, entityIds) {
+        const assembled = await this.buildCatalogPushItems(orgId, storeId, entityIds);
+        if (!assembled.ok)
+            return assembled;
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store || store.status !== "connected")
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        const connector = this.connectors.get(store.provider);
+        if (!connector?.pushCatalog)
+            return PluginErr(`Catalog push is not supported by provider "${store.provider}".`);
+        if (assembled.value.items.length === 0)
+            return Ok({
+                outcomes: [],
+                skipped: assembled.value.skipped,
+                warnings: assembled.value.warnings,
+            });
+        const writeAhead = await this.recordOutboundPush(orgId, storeId, assembled.value.items.map((item) => ({ externalId: item.externalId, ok: true })), assembled.value.items, "write-ahead");
+        if (!writeAhead.ok)
+            return writeAhead;
+        let result;
+        try {
+            result = await connector.pushCatalog(store, assembled.value.items);
+        }
+        catch (error) {
+            const connectorError = {
+                code: "CATALOG_PUSH_THROWN",
+                message: error instanceof Error ? error.message : "Catalog push failed.",
+            };
+            const cleared = await this.recordOutboundPush(orgId, storeId, assembled.value.items.map((item) => ({ externalId: item.externalId, ok: false, error: connectorError })), assembled.value.items);
+            if (!cleared.ok)
+                return cleared;
+            return PluginErr(connectorError.message, connectorError.code);
+        }
+        if (!result.ok) {
+            const cleared = await this.recordOutboundPush(orgId, storeId, assembled.value.items.map((item) => ({ externalId: item.externalId, ok: false, error: result.error })), assembled.value.items);
+            if (!cleared.ok)
+                return cleared;
+            return PluginErr(result.error.message, result.error.code);
+        }
+        const recorded = await this.recordOutboundPush(orgId, storeId, result.value.outcomes, assembled.value.items);
+        if (!recorded.ok)
+            return recorded;
+        const successfulEntityIds = assembled.value.items
+            .filter((item) => result.value.outcomes.some((outcome) => outcome.externalId === item.externalId && outcome.ok))
+            .map((item) => item.externalId);
+        if (successfulEntityIds.length > 0) {
+            const mappings = await this.db.select({ entityId: channelEntityMap.entityId }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), inArray(channelEntityMap.externalId, successfulEntityIds)));
+            const actor = createSystemActor(orgId);
+            try {
+                await this.transact(async (tx) => {
+                    const txContext = createTxContext(tx, { actor });
+                    for (const entityId of [...new Set(mappings.map((mapping) => mapping.entityId))]) {
+                        const revision = await this.catalog.recordEntityRevision(entityId, actor, "push", txContext);
+                        if (!revision.ok)
+                            throw new Error(revision.error.message);
+                    }
+                });
+            }
+            catch (error) {
+                return PluginErr(error instanceof Error ? error.message : "Failed to record catalog push revisions.");
+            }
+        }
+        return Ok({
+            ...result.value,
+            skipped: assembled.value.skipped,
+            warnings: assembled.value.warnings,
+        });
+    }
+    async previewCatalogPush(orgId, storeId, entityIds) {
+        const assembledEntityIds = await this.resolveCatalogPushEntityIds(orgId, storeId, entityIds);
+        const assembled = await this.buildCatalogPushItems(orgId, storeId, assembledEntityIds);
+        if (!assembled.ok)
+            return assembled;
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store || store.status !== "connected")
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        const connector = this.connectors.get(store.provider);
+        if (!connector?.pushCatalog)
+            return PluginErr(`Catalog push is not supported by provider "${store.provider}".`);
+        if (assembled.value.items.length === 0) {
+            return Ok({ items: [], skipped: assembled.value.skipped, warnings: assembled.value.warnings });
+        }
+        let result;
+        try {
+            result = await connector.pushCatalog(store, assembled.value.items, { dryRun: true });
+        }
+        catch (error) {
+            return PluginErr(error instanceof Error ? error.message : "Catalog push preview failed.", "CATALOG_PREVIEW_THROWN");
+        }
+        if (!result.ok)
+            return PluginErr(result.error.message, result.error.code);
+        const failed = result.value.outcomes.find((outcome) => !outcome.ok);
+        if (failed)
+            return PluginErr(failed.error?.message ?? `Catalog push preview failed for item "${failed.externalId}".`, failed.error?.code ?? "CATALOG_PREVIEW_FAILED");
+        const mappings = assembledEntityIds.length === 0
+            ? []
+            : await this.db.select({ entityId: channelEntityMap.entityId, externalId: channelEntityMap.externalId }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), inArray(channelEntityMap.entityId, assembledEntityIds)));
+        const externalByEntity = new Map(mappings.map((mapping) => [mapping.entityId, mapping.externalId]));
+        const skippedByExternal = new Map();
+        for (const skipped of assembled.value.skipped) {
+            const externalId = externalByEntity.get(skipped.entityId);
+            if (!externalId)
+                continue;
+            const existing = skippedByExternal.get(externalId) ?? [];
+            existing.push(skipped);
+            skippedByExternal.set(externalId, existing);
+        }
+        const outcomeByExternalId = new Map(result.value.outcomes.map((outcome) => [outcome.externalId, outcome]));
+        const beforeFor = (externalId, fieldPath) => {
+            const previousFields = outcomeByExternalId.get(externalId)?.previousFields;
+            if (previousFields === undefined) {
+                return { before: { status: "unavailable" }, beforeStatus: "unavailable" };
+            }
+            const previous = previousFields.find((field) => field.fieldPath === fieldPath);
+            if (!previous)
+                return { before: null, beforeStatus: "missing" };
+            return { before: previous.value, beforeStatus: "value" };
+        };
+        const items = assembled.value.items.map((item) => {
+            const diffs = item.fields.map((field) => ({
+                fieldPath: field.fieldPath,
+                target: field.target,
+                remoteKey: field.remoteKey ?? null,
+                ...beforeFor(item.externalId, field.fieldPath),
+                after: field.value,
+                owner: "platform",
+                willWrite: true,
+            }));
+            for (const image of item.images ?? []) {
+                diffs.push({
+                    fieldPath: image.fieldPath,
+                    target: image.target,
+                    remoteKey: image.remoteKey,
+                    ...beforeFor(item.externalId, image.fieldPath),
+                    after: pushFieldValue(item, image.fieldPath),
+                    owner: "platform",
+                    willWrite: true,
+                });
+            }
+            for (const skipped of skippedByExternal.get(item.externalId) ?? []) {
+                if (skipped.value === undefined || skipped.owner === undefined)
+                    continue;
+                diffs.push({
+                    fieldPath: skipped.fieldPath,
+                    target: skipped.target ?? null,
+                    remoteKey: skipped.remoteKey ?? null,
+                    ...beforeFor(item.externalId, skipped.fieldPath),
+                    after: skipped.value,
+                    owner: skipped.owner,
+                    willWrite: false,
+                    reason: skipped.reason,
+                });
+            }
+            return { externalId: item.externalId, diffs };
+        });
+        return Ok({ items, skipped: assembled.value.skipped, warnings: assembled.value.warnings });
+    }
+    async getCatalogWriteSettings(orgId, storeId) {
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store)
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        const warnings = [];
+        return Ok({
+            enabled: store.catalogWriteEnabled === true,
+            overrides: store.catalogFieldMapping,
+            merged: this.resolveCatalogFieldMapping(store, undefined, warnings),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        });
+    }
+    async updateCatalogWriteEnabled(orgId, storeId, enabled) {
+        const rows = await this.db
+            .update(connectedStores)
+            .set({ catalogWriteEnabled: enabled, updatedAt: new Date() })
+            .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)))
+            .returning();
+        if (!rows[0])
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        return this.getCatalogWriteSettings(orgId, storeId);
+    }
+    async updateCatalogFieldMapping(orgId, storeId, mapping) {
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store)
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        let normalized;
+        try {
+            normalized = normalizeCatalogFieldMapping(mapping, store.provider);
+        }
+        catch (error) {
+            return PluginErr(error instanceof Error ? error.message : "Catalog mapping is invalid.", "INVALID_MAPPING");
+        }
+        await this.db
+            .update(connectedStores)
+            .set({ catalogFieldMapping: normalized, updatedAt: new Date() })
+            .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+        return this.getCatalogWriteSettings(orgId, storeId);
+    }
     async connectStore(orgId, input) {
         if (!this.connectors.has(input.provider)) {
             return PluginErr(`No connector registered for provider "${input.provider}".`, "NOT_FOUND");
         }
-        const rows = await this.db
-            .insert(connectedStores)
-            .values({
-            organizationId: orgId,
-            provider: input.provider,
-            credentials: input.credentials,
-            storeDomain: input.storeDomain,
-            webhookSecret: input.webhookSecret ?? crypto.randomUUID(),
-        })
-            .returning();
+        const existingRows = await this.db
+            .select()
+            .from(connectedStores)
+            .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.provider, input.provider), eq(connectedStores.storeDomain, input.storeDomain)));
+        const reconnect = existingRows.find((row) => row.status !== "connected");
+        const rows = reconnect
+            ? await this.db
+                .update(connectedStores)
+                .set({
+                credentials: input.credentials,
+                status: "connected",
+                catalogWriteEnabled: false,
+                webhookSecret: input.webhookSecret ?? crypto.randomUUID(),
+                updatedAt: new Date(),
+            })
+                .where(eq(connectedStores.id, reconnect.id))
+                .returning()
+            : await this.db
+                .insert(connectedStores)
+                .values({
+                organizationId: orgId,
+                provider: input.provider,
+                credentials: input.credentials,
+                storeDomain: input.storeDomain,
+                webhookSecret: input.webhookSecret ?? crypto.randomUUID(),
+            })
+                .returning();
         const connector = this.connectors.get(input.provider);
         const store = rows[0];
         if (connector.registerWebhooks) {
@@ -258,78 +1560,468 @@ export class ChannelConnectorService {
             .update(connectedStores)
             .set({ catalogCursor: null, lastSyncAt: new Date(), updatedAt: new Date() })
             .where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
-        return Ok({ imported: result.value.imported, cursor: null });
+        return Ok({
+            imported: result.value.imported,
+            cursor: null,
+            ...(result.value.skipped.length > 0 ? { skipped: uniqueSkipped(result.value.skipped) } : {}),
+            ...(result.value.conflicts.length > 0 ? { conflicts: result.value.conflicts } : {}),
+            ...(result.value.warnings.length > 0 ? { warnings: result.value.warnings } : {}),
+        });
+    }
+    async promoteLegacyAttributes(orgId, storeId, actor, dryRun) {
+        const mappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity")));
+        let created = 0;
+        for (const entityId of new Set(mappings.map((mapping) => mapping.entityId))) {
+            const [entity] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, entityId)));
+            if (!entity)
+                continue;
+            const attributes = await this.db.select().from(sellableAttributes).where(eq(sellableAttributes.entityId, entity.id));
+            if (attributes.length > 0)
+                continue;
+            const metadata = entity.metadata ?? {};
+            if (typeof metadata.title !== "string")
+                continue;
+            const owners = await this.catalog.resolveFieldOwners(entity.id, storeId);
+            if (owners.get("attributes.en.title") === "platform")
+                continue;
+            if (dryRun) {
+                created += 1;
+                continue;
+            }
+            const promoted = await this.catalog.setAttributes(entity.id, "en", {
+                title: metadata.title,
+                ...(typeof metadata.description === "string" ? { description: metadata.description } : {}),
+            }, actor, CHANNEL_CONVERGENCE_CTX);
+            if (!promoted.ok)
+                return PluginErr(promoted.error.message);
+            const [confirmed] = await this.db.select({ id: sellableAttributes.id, title: sellableAttributes.title, description: sellableAttributes.description }).from(sellableAttributes).where(and(eq(sellableAttributes.entityId, entity.id), eq(sellableAttributes.locale, "en")));
+            if (!confirmed || confirmed.title !== metadata.title || (typeof metadata.description === "string" && confirmed.description !== metadata.description)) {
+                return PluginErr(`Legacy attributes for entity "${entity.id}" were not persisted.`);
+            }
+            const nextMetadata = { ...metadata };
+            delete nextMetadata.title;
+            if (typeof metadata.description === "string")
+                delete nextMetadata.description;
+            await this.db.update(sellableEntities).set({ metadata: nextMetadata, updatedAt: new Date() }).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, entity.id)));
+            created += 1;
+        }
+        return Ok(created);
+    }
+    async saveBackfillState(orgId, storeId, state) {
+        const [store] = await this.db.select({ breakerState: connectedStores.breakerState }).from(connectedStores).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+        await this.db.update(connectedStores).set({
+            breakerState: { ...(store?.breakerState ?? {}), catalogBackfill: state },
+            updatedAt: new Date(),
+        }).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+    }
+    async backfillCatalog(orgId, storeId, actor, options = {}) {
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store || store.status !== "connected")
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        const connector = this.connectors.get(store.provider);
+        if (!connector)
+            return PluginErr(`No connector registered for provider "${store.provider}".`);
+        const dryRun = options.dryRun === true;
+        const saved = store.breakerState.catalogBackfill;
+        const savedState = saved && typeof saved === "object" ? saved : undefined;
+        // Undefined resume derives from persisted state, so a retried job or a
+        // re-triggered run continues an unfinished backfill instead of restarting.
+        const resume = options.resume ?? (savedState !== undefined && !savedState.completedAt);
+        if (resume && savedState?.completedAt && savedState.cursor === null) {
+            return Ok({
+                ...savedState.report,
+                cursor: null,
+                complete: true,
+                ...(savedState.skipped?.length ? { skipped: savedState.skipped } : {}),
+                ...(savedState.conflicts?.length ? { conflicts: savedState.conflicts } : {}),
+                ...(savedState.warnings?.length ? { warnings: savedState.warnings } : {}),
+            });
+        }
+        const report = resume && savedState ? { ...savedState.report } : {
+            entitiesTouched: 0,
+            attributesCreated: 0,
+            mediaImported: 0,
+            variantsGivenOptionValues: 0,
+        };
+        const skipped = resume && savedState?.skipped ? [...savedState.skipped] : [];
+        const conflicts = resume && savedState?.conflicts ? [...savedState.conflicts] : [];
+        const warnings = resume && savedState?.warnings ? [...savedState.warnings] : [];
+        const promoted = await this.promoteLegacyAttributes(orgId, storeId, actor, dryRun);
+        if (!promoted.ok)
+            return promoted;
+        report.attributesCreated += promoted.value;
+        let cursor = resume && savedState?.cursor ? savedState.cursor : undefined;
+        let pages = 0;
+        if (!dryRun) {
+            await this.saveBackfillState(orgId, storeId, {
+                cursor: cursor ?? null,
+                report,
+                ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+                ...(conflicts.length > 0 ? { conflicts } : {}),
+                ...(warnings.length > 0 ? { warnings } : {}),
+            });
+        }
+        do {
+            const page = await connector.importCatalog(store, cursor);
+            if (!page.ok)
+                return PluginErr(page.error.message);
+            const converged = await this.convergeCatalogItems(orgId, storeId, page.value.items, actor, true, dryRun);
+            if (!converged.ok)
+                return converged;
+            report.entitiesTouched += converged.value.entitiesTouched;
+            report.attributesCreated += converged.value.attributesCreated;
+            report.mediaImported += converged.value.mediaImported;
+            report.variantsGivenOptionValues += converged.value.variantsGivenOptionValues;
+            skipped.push(...converged.value.skipped);
+            conflicts.push(...converged.value.conflicts);
+            warnings.push(...converged.value.warnings);
+            cursor = page.value.nextCursor ?? undefined;
+            pages += 1;
+            // The final state is written once with completedAt below; a cursor-null
+            // checkpoint without it would read as a fresh start after a crash.
+            if (!dryRun && cursor) {
+                await this.saveBackfillState(orgId, storeId, {
+                    cursor,
+                    report,
+                    ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+                    ...(conflicts.length > 0 ? { conflicts } : {}),
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                });
+            }
+            if (options.maxPages !== undefined && pages >= options.maxPages && cursor) {
+                return Ok({
+                    ...report,
+                    cursor,
+                    complete: false,
+                    ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+                    ...(conflicts.length > 0 ? { conflicts } : {}),
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                });
+            }
+        } while (cursor);
+        if (!dryRun) {
+            await this.saveBackfillState(orgId, storeId, {
+                cursor: null,
+                report,
+                ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+                ...(conflicts.length > 0 ? { conflicts } : {}),
+                ...(warnings.length > 0 ? { warnings } : {}),
+                completedAt: new Date().toISOString(),
+            });
+        }
+        return Ok({
+            ...report,
+            cursor: null,
+            complete: true,
+            ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+            ...(conflicts.length > 0 ? { conflicts } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        });
     }
-    async convergeCatalogItems(orgId, storeId, items, actor) {
+    async estimateCatalogItems(orgId, storeId, items) {
+        const stats = {
+            imported: 0,
+            converged: 0,
+            entitiesTouched: 0,
+            attributesCreated: 0,
+            mediaImported: 0,
+            variantsGivenOptionValues: 0,
+            skipped: [],
+            conflicts: [],
+            warnings: [],
+        };
+        const assets = await this.db.select().from(mediaAssets).where(eq(mediaAssets.organizationId, orgId));
+        for (const item of items) {
+            const [entityMapping] = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, item.externalId)));
+            if (!entityMapping) {
+                stats.imported += 1;
+                stats.entitiesTouched += 1;
+                stats.attributesCreated += item.attributes?.length || 1;
+                stats.variantsGivenOptionValues += item.variants.filter((variant) => Object.keys(variant.optionValues ?? {}).some((name) => item.options?.some((option) => option.name === name))).length;
+                stats.mediaImported += item.images?.length ?? 0;
+                continue;
+            }
+            const [entity] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, entityMapping.entityId)));
+            if (!entity)
+                continue;
+            const owners = await this.catalog.resolveFieldOwners(entity.id, storeId);
+            stats.skipped.push(...importedFieldPaths(item)
+                .filter((path) => owners.get(path) === "platform")
+                .map((fieldPath) => ({ entityId: entity.id, fieldPath })));
+            let touched = false;
+            const attributes = await this.db.select().from(sellableAttributes).where(eq(sellableAttributes.entityId, entity.id));
+            const locales = new Set(attributes.map((attribute) => attribute.locale));
+            const metadata = entity.metadata ?? {};
+            if (attributes.length === 0 && typeof metadata.title === "string") {
+                locales.add("en");
+                touched = true;
+            }
+            const sourceAttributes = item.attributes?.length
+                ? item.attributes
+                : [{ locale: "en", title: item.title, ...(item.description !== undefined ? { description: item.description } : {}) }];
+            for (const attribute of sourceAttributes) {
+                if (!locales.has(attribute.locale)) {
+                    stats.attributesCreated += 1;
+                    locales.add(attribute.locale);
+                    touched = true;
+                }
+            }
+            const remoteMetadata = mergeMetadata(entity.metadata, item.metadata ?? {});
+            const remoteStatus = item.status ?? (entity.status === "archived" ? "active" : undefined);
+            const entityChanged = entity.slug !== item.slug
+                || hash(remoteMetadata) !== hash(entity.metadata ?? {})
+                || (remoteStatus !== undefined && remoteStatus !== entity.status);
+            if (entityChanged) {
+                stats.converged += 1;
+                touched = true;
+            }
+            const optionValueIds = new Map();
+            const existingTypes = await this.db.select().from(optionTypes).where(eq(optionTypes.entityId, entity.id));
+            for (const sourceType of item.options ?? []) {
+                const existingType = existingTypes.find((optionType) => optionType.name === sourceType.name);
+                if (!existingType) {
+                    touched = true;
+                    optionValueIds.set(sourceType.name, new Map(sourceType.values.map((value) => [value.value, `new:${sourceType.name}:${value.value}`])));
+                    continue;
+                }
+                const existingValues = await this.db.select().from(optionValues).where(eq(optionValues.optionTypeId, existingType.id));
+                const valueIds = new Map();
+                for (const sourceValue of sourceType.values) {
+                    const existingValue = existingValues.find((value) => value.value === sourceValue.value);
+                    if (!existingValue)
+                        touched = true;
+                    valueIds.set(sourceValue.value, existingValue?.id ?? `new:${sourceType.name}:${sourceValue.value}`);
+                }
+                optionValueIds.set(sourceType.name, valueIds);
+            }
+            const variantMappings = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "variant"), eq(channelEntityMap.entityId, entity.id)));
+            const variantIds = new Map();
+            for (const sourceVariant of item.variants) {
+                const mapping = variantMappings.find((row) => row.externalId === sourceVariant.externalId);
+                const variantId = mapping?.variantId ?? `new:${sourceVariant.externalId}`;
+                variantIds.set(sourceVariant.externalId, variantId);
+                const desiredIds = [...new Set(Object.entries(sourceVariant.optionValues ?? {})
+                        .map(([name, value]) => optionValueIds.get(name)?.get(value))
+                        .filter((optionValueId) => optionValueId !== undefined))].sort();
+                if (!mapping?.variantId) {
+                    if (desiredIds.length > 0)
+                        stats.variantsGivenOptionValues += 1;
+                    touched = true;
+                    continue;
+                }
+                const current = await this.db.select().from(variantOptionValues).where(eq(variantOptionValues.variantId, mapping.variantId));
+                const currentIds = current.map((row) => row.optionValueId).sort();
+                if (currentIds.length !== desiredIds.length || currentIds.some((id, index) => id !== desiredIds[index])) {
+                    if (desiredIds.length > 0)
+                        stats.variantsGivenOptionValues += 1;
+                    touched = true;
+                }
+            }
+            const links = await this.db.select().from(entityMedia).where(eq(entityMedia.entityId, entity.id));
+            for (const image of item.images ?? []) {
+                const urlHash = hash(image.url);
+                const asset = assets.find((row) => {
+                    const assetMetadata = row.metadata ?? {};
+                    return (image.externalId != null && assetMetadata.channelImageExternalId === image.externalId)
+                        || assetMetadata.channelImageUrlHash === urlHash;
+                });
+                const mediaAssetId = asset?.id ?? `new:${urlHash}`;
+                if (!asset)
+                    stats.mediaImported += 1;
+                const targets = image.variantExternalIds?.length
+                    ? image.variantExternalIds.map((externalId) => ({ externalId, variantId: variantIds.get(externalId) }))
+                    : [{ externalId: undefined, variantId: undefined }];
+                for (const target of targets) {
+                    if (image.variantExternalIds?.length && !target.variantId) {
+                        stats.warnings.push(`Skipped image "${image.externalId ?? image.url}" for unmapped variant "${target.externalId}".`);
+                        continue;
+                    }
+                    const existingLink = links.find((link) => link.mediaAssetId === mediaAssetId && (target.variantId === undefined ? link.variantId === null : link.variantId === target.variantId));
+                    if (!existingLink)
+                        touched = true;
+                }
+            }
+            if (touched)
+                stats.entitiesTouched += 1;
+        }
+        return Ok(stats);
+    }
+    async convergeCatalogItems(orgId, storeId, items, actor, force = false, dryRun = false) {
+        if (dryRun)
+            return this.estimateCatalogItems(orgId, storeId, items);
         let imported = 0;
         let converged = 0;
+        let entitiesTouched = 0;
+        let attributesCreated = 0;
+        let mediaImported = 0;
+        let variantsGivenOptionValues = 0;
+        const skipped = [];
+        const conflicts = [];
+        const warnings = [];
         for (const item of items) {
+            const remoteHash = hash(item);
             const existing = await this.db
                 .select()
                 .from(channelEntityMap)
                 .where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, item.externalId)));
             const entityMapping = existing.find((entry) => entry.kind === "entity");
+            let entityId;
+            let isNew = false;
+            let entityTouched = false;
+            let existingEntity;
             if (entityMapping) {
                 const [entity] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, entityMapping.entityId)));
-                if (entityMapping.syncHash !== hash(item) || entity?.status === "archived") {
-                    const updated = await this.catalog.update(entityMapping.entityId, {
-                        slug: item.slug,
-                        metadata: {
-                            ...(item.metadata ?? {}),
-                            title: item.title,
-                            ...(item.description !== undefined ? { description: item.description } : {}),
-                        },
-                        ...(entity?.status === "archived" ? { status: "active", isVisible: true } : {}),
-                    }, actor);
-                    if (!updated.ok)
-                        return PluginErr(updated.error.message);
-                    await this.db.update(channelEntityMap).set({ syncHash: hash(item), lastSyncedAt: new Date() }).where(eq(channelEntityMap.id, entityMapping.id));
-                    converged += 1;
+                if (!entity) {
+                    warnings.push(`Skipped "${item.externalId}": mapped entity ${entityMapping.entityId} no longer exists.`);
+                    continue;
                 }
-                continue;
+                entityId = entityMapping.entityId;
+                existingEntity = entity;
             }
-            const entity = await this.catalog.create({
-                type: "product",
-                slug: item.slug,
-                sourceStoreId: storeId,
-                metadata: {
-                    ...(item.metadata ?? {}),
-                    title: item.title,
-                    ...(item.description !== undefined ? { description: item.description } : {}),
-                },
-            }, actor);
-            if (!entity.ok)
-                return PluginErr(entity.error.message);
-            await this.db.insert(channelEntityMap).values({
-                organizationId: orgId,
-                storeId,
-                kind: "entity",
-                externalId: item.externalId,
-                entityId: entity.value.id,
-                syncHash: hash(item),
-            });
-            for (const sourceVariant of item.variants) {
-                const variant = await this.catalog.createVariant({
-                    entityId: entity.value.id,
-                    options: {},
-                    ...(sourceVariant.sku !== undefined ? { sku: sourceVariant.sku } : {}),
-                    ...(sourceVariant.barcode !== undefined ? { barcode: sourceVariant.barcode } : {}),
+            else {
+                const status = item.status;
+                const entity = await this.catalog.create({
+                    type: "product",
+                    slug: item.slug,
+                    sourceStoreId: storeId,
+                    metadata: mergeMetadata(undefined, item.metadata ?? {}),
+                    ...(status !== undefined ? { status, isVisible: status === "active" } : {}),
                 }, actor);
-                if (!variant.ok)
-                    return PluginErr(variant.error.message);
+                if (!entity.ok)
+                    return PluginErr(entity.error.message);
+                entityId = entity.value.id;
+                isNew = true;
+                imported += 1;
+                entityTouched = true;
+            }
+            const ownershipBeforeSeed = await this.catalog.resolveFieldOwners(entityId, storeId);
+            const seedPaths = importedFieldPaths(item).filter((path) => !ownershipBeforeSeed.has(path));
+            const seeded = await this.catalog.seedImportedFieldOwnership(entityId, storeId, seedPaths);
+            if (!seeded.ok)
+                return PluginErr(seeded.error.message);
+            for (const path of seedPaths)
+                ownershipBeforeSeed.set(path, "store");
+            const owners = ownershipBeforeSeed;
+            const outboundEcho = entityMapping ? this.isOutboundEcho(entityMapping, item) : false;
+            const remoteChanged = entityMapping === undefined || entityMapping.syncHash !== remoteHash;
+            // An unchanged remote item writes nothing and advances no baseline:
+            // converging a stale replay would revert local edits to shared and
+            // unowned fields that the store never actually changed.
+            if (!force && !remoteChanged && existingEntity && existingEntity.status !== "archived") {
+                continue;
+            }
+            const shared = existingEntity
+                ? await this.detectSharedConflicts(entityId, storeId, existingEntity, entityMapping, item, owners, importedFieldPaths(item), remoteHash, outboundEcho ? { certifiedPaths: new Set(entityMapping?.outboundFieldPaths ?? []) } : undefined)
+                : { paths: [], conflicts: [] };
+            const persistedConflicts = await this.persistCatalogConflicts(orgId, shared.conflicts, requireUserId(actor));
+            if (!persistedConflicts.ok)
+                return persistedConflicts;
+            const owned = this.filterOwnedFields(item, owners);
+            const heldSharedPaths = [...new Set([...(entityMapping?.heldFieldPaths ?? []), ...shared.paths])];
+            // A newly held path revokes any force left from an earlier resolution of
+            // that same path: the force was the operator's answer to a question that
+            // has since been asked again, and it must not pre-empt the new one.
+            const survivingForcedPaths = (entityMapping?.forcedPushFieldPaths ?? []).filter((path) => !heldSharedPaths.includes(path));
+            const held = this.filterConflictingFields(owned.writable, heldSharedPaths);
+            const writable = held.writable;
+            const blockedPaths = new Set([...owned.skipped, ...heldSharedPaths]);
+            skipped.push(...owned.skipped.map((fieldPath) => ({ entityId, fieldPath })));
+            conflicts.push(...shared.conflicts.map(({ platformValue: _platformValue, storeValue: _storeValue, ...conflict }) => conflict));
+            for (const conflict of shared.conflicts) {
+                warnings.push(`Held shared field conflict for entity "${conflict.entityId}", store "${conflict.storeId}", field "${conflict.fieldPath}" (local ${conflict.localValueSummary}, remote ${conflict.remoteValueSummary}).`);
+            }
+            if (existingEntity && entityMapping) {
+                const remoteMetadata = mergeMetadata(existingEntity.metadata, writable.metadata ?? {});
+                const remoteStatus = ownerAllows(owners, "entity.status") && !blockedPaths.has("entity.status")
+                    ? writable.status ?? (existingEntity.status === "archived" ? "active" : undefined)
+                    : undefined;
+                const updateInput = {};
+                if (ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && existingEntity.slug !== writable.slug) {
+                    updateInput.slug = writable.slug;
+                }
+                if (hash(remoteMetadata) !== hash(existingEntity.metadata ?? {}))
+                    updateInput.metadata = remoteMetadata;
+                if (remoteStatus !== undefined && !blockedPaths.has("entity.status") && remoteStatus !== existingEntity.status) {
+                    updateInput.status = remoteStatus;
+                    updateInput.isVisible = remoteStatus === "active";
+                }
+                const shouldUpdate = force
+                    ? Object.keys(updateInput).length > 0
+                    : remoteChanged || existingEntity.status === "archived";
+                if (shouldUpdate) {
+                    converged += 1;
+                    if (Object.keys(updateInput).length > 0) {
+                        const updated = await this.catalog.update(entityMapping.entityId, updateInput, actor, CHANNEL_CONVERGENCE_CTX);
+                        if (!updated.ok)
+                            return PluginErr(updated.error.message);
+                        entityTouched = true;
+                    }
+                }
+            }
+            const optionAxes = await this.upsertOptionAxes(entityId, writable, actor);
+            if (!optionAxes.ok)
+                return optionAxes;
+            const attributes = await this.setCatalogAttributesIfWritable(entityId, writable, actor, blockedPaths, CHANNEL_CONVERGENCE_CTX);
+            if (!attributes.ok)
+                return attributes;
+            const variantIds = await this.upsertVariants(orgId, storeId, entityId, writable, optionAxes.value.value, actor, warnings, !heldSharedPaths.includes("options") && owners.get("options") !== "platform", item);
+            if (!variantIds.ok)
+                return variantIds;
+            const taxonomy = await this.applyTaxonomy(orgId, entityId, writable, actor, warnings);
+            if (!taxonomy.ok)
+                return taxonomy;
+            const media = await this.applyMedia(orgId, entityId, writable, variantIds.value.value, actor, warnings, owners);
+            if (!media.ok)
+                return media;
+            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 || media.value.changed || attributes.value.changed;
+            if (entityTouched)
+                entitiesTouched += 1;
+            if (entityTouched) {
+                const revision = await this.catalog.recordEntityRevision(entityId, actor, "import");
+                if (!revision.ok)
+                    return PluginErr(revision.error.message);
+            }
+            const revisionMarkers = await this.catalog.repository.findRevisionMarkers(entityId);
+            const latestRevisionAt = revisionMarkers.at(-1)?.createdAt;
+            const lastSyncedAt = latestRevisionAt ?? entityMapping?.lastSyncedAt ?? new Date();
+            if (isNew) {
                 await this.db.insert(channelEntityMap).values({
                     organizationId: orgId,
                     storeId,
-                    kind: "variant",
-                    externalId: sourceVariant.externalId,
-                    entityId: entity.value.id,
-                    variantId: variant.value.id,
-                    syncHash: hash(sourceVariant),
+                    kind: "entity",
+                    externalId: item.externalId,
+                    entityId,
+                    syncHash: remoteHash,
+                    lastSyncedAt,
+                    heldFieldPaths: heldSharedPaths,
+                    forcedPushFieldPaths: survivingForcedPaths,
                 });
             }
-            imported += 1;
+            else if (entityMapping) {
+                await this.db.update(channelEntityMap).set({
+                    syncHash: remoteHash,
+                    lastSyncedAt,
+                    heldFieldPaths: heldSharedPaths,
+                    forcedPushFieldPaths: survivingForcedPaths,
+                }).where(eq(channelEntityMap.id, entityMapping.id));
+            }
+            await this.db.update(channelEntityMap).set({ lastSyncedAt }).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.entityId, entityId), eq(channelEntityMap.kind, "variant")));
         }
-        return Ok({ imported, converged });
+        return Ok({
+            imported,
+            converged,
+            entitiesTouched,
+            attributesCreated,
+            mediaImported,
+            variantsGivenOptionValues,
+            skipped,
+            conflicts,
+            warnings,
+        });
     }
     async reconcile(orgId, storeId, actor) {
         const store = await this.getStoreRecord(orgId, storeId);
@@ -354,11 +2046,17 @@ export class ChannelConnectorService {
             return converged;
         const present = new Set(items.map((item) => item.externalId));
         let archived = 0;
+        const skipped = [...converged.value.skipped];
         for (const mapping of entityMappings) {
             if (present.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") {
+                const owners = await this.catalog.resolveFieldOwners(mapping.entityId, storeId);
+                if (owners.get("entity.status") === "platform") {
+                    skipped.push({ entityId: mapping.entityId, fieldPath: "entity.status" });
+                    continue;
+                }
                 const result = await this.catalog.archive(mapping.entityId, actor);
                 if (!result.ok)
                     return PluginErr(result.error.message);
@@ -389,12 +2087,17 @@ export class ChannelConnectorService {
             inventoryUpdated += 1;
         }
         const threshold = this.options.driftAlertThreshold ?? 25;
+        const openConflictRows = await this.db.select({ id: channelCatalogConflicts.id }).from(channelCatalogConflicts).where(and(eq(channelCatalogConflicts.organizationId, orgId), eq(channelCatalogConflicts.storeId, storeId), eq(channelCatalogConflicts.state, "open")));
         const report = {
             imported: converged.value.imported,
             converged: converged.value.converged,
             archived,
             inventoryUpdated,
+            openConflicts: openConflictRows.length,
             driftAlert: converged.value.imported + converged.value.converged + archived > threshold,
+            ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+            ...(converged.value.conflicts.length > 0 ? { conflicts: converged.value.conflicts } : {}),
+            ...(converged.value.warnings.length > 0 ? { warnings: converged.value.warnings } : {}),
         };
         await this.db.update(connectedStores).set({
             lastReconcileAt: new Date(),
@@ -411,6 +2114,134 @@ export class ChannelConnectorService {
         const report = store.lastReconcileReport;
         return Ok({ lastReconcileAt: store.lastReconcileAt, report, driftAlert: report?.driftAlert ?? false });
     }
+    async listCatalogConflicts(orgId, storeId, state = "open") {
+        const conditions = [eq(channelCatalogConflicts.organizationId, orgId), eq(channelCatalogConflicts.state, state)];
+        if (storeId !== undefined)
+            conditions.push(eq(channelCatalogConflicts.storeId, storeId));
+        return Ok(await this.db.select().from(channelCatalogConflicts).where(and(...conditions)));
+    }
+    async resolveCatalogConflict(orgId, id, choose, actor) {
+        const [conflict] = await this.db.select().from(channelCatalogConflicts).where(and(eq(channelCatalogConflicts.organizationId, orgId), eq(channelCatalogConflicts.id, id), eq(channelCatalogConflicts.state, "open")));
+        if (!conflict)
+            return PluginErr("Catalog conflict not found or already resolved.", "NOT_FOUND");
+        if (choose === "platform" && !this.jobs)
+            return PluginErr("Jobs are not configured.", "JOBS_UNAVAILABLE");
+        const [mapping] = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, conflict.storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.entityId, conflict.entityId)));
+        if (!mapping)
+            return PluginErr("Catalog conflict mapping not found.", "NOT_FOUND");
+        const systemActor = createSystemActor(orgId);
+        let resolutionBaselineAt;
+        if (choose === "store") {
+            const applied = await this.applyStoreConflictValue(orgId, conflict, systemActor);
+            if (!applied.ok)
+                return PluginErr(applied.error, applied.code);
+            const revisions = await this.catalog.repository.findRevisionMarkers(conflict.entityId);
+            resolutionBaselineAt = revisions.at(-1)?.createdAt;
+        }
+        const heldFieldPaths = (mapping.heldFieldPaths ?? []).filter((path) => path !== conflict.fieldPath);
+        const forcedPushFieldPaths = choose === "platform"
+            ? [...new Set([...(mapping.forcedPushFieldPaths ?? []), conflict.fieldPath])]
+            : mapping.forcedPushFieldPaths ?? [];
+        const [resolved] = await this.db.update(channelCatalogConflicts).set({
+            state: "resolved",
+            resolvedBy: requireUserId(actor),
+            updatedAt: new Date(),
+        }).where(and(eq(channelCatalogConflicts.organizationId, orgId), eq(channelCatalogConflicts.id, id), eq(channelCatalogConflicts.state, "open"))).returning();
+        if (!resolved)
+            return PluginErr("Catalog conflict not found or already resolved.", "NOT_FOUND");
+        await this.db.update(channelEntityMap).set({
+            heldFieldPaths,
+            forcedPushFieldPaths,
+            ...(resolutionBaselineAt ? { lastSyncedAt: resolutionBaselineAt } : {}),
+        }).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.id, mapping.id)));
+        await this.db.insert(channelCatalogConflictEvents).values({
+            organizationId: orgId,
+            conflictId: conflict.id,
+            fromState: "open",
+            toState: "resolved",
+            reason: `Operator chose the ${choose} value.`,
+            changedBy: requireUserId(actor),
+        });
+        if (choose === "platform") {
+            await this.jobs.enqueue("channel/push-catalog", {
+                organizationId: orgId,
+                storeId: conflict.storeId,
+                entityIds: [conflict.entityId],
+            }, {
+                organizationId: orgId,
+                concurrencyKey: catalogPushConcurrencyKey({ storeId: conflict.storeId, entityIds: [conflict.entityId] }),
+                supersedes: true,
+            });
+        }
+        return Ok(resolved);
+    }
+    async applyStoreConflictValue(orgId, conflict, actor) {
+        const [root, segment, field] = conflict.fieldPath.split(".");
+        if (root === "entity" && segment === "slug") {
+            if (typeof conflict.storeValue !== "string")
+                return PluginErr("The stored catalog value is not a valid slug.", "INVALID_CONFLICT_VALUE");
+            const updated = await this.catalog.update(conflict.entityId, { slug: conflict.storeValue }, actor, CHANNEL_CONVERGENCE_CTX);
+            return updated.ok ? Ok(undefined) : PluginErr(updated.error.message);
+        }
+        if (root === "entity" && segment === "status") {
+            if (typeof conflict.storeValue !== "string")
+                return PluginErr("The stored catalog value is not a valid status.", "INVALID_CONFLICT_VALUE");
+            const status = ["draft", "active", "archived", "discontinued"].find((value) => value === conflict.storeValue);
+            if (!status)
+                return PluginErr("The stored catalog value is not a valid status.", "INVALID_CONFLICT_VALUE");
+            const updated = await this.catalog.update(conflict.entityId, { status, isVisible: status === "active" }, actor, CHANNEL_CONVERGENCE_CTX);
+            return updated.ok ? Ok(undefined) : PluginErr(updated.error.message);
+        }
+        if (root === "entity" && segment === "metadata" && field) {
+            const [entity] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, conflict.entityId)));
+            if (!entity)
+                return PluginErr("Catalog entity not found.", "NOT_FOUND");
+            const updated = await this.catalog.update(conflict.entityId, {
+                metadata: { ...(entity.metadata ?? {}), [field]: conflict.storeValue },
+            }, actor, CHANNEL_CONVERGENCE_CTX);
+            return updated.ok ? Ok(undefined) : PluginErr(updated.error.message);
+        }
+        if (root === "attributes" && segment && field && attributeFields.some((attributeField) => attributeField === field)) {
+            const [attribute] = await this.db.select().from(sellableAttributes).where(and(eq(sellableAttributes.entityId, conflict.entityId), eq(sellableAttributes.locale, segment)));
+            const title = attribute?.title ?? "";
+            const attrs = { title };
+            if (field === "title") {
+                if (typeof conflict.storeValue !== "string")
+                    return PluginErr("The stored catalog value is not valid text.", "INVALID_CONFLICT_VALUE");
+                attrs.title = conflict.storeValue;
+            }
+            else if (field === "subtitle") {
+                if (typeof conflict.storeValue !== "string")
+                    return PluginErr("The stored catalog value is not valid text.", "INVALID_CONFLICT_VALUE");
+                attrs.subtitle = conflict.storeValue;
+            }
+            else if (field === "description") {
+                if (typeof conflict.storeValue !== "string")
+                    return PluginErr("The stored catalog value is not valid text.", "INVALID_CONFLICT_VALUE");
+                attrs.description = conflict.storeValue;
+            }
+            else if (field === "richDescription") {
+                attrs.richDescription = conflict.storeValue;
+            }
+            else if (field === "seoTitle") {
+                if (typeof conflict.storeValue !== "string")
+                    return PluginErr("The stored catalog value is not valid text.", "INVALID_CONFLICT_VALUE");
+                attrs.seoTitle = conflict.storeValue;
+            }
+            else if (field === "seoDescription") {
+                if (typeof conflict.storeValue !== "string")
+                    return PluginErr("The stored catalog value is not valid text.", "INVALID_CONFLICT_VALUE");
+                attrs.seoDescription = conflict.storeValue;
+            }
+            const updated = await this.catalog.setAttributes(conflict.entityId, segment, attrs, actor, CHANNEL_CONVERGENCE_CTX);
+            return updated.ok ? Ok(undefined) : PluginErr(updated.error.message);
+        }
+        if (root === "customFields" && segment && field === "en") {
+            const updated = await this.catalog.update(conflict.entityId, { customFields: { [segment]: conflict.storeValue } }, actor, CHANNEL_CONVERGENCE_CTX);
+            return updated.ok ? Ok(undefined) : PluginErr(updated.error.message);
+        }
+        return PluginErr(`Conflict field path "${conflict.fieldPath}" cannot be resolved to the store value.`, "UNSUPPORTED_CONFLICT_FIELD");
+    }
     async syncInventory(orgId, storeId, actor) {
         const store = await this.getStoreRecord(orgId, storeId);
         if (!store || store.status !== "connected")
@@ -447,19 +2278,34 @@ export class ChannelConnectorService {
             return PluginErr("Connected store not found.", "NOT_FOUND");
         const actor = createSystemActor(orgId);
         const data = event.data;
+        let skipped = [];
+        let conflicts = [];
+        let warnings = [];
         if (event.type === "products/update") {
             const productId = String(data.id ?? data.product_id ?? "");
             const mapping = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, productId)));
-            if (mapping[0])
-                await this.convergeCatalogItem(orgId, storeId, mapping[0].entityId, data, actor);
+            if (mapping[0]) {
+                const converged = await this.convergeCatalogItem(orgId, storeId, mapping[0].entityId, data, actor);
+                if (!converged.ok)
+                    return converged;
+                skipped = converged.value.skipped;
+                conflicts = converged.value.conflicts;
+                warnings = converged.value.warnings;
+            }
         }
         else if (event.type === "products/delete") {
             const productId = String(data.id ?? data.product_id ?? "");
             const mapping = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.externalId, productId)));
             if (mapping[0]) {
-                const archived = await this.catalog.archive(mapping[0].entityId, actor);
-                if (!archived.ok)
-                    return PluginErr(archived.error.message);
+                const owners = await this.catalog.resolveFieldOwners(mapping[0].entityId, storeId);
+                if (owners.get("entity.status") === "platform") {
+                    skipped.push({ entityId: mapping[0].entityId, fieldPath: "entity.status" });
+                }
+                else {
+                    const archived = await this.catalog.archive(mapping[0].entityId, actor);
+                    if (!archived.ok)
+                        return PluginErr(archived.error.message);
+                }
             }
         }
         else if (event.type === "inventory_levels/update") {
@@ -513,6 +2359,15 @@ export class ChannelConnectorService {
                 return disconnected;
             return Ok({ processed: true });
         }
+        if (skipped.length > 0 || conflicts.length > 0 || warnings.length > 0) {
+            const report = {
+                ...(store.lastReconcileReport ?? {}),
+                ...(skipped.length > 0 ? { skipped: uniqueSkipped(skipped) } : {}),
+                ...(conflicts.length > 0 ? { conflicts } : {}),
+                ...(warnings.length > 0 ? { warnings } : {}),
+            };
+            await this.db.update(connectedStores).set({ lastReconcileReport: report, updatedAt: new Date() }).where(and(eq(connectedStores.organizationId, orgId), eq(connectedStores.id, storeId)));
+        }
         return Ok({ processed: true });
     }
     complianceEmail(data) {
@@ -571,6 +2426,122 @@ export class ChannelConnectorService {
     }
     async convergeCatalogItem(orgId, storeId, entityId, data, actor) {
         const product = data.product && typeof data.product === "object" ? data.product : data;
+        const remoteMetadata = product.metadata && typeof product.metadata === "object" && !Array.isArray(product.metadata)
+            ? product.metadata
+            : {};
+        const [mapping] = await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), eq(channelEntityMap.entityId, entityId)));
+        const [entity] = await this.db.select().from(sellableEntities).where(and(eq(sellableEntities.organizationId, orgId), eq(sellableEntities.id, entityId)));
+        if (!mapping || !entity)
+            return Ok({ skipped: [], conflicts: [], warnings: [] });
+        const [currentAttribute] = await this.db.select().from(sellableAttributes).where(and(eq(sellableAttributes.entityId, entityId), eq(sellableAttributes.locale, "en")));
+        const title = typeof product.title === "string" ? product.title : currentAttribute?.title ?? entity.slug;
+        const description = product.description !== undefined
+            ? String(product.description)
+            : currentAttribute?.description ?? undefined;
+        const status = typeof product.status === "string" && ["draft", "active", "archived", "discontinued"].includes(product.status)
+            ? product.status
+            : undefined;
+        const customFields = product.customFields && typeof product.customFields === "object" && !Array.isArray(product.customFields)
+            ? product.customFields
+            : undefined;
+        const images = Array.isArray(product.images)
+            ? product.images.flatMap((raw) => {
+                if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                    return [];
+                const image = raw;
+                const role = typeof image.role === "string" ? pushCatalogImageRole(image.role) : undefined;
+                const url = typeof image.url === "string" ? image.url : typeof image.src === "string" ? image.src : undefined;
+                return role && url ? [{ role, url }] : [];
+            })
+            : [];
+        const remoteItem = {
+            externalId: mapping.externalId,
+            slug: typeof product.slug === "string" ? product.slug : entity.slug,
+            title,
+            ...(description !== undefined ? { description } : {}),
+            ...(status !== undefined ? { status } : {}),
+            attributes: [{ locale: "en", title, ...(description !== undefined ? { description } : {}) }],
+            ...(Object.keys(remoteMetadata).length > 0 ? { metadata: remoteMetadata } : {}),
+            ...(customFields !== undefined ? { customFields } : {}),
+            ...(images.length > 0 ? { images } : {}),
+            variants: [],
+        };
+        const fieldPaths = [];
+        if (typeof product.slug === "string")
+            fieldPaths.push("entity.slug");
+        if (status !== undefined)
+            fieldPaths.push("entity.status");
+        for (const key of Object.keys(remoteMetadata)) {
+            const path = `entity.metadata.${key}`;
+            if (isValidFieldPath(path))
+                fieldPaths.push(path);
+        }
+        if (typeof product.title === "string")
+            fieldPaths.push("attributes.en.title");
+        if (product.description !== undefined)
+            fieldPaths.push("attributes.en.description");
+        for (const [name, locales] of Object.entries(customFields ?? {})) {
+            if (!locales || typeof locales !== "object" || Array.isArray(locales))
+                continue;
+            for (const locale of Object.keys(locales)) {
+                const path = `customFields.${name}.${locale}`;
+                if (isValidFieldPath(path))
+                    fieldPaths.push(path);
+            }
+        }
+        for (const image of images)
+            fieldPaths.push(`media.${image.role}`);
+        const ownershipBeforeSeed = await this.catalog.resolveFieldOwners(entityId, storeId);
+        const seedPaths = fieldPaths.filter((path) => !ownershipBeforeSeed.has(path));
+        const seeded = await this.catalog.seedImportedFieldOwnership(entityId, storeId, seedPaths);
+        if (!seeded.ok)
+            return PluginErr(seeded.error.message);
+        for (const path of seedPaths)
+            ownershipBeforeSeed.set(path, "store");
+        const owners = ownershipBeforeSeed;
+        const remoteHash = hash(product);
+        const outboundEcho = this.isOutboundEcho(mapping, remoteItem);
+        const shared = await this.detectSharedConflicts(entityId, storeId, entity, mapping, remoteItem, owners, fieldPaths, remoteHash, outboundEcho ? { certifiedPaths: new Set(mapping.outboundFieldPaths ?? []) } : undefined);
+        const persistedConflicts = await this.persistCatalogConflicts(orgId, shared.conflicts, requireUserId(actor));
+        if (!persistedConflicts.ok)
+            return persistedConflicts;
+        const owned = this.filterOwnedFieldsAtPaths(remoteItem, owners, fieldPaths);
+        const heldPaths = [...new Set([...(mapping.heldFieldPaths ?? []), ...shared.paths])];
+        // Same revocation as the reconcile path: a newly held path cancels any force
+        // left from an earlier resolution, so a webhook-raised conflict cannot be
+        // pre-empted by an operator's answer to a previous one.
+        const survivingForcedPaths = (mapping.forcedPushFieldPaths ?? []).filter((path) => !heldPaths.includes(path));
+        const held = this.filterConflictingFields(owned.writable, heldPaths);
+        const blockedPaths = new Set([
+            ...owned.skipped,
+            ...heldPaths,
+            ...(!fieldPaths.includes("attributes.en.title") ? ["attributes.en.title"] : []),
+        ]);
+        const skipped = owned.skipped.map((fieldPath) => ({ entityId, fieldPath }));
+        const conflicts = shared.conflicts.map(({ platformValue: _platformValue, storeValue: _storeValue, ...conflict }) => conflict);
+        const warnings = conflicts.map((conflict) => `Held shared field conflict for entity "${conflict.entityId}", store "${conflict.storeId}", field "${conflict.fieldPath}" (local ${conflict.localValueSummary}, remote ${conflict.remoteValueSummary}).`);
+        const writable = held.writable;
+        const updateInput = {};
+        if (fieldPaths.includes("entity.slug") && ownerAllows(owners, "entity.slug") && !blockedPaths.has("entity.slug") && entity.slug !== writable.slug) {
+            updateInput.slug = writable.slug;
+        }
+        if (Object.keys(writable.metadata ?? {}).length > 0) {
+            const remoteEntityMetadata = mergeMetadata(entity.metadata, writable.metadata ?? {});
+            if (hash(remoteEntityMetadata) !== hash(entity.metadata ?? {}))
+                updateInput.metadata = remoteEntityMetadata;
+        }
+        if (fieldPaths.includes("entity.status") && ownerAllows(owners, "entity.status") && !blockedPaths.has("entity.status") && typeof writable.status === "string" && writable.status !== entity.status) {
+            updateInput.status = writable.status;
+            updateInput.isVisible = writable.status === "active";
+        }
+        if (Object.keys(updateInput).length > 0) {
+            const updated = await this.catalog.update(entityId, updateInput, actor, CHANNEL_CONVERGENCE_CTX);
+            if (!updated.ok)
+                return PluginErr(updated.error.message);
+        }
+        const attributes = await this.setCatalogAttributesIfWritable(entityId, writable, actor, blockedPaths, CHANNEL_CONVERGENCE_CTX);
+        if (!attributes.ok)
+            return attributes;
         const levels = Array.isArray(product.variants) ? product.variants : [];
         for (const variant of levels) {
             const externalId = String(variant.id ?? variant.variation_id ?? "");
@@ -578,6 +2549,15 @@ export class ChannelConnectorService {
             if (externalId && available !== undefined)
                 await this.setMappedInventory(orgId, storeId, externalId, Number(available), actor);
         }
+        const revisionMarkers = await this.catalog.repository.findRevisionMarkers(entityId);
+        const lastSyncedAt = revisionMarkers.at(-1)?.createdAt ?? mapping.lastSyncedAt;
+        await this.db.update(channelEntityMap).set({
+            syncHash: remoteHash,
+            lastSyncedAt,
+            heldFieldPaths: heldPaths,
+            forcedPushFieldPaths: survivingForcedPaths,
+        }).where(eq(channelEntityMap.id, mapping.id));
+        return Ok({ skipped, conflicts, warnings });
     }
     async createRefundRequest(orgId, store, data, actor) {
         const remoteRefundId = String(data.id ?? data.refund_id ?? "");
@@ -613,9 +2593,9 @@ export class ChannelConnectorService {
         const max = this.options.refundAutoMax ?? order.amountCaptured ?? order.grandTotal;
         const ageOk = Date.now() - store.createdAt.getTime() >= (this.options.newStoreDays ?? 7) * 86_400_000;
         const auto = clean && amount > 0 && ageOk && amount <= max;
-        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, state: auto ? "approved" : "requested", approvedBy: auto ? actor.userId : null }).returning();
+        const rows = await this.db.insert(channelRefundRequests).values({ organizationId: orgId, storeId: store.id, orderId, remoteRefundId, amount, state: auto ? "approved" : "requested", approvedBy: auto ? requireUserId(actor) : null }).returning();
         const request = rows[0];
-        await this.db.insert(channelRefundEvents).values({ organizationId: orgId, requestId: request.id, fromState: null, toState: request.state, reason: auto ? "Automatic guarded refund" : "Operator approval required", changedBy: actor.userId });
+        await this.db.insert(channelRefundEvents).values({ organizationId: orgId, requestId: request.id, fromState: null, toState: request.state, reason: auto ? "Automatic guarded refund" : "Operator approval required", changedBy: requireUserId(actor) });
         if (auto) {
             const result = await this.executeRefund(request, refundLines, actor);
             if (!result.ok)
@@ -629,7 +2609,7 @@ export class ChannelConnectorService {
         if (!result.ok)
             return PluginErr(result.error?.message ?? "Refund execution failed.");
         const [updated] = await this.db.update(channelRefundRequests).set({ state: "executed", updatedAt: new Date() }).where(and(eq(channelRefundRequests.organizationId, request.organizationId), eq(channelRefundRequests.id, request.id), eq(channelRefundRequests.state, "approved"))).returning();
-        await this.db.insert(channelRefundEvents).values({ organizationId: request.organizationId, requestId: request.id, fromState: "approved", toState: "executed", reason: "Platform refund executed", changedBy: actor.userId });
+        await this.db.insert(channelRefundEvents).values({ organizationId: request.organizationId, requestId: request.id, fromState: "approved", toState: "executed", reason: "Platform refund executed", changedBy: requireUserId(actor) });
         return Ok(updated);
     }
     async listRefundRequests(orgId) {
@@ -728,7 +2708,7 @@ export class ChannelConnectorService {
         if (created.value.state === "confirmed")
             return created;
         if (created.value.state !== "exported") {
-            const exported = await this.transitionExport(orgId, created.value.id, "exported", actor.userId, "Export attempt started.");
+            const exported = await this.transitionExport(orgId, created.value.id, "exported", requireUserId(actor), "Export attempt started.");
             if (!exported.ok)
                 return exported;
         }
@@ -738,7 +2718,7 @@ export class ChannelConnectorService {
             .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.id, created.value.id)));
         const pushed = await connector.pushOrder(store, slice);
         if (!pushed.ok) {
-            return this.transitionExport(orgId, created.value.id, "failed", actor.userId, pushed.error.message, pushed.error.retriable === true ? "transient" : "definitive");
+            return this.transitionExport(orgId, created.value.id, "failed", requireUserId(actor), pushed.error.message, pushed.error.retriable === true ? "transient" : "definitive");
         }
         await this.db
             .update(channelOrderExports)
@@ -750,13 +2730,13 @@ export class ChannelConnectorService {
             .where(and(eq(channelOrderExports.organizationId, orgId), eq(channelOrderExports.id, created.value.id)));
         const remoteStatus = await connector.fetchOrderStatus(store, pushed.value.remoteOrderId);
         if (!remoteStatus.ok) {
-            return this.transitionExport(orgId, created.value.id, "failed", actor.userId, remoteStatus.error.message, remoteStatus.error.retriable === true ? "transient" : "definitive");
+            return this.transitionExport(orgId, created.value.id, "failed", requireUserId(actor), remoteStatus.error.message, remoteStatus.error.retriable === true ? "transient" : "definitive");
         }
         if (remoteStatus.value.status === "confirmed") {
-            return this.transitionExport(orgId, created.value.id, "confirmed", actor.userId, "Remote order confirmed.");
+            return this.transitionExport(orgId, created.value.id, "confirmed", requireUserId(actor), "Remote order confirmed.");
         }
         if (remoteStatus.value.status === "failed" || remoteStatus.value.status === "cancelled") {
-            return this.transitionExport(orgId, created.value.id, "failed", actor.userId, `Remote order status: ${remoteStatus.value.status}.`);
+            return this.transitionExport(orgId, created.value.id, "failed", requireUserId(actor), `Remote order status: ${remoteStatus.value.status}.`);
         }
         const refreshed = await this.getExport(orgId, created.value.id);
         return refreshed;
@@ -845,4 +2825,347 @@ export class ChannelConnectorService {
     abandonExport(orgId, exportId, changedBy, reason) {
         return this.transitionExport(orgId, exportId, "abandoned", changedBy, reason);
     }
+    async resolveCatalogPushEntityIds(orgId, storeId, entityIds) {
+        if (entityIds !== undefined)
+            return [...new Set(entityIds)].sort();
+        const mappings = await this.db.select({ entityId: channelEntityMap.entityId }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity")));
+        return [...new Set(mappings.map((mapping) => mapping.entityId))].sort();
+    }
+    async createCatalogPush(orgId, storeId, entityId) {
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store || store.status !== "connected") {
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        }
+        const rows = await this.db
+            .insert(channelCatalogPushes)
+            .values({ organizationId: orgId, storeId, entityId })
+            .onConflictDoNothing({ target: [channelCatalogPushes.storeId, channelCatalogPushes.entityId] })
+            .returning();
+        if (rows[0])
+            return Ok(rows[0]);
+        const existing = await this.db
+            .select()
+            .from(channelCatalogPushes)
+            .where(and(eq(channelCatalogPushes.organizationId, orgId), eq(channelCatalogPushes.storeId, storeId), eq(channelCatalogPushes.entityId, entityId)));
+        if (!existing[0])
+            return PluginErr("Failed to create channel catalog push.");
+        return Ok(existing[0]);
+    }
+    async transitionCatalogPush(orgId, pushId, toState, changedBy, reason, failureKind, payloadSnapshot) {
+        return this.transact(async (tx) => {
+            const currentRows = await tx
+                .select()
+                .from(channelCatalogPushes)
+                .where(and(eq(channelCatalogPushes.organizationId, orgId), eq(channelCatalogPushes.id, pushId)));
+            const current = currentRows[0];
+            if (!current)
+                return PluginErr("Channel catalog push not found.", "NOT_FOUND");
+            if (!canCatalogPushTransition(current.state, toState)) {
+                const error = new CommerceInvalidTransitionError(`Cannot transition channel catalog push from ${current.state} to ${toState}.`);
+                return PluginErr(error.message, error.code);
+            }
+            const updatedRows = await tx
+                .update(channelCatalogPushes)
+                .set({
+                state: toState,
+                updatedAt: new Date(),
+                ...(payloadSnapshot !== undefined ? { payloadSnapshot } : {}),
+                ...(toState === "exported" ? { attempts: current.attempts + 1, lastError: null, failureKind: null } : {}),
+                ...(toState === "failed" ? { lastError: reason ?? "Catalog push failed." } : {}),
+                ...(toState === "failed" ? { failureKind: failureKind ?? "definitive" } : {}),
+                ...(toState === "confirmed" ? { lastError: null, failureKind: null } : {}),
+            })
+                .where(and(eq(channelCatalogPushes.organizationId, orgId), eq(channelCatalogPushes.id, pushId), eq(channelCatalogPushes.state, current.state)))
+                .returning();
+            const updated = updatedRows[0];
+            if (!updated)
+                return PluginErr("Channel catalog push changed concurrently.", "CONFLICT");
+            await tx.insert(channelCatalogPushEvents).values({
+                organizationId: orgId,
+                pushId,
+                fromState: current.state,
+                toState,
+                reason: reason ?? null,
+                changedBy,
+            });
+            return Ok(updated);
+        });
+    }
+    async recordCatalogPushRevisions(orgId, entityIds, actor) {
+        if (entityIds.length === 0)
+            return Ok(undefined);
+        try {
+            await this.transact(async (tx) => {
+                const txContext = createTxContext(tx, { actor });
+                for (const entityId of [...new Set(entityIds)]) {
+                    const revision = await this.catalog.recordEntityRevision(entityId, actor, "push", txContext);
+                    if (!revision.ok)
+                        throw new Error(revision.error.message);
+                }
+            });
+        }
+        catch (error) {
+            return PluginErr(error instanceof Error ? error.message : "Failed to record catalog push revisions.");
+        }
+        return Ok(undefined);
+    }
+    async executeCatalogPushJob(orgId, storeId, options, actor, runtime) {
+        const store = await this.getStoreRecord(orgId, storeId);
+        if (!store || store.status !== "connected")
+            return PluginErr("Connected store not found.", "NOT_FOUND");
+        if (!store.catalogWriteEnabled)
+            return Ok({ noop: true });
+        const connector = this.connectors.get(store.provider);
+        if (!connector?.pushCatalog)
+            return Ok({ noop: true });
+        if (isCatalogPushBreakerOpen(store.breakerState)) {
+            await runtime.jobs.enqueue("channel/push-catalog", {
+                organizationId: orgId,
+                storeId,
+                ...(options.entityIds ? { entityIds: options.entityIds } : {}),
+                ...(options.forceFieldPaths ? { forceFieldPaths: options.forceFieldPaths } : {}),
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+            }, {
+                organizationId: orgId,
+                concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: options.entityIds }),
+                supersedes: false,
+                delayMs: CATALOG_PUSH_BREAKER_RETRY_MS,
+            });
+            return Ok({ rescheduled: true });
+        }
+        const allEntityIds = await this.resolveCatalogPushEntityIds(orgId, storeId, options.entityIds);
+        const batchSize = catalogPushBatchSize(store.provider);
+        const pageEntityIds = options.cursor
+            ? allEntityIds.filter((entityId) => entityId > options.cursor).slice(0, batchSize)
+            : allEntityIds.slice(0, batchSize);
+        if (pageEntityIds.length === 0)
+            return Ok({ complete: true, pushed: 0, failed: 0 });
+        // Abandoned is terminal: a row that exhausted its attempts stays out of
+        // every later sweep until an operator re-arms it.
+        const abandonedRows = await this.db.select({ entityId: channelCatalogPushes.entityId }).from(channelCatalogPushes).where(and(eq(channelCatalogPushes.organizationId, orgId), eq(channelCatalogPushes.storeId, storeId), eq(channelCatalogPushes.state, "abandoned"), inArray(channelCatalogPushes.entityId, pageEntityIds)));
+        const abandonedEntityIds = new Set(abandonedRows.map((row) => row.entityId));
+        const batchEntityIds = pageEntityIds.filter((entityId) => !abandonedEntityIds.has(entityId));
+        if (batchEntityIds.length === 0) {
+            const batchCursor = pageEntityIds[pageEntityIds.length - 1];
+            const hasMore = allEntityIds.some((entityId) => entityId > batchCursor);
+            if (!hasMore)
+                return Ok({ complete: true, pushed: 0, failed: 0 });
+            await runtime.jobs.enqueue("channel/push-catalog", {
+                organizationId: orgId,
+                storeId,
+                ...(options.entityIds ? { entityIds: options.entityIds } : {}),
+                ...(options.forceFieldPaths ? { forceFieldPaths: options.forceFieldPaths } : {}),
+                cursor: batchCursor,
+            }, {
+                organizationId: orgId,
+                concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: options.entityIds }),
+                supersedes: false,
+            });
+            return Ok({ complete: false, cursor: batchCursor, pushed: 0, failed: 0 });
+        }
+        const assembled = await this.buildCatalogPushItems(orgId, storeId, batchEntityIds, {
+            ...(options.forceFieldPaths ? { forceFieldPaths: options.forceFieldPaths } : {}),
+        });
+        if (!assembled.ok)
+            return assembled;
+        const mappings = await this.db.select({
+            entityId: channelEntityMap.entityId,
+            externalId: channelEntityMap.externalId,
+        }).from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId), eq(channelEntityMap.kind, "entity"), inArray(channelEntityMap.entityId, batchEntityIds)));
+        const externalByEntity = new Map(mappings.map((mapping) => [mapping.entityId, mapping.externalId]));
+        const entityByExternal = new Map(mappings.map((mapping) => [mapping.externalId, mapping.entityId]));
+        const itemByExternal = new Map(assembled.value.items.map((item) => [item.externalId, item]));
+        let pushed = 0;
+        let failed = 0;
+        if (assembled.value.items.length === 0) {
+            for (const entityId of batchEntityIds) {
+                const created = await this.createCatalogPush(orgId, storeId, entityId);
+                if (!created.ok)
+                    return created;
+                if (created.value.state === "confirmed" || created.value.state === "abandoned") {
+                    if (created.value.state === "confirmed")
+                        pushed += 1;
+                    continue;
+                }
+                const confirmed = await this.transitionCatalogPush(orgId, created.value.id, "confirmed", requireUserId(actor), "No platform-owned fields to push.", undefined, null);
+                if (!confirmed.ok)
+                    return confirmed;
+                pushed += 1;
+            }
+        }
+        else {
+            const pushIds = new Map();
+            const pushAttempts = new Map();
+            for (const entityId of batchEntityIds) {
+                const externalId = externalByEntity.get(entityId);
+                const item = externalId ? itemByExternal.get(externalId) : undefined;
+                if (!item)
+                    continue;
+                const created = await this.createCatalogPush(orgId, storeId, entityId);
+                if (!created.ok)
+                    return created;
+                pushIds.set(item.externalId, created.value.id);
+                pushAttempts.set(item.externalId, created.value.attempts);
+                if (created.value.state === "pending" || created.value.state === "confirmed" || created.value.state === "failed") {
+                    const exported = await this.transitionCatalogPush(orgId, created.value.id, "exported", requireUserId(actor), "Catalog push attempt started.", undefined, item);
+                    if (!exported.ok)
+                        return exported;
+                    pushAttempts.set(item.externalId, exported.value.attempts);
+                }
+            }
+            const items = assembled.value.items;
+            const writeAhead = await this.recordOutboundPush(orgId, storeId, items.map((item) => ({ externalId: item.externalId, ok: true })), items, "write-ahead");
+            if (!writeAhead.ok)
+                return writeAhead;
+            let result;
+            try {
+                result = await connector.pushCatalog(store, items);
+            }
+            catch (error) {
+                const connectorError = {
+                    code: "CATALOG_PUSH_THROWN",
+                    message: error instanceof Error ? error.message : "Catalog push failed.",
+                };
+                const cleared = await this.recordOutboundPush(orgId, storeId, items.map((item) => ({ externalId: item.externalId, ok: false, error: connectorError })), items);
+                if (!cleared.ok)
+                    return cleared;
+                for (const item of items) {
+                    const pushId = pushIds.get(item.externalId);
+                    if (!pushId)
+                        continue;
+                    const attempts = pushAttempts.get(item.externalId) ?? 0;
+                    if (attempts >= CATALOG_PUSH_MAX_ATTEMPTS) {
+                        await this.transitionCatalogPush(orgId, pushId, "abandoned", requireUserId(actor), connectorError.message);
+                    }
+                    else {
+                        await this.transitionCatalogPush(orgId, pushId, "failed", requireUserId(actor), connectorError.message, "transient");
+                    }
+                    failed += 1;
+                }
+                const maxAttempts = Math.max(0, ...items.map((item) => pushAttempts.get(item.externalId) ?? 0));
+                if (maxAttempts < CATALOG_PUSH_MAX_ATTEMPTS) {
+                    await runtime.jobs.enqueue("channel/push-catalog", {
+                        organizationId: orgId,
+                        storeId,
+                        ...(options.entityIds ? { entityIds: options.entityIds } : {}),
+                        ...(options.forceFieldPaths ? { forceFieldPaths: options.forceFieldPaths } : {}),
+                        ...(options.cursor ? { cursor: options.cursor } : {}),
+                    }, {
+                        organizationId: orgId,
+                        concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: options.entityIds }),
+                        supersedes: false,
+                        delayMs: catalogPushRetryDelayMs(maxAttempts),
+                    });
+                }
+                return Ok({ rescheduled: true, pushed, failed });
+            }
+            if (!result.ok) {
+                const cleared = await this.recordOutboundPush(orgId, storeId, items.map((item) => ({ externalId: item.externalId, ok: false, error: result.error })), items);
+                if (!cleared.ok)
+                    return cleared;
+                for (const item of items) {
+                    const pushId = pushIds.get(item.externalId);
+                    if (!pushId)
+                        continue;
+                    const attempts = pushAttempts.get(item.externalId) ?? 0;
+                    const failureKind = result.error.retriable === true ? "transient" : "definitive";
+                    if (failureKind === "transient" && attempts >= CATALOG_PUSH_MAX_ATTEMPTS) {
+                        await this.transitionCatalogPush(orgId, pushId, "abandoned", requireUserId(actor), result.error.message);
+                    }
+                    else {
+                        await this.transitionCatalogPush(orgId, pushId, "failed", requireUserId(actor), result.error.message, failureKind);
+                    }
+                    failed += 1;
+                }
+                if (result.error.retriable === true) {
+                    const maxAttempts = Math.max(0, ...items.map((item) => pushAttempts.get(item.externalId) ?? 0));
+                    if (maxAttempts < CATALOG_PUSH_MAX_ATTEMPTS) {
+                        await runtime.jobs.enqueue("channel/push-catalog", {
+                            organizationId: orgId,
+                            storeId,
+                            ...(options.entityIds ? { entityIds: options.entityIds } : {}),
+                            ...(options.forceFieldPaths ? { forceFieldPaths: options.forceFieldPaths } : {}),
+                            ...(options.cursor ? { cursor: options.cursor } : {}),
+                        }, {
+                            organizationId: orgId,
+                            concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: options.entityIds }),
+                            supersedes: false,
+                            delayMs: catalogPushRetryDelayMs(maxAttempts),
+                        });
+                    }
+                    return Ok({ rescheduled: true, pushed, failed });
+                }
+                const batchCursor = pageEntityIds[pageEntityIds.length - 1];
+                const hasMore = allEntityIds.some((entityId) => entityId > batchCursor);
+                return Ok({ complete: !hasMore, pushed, failed });
+            }
+            const recorded = await this.recordOutboundPush(orgId, storeId, result.value.outcomes, items);
+            if (!recorded.ok)
+                return recorded;
+            const successfulEntityIds = [];
+            for (const outcome of result.value.outcomes) {
+                const pushId = pushIds.get(outcome.externalId);
+                const entityId = entityByExternal.get(outcome.externalId);
+                if (!pushId || !entityId)
+                    continue;
+                const item = itemByExternal.get(outcome.externalId);
+                if (outcome.ok) {
+                    const confirmed = await this.transitionCatalogPush(orgId, pushId, "confirmed", requireUserId(actor), "Remote catalog confirmed item.", undefined, item ?? null);
+                    if (!confirmed.ok)
+                        return confirmed;
+                    successfulEntityIds.push(entityId);
+                    pushed += 1;
+                    continue;
+                }
+                const failureKind = outcome.error?.retriable === true ? "transient" : "definitive";
+                const attempts = pushAttempts.get(outcome.externalId) ?? 0;
+                if (failureKind === "transient" && attempts >= CATALOG_PUSH_MAX_ATTEMPTS) {
+                    const abandoned = await this.transitionCatalogPush(orgId, pushId, "abandoned", requireUserId(actor), outcome.error?.message ?? "Catalog push failed.", undefined, item ?? null);
+                    if (!abandoned.ok)
+                        return abandoned;
+                }
+                else {
+                    const failedPush = await this.transitionCatalogPush(orgId, pushId, "failed", requireUserId(actor), outcome.error?.message ?? "Catalog push failed.", failureKind, item ?? null);
+                    if (!failedPush.ok)
+                        return failedPush;
+                    if (failureKind === "transient") {
+                        await runtime.jobs.enqueue("channel/push-catalog", {
+                            organizationId: orgId,
+                            storeId,
+                            entityIds: [entityId],
+                            ...(options.forceFieldPaths?.[entityId]
+                                ? { forceFieldPaths: { [entityId]: options.forceFieldPaths[entityId] } }
+                                : {}),
+                        }, {
+                            organizationId: orgId,
+                            concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: [entityId] }),
+                            supersedes: true,
+                            delayMs: catalogPushRetryDelayMs(attempts),
+                        });
+                    }
+                }
+                failed += 1;
+            }
+            const revisions = await this.recordCatalogPushRevisions(orgId, successfulEntityIds, actor);
+            if (!revisions.ok)
+                return revisions;
+        }
+        const batchCursor = pageEntityIds[pageEntityIds.length - 1];
+        const hasMore = allEntityIds.some((entityId) => entityId > batchCursor);
+        if (hasMore) {
+            await runtime.jobs.enqueue("channel/push-catalog", {
+                organizationId: orgId,
+                storeId,
+                ...(options.entityIds ? { entityIds: options.entityIds } : {}),
+                ...(options.forceFieldPaths ? { forceFieldPaths: options.forceFieldPaths } : {}),
+                cursor: batchCursor,
+            }, {
+                organizationId: orgId,
+                concurrencyKey: catalogPushConcurrencyKey({ storeId, entityIds: options.entityIds }),
+                supersedes: false,
+            });
+            return Ok({ complete: false, cursor: batchCursor, pushed, failed });
+        }
+        return Ok({ complete: true, pushed, failed });
+    }
 }