@endora-commerce/mod-catalog 0.100.0

package/dist/ports/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The port interfaces `catalog` publishes whose signature carries the caller's
+ * `EntityManager`, and **nothing that exists at runtime** (D-169, D-171).
+ *
+ * `tsc` compiles this file to `export {};`. That is the property D-171 makes
+ * the boundary decision on — *a subpath is contract surface iff the module it
+ * resolves to exports no runtime binding* — so a consumer naming this subpath
+ * names a declaration and can name nothing else. Every other `catalog` port is
+ * declared in `@endora-commerce/contracts`; one lands here only when its
+ * signature stops it living there: that package is compiled by `admin` and
+ * `storefront`, and FR-034 keeps it free of `@mikro-orm` imports.
+ *
+ * No entity class leaves by this door, type-only included (D-168).
+ */
+import type { EntityManager } from '@mikro-orm/postgresql';
+/** A baseline value removed from under a rename's destination. */
+export interface CatalogDisplacedAttributeValue {
+    readonly productId: string;
+    readonly value: unknown;
+}
+/** An override row removed from under a rename's destination. */
+export interface CatalogDisplacedValueOverride {
+    readonly productId: string;
+    readonly channelId: string;
+    readonly languageCode: string | null;
+    /** The stored `{ v: … }` wrapper, as it was. */
+    readonly value: unknown;
+}
+/**
+ * What a rename does when something is already stored under `toKey`. There is
+ * no default: the caller states the choice, for the reason D-169 makes the
+ * `EntityManager` required — a default is a decision the caller never saw.
+ *
+ * - `refuse` — throw `target_occupied`, naming the key and both counts, before
+ *   anything is written.
+ * - `displace` — remove everything under `toKey`, baseline values and override
+ *   rows alike, on every product that holds it, and return it in
+ *   {@link CatalogAttributeValueKeyMove.displaced}; then move the key.
+ */
+export interface CatalogAttributeValueKeyRenameOptions {
+    readonly occupied: 'refuse' | 'displace';
+}
+/** How many rows a value-key rename moved, per place the key is stored. */
+export interface CatalogAttributeValueKeyMove {
+    /** Products whose `attribute_values` map carried the old key. */
+    readonly products: number;
+    /** Channel/locale override rows keyed by the old key. */
+    readonly overrides: number;
+    /** What `displace` removed from under `toKey`; both lists empty otherwise. */
+    readonly displaced: {
+        readonly values: readonly CatalogDisplacedAttributeValue[];
+        readonly overrides: readonly CatalogDisplacedValueOverride[];
+    };
+}
+/**
+ * Container name: `catalogAttributeValueKeyPort`. Owner: `catalog`.
+ *
+ * Renames an attribute's **value key** everywhere the catalogue stores it as a
+ * string — the `products.attribute_values` JSONB map and
+ * `product_value_overrides.attribute_key` — inside the **caller's**
+ * transaction (`specs/134-paid-module-extraction/research.md` D12, *Ergonode
+ * fallback boundary*).
+ *
+ * It is one half of a key rename and never the whole of one. The definition's
+ * key is `custom_fields`' row, renamed through `applyRenameKey` on
+ * `@endora-commerce/mod-custom-fields/ports` in the same transaction, and the
+ * caller publishes that seam's invalidation after it commits. The seam exists
+ * for a module repairing keys **it derived itself** — the connector owns which
+ * rows are candidates and where each one goes; `catalog` owns the rows.
+ *
+ * **The `EntityManager` is required and never optional** (D-169): the two
+ * statements and the definition rename must commit or roll back together, and
+ * an optional transaction lets a caller hand one to an implementation that
+ * ignores it and receive a silently non-atomic write.
+ *
+ * **Data already under `toKey`** is never merged into the moved value and never
+ * left to collide with it (`specs/134-paid-module-extraction/research.md` D12,
+ * *what a rename does to data already under its destination*). The caller
+ * chooses with {@link CatalogAttributeValueKeyRenameOptions}: `refuse` writes
+ * nothing, `displace` removes it — on every product that holds it, not only
+ * those also holding `fromKey` — and hands it back so the caller can record
+ * it. The destination rows are read `for update`, on the caller's transaction,
+ * before anything is written.
+ *
+ * The moves are conditioned on `fromKey`, so re-running is a no-op; a rename
+ * to the same key issues nothing. `name`, `description` and any key outside
+ * the attribute grammar are refused before a statement is issued.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError`, so nothing half-executes. Whether `catalog` has an off
+ * state at all is its manifest's `activation` to say, not this line's.
+ */
+export interface CatalogAttributeValueKeyApi {
+    renameValueKey(em: EntityManager, fromKey: string, toKey: string, options: CatalogAttributeValueKeyRenameOptions): Promise<CatalogAttributeValueKeyMove>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/ports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,kEAAkE;AAClE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,iEAAiE;AACjE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;CAC1C;AAED,2EAA2E;AAC3E,MAAM,WAAW,4BAA4B;IAC3C,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,8BAA8B,EAAE,CAAC;QAC3D,QAAQ,CAAC,SAAS,EAAE,SAAS,6BAA6B,EAAE,CAAC;KAC9D,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,2BAA2B;IAC1C,cAAc,CACZ,EAAE,EAAE,aAAa,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,qCAAqC,GAC7C,OAAO,CAAC,4BAA4B,CAAC,CAAC;CAC1C"}

package/dist/ports/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":""}

package/docs/catalog/attachments.md

@@ -0,0 +1,69 @@
+---
+title: Product Attachments
+---
+
+# Product Attachments
+
+Product Attachments are downloadable files (certificates, technical
+specifications, product cards, generic PDFs) attached to a Product.
+They wrap an underlying `Asset` row, so the same file can be linked to
+multiple Products without duplication — the `assets` row survives even
+when an attachment is deleted.
+
+## Attachment Types
+
+The `attachment_types` dictionary categorizes attachments. Migration
+021 seeds four standard rows with deterministic UUIDs so seeds and
+tests can reference them stably:
+
+- `certificate` — Certificate / Certyfikat
+- `tech_spec` — Technical specification / Specyfikacja techniczna
+- `product_card` — Product card / Karta produktu
+- `pdf` — generic PDF
+
+Admins can add custom types via the **Attachment Types** page in the
+admin panel. Deleting a type that any product still references returns
+`409 ATTACHMENT_TYPE_IN_USE`.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/catalog/attachment-types` | admin | List types with usage counts |
+| `POST /api/v1/admin/catalog/attachment-types` | admin | Create custom type |
+| `PATCH /api/v1/admin/catalog/attachment-types/:id` | admin | Update name / position |
+| `DELETE /api/v1/admin/catalog/attachment-types/:id` | admin | Delete; rejects when in use |
+| `GET /api/v1/admin/catalog/products/:id/attachments` | admin | List attachments on a product |
+| `POST /api/v1/admin/catalog/products/:id/attachments` | admin | Attach an existing Asset |
+| `PATCH /api/v1/admin/catalog/products/:id/attachments/:attachmentId` | admin | Update name / description / type / position |
+| `DELETE /api/v1/admin/catalog/products/:id/attachments/:attachmentId` | admin | Remove (Asset survives) |
+
+## Errors
+
+| Code | Status | When |
+| --- | --- | --- |
+| `ASSET_KIND_NOT_SUPPORTED` | 400 | Attachment Assets must be `pdf`, `certificate`, or `other` (image/video are gallery-only) |
+| `ATTACHMENT_TYPE_IN_USE` | 409 | Delete blocked by usage |
+| `ATTACHMENT_TYPE_CODE_TAKEN` | 409 | `code` collision on create |
+| `ATTACHMENT_TYPE_NOT_FOUND` | 404 | `:id` missing |
+| `ATTACHMENT_NOT_FOUND` | 404 | `:attachmentId` missing |
+
+## Storefront integration
+
+`productDetail.attachments[]` carries the full type and Asset metadata
+(filename, sizeBytes, mimeType, url). The `<AttachmentsList>` component
+groups by AttachmentType (preserving first-seen order so admin-curated
+positions shape the section ordering), renders one heading per type,
+and emits download anchors with `download={filename}` for clean file
+names.
+
+## Storage
+
+`attachment_types` (id, code unique, name jsonb, position) +
+`product_attachments` (id, product_id FK CASCADE, asset_id FK RESTRICT,
+attachment_type_id FK RESTRICT, name, description, position).
+
+The Foundation has no public `AssetsService` — the catalog uses direct
+`Asset` entity imports across modules. An admin Asset upload UI is a
+foundation-level follow-up; until then, admins paste an existing
+asset id when creating an attachment.

package/docs/catalog/attribute-sets.md

@@ -0,0 +1,63 @@
+---
+title: Attribute Sets
+---
+
+# Attribute Sets
+
+Attribute Sets group `ProductAttribute` definitions into reusable
+schemas. Every Product is wired to exactly one Attribute Set; the system
+ships a `default` set that applies when admins do not pick one.
+
+## Why they exist
+
+Without sets, every Product carries its full attribute graph in
+`attributeValues`. Different product types (electronics, apparel,
+chemicals) need different attributes, but the foundation schema
+treated every key as global. Sets let admins curate a focused authoring
+experience per category and let the storefront render a tighter
+attribute table.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/catalog/attribute-sets` | admin | List all sets including `default` |
+| `GET /api/v1/admin/catalog/attribute-sets/:id` | admin | Set detail with assigned attributes |
+| `POST /api/v1/admin/catalog/attribute-sets` | admin | Create custom set (`code` snake_case, unique) |
+| `PATCH /api/v1/admin/catalog/attribute-sets/:id` | admin | Update name; system Default is immutable |
+| `DELETE /api/v1/admin/catalog/attribute-sets/:id` | admin | Delete; rejects with 409 when any Product references the set |
+| `POST /api/v1/admin/catalog/attribute-sets/:id/attributes` | admin | Assign attributes to the set |
+| `DELETE /api/v1/admin/catalog/attribute-sets/:id/attributes/:key` | admin | Unassign |
+
+The Product create/update payload accepts `attributeSetId`. When
+omitted, the system Default Set is used.
+
+## Errors
+
+| Code | Status | When |
+| --- | --- | --- |
+| `ATTRIBUTE_SET_CODE_TAKEN` | 409 | `code` already exists |
+| `ATTRIBUTE_SET_IN_USE` | 409 | Delete blocked: at least one Product references the set |
+| `SYSTEM_ATTRIBUTE_SET_IMMUTABLE` | 409 | Mutating the seeded Default Set |
+| `ATTRIBUTE_SET_NOT_FOUND` | 404 | `:id` missing |
+| `ATTRIBUTE_NOT_FOUND` | 404 | `:key` missing on assignment |
+
+## Storefront integration
+
+`productDetail.attributeSet` carries `{id, code, name}` so themes can
+render the set label above the attribute table. Foundation reference
+theme renders the localized set name as a small subheading.
+
+## Storage
+
+`attribute_sets` (id, code unique, name jsonb, is_system bool) +
+`attribute_set_attributes` (composite PK on (set_id, attribute_id)).
+The system Default row is seeded by migration 017 with deterministic
+UUID `defa0017-0000-4000-8000-000000000000` so seeds and tests can
+reference it stably.
+
+## Audit log
+
+AttributeSet CRUD writes one `AuditLogEntry` per mutation with
+`stateBefore` and `stateAfter` so the audit page surfaces who changed
+what.

package/docs/catalog/attributes.md

@@ -0,0 +1,244 @@
+---
+title: Attributes
+---
+
+# Attributes
+
+An **Attribute** is a single named property that can be attached to a
+Product — `color`, `gear_ratio`, `material`, `weight`. Attributes
+are the lower-level primitive consumed by everything that decorates a
+product: the storefront filter sidebar, the PDP "Parametry produktu"
+tab, the Compare page, the Promotion Rule editor, the search index,
+and the configurable-product variant picker.
+
+Attributes are grouped into [Attribute Sets](./attribute-sets.md) which
+are then pinned to a Product so the admin editor renders just the
+fields that family actually needs. This page covers the attribute
+itself; the set ↔ product wiring lives on the Attribute Sets page.
+
+## Anatomy
+
+Every attribute carries:
+
+| Field | Purpose |
+| --- | --- |
+| `key` | Stable, URL-safe identifier — `^[a-z][a-z0-9_]*$`, unique platform-wide (case-insensitive). Used in filter URLs, search payloads, and the product JSONB key. |
+| `label` | `Record<bcp47-tag, string>` per-locale label map. |
+| `labelDefault` | Fallback label used when the active storefront / admin locale is missing from `label`. |
+| `valueType` | One of `string`, `number`, `boolean`, `price`, `date`, `select`, `multiselect`, `enum`. |
+| `options[]` | Ordered list of selectable options — only for `select` / `multiselect` / `enum`. See [Option lists](#option-lists) below. |
+
+Plus the behavioural flags and a numeric position:
+
+| Flag | Default | Consumed by |
+| --- | --- | --- |
+| `isFilterable` | `false` | Storefront filter sidebar |
+| `isSearchable` | `false` | Search indexer (Meilisearch) |
+| `isComparable` | `false` | Storefront Compare page |
+| `isVariantAxis` | `false` | Configurable-product variant picker |
+| `isRequired` | `false` | Product-save validator (only when the attribute is in the assigned Attribute Set) |
+| `isPromoRule` | `false` | Promotion Rule criterion picker |
+| `isVisibleOnProductPage` | `false` | PDP "Parametry produktu" tab |
+| `displayAsSlider` | `false` | Storefront sidebar — renders a range slider; only valid for `valueType ∈ ('number','price')` |
+| `filterPosition` | `0` | Storefront sidebar sort key (ascending; ties broken alphabetically by the resolved label) |
+
+## Value types
+
+| Type | Storage | Notes |
+| --- | --- | --- |
+| `string` | string | Free-text. |
+| `number` | number | Numeric; supports `displayAsSlider` for range filters. |
+| `boolean` | boolean | Two-state. |
+| `price` | number | Money amount — formatted in the active currency / locale. Supports `displayAsSlider`. |
+| `date` | ISO 8601 date string | |
+| `select` | option `value` | Single choice from `options[]`. At most one option may carry `isDefault = true`. |
+| `multiselect` | array of option `value`s | Multiple choices from `options[]`. Any number of options may carry `isDefault = true`. |
+| `enum` | option `value` | Same storage shape as `select`; renders as a compact pill / segmented control on storefront filters and the PDP rather than a dropdown. |
+
+Changing `valueType` while any product carries a value the new type
+cannot represent is refused with `attribute_type_change_unsafe`.
+
+## Option lists
+
+For `select` / `multiselect` / `enum` attributes the option list is
+authored inline on the attribute editor. Each option carries:
+
+| Field | Purpose |
+| --- | --- |
+| `value` | Stable identifier — `^[a-z0-9_-]{1,200}$`, unique within the attribute. Encoded into filter URLs and stored on every product that carries that value. |
+| `label` | `Record<bcp47-tag, string>` per-locale label map. |
+| `labelDefault` | Fallback label when the active locale is missing from `label`. |
+| `isDefault` | Optional pre-selection on new products. `select` / `enum` allow at most one; `multiselect` allows any number. |
+| `sortOrder` | Render order; ties broken by `value` ASC. |
+
+Option **values** are immutable while any product still carries them —
+the operator must migrate dependent values first. Option **labels** can
+always be renamed. Deleting an option is refused with
+`409 option_in_use` while any product still carries that value.
+
+## Public surface
+
+Admin routes are gated by `catalog:read` (list / get) /
+`catalog:write` (mutations).
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `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 flags + inline `options[]` for select-style types) |
+| `PATCH /api/v1/admin/catalog/attributes/:key` | admin | Update labels and 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 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 |
+
+Filter sidebar reads consume `GET /api/v1/catalog/filters` (defined on
+the [Catalog](../catalog.md) page) — that endpoint resolves the
+currently visible filterable attributes per Sales Channel and orders
+them by `filterPosition`.
+
+## Errors
+
+| Code | Status | When |
+| --- | --- | --- |
+| `attribute_key_invalid` | 400 | `key` does not match `^[a-z][a-z0-9_]*$` |
+| `duplicate_key` | 409 | Attribute key already exists (case-insensitive) |
+| `attribute_in_use_by_set` | 409 | Delete blocked: at least one Attribute Set still references the attribute |
+| `attribute_type_change_unsafe` | 409 | `valueType` change refused — some product carries a value the new type cannot represent |
+| `default_option_ambiguous` | 409 | More than one option flagged `isDefault = true` on a `select` / `enum` attribute |
+| `option_in_use` | 409 | Delete (or value rename) blocked: a product still carries this option value |
+| `attribute_not_found` | 404 | `:idOrKey` missing |
+| `option_not_found` | 404 | `:optionId` missing |
+
+## Storefront integration
+
+### Filter sidebar
+
+Category and search pages render a chip per `isFilterable` attribute
+that has at least one value across the currently visible products.
+Chips appear ordered by `filterPosition` ascending, ties broken
+alphabetically by the resolved per-locale label. Attributes with no
+values across the current page are omitted (no empty filter).
+
+### PDP "Parametry produktu" tab
+
+Every PDP carries a `Parametry produktu` tab that lists every
+attribute meeting both:
+
+- the product has a value for the attribute, **and**
+- the attribute is flagged `isVisibleOnProductPage = true`.
+
+For `select` / `multiselect` / `enum` values the tab renders the
+option's per-locale label, not the raw `value`. The detail payload
+field is assembled by `CatalogQueryService.buildVisibleAttributesProjection()`.
+
+### Search index
+
+Toggling `isSearchable` propagates into the Meilisearch indexer's
+payload on the next refresh cycle. Textual types (`string`, plus the
+option labels of `select` / `multiselect` / `enum`) feed the lexical
+and (when enabled) semantic index; numeric / boolean / price / date
+types feed range / exact-match filters.
+
+### Compare page
+
+Comparison rows on the storefront Compare page list every attribute
+flagged `isComparable = true` for which at least one product in the
+comparison carries a value. The list is sourced via
+`CatalogQueryService.comparableAttributeKeys()`.
+
+### Variant picker
+
+Configurable products expose a variant picker whose axes come from the
+attributes flagged `isVariantAxis = true` on the product's currently
+assigned Attribute Set.
+
+## Storage
+
+Since migration `102` an attribute is split between the
+generic Custom Fields layer that the `custom_fields` module owns and
+a catalog-owned extension row. The API shape above is unchanged — the
+admin surface composes the two back into the legacy form.
+
+`custom_field_definitions` (owned by `custom_fields`, rows with
+`entity_type = 'product'`):
+
+- `id uuid PK`, `key` (unique per entity type), `label jsonb`,
+  `label_default`, `value_type` (generic six-type set: `text` |
+  `number` | `boolean` | `date` | `select` | `multiselect`),
+  `required`, `sort_order`. The legacy eight-value `valueType` form is
+  derived bijectively from the generic type plus the extension
+  refinements below (`enum` = `select` + `select_display='pill'`,
+  `price` = `number` + `numeric_kind='price'`, ...).
+
+`custom_field_options` (owned by `custom_fields`):
+
+- Option rows keyed UNIQUE `(definition_id, value)` with per-locale
+  `label`, `label_default`, `is_default`, `sort_order`. The
+  catalog-owned `attribute_options` table (migration `032`) was dropped
+  by migration `102` after its rows moved here.
+
+`product_attributes` (owned by `catalog`) — the 1:1 **extension**:
+
+- `id uuid PK` (stable — admin API attribute ids survived the
+  migration), `custom_field_definition_id uuid NOT NULL UNIQUE` FK →
+  `custom_field_definitions.id` ON DELETE RESTRICT.
+- Boolean flags: `is_searchable`, `is_filterable`, `is_variant_axis`,
+  `is_comparable`, `quick_searchable`, `is_promo_rule`,
+  `is_visible_on_product_page`, `display_as_slider`,
+  `channel_scoped`, `language_scoped`, `mass_editable`.
+- `filter_position int NOT NULL DEFAULT 0`.
+- Presentation refinements: `select_display varchar(16) NULL`
+  (`pill` = legacy `enum`, `dropdown` = legacy `select`) and
+  `numeric_kind varchar(8) NULL` (`number` | `price`).
+- The duplicated definition columns (`key`, `label`, `label_default`,
+  `value_type`, `is_required`) were dropped by migration `102` — the
+  definition row is the single source of truth for them.
+
+`products.attribute_values jsonb` carries the per-product map keyed by
+attribute `key`; the values themselves have never moved out of it.
+Values are retained server-side even when the attribute leaves the
+product's currently assigned Attribute Set — switching back surfaces
+them again.
+
+All attribute and option mutations flow through the catalog Commands
+behind `/catalog/attributes` — the generic Custom Fields admin surface
+lists product definitions read-only and refuses mutations with
+`409 host_managed`.
+
+## Events emitted
+
+- `attribute.updated.v1` — picked up by the search indexer and
+  bridged to webhook subscribers.
+
+## Audit log
+
+Attribute and option CRUD writes one `AuditLogEntry` per mutation
+with `stateBefore` and `stateAfter` so the audit page surfaces who
+flipped which flag.
+
+## Cross-module consumers
+
+Three methods on `CatalogQueryService` are the documented service
+ports other modules call — a module never reaches into catalog
+internals:
+
+- `comparableAttributeKeys(): string[]` — the storefront Compare page.
+- `promoRuleAttributeKeys(): string[]` + `getAttributeWithOptions(key)`
+  — the Promotion Rule criterion picker and resolver.
+- `buildVisibleAttributesProjection()` — internal, used by the PDP
+  detail response to assemble the `visibleAttributes[]` payload.
+
+## See also
+
+- [Attribute Sets](./attribute-sets.md) — bundling attributes into
+  per-family schemas pinned to a Product.
+- [Catalog](../catalog.md) — the parent module, including the
+  storefront `GET /api/v1/catalog/filters` endpoint that consumes
+  `filterPosition`.
+- The `search` module's Meilisearch indexer, which consumes the
+  `isSearchable` flag.
+- The `promotions` module's Promotion Rule editor, which consumes the
+  `isPromoRule` flag.

package/docs/catalog/composite-products.md

@@ -0,0 +1,115 @@
+---
+title: Composite Products
+---
+
+# Composite Products: grouped, bundle, virtual
+
+The Catalog supports three product types beyond `simple` /
+`configurable`. Each carries a type-discriminated payload on the PDP
+and renders a dedicated component in the storefront's action zone.
+
+## Types
+
+### Grouped
+
+A parent product with a fixed list of child products at fixed
+quantities. The buyer cannot configure which children — they buy the
+whole set. Use case: "Starter kit" SKU that bundles two simple
+products at quantities 2 and 1.
+
+### Bundle
+
+A parent product with named slots, each with min / max quantity ranges
+and one or more option products to choose between. Use case:
+configurable workstation where the buyer picks a CPU (slot, min=1
+max=1) and add-on accessories (slot, min=0 max=3).
+
+### Virtual
+
+A digital product with `downloadAssetId` (server-hosted file) **or**
+`downloadUrl` (external link) — exactly one of the two MUST be set
+(Zod refine + service-layer guard). Use case: e-book PDF, license key
+fulfilment, link to a third-party download portal.
+
+## No nested composites
+
+A grouped product cannot include another grouped or bundle product as
+a child. A bundle's slot options cannot be grouped or bundle products
+either. The rule is enforced at the service layer because PostgreSQL
+CHECK constraints cannot JOIN `products` to inspect the foreign row's
+`type`. Surfaces as `NESTED_COMPOSITE_NOT_ALLOWED` (400).
+
+## Public surface
+
+### Admin
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET / POST / PATCH / DELETE /products/:id/grouped-items[/:itemId]` | Grouped CRUD |
+| `GET / POST / PATCH / DELETE /products/:id/bundle-slots[/:slotId]` | Bundle slot CRUD |
+| `POST / DELETE /products/:id/bundle-slots/:slotId/options[/:optionId]` | Slot option CRUD |
+
+### Storefront
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `POST /api/v1/catalog/products/:idOrSlug/bundle-configuration/validate` | Pure compute: validate a buyer's bundle configuration |
+
+The validation endpoint is the only POST on the public catalog surface.
+It returns `{valid, errors[], resolvedSelections}` rather than
+non-2xx — the storefront wants the structured error list so it can
+highlight every offending slot.
+
+## Validation errors (inside the response envelope)
+
+| Code | When |
+| --- | --- |
+| `MIN_NOT_MET` | Total selected qty for a slot < `minQuantity` |
+| `MAX_EXCEEDED` | Total selected qty for a slot > `maxQuantity` |
+| `UNKNOWN_OPTION` | `optionId` not part of the slot |
+
+HTTP-level rejections (400 `PRODUCT_TYPE_MISMATCH` when the product is
+not a bundle, 404 `PRODUCT_NOT_FOUND`) still apply.
+
+## CRUD-level errors
+
+| Code | Status | When |
+| --- | --- | --- |
+| `PRODUCT_TYPE_MISMATCH` | 400 | Calling grouped/bundle endpoints against the wrong parent type |
+| `NESTED_COMPOSITE_NOT_ALLOWED` | 400 | Child / option product is itself grouped or bundle |
+| `INVALID_QUANTITY_RANGE` | 400 | Slot `minQuantity > maxQuantity` |
+| `OPTION_ALREADY_EXISTS` | 409 | Same option product reused in a slot |
+| `GROUPED_ITEM_NOT_FOUND` | 404 | `:itemId` missing |
+| `BUNDLE_SLOT_NOT_FOUND` | 404 | `:slotId` missing |
+| `BUNDLE_SLOT_OPTION_NOT_FOUND` | 404 | `:optionId` missing |
+
+## Storefront integration
+
+`productDetail` carries one of three branches based on `type`:
+
+- `groupedItems[]` when type='grouped' — `{id, position, quantity, product{...}}`
+- `bundleSlots[]` when type='bundle' — `{id, name, minQuantity, maxQuantity, position, options: [{id, defaultQuantity, position, product{...}}]}`
+- `virtual` when type='virtual' — `{downloadAssetId, downloadUrl}`
+
+The PDP type-switches the action zone:
+
+| `product.type` | Component | UX |
+| --- | --- | --- |
+| `simple`, `configurable` | legacy Add-to-cart + RFQ + VariantPicker | unchanged |
+| `grouped` | `<GroupedSummary>` | Read-only list + "Add bundle to cart" CTA |
+| `bundle` | `<BundleConfigurator>` | Per-slot select + qty input; CTA disabled when any slot is required |
+| `virtual` | `<VirtualCta>` | "Buy and download" CTA + delivery copy |
+
+## Storage
+
+- `grouped_items` (id, parent_product_id FK CASCADE, child_product_id
+  FK RESTRICT, quantity, position; UNIQUE (parent, child); CHECK
+  `quantity > 0` + `parent <> child`)
+- `bundle_slots` (id, parent_product_id FK CASCADE, name jsonb,
+  minQuantity / maxQuantity int; CHECK `min_quantity <= max_quantity` +
+  `min_quantity >= 0` + `max_quantity > 0`)
+- `bundle_slot_options` (id, slot_id FK CASCADE, option_product_id FK
+  RESTRICT, default_quantity, position; UNIQUE (slot, option_product))
+
+Virtual download fields live on the `products` table itself:
+`download_asset_id` FK nullable + `download_url` varchar nullable.

package/docs/catalog/gallery-and-labels.md

@@ -0,0 +1,73 @@
+---
+title: Product Gallery
+---
+
+# Product Gallery
+
+Each Product can carry a curated gallery of image and video Assets, with
+three labels that pin the storefront's resolution chain:
+
+- **Base Image** — the primary hero shown on the PDP. Exactly one per Product.
+- **Small Image** — emphasized in the thumbnail strip. Exactly one per Product.
+- **Thumbnail** — the listing-card image. Exactly one per Product.
+
+Each Gallery Item can carry **one to three** of these labels (the same
+asset can be both Base Image and Thumbnail, for example). The "exactly
+one per Product per label" invariant is enforced by a database
+`UNIQUE (product_id, label)` constraint, so collisions surface as a
+typed conflict error rather than silent data corruption.
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/admin/catalog/products/:id/gallery` | admin | List the Product's gallery |
+| `POST /api/v1/admin/catalog/products/:id/gallery` | admin | Attach an existing image/video Asset with optional labels |
+| `POST .../gallery?replace=true` | admin | Atomic-swap: remove conflicting labels from other items in this Product, then assign |
+| `PATCH /api/v1/admin/catalog/products/:id/gallery/:itemId` | admin | Update labels (same `?replace=true` toggle) |
+| `DELETE /api/v1/admin/catalog/products/:id/gallery/:itemId` | admin | Remove from gallery (Asset row survives) |
+| `PUT /api/v1/admin/catalog/products/:id/gallery/order` | admin | Reorder by id list |
+
+## Atomic label swap
+
+Without the `?replace=true` query, assigning a label that already exists
+on another item returns `409 GALLERY_LABEL_ALREADY_TAKEN`. With it, the
+service drops the conflicting assignments first then inserts the new
+one — all in a single transaction, so concurrent admins never see a
+half-applied state.
+
+## Errors
+
+| Code | Status | When |
+| --- | --- | --- |
+| `GALLERY_LABEL_ALREADY_TAKEN` | 409 | Label conflict without `?replace=true` |
+| `GALLERY_LABEL_LIMIT_EXCEEDED` | 400 | More than 3 labels on a single item |
+| `ASSET_KIND_NOT_SUPPORTED` | 400 | Asset kind ∉ `{image, video}` |
+| `GALLERY_ITEM_NOT_FOUND` | 404 | `:itemId` missing |
+| `PRODUCT_NOT_FOUND` | 404 | `:id` missing |
+
+## Storefront integration
+
+`productDetail.gallery[]` carries `{id, position, labels[], asset{id, kind, url}}`.
+The `<GallerySwitcher>` component renders the Base Image as the primary
+`<img>` (or the first item if no Base Image is set) and emits a thumbnail
+strip with the Small Image marked via `data-small-image="true"` for
+themes to highlight.
+
+## Listing card thumbnail resolution
+
+`ProductSummary.primaryAssetUrl` (used by the listing card) is resolved
+server-side via the chain: Thumbnail → Base Image → first gallery item
+→ legacy `product_assets` row → null.
+
+## OG image resolution
+
+`productDetail.seo.openGraph.imageUrl` prefers the gallery's Base Image
+over the listing thumbnail so social shares get the marketer's hero shot.
+
+## Storage
+
+`gallery_items` (id, product_id FK CASCADE, asset_id FK RESTRICT,
+position, timestamps) + `gallery_item_labels` (composite PK on
+(gallery_item_id, label), `UNIQUE (product_id, label)`, CHECK label IN
+('base_image', 'small_image', 'thumbnail')).