@endora-commerce/mod-catalog 0.100.0

package/docs/catalog/packaging-units.md

@@ -0,0 +1,67 @@
+---
+title: Packaging Units
+---
+
+# Packaging Units
+
+Named ordering units attached to a product — for example a **Paleta** worth
+480 pieces. They let B2B buyers order in bulk units without typing the exact
+piece count, and carry that context all the way into the order and quote
+request.
+
+## For operators
+
+Manage packaging units in the **Inventory** section of the product card
+(simple and configurable products only). Each unit has:
+
+- a **name** (operator text, e.g. `Paleta`, `Karton`) — unique within the product,
+- a **base quantity** (whole number ≥ 1) — how many base pieces the unit holds,
+- a **default** flag — the unit pre-selected on the storefront,
+- a **position** — the order units appear in.
+
+## For buyers
+
+On the product page a selector offers the available units plus a *single piece*
+option. Ordering a unit adds `baseQuantity × units` pieces to the cart as one
+line, whose displayed name gets the unit appended — e.g.
+`Łożysko 6205-2RS (Paleta)`. A packaging-unit line and a plain single-piece
+line of the same product stay separate.
+
+## How the label travels
+
+The unit name and base quantity are **snapshotted** on the line when it is
+created, so later edits to (or deletion of) a product's packaging units never
+change historical carts, orders, or quote requests.
+
+- **Cart** — `cart_items` snapshot the unit; the cart serializer composes a
+  `displayName` with the suffix.
+- **Order** — `order_items` get a `packaging_unit_snapshot`, and the unit name
+  is appended to `product_snapshot.name`, so every order document (detail,
+  invoice, CSV, email) shows it.
+- **Quote request** — `quote_request_items` snapshot the unit and append it to
+  `product_name`; cart → quote-request conversion carries the context through.
+
+## Pricing & availability
+
+Pricing reuses the existing engine on the resulting base-piece quantity
+(including price-list quantity tiers) — there is no separate per-unit price.
+Stock availability and per-line limits are evaluated on the resulting piece
+count.
+
+## API surface
+
+- Admin CRUD: `GET/POST /api/v1/admin/catalog/products/:id/packaging-units`,
+  `PATCH/DELETE …/:unitId`, `PATCH …/packaging-units/reorder`
+  (gated by `catalog:read` / `catalog:write`).
+- Public: the product detail (`GET /api/v1/catalog/products/:idOrSlug`)
+  includes an optional `packagingUnits` array.
+- Cart: `POST /api/v1/cart/items` accepts an optional `packagingUnitId`; the
+  resulting line quantity is `baseQuantity × quantity`.
+
+## Schema
+
+Table `product_packaging_units` (migration 068): `id`, `product_id`
+(FK → `products`, cascade delete), `name`, `base_quantity`
+(`CHECK >= 1`), `position`, `is_default`, timestamps; `UNIQUE (product_id,
+name)`. Additive snapshot columns: `cart_items` (069), `order_items` (070),
+`quote_request_items` (071).

package/docs/catalog/per-channel-per-language-overrides.md

@@ -0,0 +1,234 @@
+---
+title: Per-Channel + Per-Language Overrides
+---
+
+# Per-Channel + Per-Language Overrides
+
+The Catalog uses a **four-scope value model** for product attribute
+values. The same attribute key can hold up to four addressable slots
+per product:
+
+- `global` — one value across every Sales Channel and every language;
+- `language` — one value per language (e.g. system Name, Description);
+- `channel` — one value per Sales Channel the product is assigned to;
+- `channel+language` — one value per `(channel, language)` pair.
+
+Which slots are addressable for a given attribute is governed by two
+flags on the attribute definition, `channelScoped` and `languageScoped`.
+System attributes `name` and `description` are pinned channel-scoped +
+language-scoped via a backend constant
+(`SYSTEM_ATTRIBUTE_SCOPES`). User-defined attributes default to
+global-only and opt in via the attribute editor.
+
+## Why
+
+A B2B catalog routinely needs to overlay channel-specific marketing
+copy (wholesale vs. retail) and language-specific translation on the
+same product. The legacy storage — JSONB on `products.name` /
+`products.description` + a flat `products.attribute_values` JSONB —
+could express only the language dimension. The four-scope model lifts
+that ceiling without rewriting baseline storage; it adds a sibling
+overrides table that holds the channel-aware slots, and a single
+resolver function fuses the two on read.
+
+## Storage shape
+
+The global baseline keeps living where it has always lived:
+
+- `products.name` (`Record<lang, string>` JSONB) — language-scoped.
+- `products.description` (`Record<lang, string>` JSONB) — language-scoped.
+- `products.attribute_values` (`Record<key, value>` JSONB) — global by
+  default. When the attribute's `languageScoped` flag is `true`, the
+  inner value is itself keyed by language: `Record<key, Record<lang,
+  value>>`.
+
+Channel-aware slots land in a new table:
+
+```sql
+create table "product_value_overrides" (
+  "id"            uuid primary key default gen_random_uuid(),
+  "product_id"    uuid not null references "products"("id") on delete cascade,
+  "attribute_key" varchar(64) not null,
+  "channel_id"    uuid not null references "sales_channels"("id") on delete cascade,
+  "language_code" varchar(16) null,
+  "value"         jsonb not null,         -- always wrapped { "v": <scalar | object> }
+  "created_at"    timestamptz not null default now(),
+  "updated_at"    timestamptz not null default now()
+);
+```
+
+The (product, attribute, channel, language) tuple is unique under
+**two partial indexes**:
+
+```sql
+create unique index "product_value_overrides_channel_only_uniq"
+  on "product_value_overrides" ("product_id", "attribute_key", "channel_id")
+  where "language_code" is null;
+
+create unique index "product_value_overrides_channel_lang_uniq"
+  on "product_value_overrides" ("product_id", "attribute_key", "channel_id", "language_code")
+  where "language_code" is not null;
+```
+
+PostgreSQL treats `NULL` as distinct in a regular UNIQUE constraint, so
+the only correct way to model "(channel, NULL) and (channel, NULL) are
+the same row" is two partial indexes — one for each NULL semantic.
+
+The lookup path used by the resolver in tight loops is a plain btree:
+
+```sql
+create index "product_value_overrides_product_attr_idx"
+  on "product_value_overrides" ("product_id", "attribute_key");
+```
+
+A second table — `product_editor_preferences` — stores the per-(admin
+user, product) last-selected `(channelId, languageCode)` so the
+product edit page seeds the switchers from the editor's prior visit.
+It carries no FK to `sales_channels` so a deleted / un-assigned
+channel is silently tolerated on read.
+
+## The resolver
+
+The single source of truth for "what value should I show?" lives in
+`packages/contracts/src/product-value-resolver.ts`. The same TypeScript
+file is imported by the backend (admin endpoints, storefront read
+path, search indexer) and the admin SPA. By construction, the admin's
+effective-value preview cannot drift from what the storefront renders.
+
+The algorithm — `resolveAttribute({ baseline, overrides, scope, ctx })`
+— walks four steps:
+
+1. `(channel + language)` slot — when the attribute is channel-scoped
+   AND language-scoped AND the context carries both;
+2. `(channel-only)` slot — when channel-scoped AND a channel is in the
+   context;
+3. `(global + language)` baseline — for language-scoped attributes,
+   pick the requested language out of the JSONB;
+4. `(global)` baseline — single value (or primary-language pick for
+   language-scoped attrs).
+
+The first non-empty slot wins. Empty string, `null`, empty object,
+empty array are all treated as "absent" and fall through. The function
+returns both the resolved value AND a `source` tag indicating which
+slot produced the answer — the admin UI consumes this to render the
+"channel + language override" / "global baseline" badge per field.
+
+### Orphan tolerance
+
+An administrator can flip an attribute's `channelScoped` flag back to
+`false` after channel overrides have already been written. The
+resolver simply skips override rows whose attribute is no longer
+channel-scoped, so the storefront falls back to the baseline without
+any data-loss event. A future maintenance pass can drop orphan rows;
+this feature does not require it.
+
+## Write path
+
+Channel-aware overrides land through one admin endpoint:
+
+```
+PATCH /api/v1/admin/catalog/products/:id/value-overrides
+{
+  "upserts": [
+    { "attributeKey": "name",        "channelId": "<vip-uuid>", "languageCode": "en-US", "value": { "v": "VIP wholesale name (EN)" } },
+    { "attributeKey": "description", "channelId": "<vip-uuid>", "languageCode": "pl-PL", "value": { "v": "Wholesale-only Polish copy" } }
+  ],
+  "deletes": [
+    { "attributeKey": "description", "channelId": "<retail-uuid>", "languageCode": "en-US" }
+  ]
+}
+```
+
+All requested operations run in a single `em.transactional` pass.
+The handler validates every entry up front against six rules and
+rolls everything back on the first failure:
+
+| 422 code                            | Triggered when |
+| ----------------------------------- | -------------- |
+| `attribute_unknown`                 | `attributeKey` is neither a system attr (`name`, `description`) nor a row in `product_attributes`. |
+| `attribute_not_channel_scoped`      | the attribute's `channelScoped=false`, so it has no channel slot. |
+| `attribute_missing_language`        | the attribute's `languageScoped=true`, but the slot has `languageCode=null`. |
+| `channel_not_assigned_to_product`   | `channelId` is not in `sales_channel_products` for the product. |
+| `language_not_in_channel`           | `languageCode` is non-null and not in the channel's `SalesChannel.languages` array. |
+| `value_invalid`                     | the wrapped `value.v` does not match the attribute's `valueType`. |
+
+The baseline write path (Name / Description per language; global
+`attribute_values`) is unchanged — editors still use the existing
+locale-side-by-side inputs on the Details tab. Channel overrides are
+additive.
+
+## Read paths
+
+Three consumers go through the resolver:
+
+- **Admin endpoint** — `GET /api/v1/admin/catalog/products/:id?channelId=&languageCode=&includeOverridesMap=true`
+  returns the baseline product PLUS, when context params are passed, a
+  `resolved` block with `name`, `description`, `attributeValues`,
+  `sources`. When `includeOverridesMap=true`, the full override list
+  is attached for client-side switcher previews.
+- **Storefront public read** — pulls the channel from the
+  `x-sales-channel` header (the existing convention) and
+  the language from `Accept-Language`. The override layer is invisible
+  to the public client.
+- **Search indexer (Meilisearch)** — builds one document per
+  `(product, channel)` pair. Each document's `name` and `description`
+  fields are run through the resolver with `channel.defaultLanguage`
+  as the active language, so per-channel overrides flow into
+  storefront search ranking.
+
+## Admin UI
+
+The product edit page's **Details** tab gains a
+`<ProductScopeEditor>` panel above the existing locale inputs. It:
+
+1. Loads `GET /scope-context` (channels assigned to the product + each
+   channel's languages + the platform primary admin language + the
+   editor's remembered preference) and `GET /value-overrides` in
+   parallel.
+2. Renders a Sales Channel switcher (Global + each assigned channel)
+   and a Language switcher narrowed to the active channel's languages
+   (or the union of all channel languages when Global).
+3. Shows the resolved Name + Description for the active context with a
+   source badge per field — `channel + language override` / `channel
+   override` / `global baseline (language)` / `global baseline
+   (fallback)` / `no value`.
+4. Offers "Add override" / "Edit override" / "Reset to Global"
+   affordances per field. Edits go through `PATCH /value-overrides`
+   with optimistic refresh.
+5. Persists the editor's `(channel, language)` selection back via
+   `PUT /editor-preference` (debounced, best-effort) so the next visit
+   seeds the same context.
+
+Edit affordances are gated on a specific channel being selected.
+Under Global / no channel, the panel is read-only and a help string
+explains that overrides only apply per-channel.
+
+## Migration
+
+One migration `043_product_value_overrides_init.ts` ships everything:
+
+- adds `channel_scoped` + `language_scoped` boolean columns to
+  `product_attributes` (default `false`);
+- creates `product_value_overrides` with the two partial UNIQUE
+  indexes and the `(product_id, attribute_key)` btree;
+- creates `product_editor_preferences` (composite PK
+  `(admin_user_id, product_id)`).
+
+No baseline data migration. No data backfill. The `down()` is the
+exact inverse — drop the two tables and the two columns.
+
+## What is not in scope
+
+- **User-defined attribute overrides in the admin UI** — the panel
+  surfaces only the system Name + Description today. User attribute
+  overrides are accepted by the PATCH endpoint and resolved on read,
+  but the admin SPA does not yet expose a write affordance for them.
+- **Storefront public read shape change** — `products.name` and
+  `products.description` still ship as `Record<lang, string>` JSONB
+  on the public catalog endpoint. Switching to a resolved scalar is
+  a breaking change for storefront consumers and is scoped as a
+  follow-up.
+- **Channel-aware reindex enqueue** — the PATCH endpoint does not
+  yet enqueue a Meilisearch reindex job per touched channel; the
+  next per-product upsert (driven by any catalog mutation) picks it
+  up. A dedicated reindex on override write is a small follow-up.

package/docs/catalog/product-links.md

@@ -0,0 +1,79 @@
+---
+title: Product Links
+---
+
+# Product Links
+
+Directed links between Products that drive cross-merchandising on the
+PDP and cart. Three kinds:
+
+- **Related** — "Related products" section on the PDP
+- **Up-sell** — "You might also like" on the PDP
+- **Cross-sell** — "You may also need" on the cart page
+
+## DB-level guarantees
+
+Migration 022 ships three constraints that make incorrect link data
+impossible:
+
+- `UNIQUE (source_product_id, target_product_id, kind)` — same pair can
+  appear once per kind, never twice for the same kind
+- `CHECK source_product_id <> target_product_id` — defence-in-depth
+  against self-links beyond the API-layer guard
+- `CHECK kind IN ('related','up_sell','cross_sell')`
+
+Both FK columns cascade on product delete: link rows have no value when
+either side is gone.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/catalog/products/:id/links?kind=...` | admin | List links optionally filtered by kind |
+| `POST /api/v1/admin/catalog/products/:id/links` | admin | Bulk create — all-or-nothing transaction |
+| `DELETE /api/v1/admin/catalog/products/:id/links/:linkId` | admin | Remove a single link |
+| `PUT /api/v1/admin/catalog/products/:id/links/:kind/order` | admin | Reorder by id list |
+| `GET /api/v1/catalog/products/:idOrSlug/links?kind=...` | storefront | Storefront read; archived/channel-restricted targets filtered server-side |
+
+## Bulk create semantics
+
+`POST .../links` accepts a `links[]` array where each entry has
+`{targetProductId, kind, position?}`. The service validates the whole
+batch before inserting any row:
+
+1. Source product exists and is not archived (404 otherwise)
+2. No entry has `targetProductId === sourceProductId` (400)
+3. All targets exist (404 with the offending id)
+4. No `(source, target, kind)` already exists (409)
+
+If any check fails, **no rows are inserted**. This matches the admin UX
+of submitting a curated batch — partial inserts would surprise an
+admin who's still finishing their picks.
+
+## Errors
+
+| Code | Status | When |
+| --- | --- | --- |
+| `SELF_LINK_NOT_ALLOWED` | 400 | source = target |
+| `LINK_ALREADY_EXISTS` | 409 | Duplicate `(source, target, kind)` |
+| `TARGET_PRODUCT_NOT_FOUND` | 404 | Any target id missing |
+| `PRODUCT_LINK_NOT_FOUND` | 404 | `:linkId` missing |
+
+## Storefront integration
+
+`productDetail.links` carries pre-grouped arrays sliced to default page
+sizes: `related[8]`, `upSell[4]`, `crossSell[4]`. Each entry is a
+storefront-shape link
+summary `{id, kind, position, product{id, sku, slug, name,
+primaryAssetUrl, price}}` so the listing card renders without a
+follow-up fetch.
+
+The `<ProductLinksSections>` PDP component renders Related and Up-sell
+under their own headings. The `<CrossSellSection>` cart component
+fetches cross-sell links per cart item and dedupes by product id so the
+same target shows up once even when reached via multiple cart entries.
+
+## Storage
+
+Single `product_links` table with the constraints above plus indexes on
+`(source_product_id, kind)` and `(target_product_id)`.

package/docs/catalog.md

@@ -0,0 +1,207 @@
+---
+title: catalog
+sidebar_label: Catalog
+description: Products, variants, categories, attributes, sales channels
+---
+
+# `catalog`
+
+The product catalog: Products, ProductVariants, Categories,
+ProductAttributes, and SalesChannels. Owns all read paths the storefront
+depends on and the admin-side authoring surface.
+
+## Public surface
+
+Admin routes are gated by `catalog:read` (list / get) /
+`catalog:write` (mutations).
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/catalog/products` | storefront / API key | List/search/filter products in the active Sales Channel |
+| `GET /api/v1/catalog/products/:idOrSlug` | storefront | Product detail (price omitted on non-public Sales Channels) |
+| `GET /api/v1/catalog/categories` | storefront | Nested category tree |
+| `GET /api/v1/catalog/filters` | storefront | Filterable attributes for the active Sales Channel |
+| `GET /api/v1/catalog/sitemap.xml` | crawlers | SEO sitemap |
+| `GET /api/v1/admin/catalog/products?includeArchived` | admin | Admin product list (includes drafts; archived rows opt-in) |
+| `GET /api/v1/admin/catalog/products/:id` | admin | Product detail |
+| `POST /api/v1/admin/catalog/products` | admin | Create product (`type` immutable post-create; `sku` is editable) |
+| `PATCH /api/v1/admin/catalog/products/:id` | admin | Update (incl. `sku`); writes an audit row with stateBefore / stateAfter; refuses with `409 sku_in_use` if the new SKU already belongs to another product |
+| `DELETE /api/v1/admin/catalog/products/:id` | admin | Archive (soft) |
+| `GET /api/v1/admin/catalog/attributes` | admin | List attributes |
+| `GET /api/v1/admin/catalog/attributes/by-flag?flag=isPromoRule\|isComparable\|...` | admin | Picker payload — every attribute carrying the requested flag |
+| `GET /api/v1/admin/catalog/attributes/:idOrKey` | admin | Single attribute read |
+| `POST /api/v1/admin/catalog/attributes` | admin | Create attribute (accepts the new flags + inline `options[]` for select-style types) |
+| `PATCH /api/v1/admin/catalog/attributes/:key` | admin | Hot-toggle `isFilterable` / `isSearchable` / `isVariantAxis` / `isPromoRule` / `isComparable` / `isVisibleOnProductPage` / `isRequired` / `filterPosition` (re-emits `attribute.updated.v1`) |
+| `DELETE /api/v1/admin/catalog/attributes/:idOrKey` | admin | Delete; refused with `409 attribute_in_use_by_set` while any Attribute Set still references it |
+| `GET /api/v1/admin/catalog/attributes/:idOrKey/options` | admin | List option-list rows for select/enum/multiselect attributes |
+| `POST /api/v1/admin/catalog/attributes/:idOrKey/options` | admin | Append an option |
+| `PATCH /api/v1/admin/catalog/attribute-options/:optionId` | admin | Patch label / labelDefault / isDefault / sortOrder (option `value` is immutable) |
+| `DELETE /api/v1/admin/catalog/attribute-options/:optionId` | admin | Remove; refused with `409 option_in_use` while any product still carries the value |
+| `POST /api/v1/admin/catalog/attribute-set-preview` | admin | Preview which Set's attributes will be edited / hidden when an operator switches a product's Attribute Set |
+| `GET /api/v1/admin/catalog/categories` | admin | Flat list, the UI folds into a tree |
+| `POST /api/v1/admin/catalog/categories` | admin | Create (parent must exist) |
+| `PATCH /api/v1/admin/catalog/categories/:id` | admin | Update; reparenting walks the new parent's chain to refuse cycles (409) |
+| `DELETE /api/v1/admin/catalog/categories/:id` | admin | Soft-delete; rejects with 409 if any active child still references the row |
+| `PUT /api/v1/catalog/products/by-sku/:sku` | API key | Idempotent upsert (PIM sync) |
+
+## Entities
+
+`Product`, `ProductVariant`, `Category`, `ProductAttribute`,
+`SalesChannel`, plus the M:N bridges
+`product_categories`, `sales_channel_products`, `product_assets`.
+
+## Events emitted
+
+`product.created.v1`, `product.updated.v1`, `product.archived.v1`,
+`attribute.updated.v1`. Picked up by the search indexer and bridged to
+webhook subscribers.
+
+## Extension points
+
+- **Per-Sales-Channel pricing** — query service receives a SalesChannel
+  context; new gating (e.g. customer-segment-specific catalogs) is added by
+  composing into `catalog-query.service.ts`.
+- **Slug uniqueness** — the slug is unique across all Sales Channels by
+  default; override the slugifier in `catalog-admin.service.ts` if locale
+  collisions become a concern.
+
+## Product structure and composition surfaces
+
+The catalog grew several capability surfaces, each with its own page:
+
+- [Attribute Sets](./catalog/attribute-sets.md) — reusable attribute
+  schemas pinned to Products, with a system Default
+- [Product Gallery](./catalog/gallery-and-labels.md) — image / video
+  gallery with Base / Small / Thumbnail label invariants enforced at
+  the database level
+- [Attachments](./catalog/attachments.md) — downloadable files
+  (certificates, tech specs, ...) with a typed dictionary
+- [Product Links](./catalog/product-links.md) — Related, Up-sell,
+  Cross-sell pairings driving cross-merchandising on the PDP and cart
+- [Composite Products](./catalog/composite-products.md) — `grouped`
+  (fixed children), `bundle` (configurable slots), `virtual` (digital
+  delivery)
+
+Five product types are now supported: `simple`, `configurable`,
+`grouped`, `bundle`, `virtual`. `simple` and `configurable` are the
+original pair; the other three were added later.
+
+## Attribute extensions on the Catalog read paths
+
+The Attributes work added the operational surface the storefront
+needs to render rich product information and the search / promotions
+modules need to resolve customer queries. The dedicated
+[Attributes](./catalog/attributes.md) page covers the attribute
+authoring surface in full — this section only summarises what changed
+on the Catalog read paths.
+
+### New attribute flags
+
+`ProductAttribute` gains four behavioural flags + a numeric position +
+a per-locale label fallback:
+
+- `isPromoRule` (boolean) — picker eligibility for the Promotion Rule
+  editor's `attribute` criterion variant
+- `isVisibleOnProductPage` (boolean) — surface the attribute on the
+  storefront PDP "Parametry produktu" tab when the product carries a
+  value
+- `isRequired` (boolean) — enforced at product save time when the
+  attribute is part of the product's Attribute Set
+- `filterPosition` (number) — sort key for the storefront filter sidebar
+  (lower comes first; ties broken by label)
+- `labelDefault` (string) — fallback used when the active locale has no
+  matching key in the per-locale `label` JSONB
+
+### Option lists
+
+Select-style attribute types (`select`, `enum`, `multiselect`) carry an
+ordered option list — each row keyed by `(definition, value)` with
+per-locale label + fallback + sort order + default flag. The legacy
+`enum_values: string[]` JSONB column on `product_attributes` was
+decommissioned by migration 032 (into the catalog-owned
+`attribute_options` table), and migration 102 moved the
+rows into the generic `custom_field_options` table. Existing readers
+project the option list back into the legacy form for backward
+compatibility at the API boundary.
+
+### Editable SKU
+
+Product `sku` is mutable. The internal canonical reference for every
+cross-module link (assets, links, RFQ items, ...) is the `Product.id`
+UUID, which never changes. Updating the SKU writes an audit row and
+refuses with `409 sku_in_use` if the new value already belongs to
+another product.
+
+### Attribute Set swap
+
+When an operator assigns a different Attribute Set to a Product, the
+admin form re-renders to show only the new Set's attributes. Values
+for attributes outside the new Set stay in the JSONB column server-side
+— switching back surfaces them again. The
+`attribute-set-preview` endpoint lets the editor warn the operator
+which fields will be hidden vs. retained before they confirm.
+
+### Cross-module read surface
+
+Two methods on `CatalogQueryService` cross module boundaries (the
+documented service ports):
+
+- `comparableAttributeKeys(): string[]` — Compare
+- `promoRuleAttributeKeys(): string[]` + `getAttributeWithOptions(key)`
+  — Promotions
+- `buildVisibleAttributesProjection()` — internal, used by the PDP
+  detail response to assemble the `visibleAttributes[]` payload
+
+## Attributes as Custom Field extensions
+
+The attribute definition store has converged onto the generic Custom
+Fields layer that the `custom_fields` module owns, adapter-shaped rather
+than rewritten. Nothing changed on the
+HTTP surface — every endpoint above keeps its shape — but the storage
+and ownership model is different:
+
+- **A product attribute is a catalog extension of a product-host Custom
+  Field definition.** The generic identity (`key`, per-locale `label` +
+  `labelDefault`, `valueType`, `required`) lives on a
+  `custom_field_definitions` row with `entity_type = 'product'`. The
+  `product_attributes` table remains, rebuilt as a thin 1:1 extension
+  row (`custom_field_definition_id` UNIQUE FK) carrying only the
+  catalog behaviour flags (`isSearchable`, `isFilterable`,
+  `isVariantAxis`, `displayAsSlider`, `isComparable`,
+  `quickSearchable`, `isPromoRule`, `filterPosition`,
+  `isVisibleOnProductPage`, `channelScoped`, `languageScoped`,
+  `massEditable`) plus two presentation refinements (`selectDisplay`,
+  `numericKind`) that keep the legacy `enum`/`select` and
+  `number`/`price` distinctions lossless. **Flags stay catalog-owned**
+  — the generic core never interprets them.
+- **Options live in `custom_field_options`.** The catalog-owned
+  `attribute_options` table is gone; option lists are ordinary Custom
+  Field option rows on the product-host definition.
+- **Single write surface: `/catalog/attributes`.** Attribute and
+  option mutations are catalog Commands that create/update/delete the
+  definition and the extension together in one transaction (one audit
+  row), using the transactional apply seam exported by
+  `custom_fields`. The generic Custom Fields admin surface lists
+  product definitions read-only and refuses mutations with
+  `409 host_managed`.
+- **Migration `102_attributes_on_custom_fields.ts`** performed the
+  one-time convergence in a single transaction: backfilled one
+  definition per legacy attribute (key, labels, mapped value type,
+  required, deterministic sort order), moved `attribute_options` rows
+  into `custom_field_options`, re-keyed `attribute_set_attributes` to
+  definition ids, added `custom_field_definition_id` /
+  `select_display` / `numeric_kind` to `product_attributes`, dropped
+  the duplicated columns (`key`, `label`, `label_default`,
+  `value_type`, `is_required`), and dropped `attribute_options`. The
+  migration is reversible (`down()` restores the legacy shape) and
+  aborts loudly on a reserved-key collision.
+- **Attribute values did not move** — `products.attribute_values`,
+  `product_variants.variant_attribute_values`, and
+  `product_value_overrides` keep their shape and catalog ownership
+  (the host owns its data).
+
+Internal consumers (search, quick order, comparisons, bulk edit, the
+promotions port, the scope editor) read attributes through the
+catalog-exported `CatalogAttributeReadService`, which composes the
+definition and the extension into the legacy-shaped
+`CatalogAttributeView`.