@porulle/core 0.54.0 → 0.55.0

package/dist/modules/catalog/service.js

@@ -204,6 +204,9 @@ export class CatalogServiceImpl {
             requestId: ctx.requestId,
         }, ctx);
     }
+    notifyEntityChanged(entityId, changedFieldPaths, actor, ctx) {
+        return this.entities.notifyEntityUpdated(entityId, changedFieldPaths, actor, ctx);
+    }
     async recordEntityRevision(entityId, actor, reason = "update", ctx) {
         try {
             return await this.withMutation(actor, ctx, async (txCtx) => {
@@ -567,17 +570,27 @@ export class CatalogServiceImpl {
     addToCategory(entityId, categoryId, actor, ctx) {
         return this.withMutationResult(actor, ctx, async (txCtx) => {
             const result = await this.categories.addToCategory(entityId, categoryId, actor, txCtx);
-            if (result.ok)
-                await this.captureRevision(entityId, actor, "update", txCtx);
-            return result;
+            if (!result.ok)
+                return result;
+            // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+            // is already linked moves nothing.
+            if (result.value)
+                await this.entities.notifyEntityUpdated(entityId, ["categories"], actor, txCtx);
+            await this.captureRevision(entityId, actor, "update", txCtx);
+            return Ok(undefined);
         });
     }
     removeFromCategory(entityId, categoryId, actor, ctx) {
         return this.withMutationResult(actor, ctx, async (txCtx) => {
             const result = await this.categories.removeFromCategory(entityId, categoryId, actor, txCtx);
-            if (result.ok)
-                await this.captureRevision(entityId, actor, "update", txCtx);
-            return result;
+            if (!result.ok)
+                return result;
+            // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+            // is already linked moves nothing.
+            if (result.value)
+                await this.entities.notifyEntityUpdated(entityId, ["categories"], actor, txCtx);
+            await this.captureRevision(entityId, actor, "update", txCtx);
+            return Ok(undefined);
         });
     }
     listBrands(ctx) {
@@ -595,17 +608,27 @@ export class CatalogServiceImpl {
     addToBrand(entityId, brandId, actor, ctx) {
         return this.withMutationResult(actor, ctx, async (txCtx) => {
             const result = await this.brands.addToBrand(entityId, brandId, actor, txCtx);
-            if (result.ok)
-                await this.captureRevision(entityId, actor, "update", txCtx);
-            return result;
+            if (!result.ok)
+                return result;
+            // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+            // is already linked moves nothing.
+            if (result.value)
+                await this.entities.notifyEntityUpdated(entityId, ["brand"], actor, txCtx);
+            await this.captureRevision(entityId, actor, "update", txCtx);
+            return Ok(undefined);
         });
     }
     removeFromBrand(entityId, brandId, actor, ctx) {
         return this.withMutationResult(actor, ctx, async (txCtx) => {
             const result = await this.brands.removeFromBrand(entityId, brandId, actor, txCtx);
-            if (result.ok)
-                await this.captureRevision(entityId, actor, "update", txCtx);
-            return result;
+            if (!result.ok)
+                return result;
+            // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+            // is already linked moves nothing.
+            if (result.value)
+                await this.entities.notifyEntityUpdated(entityId, ["brand"], actor, txCtx);
+            await this.captureRevision(entityId, actor, "update", txCtx);
+            return Ok(undefined);
         });
     }
     createOptionType(input, actor, ctx) {

package/dist/modules/media/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/media/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/media/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/media/service.js

@@ -181,6 +181,9 @@ export class MediaService {
                     throw new Error("Catalog service is required for media revision capture.");
                 }
                 const catalogService = catalog;
+                // A new attachment versions the entity: the hero drives the image embedding, so a consumer
+                // that versions on `updated_at` must see it.
+                await catalogService.notifyEntityChanged(input.entityId, [`media.${input.role}`], actor ?? txCtx.actor, txCtx);
                 const revision = await catalogService.recordEntityRevision(input.entityId, actor ?? txCtx.actor, "update", txCtx);
                 if (!revision.ok)
                     throw revision.error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/core",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/index.ts

@@ -227,6 +227,8 @@ export type {
   ImportProductsReport,
   ImportRowFailureCode,
 } from "./modules/catalog/import-service.js";
+export { writeEntityLinks, linkFieldPaths } from "./modules/catalog/entity-links.js";
+export type { EntityLinkRows, EntityMediaRole, WrittenEntityLinks } from "./modules/catalog/entity-links.js";
 export type {
   TxContext,
   WithTransactionOptions,

package/src/modules/catalog/brand-service.ts

@@ -70,7 +70,7 @@ export class BrandService {
     return Ok(undefined);
   }
 
-  async addToBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  async addToBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<boolean>> {
     try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
     const entity = await this.deps.repository.findEntityById(entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
@@ -82,11 +82,11 @@ export class BrandService {
     if (!brand) {
       brand = await this.repo.createBrand({ organizationId: addBrandOrgId, slug: brandId, displayName: brandId, metadata: {} }, ctx);
     }
-    await this.repo.addEntityToBrand(entityId, brand.id, 0, ctx);
-    return Ok(undefined);
+    const added = await this.repo.addEntityToBrand(entityId, brand.id, 0, ctx);
+    return Ok(added);
   }
 
-  async removeFromBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  async removeFromBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<boolean>> {
     try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
     const entity = await this.deps.repository.findEntityById(entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
@@ -96,6 +96,6 @@ export class BrandService {
     if (!brand) brand = await this.repo.findBrandBySlug(resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config), brandId, ctx);
     const removed = await this.repo.removeEntityFromBrand(entityId, brand?.id ?? brandId, ctx);
     if (!removed) return Err(new CommerceNotFoundError("Brand assignment not found."));
-    return Ok(undefined);
+    return Ok(true);
   }
 }

package/src/modules/catalog/category-service.ts

@@ -93,7 +93,7 @@ export class CategoryService {
     return Ok(undefined);
   }
 
-  async addToCategory(entityId: string, categoryId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  async addToCategory(entityId: string, categoryId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<boolean>> {
     try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
     const entity = await this.deps.repository.findEntityById(entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
@@ -105,11 +105,11 @@ export class CategoryService {
     if (!category) {
       category = await this.repo.createCategory({ organizationId: addCatOrgId, slug: categoryId, sortOrder: 0, metadata: {} }, ctx);
     }
-    await this.repo.addEntityToCategory(entityId, category.id, 0, ctx);
-    return Ok(undefined);
+    const added = await this.repo.addEntityToCategory(entityId, category.id, 0, ctx);
+    return Ok(added);
   }
 
-  async removeFromCategory(entityId: string, categoryId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  async removeFromCategory(entityId: string, categoryId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<boolean>> {
     try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
     const entity = await this.deps.repository.findEntityById(entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
@@ -119,6 +119,6 @@ export class CategoryService {
     if (!category) category = await this.repo.findCategoryBySlug(resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config), categoryId, ctx);
     const removed = await this.repo.removeEntityFromCategory(entityId, category?.id ?? categoryId, ctx);
     if (!removed) return Err(new CommerceNotFoundError("Category assignment not found."));
-    return Ok(undefined);
+    return Ok(true);
   }
 }

package/src/modules/catalog/entity-links.ts

@@ -0,0 +1,114 @@
+import { and, eq, isNull, ne, or, sql, type SQL } from "drizzle-orm";
+import type { PluginDb } from "../../kernel/database/plugin-types.js";
+import { mediaAssets, entityMedia } from "../media/schema.js";
+import { brands, categories, entityBrands, entityCategories, entityTags, sellableEntities, tags } from "./schema.js";
+
+/**
+ * THE writer of an entity's link rows — categories, brand, tags, media — for the bulk paths: the
+ * page import (`importProducts`) and the channel converge, both of which write links directly
+ * rather than one service call per link.
+ *
+ * - One statement per link class, however many entities the rows span.
+ * - Org scope is enforced IN the statement: a row whose entity, or whose category / brand / tag /
+ *   media asset, belongs to another organization matches nothing and is not written. Callers
+ *   resolve ids within their org already; this makes a slip a no-write instead of a cross-org link.
+ * - Idempotent: a link that already exists is not rewritten and is not returned. What comes back
+ *   is exactly what changed, which is what a caller versions the entity from (`linkFieldPaths`).
+ */
+export type EntityMediaRole = (typeof entityMedia.$inferInsert)["role"];
+
+export interface EntityLinkRows {
+  categories?: ReadonlyArray<{ entityId: string; categoryId: string; sortOrder: number }>;
+  brands?: ReadonlyArray<{ entityId: string; brandId: string; sortOrder: number }>;
+  tags?: ReadonlyArray<{ entityId: string; tagId: string }>;
+  /** New media links. */
+  media?: ReadonlyArray<{ entityId: string; variantId: string | null; mediaAssetId: string; role: EntityMediaRole; sortOrder: number }>;
+  /** Existing media links whose role or sort order should become these; unchanged ones write nothing. */
+  mediaPlacements?: ReadonlyArray<{ entityId: string; variantId: string | null; mediaAssetId: string; role: EntityMediaRole; sortOrder: number }>;
+}
+
+export interface WrittenEntityLinks {
+  categories: Array<typeof entityCategories.$inferSelect>;
+  brands: Array<typeof entityBrands.$inferSelect>;
+  tags: Array<typeof entityTags.$inferSelect>;
+  media: Array<typeof entityMedia.$inferSelect>;
+  placed: Array<typeof entityMedia.$inferSelect>;
+}
+
+const valuesOf = (rows: ReadonlyArray<readonly SQL[]>): SQL =>
+  sql.join(rows.map((row) => sql`(${sql.join([...row], sql`, `)})`), sql`, `);
+
+const entityInOrg = (orgId: string): SQL =>
+  sql`join ${sellableEntities} on ${sellableEntities.id} = v.entity_id and ${sellableEntities.organizationId} = ${orgId}`;
+
+export async function writeEntityLinks(
+  db: Pick<PluginDb, "insert" | "update">,
+  orgId: string,
+  rows: EntityLinkRows,
+): Promise<WrittenEntityLinks> {
+  const written: WrittenEntityLinks = { categories: [], brands: [], tags: [], media: [], placed: [] };
+  if (rows.categories?.length) {
+    written.categories = await db.insert(entityCategories).select(sql`
+      select v.entity_id, v.category_id, v.sort_order
+      from (values ${valuesOf(rows.categories.map((row) => [sql`${row.entityId}::uuid`, sql`${row.categoryId}::uuid`, sql`${row.sortOrder}::integer`]))})
+        as v(entity_id, category_id, sort_order)
+      join ${categories} on ${categories.id} = v.category_id and ${categories.organizationId} = ${orgId}
+      ${entityInOrg(orgId)}`).onConflictDoNothing().returning();
+  }
+  if (rows.brands?.length) {
+    written.brands = await db.insert(entityBrands).select(sql`
+      select v.entity_id, v.brand_id, v.sort_order
+      from (values ${valuesOf(rows.brands.map((row) => [sql`${row.entityId}::uuid`, sql`${row.brandId}::uuid`, sql`${row.sortOrder}::integer`]))})
+        as v(entity_id, brand_id, sort_order)
+      join ${brands} on ${brands.id} = v.brand_id and ${brands.organizationId} = ${orgId}
+      ${entityInOrg(orgId)}`).onConflictDoNothing().returning();
+  }
+  if (rows.tags?.length) {
+    written.tags = await db.insert(entityTags).select(sql`
+      select v.entity_id, v.tag_id
+      from (values ${valuesOf(rows.tags.map((row) => [sql`${row.entityId}::uuid`, sql`${row.tagId}::uuid`]))})
+        as v(entity_id, tag_id)
+      join ${tags} on ${tags.id} = v.tag_id and ${tags.organizationId} = ${orgId}
+      ${entityInOrg(orgId)}`).onConflictDoNothing().returning();
+  }
+  if (rows.media?.length) {
+    written.media = await db.insert(entityMedia).select(sql`
+      select v.entity_id, v.variant_id, v.media_asset_id, v.role, v.sort_order, now()
+      from (values ${valuesOf(rows.media.map((row) => [
+        sql`${row.entityId}::uuid`, sql`${row.variantId}::uuid`, sql`${row.mediaAssetId}::uuid`, sql`${row.role}::text`, sql`${row.sortOrder}::integer`,
+      ]))}) as v(entity_id, variant_id, media_asset_id, role, sort_order)
+      join ${mediaAssets} on ${mediaAssets.id} = v.media_asset_id and ${mediaAssets.organizationId} = ${orgId}
+      ${entityInOrg(orgId)}`).onConflictDoNothing().returning();
+  }
+  // ponytail: one UPDATE per re-placed link; a role/sort change upstream is rare, batch it if a
+  // store ever reshuffles whole galleries on every sync.
+  for (const row of rows.mediaPlacements ?? []) {
+    written.placed.push(...await db.update(entityMedia).set({ role: row.role, sortOrder: row.sortOrder }).where(and(
+      eq(entityMedia.entityId, row.entityId),
+      eq(entityMedia.mediaAssetId, row.mediaAssetId),
+      row.variantId === null ? isNull(entityMedia.variantId) : eq(entityMedia.variantId, row.variantId),
+      or(ne(entityMedia.role, row.role), ne(entityMedia.sortOrder, row.sortOrder)),
+      sql`exists (select 1 from ${sellableEntities} where ${sellableEntities.id} = ${entityMedia.entityId} and ${sellableEntities.organizationId} = ${orgId})`,
+    )).returning());
+  }
+  return written;
+}
+
+/**
+ * The field paths each entity's written links changed, sorted — the names the catalog services
+ * version links under (`categories`, `brand`, `tags`, `media.<role>`), so a consumer sees the same
+ * paths whichever path wrote the link.
+ */
+export function linkFieldPaths(written: WrittenEntityLinks): Map<string, string[]> {
+  const byEntity = new Map<string, Set<string>>();
+  const add = (entityId: string, path: string) => {
+    const paths = byEntity.get(entityId) ?? new Set<string>();
+    paths.add(path);
+    byEntity.set(entityId, paths);
+  };
+  for (const row of written.categories) add(row.entityId, "categories");
+  for (const row of written.brands) add(row.entityId, "brand");
+  for (const row of written.tags) add(row.entityId, "tags");
+  for (const row of [...written.media, ...written.placed]) add(row.entityId, `media.${row.role}`);
+  return new Map([...byEntity].map(([entityId, paths]) => [entityId, [...paths].sort()]));
+}

package/src/modules/catalog/import-service.ts

@@ -9,13 +9,11 @@ import { createTxContext, isWriteContextTransactional, resolveWriteContextHookCo
 import { runAfterHooks } from "../../kernel/hooks/executor.js";
 import type { AfterHook } from "../../kernel/hooks/types.js";
 import { isValidFieldPath, type FieldPath } from "./ownership.js";
+import { writeEntityLinks } from "./entity-links.js";
 import {
   brands,
   categories,
   catalogFieldOwnership,
-  entityBrands,
-  entityCategories,
-  entityTags,
   optionTypes,
   optionValues,
   sellableAttributes,
@@ -137,7 +135,7 @@ export interface ImportProductsReport extends Record<string, unknown> {
   rows: ImportProductRowResult[];
 }
 
-type Writer = Pick<PluginDb, "insert" | "select">;
+type Writer = Pick<PluginDb, "insert" | "select" | "update">;
 
 /** The drizzle handle a transaction context carries (typed `unknown` on the context). */
 const writerOf = (txCtx: TxContext): PluginDb => txCtx.tx as PluginDb;
@@ -391,7 +389,6 @@ async function writeItem(
     if (priceRows.length > 0) await sp.insert(prices).values(priceRows);
   }
 
-  const categoryLinks: Row[] = [];
   const categoryInputs = [...new Set(item.categories ?? [])].flatMap((slug, index) => {
     const category = taxonomy.categories.get(slug);
     if (!category) throw new Error(`Category "${slug}" was not resolved for the page.`);
@@ -401,20 +398,18 @@ async function writeItem(
     }
     return [{ entityId, categoryId: category.id, sortOrder: index }];
   });
-  if (categoryInputs.length > 0) categoryLinks.push(...asRows(await sp.insert(entityCategories).values(categoryInputs).returning()));
-  const brandLinks: Row[] = [];
-  if (item.brand) {
-    const brandId = taxonomy.brands.get(item.brand);
-    if (brandId === undefined) throw new Error(`Brand "${item.brand}" was not resolved for the page.`);
-    brandLinks.push(...asRows(await sp.insert(entityBrands).values([{ entityId, brandId, sortOrder: 0 }]).returning()));
-  }
-  const tagLinks: Row[] = [];
+  const brandId = item.brand ? taxonomy.brands.get(item.brand) : undefined;
+  if (item.brand && brandId === undefined) throw new Error(`Brand "${item.brand}" was not resolved for the page.`);
   const tagInputs = [...new Set(item.tags ?? [])].map((slug) => {
     const tagId = taxonomy.tags.get(slug);
     if (tagId === undefined) throw new Error(`Tag "${slug}" was not resolved for the page.`);
     return { entityId, tagId };
   });
-  if (tagInputs.length > 0) tagLinks.push(...asRows(await sp.insert(entityTags).values(tagInputs).returning()));
+  const links = await writeEntityLinks(sp, orgId, {
+    categories: categoryInputs,
+    brands: brandId === undefined ? [] : [{ entityId, brandId, sortOrder: 0 }],
+    tags: tagInputs,
+  });
 
   const ownedPaths = [...new Set(item.ownedFieldPaths ?? [])] as FieldPath[];
   if (ownedPaths.length > 0) {
@@ -434,9 +429,9 @@ async function writeItem(
     attributes: asRows(attributeRows).sort((a, b) => String(a.locale).localeCompare(String(b.locale)) || String(a.id).localeCompare(String(b.id))),
     customFields: [],
     media: [],
-    categories: categoryLinks.sort(byKey("categoryId")),
-    brands: brandLinks.sort(byKey("brandId")),
-    tags: tagLinks.sort(byKey("tagId")),
+    categories: asRows(links.categories).sort(byKey("categoryId")),
+    brands: asRows(links.brands).sort(byKey("brandId")),
+    tags: asRows(links.tags).sort(byKey("tagId")),
   };
   return { entityId, variantIds, warnings, snapshot };
 }

package/src/modules/catalog/repository/index.ts

@@ -923,17 +923,20 @@ export class CatalogRepository {
     return rows.map((r) => r.entityId);
   }
 
+  /** True when the link was inserted; false when it already existed. */
   async addEntityToCategory(
     entityId: string,
     categoryId: string,
     sortOrder = 0,
     ctx?: TxContext,
-  ): Promise<void> {
+  ): Promise<boolean> {
     const db = this.getDb(ctx);
-    await db
+    const inserted = await db
       .insert(entityCategories)
       .values({ entityId, categoryId, sortOrder })
-      .onConflictDoNothing();
+      .onConflictDoNothing()
+      .returning({ entityId: entityCategories.entityId });
+    return inserted.length > 0;
   }
 
   async removeEntityFromCategory(
@@ -1079,17 +1082,20 @@ export class CatalogRepository {
     await db.delete(entityTags).where(eq(entityTags.entityId, entityId));
   }
 
+  /** True when the link was inserted; false when it already existed. */
   async addEntityToBrand(
     entityId: string,
     brandId: string,
     sortOrder = 0,
     ctx?: TxContext,
-  ): Promise<void> {
+  ): Promise<boolean> {
     const db = this.getDb(ctx);
-    await db
+    const inserted = await db
       .insert(entityBrands)
       .values({ entityId, brandId, sortOrder })
-      .onConflictDoNothing();
+      .onConflictDoNothing()
+      .returning({ entityId: entityBrands.entityId });
+    return inserted.length > 0;
   }
 
   async removeEntityFromBrand(

package/src/modules/catalog/service.ts

@@ -379,6 +379,16 @@ export interface CatalogService {
     actor: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<{ created: Variant[]; skipped: number }>>;
+  /**
+   * Move the entity's `updated_at` and fire `catalog.afterUpdate` for a change to rows RELATED to
+   * it (links, media) — the versioning contract consumers rely on to re-read a product.
+   */
+  notifyEntityChanged(
+    entityId: string,
+    changedFieldPaths: readonly string[],
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<void>;
   recordEntityRevision(
     entityId: string,
     actor: Actor | null,
@@ -678,6 +688,15 @@ export class CatalogServiceImpl implements CatalogService {
     }, ctx);
   }
 
+  notifyEntityChanged(
+    entityId: string,
+    changedFieldPaths: readonly string[],
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<void> {
+    return this.entities.notifyEntityUpdated(entityId, changedFieldPaths, actor, ctx);
+  }
+
   async recordEntityRevision(
     entityId: string,
     actor: Actor | null,
@@ -1134,16 +1153,24 @@ export class CatalogServiceImpl implements CatalogService {
   addToCategory(entityId: string, categoryId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const result = await this.categories.addToCategory(entityId, categoryId, actor, txCtx);
-      if (result.ok) await this.captureRevision(entityId, actor, "update", txCtx);
-      return result;
+      if (!result.ok) return result;
+      // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+      // is already linked moves nothing.
+      if (result.value) await this.entities.notifyEntityUpdated(entityId, ["categories"], actor, txCtx);
+      await this.captureRevision(entityId, actor, "update", txCtx);
+      return Ok(undefined);
     });
   }
 
   removeFromCategory(entityId: string, categoryId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const result = await this.categories.removeFromCategory(entityId, categoryId, actor, txCtx);
-      if (result.ok) await this.captureRevision(entityId, actor, "update", txCtx);
-      return result;
+      if (!result.ok) return result;
+      // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+      // is already linked moves nothing.
+      if (result.value) await this.entities.notifyEntityUpdated(entityId, ["categories"], actor, txCtx);
+      await this.captureRevision(entityId, actor, "update", txCtx);
+      return Ok(undefined);
     });
   }
 
@@ -1166,16 +1193,24 @@ export class CatalogServiceImpl implements CatalogService {
   addToBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const result = await this.brands.addToBrand(entityId, brandId, actor, txCtx);
-      if (result.ok) await this.captureRevision(entityId, actor, "update", txCtx);
-      return result;
+      if (!result.ok) return result;
+      // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+      // is already linked moves nothing.
+      if (result.value) await this.entities.notifyEntityUpdated(entityId, ["brand"], actor, txCtx);
+      await this.captureRevision(entityId, actor, "update", txCtx);
+      return Ok(undefined);
     });
   }
 
   removeFromBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const result = await this.brands.removeFromBrand(entityId, brandId, actor, txCtx);
-      if (result.ok) await this.captureRevision(entityId, actor, "update", txCtx);
-      return result;
+      if (!result.ok) return result;
+      // A link that actually changed versions the entity (an indexed facet moved); re-linking what
+      // is already linked moves nothing.
+      if (result.value) await this.entities.notifyEntityUpdated(entityId, ["brand"], actor, txCtx);
+      await this.captureRevision(entityId, actor, "update", txCtx);
+      return Ok(undefined);
     });
   }
 

package/src/modules/media/service.ts

@@ -287,6 +287,7 @@ export class MediaService {
           throw new Error("Catalog service is required for media revision capture.");
         }
         const catalogService = catalog as {
+          notifyEntityChanged: (entityId: string, changedFieldPaths: readonly string[], actor: Actor | null, ctx?: TxContext) => Promise<void>;
           recordEntityRevision: (
             entityId: string,
             actor: Actor | null,
@@ -294,6 +295,9 @@ export class MediaService {
             ctx?: TxContext,
           ) => Promise<Result<unknown>>;
         };
+        // A new attachment versions the entity: the hero drives the image embedding, so a consumer
+        // that versions on `updated_at` must see it.
+        await catalogService.notifyEntityChanged(input.entityId, [`media.${input.role}`], actor ?? txCtx.actor, txCtx);
         const revision = await catalogService.recordEntityRevision(input.entityId, actor ?? txCtx.actor, "update", txCtx);
         if (!revision.ok) throw revision.error;
         return Ok(undefined);