@porulle/core 0.10.8 → 0.13.0

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

@@ -1,4 +1,4 @@
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import { assertPermission } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import {
@@ -21,8 +21,12 @@ import type {
 import { Err, Ok, type Result } from "../../kernel/result.js";
 import { createLogger } from "../../utils/logger.js";
 import { paginate } from "../../utils/pagination.js";
+import type { JobsAdapter } from "../../kernel/jobs/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
-import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogWriteContext, TxContext } from "../../kernel/database/tx-context.js";
+import { isWriteContextTransactional } from "../../kernel/database/tx-context.js";
+import { canReadUnpublishedCatalog, isCatalogEntityVisible } from "./read-policy.js";
+import { isValidFieldPath } from "./ownership.js";
 import type {
   CatalogServiceDeps,
   CatalogEntityHydrated,
@@ -36,6 +40,7 @@ import type {
   CreateOptionTypeInput,
   CreateOptionValueInput,
   CreateVariantInput,
+  EntityFieldDefinitionResolver,
 } from "./service.js";
 import type {
   SellableEntity,
@@ -51,6 +56,26 @@ function hookDatabaseArg(database: CatalogServiceDeps["database"]): { database:
   return { database: { db: database.db as PluginDb } };
 }
 
+const attributeFields = ["title", "subtitle", "description", "richDescription", "seoTitle", "seoDescription"] as const;
+
+function catalogHookContext(
+  deps: CatalogServiceDeps,
+  actor: Actor | null,
+  ctx: CatalogWriteContext | undefined,
+  operation: string,
+): HookContext {
+  return createHookContext({
+    actor,
+    tx: isWriteContextTransactional(ctx) ? ctx.tx : null,
+    logger: createLogger(`catalog.${operation}`),
+    services: deps.services,
+    ...(deps.services.jobs ? { jobs: deps.services.jobs as JobsAdapter } : {}),
+    context: { moduleName: "catalog", ...(ctx?.hookContext ?? {}) },
+    ...hookDatabaseArg(deps.database),
+    commerceConfig: deps.config,
+  });
+}
+
 type CatalogCreateBeforeHook = BeforeHook<CreateEntityInput>;
 type CatalogCreateAfterHook = AfterHook<SellableEntity>;
 type CatalogUpdateBeforeHook = BeforeHook<UpdateEntityInput>;
@@ -69,6 +94,7 @@ function getCustomFieldValue(field: SellableCustomField): unknown {
   switch (field.fieldType) {
     case "text":
     case "relation":
+    case "select":
       return field.textValue;
     case "number":
       return field.numberValue;
@@ -83,8 +109,14 @@ function getCustomFieldValue(field: SellableCustomField): unknown {
   }
 }
 
+type CustomFieldData = Omit<SellableCustomFieldInsert, "entityId" | "fieldName" | "locale">;
+type ValidatedCustomField = { fieldName: string; locale: string; data: CustomFieldData | null };
+
 export class EntityService {
-  constructor(private readonly deps: CatalogServiceDeps) {}
+  constructor(
+    private readonly deps: CatalogServiceDeps,
+    private readonly resolveEntityFieldDefinitions: EntityFieldDefinitionResolver,
+  ) {}
 
   private get repo() {
     return this.deps.repository;
@@ -92,7 +124,7 @@ export class EntityService {
 
   private assertSameOrg(resource: { organizationId?: string | null } | undefined, actor: Actor | null): void {
     if (!resource) return;
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, this.deps.config);
     if (resource.organizationId && resource.organizationId !== orgId) {
       throw new CommerceNotFoundError("Entity not found.");
     }
@@ -102,22 +134,38 @@ export class EntityService {
     if (entity.sourceStoreId != null) assertPermission(actor, "catalog:sync");
   }
 
-  private async validateAndCreateCustomFields(entityId: string, entityType: string, customFields: Record<string, unknown> | undefined, ctx?: TxContext): Promise<Result<void>> {
-    if (!customFields) return Ok(undefined);
+  private async validateCustomFields(entityType: string, customFields: Record<string, unknown> | undefined, actor: Actor | null, ctx?: TxContext): Promise<Result<ValidatedCustomField[]>> {
+    if (!customFields) return Ok([]);
     const entityConfig = this.deps.config.entities?.[entityType];
-    if (!entityConfig) return Ok(undefined);
-    const definitionMap = new Map(entityConfig.fields.map((f) => [f.name, f]));
+    const definitions = await this.resolveEntityFieldDefinitions(entityType, actor ?? ctx?.actor ?? null, ctx);
+    if (!entityConfig && definitions.length === 0) return Ok([]);
+    const definitionMap = new Map(definitions.map((f) => [f.name, f]));
+    const validated: ValidatedCustomField[] = [];
     for (const [name, value] of Object.entries(customFields)) {
       const def = definitionMap.get(name);
       if (!def) return Err(new CommerceValidationError(`Unknown custom field: ${name}`));
+      if (value === null) {
+        validated.push({ fieldName: name, locale: "en", data: null });
+        continue;
+      }
       const type = def.type;
+      let normalized = value;
       let valid = false;
       switch (type) {
         case "text":
         case "relation":
-        case "select":
           valid = typeof value === "string";
           break;
+        case "select": {
+          if (typeof value !== "string") break;
+          const trimmed = value.trim();
+          if (def.options && !def.options.includes(trimmed)) {
+            return Err(new CommerceValidationError(`Value "${trimmed}" is not permitted for field ${name}. Allowed: ${def.options.join(", ")}`));
+          }
+          normalized = trimmed;
+          valid = true;
+          break;
+        }
         case "number":
           valid = typeof value === "number";
           break;
@@ -134,29 +182,50 @@ export class EntityService {
           valid = false;
       }
       if (!valid) return Err(new CommerceValidationError(`Custom field ${name} expected type ${type}.`));
-      const fieldType = (type === "select" ? "text" : type) as SellableCustomField["fieldType"];
-      const insertData: SellableCustomFieldInsert = { entityId, fieldName: name, fieldType };
+      const fieldType = type as SellableCustomField["fieldType"];
+      const insertData: CustomFieldData = {
+        fieldType,
+        source: "merchant",
+        status: "approved",
+        confidence: null,
+        evidence: null,
+        approvedAt: null,
+        approvedBy: null,
+      };
       switch (fieldType) {
         case "text":
         case "relation":
-          insertData.textValue = value as string;
+        case "select":
+          insertData.textValue = normalized as string;
           break;
         case "number":
-          insertData.numberValue = value as number;
+          insertData.numberValue = normalized as number;
           break;
         case "boolean":
-          insertData.booleanValue = value as boolean;
+          insertData.booleanValue = normalized as boolean;
           break;
         case "date":
-          insertData.dateValue = value instanceof Date ? value : new Date(value as string);
+          insertData.dateValue = normalized instanceof Date ? normalized : new Date(normalized as string);
           break;
         case "json":
-          insertData.jsonValue = value;
+          insertData.jsonValue = normalized;
           break;
       }
-      await this.repo.createCustomField(insertData, ctx);
+      validated.push({ fieldName: name, locale: "en", data: insertData });
+    }
+    return Ok(validated);
+  }
+
+  private async writeCustomFields(entityId: string, customFields: ValidatedCustomField[], ctx?: TxContext, upsert = false): Promise<void> {
+    for (const customField of customFields) {
+      if (customField.data === null) {
+        await this.repo.deleteCustomField(entityId, customField.fieldName, customField.locale, ctx);
+      } else if (upsert) {
+        await this.repo.upsertCustomField(entityId, customField.fieldName, customField.locale, customField.data, ctx);
+      } else {
+        await this.repo.createCustomField({ ...customField.data, entityId, fieldName: customField.fieldName, locale: customField.locale }, ctx);
+      }
     }
-    return Ok(undefined);
   }
 
   private async hydrateEntity(entity: SellableEntity, options?: GetOptions, ctx?: TxContext): Promise<CatalogEntityHydrated> {
@@ -185,14 +254,16 @@ export class EntityService {
     }
     if (options?.includeCategories) hydrated.categories = await this.repo.findEntityCategories(entity.id, ctx);
     if (options?.includeBrands) hydrated.brands = await this.repo.findEntityBrands(entity.id, ctx);
+    if (options?.includeCustomFields) hydrated.customFields = await this.repo.findCustomFieldsByEntityId(entity.id, ctx);
     if (options?.includeMedia) {
       const mediaService = this.deps.services.media as {
         listEntityMedia?: (
           entityId: string,
           opts?: { orgId?: string },
+          ctx?: TxContext,
         ) => Promise<{ ok: boolean; value?: CatalogEntityHydrated["media"] }>;
       } | undefined;
-      const mediaResult = await mediaService?.listEntityMedia?.(entity.id, { orgId: entity.organizationId });
+      const mediaResult = await mediaService?.listEntityMedia?.(entity.id, { orgId: entity.organizationId }, ctx);
       hydrated.media = mediaResult?.ok && mediaResult.value ? mediaResult.value : [];
     }
     if (options?.includePricing) {
@@ -209,39 +280,46 @@ export class EntityService {
 
   async create(input: CreateEntityInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> { try {
     assertPermission(actor, "catalog:create");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, this.deps.config);
     const existingBySlug = await this.repo.findEntityBySlug(orgId, input.slug, ctx);
     if (existingBySlug) return Err(new CommerceConflictError(`Entity with slug ${input.slug} already exists.`));
     const beforeHooks = this.deps.hooks.resolve("catalog.beforeCreate") as CatalogCreateBeforeHook[];
     const afterHooks = this.deps.hooks.resolve("catalog.afterCreate") as CatalogCreateAfterHook[];
-    const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+    const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const processedInput = await runBeforeHooks(beforeHooks, input, "create", context);
     if (processedInput.sourceStoreId != null) assertPermission(actor, "catalog:sync");
-    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, ...(processedInput.sourceStoreId !== undefined ? { sourceStoreId: processedInput.sourceStoreId } : {}), ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
+    const customFieldsResult = await this.validateCustomFields(processedInput.type, processedInput.customFields, actor, ctx);
+    if (!customFieldsResult.ok) return customFieldsResult;
+    const statuses = ["draft", "active", "archived", "discontinued"] as const;
+    const status = statuses.find((value) => value === processedInput.status) ?? "draft";
+    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status, isVisible: status === "active", ...(processedInput.sourceStoreId !== undefined ? { sourceStoreId: processedInput.sourceStoreId } : {}), ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
     if (processedInput.attributes) {
       await this.repo.createAttribute({ entityId: entity.id, locale: processedInput.attributes.locale ?? "en", title: processedInput.attributes.title, subtitle: processedInput.attributes.subtitle, description: processedInput.attributes.description, richDescription: processedInput.attributes.richDescription, seoTitle: processedInput.attributes.seoTitle, seoDescription: processedInput.attributes.seoDescription }, ctx);
     }
-    const customFieldsResult = await this.validateAndCreateCustomFields(entity.id, entity.type, processedInput.customFields, ctx);
-    if (!customFieldsResult.ok) return customFieldsResult;
+    await this.writeCustomFields(entity.id, customFieldsResult.value, ctx);
     const hookReport = await runAfterHooks(afterHooks, null, entity, "create", context);
     const hydrated = await this.hydrateEntity(entity, undefined, ctx);
     return Ok(hydrated, hookReport.hasErrors ? { hookErrors: hookReport.errors } : undefined);
   } catch (error) { return Err(toCommerceError(error)); } }
 
-  async update(id: string, input: UpdateEntityInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> { try {
+  async update(id: string, input: UpdateEntityInput, actor: Actor | null, ctx?: CatalogWriteContext): Promise<Result<CatalogEntityHydrated>> { try {
+    const txCtx = isWriteContextTransactional(ctx) ? ctx : undefined;
     assertPermission(actor, "catalog:update");
-    const existing = await this.repo.findEntityById(id, ctx);
+    const existing = await this.repo.findEntityById(id, txCtx);
     if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
     this.assertSameOrg(existing, actor);
     this.assertEntityWritable(existing, actor);
     const beforeHooks = this.deps.hooks.resolve("catalog.beforeUpdate") as CatalogUpdateBeforeHook[];
     const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate") as CatalogUpdateAfterHook[];
-    const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.update"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+    const context: HookContext = catalogHookContext(this.deps, actor, ctx, "update");
     const processed = await runBeforeHooks(beforeHooks, input, "update", context);
-    const updated = await this.repo.updateEntity(id, { ...(processed.slug !== undefined ? { slug: processed.slug } : {}), ...(processed.status !== undefined ? { status: processed.status as SellableEntity["status"] } : {}), ...(processed.taxClass !== undefined ? { taxClass: processed.taxClass } : {}), ...(processed.metadata !== undefined ? { metadata: processed.metadata } : {}), ...(processed.isVisible !== undefined ? { isVisible: processed.isVisible } : {}) }, ctx);
+    const customFieldsResult = await this.validateCustomFields(existing.type, processed.customFields, actor, txCtx);
+    if (!customFieldsResult.ok) return customFieldsResult;
+    const updated = await this.repo.updateEntity(id, { ...(processed.slug !== undefined ? { slug: processed.slug } : {}), ...(processed.status !== undefined ? { status: processed.status as SellableEntity["status"] } : {}), ...(processed.taxClass !== undefined ? { taxClass: processed.taxClass } : {}), ...(processed.metadata !== undefined ? { metadata: processed.metadata } : {}), ...(processed.isVisible !== undefined ? { isVisible: processed.isVisible } : {}) }, txCtx);
     if (!updated) return Err(new CommerceNotFoundError("Entity not found."));
+    await this.writeCustomFields(existing.id, customFieldsResult.value, txCtx, true);
     const hookReport = await runAfterHooks(afterHooks, existing, updated, "update", context);
-    const hydrated = await this.hydrateEntity(updated, undefined, ctx);
+    const hydrated = await this.hydrateEntity(updated, undefined, txCtx);
     return Ok(hydrated, hookReport.hasErrors ? { hookErrors: hookReport.errors } : undefined);
   } catch (error) { return Err(toCommerceError(error)); } }
 
@@ -261,24 +339,27 @@ export class EntityService {
     return Ok(undefined);
   } catch (error) { return Err(toCommerceError(error)); } }
 
-  async getById(id: string, options?: GetOptions, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
-    const context: HookContext = createHookContext({ actor: actor ?? null, tx: ctx?.tx ?? null, logger: createLogger("catalog.read"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+  async getById(id: string, options: GetOptions | undefined, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+    const resolvedActor = actor ?? ctx?.actor ?? null;
+    const orgId = resolveOrgIdForCommerce(resolvedActor, this.deps.config);
+    const context: HookContext = createHookContext({ actor: resolvedActor, tx: ctx?.tx ?? null, logger: createLogger("catalog.read"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const globalBeforeHooks = this.deps.hooks.resolve("catalog.beforeRead") as CatalogReadBeforeHook[];
     const globalAfterHooks = this.deps.hooks.resolve("catalog.afterRead") as CatalogReadAfterHook[];
     let processed = await runBeforeHooks(globalBeforeHooks, { id, ...(options !== undefined ? { options } : {}) }, "read", context);
-    let entity = await this.repo.findEntityById(processed.id ?? id, ctx);
+    let entity = await this.repo.findEntityById(processed.id ?? id, ctx, orgId);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    if (!isCatalogEntityVisible(entity, resolvedActor)) return Err(new CommerceNotFoundError("Entity not found."));
     const entityBeforeHooks = this.deps.hooks.resolve(`catalog.${entity.type}.beforeRead`) as CatalogReadBeforeHook[];
     if (entityBeforeHooks.length > 0) {
       processed = await runBeforeHooks(entityBeforeHooks, { ...processed, id: entity.id }, "read", context);
       const resolvedId = processed.id ?? entity.id;
       if (resolvedId !== entity.id) {
-        const refetched = await this.repo.findEntityById(resolvedId, ctx);
+        const refetched = await this.repo.findEntityById(resolvedId, ctx, orgId);
         if (!refetched) return Err(new CommerceNotFoundError("Entity not found."));
+        if (!isCatalogEntityVisible(refetched, resolvedActor)) return Err(new CommerceNotFoundError("Entity not found."));
         entity = refetched;
       }
     }
-    const resolvedActor = actor ?? ctx?.actor ?? null;
     try {
       this.assertSameOrg(entity, resolvedActor);
     } catch (error) {
@@ -290,28 +371,48 @@ export class EntityService {
     return Ok(result, report.hasErrors ? { hookErrors: report.errors } : undefined);
   }
 
-  async getBySlug(slug: string, options?: GetOptions, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
-    const context: HookContext = createHookContext({ actor: actor ?? null, tx: ctx?.tx ?? null, logger: createLogger("catalog.read"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+  /**
+   * Reads an entity for a trusted server pipeline after the request boundary
+   * has already authorized the caller. Organization scope is explicit; the
+   * storefront visibility policy is intentionally not applied, so an internal
+   * invariant check never depends on the caller's catalog permissions.
+   */
+  async getByIdForInternalUse(
+    id: string,
+    organizationId: string,
+    options?: GetOptions,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    const entity = await this.repo.findEntityById(id, ctx, organizationId);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    return Ok(await this.hydrateEntity(entity, options, ctx));
+  }
+
+  async getBySlug(slug: string, options: GetOptions | undefined, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+    const context: HookContext = createHookContext({ actor: actor ?? null, tx: ctx?.tx ?? null, logger: createLogger("catalog.read"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const globalBeforeHooks = this.deps.hooks.resolve("catalog.beforeRead") as CatalogReadBeforeHook[];
     const globalAfterHooks = this.deps.hooks.resolve("catalog.afterRead") as CatalogReadAfterHook[];
     let processed = await runBeforeHooks(globalBeforeHooks, { slug, ...(options !== undefined ? { options } : {}) }, "read", context);
     let resolvedSlug = processed.slug ?? slug;
-    const orgId = resolveOrgId(actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? null, this.deps.config);
     let entity = await this.repo.findEntityBySlug(orgId, resolvedSlug, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    if (!isCatalogEntityVisible(entity, actor ?? null)) return Err(new CommerceNotFoundError("Entity not found."));
     const entityBeforeHooks = this.deps.hooks.resolve(`catalog.${entity.type}.beforeRead`) as CatalogReadBeforeHook[];
     if (entityBeforeHooks.length > 0) {
       processed = await runBeforeHooks(entityBeforeHooks, { ...processed, id: entity.id }, "read", context);
       const nextId = processed.id ?? entity.id;
       const nextSlug = processed.slug ?? resolvedSlug;
       if (nextId !== entity.id) {
-        const refetched = await this.repo.findEntityById(nextId, ctx);
+        const refetched = await this.repo.findEntityById(nextId, ctx, orgId);
         if (!refetched) return Err(new CommerceNotFoundError("Entity not found."));
+        if (!isCatalogEntityVisible(refetched, actor ?? null)) return Err(new CommerceNotFoundError("Entity not found."));
         entity = refetched;
         resolvedSlug = nextSlug;
       } else if (nextSlug !== resolvedSlug) {
         const refetched = await this.repo.findEntityBySlug(orgId, nextSlug, ctx);
         if (!refetched) return Err(new CommerceNotFoundError("Entity not found."));
+        if (!isCatalogEntityVisible(refetched, actor ?? null)) return Err(new CommerceNotFoundError("Entity not found."));
         entity = refetched;
       }
     }
@@ -321,9 +422,9 @@ export class EntityService {
     return Ok(result, report.hasErrors ? { hookErrors: report.errors } : undefined);
   }
 
-  async list(params: ListParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>> {
+  async list(params: ListParams, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>> {
     const resolvedActor = actor ?? ctx?.actor ?? null;
-    const context: HookContext = createHookContext({ actor: resolvedActor, tx: ctx?.tx ?? null, logger: createLogger("catalog.list"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+    const context: HookContext = createHookContext({ actor: resolvedActor, tx: ctx?.tx ?? null, logger: createLogger("catalog.list"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const globalBeforeHooks = this.deps.hooks.resolve("catalog.beforeList") as CatalogListBeforeHook[];
     const globalAfterHooks = this.deps.hooks.resolve("catalog.afterList") as CatalogListAfterHook[];
     let processed = await runBeforeHooks(globalBeforeHooks, params, "list", context);
@@ -332,20 +433,28 @@ export class EntityService {
       const entityBeforeHooks = this.deps.hooks.resolve(`catalog.${initialTypeFilter}.beforeList`) as CatalogListBeforeHook[];
       if (entityBeforeHooks.length > 0) processed = await runBeforeHooks(entityBeforeHooks, processed, "list", context);
     }
-    const listOrgId = resolveOrgId(resolvedActor);
-    let entities = await this.repo.findEntities(listOrgId, { ...(processed.filter?.type ? { type: processed.filter.type } : {}), ...(processed.filter?.status ? { status: processed.filter.status } : {}) }, ctx);
+    const listOrgId = resolveOrgIdForCommerce(resolvedActor, this.deps.config);
+    const canReadUnpublished = canReadUnpublishedCatalog(resolvedActor);
+    let entities = await this.repo.findEntities(listOrgId, {
+      ...(processed.filter?.type ? { type: processed.filter.type } : {}),
+      ...(canReadUnpublished
+        ? (processed.filter?.status ? { status: processed.filter.status } : {})
+        : { status: "active", isVisible: true }),
+    }, ctx);
+    const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (processed.filter?.category) {
       const catInput = processed.filter.category;
-      const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
       let category = await this.repo.findCategoryBySlug(listOrgId, catInput, ctx);
-      if (!category && isUUID.test(catInput)) category = await this.repo.findCategoryById(catInput, ctx);
+      if (!category && isUUID.test(catInput)) category = await this.repo.findCategoryById(catInput, ctx, listOrgId);
       if (!category) return Err(new CommerceValidationError(`Category not found: "${catInput}".`));
       const entityIds = await this.repo.findEntitiesByCategory(category.id, ctx);
       entities = entities.filter((e) => new Set(entityIds).has(e.id));
     }
     if (processed.filter?.brand) {
       let brand = await this.repo.findBrandBySlug(listOrgId, processed.filter.brand, ctx);
-      if (!brand) brand = await this.repo.findBrandById(processed.filter.brand, ctx);
+      if (!brand && isUUID.test(processed.filter.brand)) {
+        brand = await this.repo.findBrandById(processed.filter.brand, ctx, listOrgId);
+      }
       if (brand) {
         const brandEntityIds: string[] = [];
         for (const entity of entities) {
@@ -401,19 +510,45 @@ export class EntityService {
   archive(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> { return this.changeStatus(id, "archived", actor, ctx); }
   discontinue(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> { return this.changeStatus(id, "discontinued", actor, ctx); }
 
-  async setAttributes(entityId: string, locale: string, attrs: SetAttributesInput, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  async setAttributes(entityId: string, locale: string, attrs: SetAttributesInput, actor: Actor | null, ctx?: CatalogWriteContext): Promise<Result<void>> {
     try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
-    const entity = await this.repo.findEntityById(entityId, ctx);
+    const txCtx = isWriteContextTransactional(ctx) ? ctx : undefined;
+    const entity = await this.repo.findEntityById(entityId, txCtx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
     try { this.assertSameOrg(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
-    await this.repo.upsertAttribute(entityId, locale, { title: attrs.title, subtitle: attrs.subtitle, description: attrs.description, richDescription: attrs.richDescription, seoTitle: attrs.seoTitle, seoDescription: attrs.seoDescription }, ctx);
+    const beforeAttr = await this.repo.findAttributeByLocale(entityId, locale, txCtx);
+    const changedFieldPaths: string[] = [];
+    for (const field of attributeFields) {
+      if (attrs[field] === undefined) continue;
+      const before = beforeAttr?.[field] ?? null;
+      const after = attrs[field] ?? null;
+      if (before !== after) {
+        const path = `attributes.${locale}.${field}`;
+        if (isValidFieldPath(path)) changedFieldPaths.push(path);
+      }
+    }
+    await this.repo.upsertAttribute(entityId, locale, { title: attrs.title, subtitle: attrs.subtitle, description: attrs.description, richDescription: attrs.richDescription, seoTitle: attrs.seoTitle, seoDescription: attrs.seoDescription }, txCtx);
+    if (changedFieldPaths.length > 0) {
+      const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate") as CatalogUpdateAfterHook[];
+      const context = catalogHookContext(this.deps, actor, ctx, "update");
+      context.context.changedFieldPaths = changedFieldPaths;
+      await runAfterHooks(afterHooks, entity, entity, "update", context);
+    }
     return Ok(undefined);
   }
 
-  async getAttributes(entityId: string, locale: string, ctx?: TxContext): Promise<Result<SellableAttribute>> {
-    const attr = await this.repo.findAttributeByLocale(entityId, locale, ctx);
-    if (!attr) return Err(new CommerceNotFoundError(`Attributes for locale ${locale} not found.`));
-    return Ok(attr);
+  async getAttributes(entityId: string, locale: string, actor: Actor | null, ctx?: TxContext): Promise<Result<SellableAttribute>> {
+    try {
+      assertPermission(actor, "catalog:read");
+      const entity = await this.repo.findEntityById(entityId, ctx, resolveOrgIdForCommerce(actor, this.deps.config));
+      if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+      if (!isCatalogEntityVisible(entity, actor)) return Err(new CommerceNotFoundError("Entity not found."));
+      const attr = await this.repo.findAttributeByLocale(entity.id, locale, ctx);
+      if (!attr) return Err(new CommerceNotFoundError(`Attributes for locale ${locale} not found.`));
+      return Ok(attr);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
   }
 
   async createOptionType(input: CreateOptionTypeInput, actor: Actor | null, ctx?: TxContext): Promise<Result<OptionType>> {
@@ -467,7 +602,7 @@ export class EntityService {
       if (!ov) return Err(new CommerceValidationError(`Option value "${optVal}" does not exist for option type "${optName}".`));
       optionValueIds.push(ov.id);
     }
-    const variant = await this.repo.createVariant({ entityId: input.entityId, status: "active", sortOrder: 0, metadata: {}, ...(input.sku !== undefined ? { sku: input.sku } : {}), ...(input.taxClass !== undefined ? { taxClass: input.taxClass } : {}) }, ctx);
+    const variant = await this.repo.createVariant({ entityId: input.entityId, status: "active", sortOrder: 0, metadata: {}, ...(input.sku !== undefined ? { sku: input.sku } : {}), ...(input.barcode !== undefined ? { barcode: input.barcode } : {}), ...(input.taxClass !== undefined ? { taxClass: input.taxClass } : {}) }, ctx);
     await this.repo.createVariantOptionValues(optionValueIds.map((optionValueId) => ({ variantId: variant.id, optionValueId })), ctx);
     return Ok(variant);
   }

package/src/modules/catalog/module.ts

@@ -6,15 +6,20 @@ import { CatalogRepository } from "./repository/index.js";
 import {
   brands,
   categories,
+  tags,
+  entityTags,
   entityBrands,
   entityCategories,
   optionTypes,
   optionValues,
   sellableAttributes,
   sellableCustomFields,
+  entityFieldDefinitions,
+  sellableEntityRevisions,
   sellableEntities,
   variantOptionValues,
   variants,
+  catalogFieldOwnership,
 } from "./schema.js";
 import { CatalogServiceImpl } from "./service.js";
 
@@ -27,14 +32,19 @@ export const catalogModule = defineModule<
     sellableEntities: typeof sellableEntities;
     sellableAttributes: typeof sellableAttributes;
     sellableCustomFields: typeof sellableCustomFields;
+    entityFieldDefinitions: typeof entityFieldDefinitions;
+    sellableEntityRevisions: typeof sellableEntityRevisions;
     categories: typeof categories;
     entityCategories: typeof entityCategories;
     brands: typeof brands;
     entityBrands: typeof entityBrands;
+    tags: typeof tags;
+    entityTags: typeof entityTags;
     optionTypes: typeof optionTypes;
     optionValues: typeof optionValues;
     variants: typeof variants;
     variantOptionValues: typeof variantOptionValues;
+    catalogFieldOwnership: typeof catalogFieldOwnership;
   },
   CatalogServiceImpl,
   CatalogModuleDeps
@@ -45,14 +55,19 @@ export const catalogModule = defineModule<
     sellableEntities,
     sellableAttributes,
     sellableCustomFields,
+    entityFieldDefinitions,
+    sellableEntityRevisions,
     categories,
     entityCategories,
     brands,
     entityBrands,
+    tags,
+    entityTags,
     optionTypes,
     optionValues,
     variants,
     variantOptionValues,
+    catalogFieldOwnership,
   }),
   service: (deps) =>
     new CatalogServiceImpl({

package/src/modules/catalog/ownership.ts

@@ -0,0 +1,17 @@
+import { CommerceValidationError } from "../../kernel/errors.js";
+
+export type FieldPath = string;
+export type FieldOwner = "platform" | "store" | "shared";
+
+const fieldPathPattern = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/;
+
+export function isValidFieldPath(value: string): value is FieldPath {
+  return fieldPathPattern.test(value);
+}
+
+export function validateFieldPath(value: string): FieldPath {
+  if (!isValidFieldPath(value)) {
+    throw new CommerceValidationError("Field path must contain dot-separated alphanumeric, underscore, or hyphen segments.");
+  }
+  return value;
+}

package/src/modules/catalog/read-policy.ts

@@ -0,0 +1,16 @@
+import { hasPermission } from "../../auth/permissions.js";
+import type { Actor } from "../../auth/types.js";
+
+type CatalogVisibility = {
+  status: string;
+  isVisible: boolean;
+};
+
+export function canReadUnpublishedCatalog(actor: Actor | null): boolean {
+  return hasPermission(actor, "catalog:read:unpublished");
+}
+
+export function isCatalogEntityVisible(entity: CatalogVisibility, actor: Actor | null): boolean {
+  return canReadUnpublishedCatalog(actor) ||
+    (entity.status === "active" && entity.isVisible);
+}