@endora-commerce/mod-comparisons 0.0.0-stage → 0.100.0

package/dist/migrations/20260830T163143_comparisons_organization_attribution.js

@@ -0,0 +1,147 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * D-187 — `comparisons` gains its organisation, and a row that names a customer
+ * account carries one.
+ *
+ * Feature 087 Group B, class 1 of 4. `Comparison` is `@CustomerScoped`, and
+ * until this migration the `allowed-set` arm of `customerFilterCond` had no
+ * column to grant on: a sales representative assigned to the buyer's own
+ * organisation was shown **none** of their comparisons and told so, through the
+ * `ORGANIZATION_ATTRIBUTION_PENDING` notice the refusing arm records. The
+ * column is what turns that into an answer.
+ *
+ * ## The column and the read arrive together, on purpose
+ *
+ * `customerOrganizationColumn` asks the ORM's own metadata whether the filtered
+ * entity carries `organizationId`, **per query**, so the entity property in
+ * this same merge request is what switches the grant on — there is no third
+ * artefact, no flag and no staging. At the same instant the notice retires
+ * itself: it is keyed on the column's *absence*.
+ *
+ * That pairing is why this migration is not "column and backfill". From the
+ * moment the grant is live, a row inserted without an organisation is invisible
+ * to the representative who serves that organisation, on a screen that has just
+ * stopped explaining itself — and MikroORM applies no filter to `INSERT`
+ * (`r1-spike.md` §4, measured), so the filter cannot refuse it. The `CHECK`
+ * below is the only refusal an `INSERT` has.
+ *
+ * ## An implication, not an equivalence
+ *
+ * `customer_account_id is null or organization_id is not null` is FR-010 and
+ * FR-011 together and nothing wider: an **owned** row has an organisation, an
+ * **ownerless** row need not. Half of this table is ownerless by construction —
+ * `comparisons_owner_xor_chk` makes every row that is not owned an anonymous
+ * one — and who an anonymous comparison belongs to is R-6's open question. The
+ * equivalence would answer it in the schema, which D-187 declines to do.
+ *
+ * ## No foreign key
+ *
+ * Matching `Cart`, which carries none. D-187 withdraws `r1-spike.md` §8's
+ * `on delete set null` recommendation as contradicting FR-011: it produces a
+ * row that names an account and no organisation, which is precisely the state
+ * this migration makes unreachable, and under the constraint below it would
+ * abort an unrelated organisation delete with a message about a table the
+ * operator was not touching. If one is ever taken here it must be `restrict`,
+ * and it is not this migration's decision.
+ *
+ * ## Derive, then count, then refuse — never delete
+ *
+ * The derivation is the owning account's own organisation, and on **this**
+ * table it is total by proof rather than by hope.
+ * `comparisons_customer_account_fk` is `on delete cascade`, so a row naming an
+ * account that is gone cannot exist; `comparisons_owner_xor_chk` makes every
+ * other row anonymous; and D-178 made `customer_accounts.organization_id`
+ * `NOT NULL`. *Derivable ⟺ has an account* is a theorem here, and the refusal
+ * branch is dead code the day it is written.
+ *
+ * It is written anyway, and that is the point of writing it: a proof that stops
+ * being true stops **silently**. Drop the foreign key, relax the XOR, or
+ * re-open D-178, and the count below is the only thing that would notice. It
+ * raises with the count and up to twenty ids and deletes nothing (D-184), in
+ * the shape `20260825T141659_customer_accounts_organization_required.ts`
+ * established and `20260830T112911_carts_organization_attribution_check.ts`
+ * repeated.
+ *
+ * ## Nothing to declare in the manifest
+ *
+ * `comparisons` already declares `organizations`, whose own
+ * `20260424T205317_organizations_init.ts` creates `customer_accounts` — far
+ * below `BASELINE_THROUGH`, so the table this reads exists whatever this
+ * module's position in the dependency order. No foreign key is added, so
+ * `fk-dependency-drift` has nothing to say either, and a migration naming
+ * another module's table is outside `check:module-boundary`'s population by
+ * that check's own rule.
+ *
+ * The standing guard is
+ * `backend/test/integration/tenancy/customer-scoped-organization-completeness.test.ts`,
+ * which derives its population from the ORM's metadata rather than from a list
+ * — so this class is covered by gaining the column, with no edit to that file.
+ */
+export class Migration20260830T163143ComparisonsOrganizationAttribution extends Migration {
+    async up() {
+        // 1. The column. Nullable, because an anonymous comparison legitimately has
+        //    none (FR-011) and this table is half anonymous by construction.
+        this.addSql(`alter table "comparisons" add column "organization_id" uuid null;`);
+        // 2. Derive the organisation from the account that owns the comparison.
+        //    Total on this table: the foreign key cascades, so an account named
+        //    here exists, and its own organisation is NOT NULL since D-178.
+        this.addSql(`
+      update "comparisons" c
+      set "organization_id" = ca."organization_id"
+      from "customer_accounts" ca
+      where ca."id" = c."customer_account_id"
+        and c."organization_id" is null;
+    `);
+        // 3. Count what is left and refuse. Provably empty today — see the block
+        //    comment. It runs because the proof rests on three facts none of which
+        //    this migration owns, and a proof that stops being true stops without
+        //    saying so.
+        this.addSql(`
+      do $$
+      declare
+        remaining bigint;
+        sample text;
+      begin
+        select count(*) into remaining
+          from "comparisons"
+         where "customer_account_id" is not null
+           and "organization_id" is null;
+        if remaining > 0 then
+          select string_agg(id::text, ', ') into sample from (
+            select "id" from "comparisons"
+             where "customer_account_id" is not null
+               and "organization_id" is null
+             order by "id" limit 20
+          ) s;
+          raise exception
+            'D-187: % comparisons row(s) still name a customer account with organization_id IS NULL after derivation. First ids: %. Every customer account has an organization (D-178) and this table cascades on account delete, so these rows contradict the schema. Do not delete them - find out how they got here.',
+            remaining, sample;
+        end if;
+      end $$;
+    `);
+        // 4. The constraint.
+        this.addSql(`
+      alter table "comparisons"
+        add constraint "comparisons_organization_attribution_chk"
+        check ("customer_account_id" is null or "organization_id" is not null);
+    `);
+        // 5. The index the entity property declares. Partial, like the two owner
+        //    indexes the init migration writes: the column is null on every
+        //    anonymous row, and the reader is an organisation-scoped list.
+        this.addSql(`
+      create index "idx_comparisons_organization"
+        on "comparisons" ("organization_id")
+        where "organization_id" is not null;
+    `);
+    }
+    async down() {
+        // The constraint, the index and the column. The organisations step 2
+        // derived go with the column they were written into — there is nothing to
+        // preserve, because each of them was already implied by the account its row
+        // names.
+        this.addSql(`alter table "comparisons" drop constraint if exists "comparisons_organization_attribution_chk";`);
+        this.addSql(`drop index if exists "idx_comparisons_organization";`);
+        this.addSql(`alter table "comparisons" drop column if exists "organization_id";`);
+    }
+}
+//# sourceMappingURL=20260830T163143_comparisons_organization_attribution.js.map

package/dist/migrations/20260830T163143_comparisons_organization_attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260830T163143_comparisons_organization_attribution.js","sourceRoot":"","sources":["../../src/migrations/20260830T163143_comparisons_organization_attribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,MAAM,OAAO,0DAA2D,SAAQ,SAAS;IAC9E,KAAK,CAAC,EAAE;QACf,4EAA4E;QAC5E,qEAAqE;QACrE,IAAI,CAAC,MAAM,CAAC,mEAAmE,CAAC,CAAC;QAEjF,wEAAwE;QACxE,wEAAwE;QACxE,oEAAoE;QACpE,IAAI,CAAC,MAAM,CAAC;;;;;;KAMX,CAAC,CAAC;QAEH,yEAAyE;QACzE,2EAA2E;QAC3E,0EAA0E;QAC1E,gBAAgB;QAChB,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;KAsBX,CAAC,CAAC;QAEH,qBAAqB;QACrB,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QAEH,yEAAyE;QACzE,oEAAoE;QACpE,mEAAmE;QACnE,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,qEAAqE;QACrE,0EAA0E;QAC1E,4EAA4E;QAC5E,SAAS;QACT,IAAI,CAAC,MAAM,CACT,iGAAiG,CAClG,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,sDAAsD,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,oEAAoE,CAAC,CAAC;IACpF,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260501T185834ComparisonsInit } from './20260501T185834_comparisons_init.js';
+import { Migration20260830T163143ComparisonsOrganizationAttribution } from './20260830T163143_comparisons_organization_attribution.js';
+export declare const migrations: (typeof Migration20260501T185834ComparisonsInit)[];
+export { Migration20260501T185834ComparisonsInit, Migration20260830T163143ComparisonsOrganizationAttribution, };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,uCAAuC,EAAE,MAAM,uCAAuC,CAAC;AAChG,OAAO,EAAE,0DAA0D,EAAE,MAAM,2DAA2D,CAAC;AAEvI,eAAO,MAAM,UAAU,oDAGtB,CAAC;AAEF,OAAO,EACL,uCAAuC,EACvC,0DAA0D,GAC3D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,31 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260501T185834ComparisonsInit } from './20260501T185834_comparisons_init.js';
+import { Migration20260830T163143ComparisonsOrganizationAttribution } from './20260830T163143_comparisons_organization_attribution.js';
+export const migrations = [
+    Migration20260501T185834ComparisonsInit,
+    Migration20260830T163143ComparisonsOrganizationAttribution,
+];
+export { Migration20260501T185834ComparisonsInit, Migration20260830T163143ComparisonsOrganizationAttribution, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,uCAAuC,EAAE,MAAM,uCAAuC,CAAC;AAChG,OAAO,EAAE,0DAA0D,EAAE,MAAM,2DAA2D,CAAC;AAEvI,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,uCAAuC;IACvC,0DAA0D;CAC3D,CAAC;AAEF,OAAO,EACL,uCAAuC,EACvC,0DAA0D,GAC3D,CAAC"}

package/docs/comparisons.md

@@ -0,0 +1,278 @@
+---
+title: Compare Products
+description: 'Compare Products: customer-curated set with display modes, share link, and PDF export'
+---
+
+# Compare Products
+
+Customer-facing product-comparison module. Owns a first-class
+`Comparison` resource (a customer-curated set of products with a chosen
+display mode and a stable shareable link), an admin observability
+surface, and the Node-side PDF export. The module deliberately holds no
+catalog data; it consumes products and the `is_comparable` attribute
+flag through the `CatalogQueryService` port.
+
+This page is written for two audiences:
+
+- **Buyers and platform administrators** who want to see *what* the
+  feature does (sections "What a buyer does", "What an administrator
+  sees", "What an administrator configures").
+- **Developers** who need to extend or operate the module (every
+  section after "Public surface").
+
+## What a buyer does
+
+### 1. Pick products to compare
+
+On any catalog list page or product detail page, click **Compare** on
+the product card. The button toggles — click it again to remove the
+product from the comparison set. A header pill (**Compare (N)**) shows
+how many products you have queued.
+
+The first time you mark a product, the storefront opens a session for
+your comparison. You don't need to be signed in.
+
+### 2. Open the comparison page
+
+Click the header pill, or navigate to `/compare`. You'll see a
+side-by-side table:
+
+- The header row always shows each product's **name**, **price** in
+  your sales-channel currency, and **base image**.
+- The body shows every comparable attribute the catalog administrator
+  has flagged for comparison (weight, material, dimensions, etc. —
+  varies per category).
+
+### 3. Switch the view
+
+The toolbar above the table has three buttons:
+
+- **All attributes** — shows everything; rows that are identical
+  across products are highlighted with a calmer styling, rows that
+  differ stand out.
+- **Common attributes only** — shows only the rows where every product
+  agrees, so you can confirm the baseline.
+- **Differences only** — shows only the rows where at least one
+  product disagrees, so the decision-relevant signal stands out.
+
+Switching is instantaneous — no reload.
+
+### 4. Share with a colleague
+
+Click **Copy share link**. The storefront writes a URL of the form
+`https://your-store/compare/share/<token>` to your clipboard. Anyone
+who opens that link sees the same comparison — without needing an
+account, and without being able to change anything. They can switch
+modes themselves (locally), but they cannot remove products, delete the
+comparison, or use *Add to cart*.
+
+The link works as long as the comparison exists. If you delete the
+comparison, the link stops working for everyone.
+
+**What the recipient sees is decided by who the recipient is**, not by
+who sent the link. A share link grants access to the comparison, never
+to anything in it:
+
+- **Prices** — a signed-in recipient sees the prices agreed with *their*
+  organization, and a recipient who is not signed in sees the store's
+  standard prices. Your negotiated prices are never disclosed by a link
+  you send, and the page says whose prices it is showing.
+- **Products** — if your comparison holds a product that is restricted
+  to your organization, a recipient outside it does not see that column.
+  The page tells them that something is not available to them rather
+  than quietly showing a shorter table. A recipient whose own
+  organization is allowed to see the product sees it normally.
+
+### 5. Add a chosen product to the cart
+
+Once you've decided, click **Add to cart** on the chosen product's
+column. The cart picks up the product subject to the same rules as if
+you'd added it from the product page (channel availability, stock).
+The comparison itself stays intact.
+
+### 6. Export to PDF
+
+Click **Export to PDF**. The storefront downloads a PDF named
+`comparison-<token>.pdf` that mirrors what's on screen — same
+products, same display mode, same column order. The PDF is generated
+fresh each time; switching the display mode and re-exporting produces
+a new file with the new mode.
+
+PDFs of three or more products land in landscape orientation; one or
+two products land in portrait.
+
+### 7. Tidy up
+
+When you're done, click **Delete comparison**. The set is cleared and
+any shared links you sent stop resolving.
+
+## Limits and edge cases
+
+- **Maximum products per comparison** — defaults to **4**. Your
+  platform operator can raise or lower this per sales channel via
+  Settings (`compare.max_products`). The eleventh add — or whichever
+  one exceeds the configured cap — is refused with a message; the
+  existing comparison stays unchanged.
+- **Removing a product** — drops a column. The remaining columns
+  recompute which rows count as common vs. different.
+- **One product in the set** — the page renders, but suggests adding
+  at least one more product to draw a meaningful comparison.
+- **Empty set** — the page invites you to add products from the
+  catalog.
+- **Product disappears from the catalog** — if a product is unpublished
+  while it is in your comparison, the column stays but is marked
+  unavailable; *Add to cart* is disabled for that column.
+- **Shared link in a different sales channel** — recipients see prices
+  in their own channel currency, and any product that isn't sold in
+  their channel still appears but is marked unavailable.
+- **Shared link opened by a buyer from another organization** — the
+  columns are re-priced for that buyer's own agreements, and any product
+  they are not entitled to see is left out with a note saying so.
+- **Multi-value attributes** — two products are treated as agreeing on
+  a multi-value attribute (e.g. a list of certifications) only when
+  their full sets of values match.
+- **Missing values** — a product without a value for a row renders an
+  `—`, and the row counts as a difference.
+
+## What an administrator sees
+
+Open **Comparisons** in the admin sidebar. The list shows every
+comparison every customer has built, with the customer's email (or
+*Anonymous* for unsigned-in builders), the sales channel, the active
+display mode, the product count, and the creation time. Filter by
+channel, owner kind, or time range; sort is newest-first by default.
+
+Click a row to open the detail view. You'll see every product and
+attribute row the customer put in the comparison — including products
+restricted to organizations other than theirs — projected through that
+customer's sales channel. **The prices here are the channel's standard
+prices, not the customer's negotiated ones**: the comparison prices for
+whoever is looking at it, and an administrator has no buying
+organization to price against. The screen says so, so a figure quoted
+back to a customer is never mistaken for the figure they were shown.
+There are no edit, delete, or share buttons on the admin view by design
+(it is read-only audit, not a tool to alter customer state).
+
+If a customer deletes their comparison on the storefront, the row
+disappears from the admin list on the next refresh.
+
+## What an administrator configures
+
+| Where | What |
+| --- | --- |
+| **Catalog → Attributes**, the `Comparable` checkbox | Picks which attributes appear as rows on the comparison page. Independent of `Searchable` / `Filterable`. |
+| **Settings → Compare**, the `compare.max_products` setting | The per-channel cap on how many products a single comparison can hold. |
+
+## Why this exists
+
+In B2B procurement, a buyer rarely chooses alone — engineers, finance
+folk, and managers all weigh in. Building a comparison once, sharing
+the link, and exporting a PDF for archival is what the feature is for.
+The admin view exists so the platform team can investigate support
+tickets that quote a shared link.
+
+---
+
+## Public surface
+
+| Verb + Path | Audience | Purpose |
+| --- | --- | --- |
+| `GET /api/v1/comparisons/me` | storefront (anonymous or customer) | Read the caller's Comparison; `204 No Content` when none |
+| `POST /api/v1/comparisons/me/products` | storefront | Add a product (creates the Comparison + `compare_token` cookie on first call); refuses with `409 COMPARISON_FULL` over the channel-resolved cap |
+| `DELETE /api/v1/comparisons/me/products/:productId` | storefront | Remove a product; `404 PRODUCT_NOT_IN_COMPARISON` if absent |
+| `PATCH /api/v1/comparisons/me` | storefront | Update the persisted display mode (`all` / `common` / `differences`) |
+| `DELETE /api/v1/comparisons/me` | storefront | Hard-delete the Comparison; the share token stops resolving for everyone |
+| `GET /api/v1/comparisons/me/pdf` | storefront (owner only) | Owner PDF export; PDF mirrors the active mode and embeds product base images; `409 COMPARISON_EMPTY` for a zero-product comparison |
+| `GET /api/v1/comparisons/share/:token` | public, no auth | Recipient view; same shape as the owner read minus `maxProducts`, plus `meta.viewerIsOwner`; priced and filtered for the *recipient* (`data.pricedFor`, `data.hiddenProductCount`); `404 COMPARISON_NOT_FOUND` for a deleted/never-existed token |
+| `GET /api/v1/admin/comparisons` | admin (`comparisons:read`) | List every Comparison with filters (channel, owner kind, time range) and cursor pagination |
+| `GET /api/v1/admin/comparisons/:id` | admin (`comparisons:read`) | Read-only detail; rendered through the comparison's recorded sales channel so the view matches what the customer reported |
+
+There is **no** comparisons-side cart proxy. The storefront's
+*Add to cart* button on the comparison page calls the existing
+`POST /api/v1/cart/items` directly.
+
+## Settings
+
+One knob under the `compare` group, registered by
+`packages/modules/comparisons/src/manifest.ts`:
+
+| Code | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `compare.max_products` | `number` | `4` | Upper bound on a single Comparison; the store-front refuses to add the (max+1)-th product per channel. Sane range `1..16`. |
+
+The bound is read at request time inside
+`ComparisonService.addProduct(...)`. Lowering the cap mid-session does
+**not** retroactively trim existing comparisons; the next add is the
+first request that picks up the new value.
+
+## Catalog flag
+
+The module relies on a new `is_comparable` boolean column on
+`product_attributes`. Catalog owns the column (migration `028` lives
+under `catalog/migrations/`); the comparisons module reads it through
+`CatalogQueryService.comparableAttributeKeys()`.
+
+The Catalog admin UI's `<AttributesManager>` exposes a `Comparable`
+checkbox alongside `Searchable` and `Filterable`; toggling it has no
+side effect (no event emission, no reindex) — the next comparison-page
+render picks up the change directly from Postgres.
+
+## Storage
+
+Two tables, both owned by the comparisons module
+(`027_comparisons_init.ts`):
+
+- `comparisons` — primary key, 22-char base64url `share_token`
+  (`UNIQUE`), exclusive owner column (`customer_account_id` *or*
+  `anonymous_token`; DB CHECK enforces XOR), `sales_channel_id` (FK
+  with `ON DELETE RESTRICT`), `display_mode`, `created_at`,
+  `updated_at`. Partial indexes on each owner column; a separate index
+  on `(sales_channel_id, created_at desc)` supports the admin overview
+  channel filter.
+- `comparison_products` — composite PK on
+  `(comparison_id, product_id)`, `position` (smallint), `added_at`.
+  Both FKs cascade. Reverse index on `product_id` for the admin list's
+  product-count aggregate.
+
+No soft-delete. A deleted comparison must resolve to a
+clear "no longer exists" state for shared-link recipients — a missing
+row + `404 COMPARISON_NOT_FOUND` already satisfies that without a
+soft-delete bit.
+
+## Anonymous → authenticated identity
+
+Anonymous customers carry the `compare_token` cookie (HttpOnly,
+SameSite=Lax, Path=/, Max-Age = 1 year). At sign-in the existing
+`onLogin` hook in `organizationsModule` extracts the cookie and calls
+`ComparisonService.adoptAnonymousComparison(...)`:
+
+- Customer with no Comparison → the anonymous one is reassigned
+  (`customer_account_id` set, `anonymous_token` cleared).
+- Customer with an existing Comparison → the anonymous one is hard-
+  deleted; the customer's curated set wins.
+
+## PDF export
+
+Generated server-side with `pdfmake` — the module's only new runtime
+dependency. Document definition is built declaratively from `ComparisonOwnerView`; product
+base images are pre-fetched by `AssetByteFetcher` (per-request cache,
+1×1 transparent PNG fallback) and embedded as data URIs. Page
+orientation is landscape when product count ≥ 3, portrait otherwise.
+
+A strict deny-all `setUrlAccessPolicy` pins the contract that pdfmake
+never opens its own network sockets — every image reaches the document
+through the AssetByteFetcher.
+
+## Module isolation
+
+| Direction | What we depend on | How |
+| --- | --- | --- |
+| Reads | Catalog products and `is_comparable` flag | `CatalogQueryService.comparableAttributeKeys()` + entity reads via the EM |
+| Reads | `compare.max_products` | `SettingsService.get(...)` — same shape Search uses |
+| Reads | Sales channel context (currency, public flag) | `getResolvedChannel()` — the channel the resolver middleware put on the request scope |
+| Reads | Customer email for the admin list | `CustomerAccount` entity — read-only join |
+| Writes | None outside its own two tables | — |
+
+The comparisons module has zero compile-time dependencies on the
+`carts` module. Removing the comparisons module leaves catalog,
+settings, sales_channels, and carts working — no dangling references.

package/i18n/en.json

@@ -0,0 +1,51 @@
+{
+  "errors.COMPARISON_FULL": "Comparison Full.",
+  "errors.COMPARISON_NOT_FOUND": "Comparison Not Found.",
+  "errors.COMPARISON_EMPTY": "Comparison Empty.",
+  "errors.PDF_GENERATION_FAILED": "Pdf Generation Failed.",
+  "error.load": "Failed to load.",
+  "common.loading": "Loading…",
+  "list.page.title": "Comparisons",
+  "list.page.description": "Read-only audit of every comparison generated on the storefront.",
+  "list.filter.salesChannelId": "Sales channel id",
+  "list.filter.uuidOptional": "uuid (optional)",
+  "list.filter.owner": "Owner",
+  "list.filter.createdAfter": "Created after",
+  "list.filter.createdBefore": "Created before",
+  "list.empty": "No comparisons match the filters.",
+  "list.column.owner": "Owner",
+  "list.column.salesChannel": "Sales channel",
+  "list.column.mode": "Mode",
+  "list.column.products": "Products",
+  "list.column.created": "Created",
+  "list.column.open": "Open",
+  "list.loadMore": "Load more",
+  "detail.page.title": "Comparison detail",
+  "detail.page.description": "Read-only view — what the customer is currently seeing.",
+  "detail.pricesNote": "Prices here are the sales channel’s standard prices, not the customer’s negotiated ones — the customer sees their own. Products restricted to other organizations are listed here in full.",
+  "detail.backToList": "Back to list",
+  "detail.owner": "Owner",
+  "detail.salesChannel": "Sales channel",
+  "detail.displayMode": "Display mode",
+  "detail.shareToken": "Share token",
+  "detail.created": "Created",
+  "detail.updated": "updated",
+  "detail.attribute": "Attribute",
+  "detail.noComparableAttributes": "No comparable attributes defined for this catalog.",
+  "owner.any": "Any",
+  "owner.customer": "Customer",
+  "owner.anonymous": "Anonymous",
+  "owner.noEmail": "(no email)",
+  "owner.noEmailOnFile": "(no email on file)",
+  "owner.anonymousWithToken": "Anonymous ({token})",
+  "displayMode.full": "Full",
+  "displayMode.compact": "Compact",
+  "displayMode.differences_only": "Differences only",
+  "displayMode.differencesOnly": "Differences only",
+  "displayMode.all": "All attributes",
+  "displayMode.common": "Common attributes",
+  "displayMode.differences": "Differences",
+  "nav.comparisons.label": "Comparisons",
+  "actions.openComparisons.label": "Comparisons",
+  "actions.openComparisons.description": "Compare-feature audit"
+}

package/i18n/pl.json

@@ -0,0 +1,51 @@
+{
+  "errors.COMPARISON_FULL": "Błąd: comparison full.",
+  "errors.COMPARISON_NOT_FOUND": "Błąd: comparison not found.",
+  "errors.COMPARISON_EMPTY": "Błąd: comparison empty.",
+  "errors.PDF_GENERATION_FAILED": "Błąd: pdf generation failed.",
+  "error.load": "Nie udało się wczytać.",
+  "common.loading": "Wczytywanie…",
+  "list.page.title": "Porównania",
+  "list.page.description": "Tylko-do-odczytu audyt wszystkich porównań wygenerowanych w sklepie.",
+  "list.filter.salesChannelId": "Id kanału sprzedaży",
+  "list.filter.uuidOptional": "uuid (opcjonalnie)",
+  "list.filter.owner": "Właściciel",
+  "list.filter.createdAfter": "Utworzone po",
+  "list.filter.createdBefore": "Utworzone przed",
+  "list.empty": "Żadne porównanie nie pasuje do filtrów.",
+  "list.column.owner": "Właściciel",
+  "list.column.salesChannel": "Kanał sprzedaży",
+  "list.column.mode": "Tryb",
+  "list.column.products": "Produkty",
+  "list.column.created": "Utworzono",
+  "list.column.open": "Otwórz",
+  "list.loadMore": "Wczytaj więcej",
+  "detail.page.title": "Szczegóły porównania",
+  "detail.page.description": "Widok tylko do odczytu — to, co aktualnie widzi klient.",
+  "detail.pricesNote": "Ceny w tym widoku to ceny standardowe kanału sprzedaży, a nie ceny wynegocjowane przez klienta — klient widzi swoje. Produkty ograniczone do innych organizacji są tutaj pokazane w całości.",
+  "detail.backToList": "Wróć do listy",
+  "detail.owner": "Właściciel",
+  "detail.salesChannel": "Kanał sprzedaży",
+  "detail.displayMode": "Tryb wyświetlania",
+  "detail.shareToken": "Token udostępniania",
+  "detail.created": "Utworzono",
+  "detail.updated": "zaktualizowano",
+  "detail.attribute": "Atrybut",
+  "detail.noComparableAttributes": "Brak porównywalnych atrybutów dla tego katalogu.",
+  "owner.any": "Dowolny",
+  "owner.customer": "Klient",
+  "owner.anonymous": "Anonimowy",
+  "owner.noEmail": "(brak e-maila)",
+  "owner.noEmailOnFile": "(brak e-maila w kartotece)",
+  "owner.anonymousWithToken": "Anonimowy ({token})",
+  "displayMode.full": "Pełny",
+  "displayMode.compact": "Kompaktowy",
+  "displayMode.differences_only": "Tylko różnice",
+  "displayMode.differencesOnly": "Tylko różnice",
+  "displayMode.all": "Wszystkie atrybuty",
+  "displayMode.common": "Wspólne atrybuty",
+  "displayMode.differences": "Różnice",
+  "nav.comparisons.label": "Porównania",
+  "actions.openComparisons.label": "Porównania",
+  "actions.openComparisons.description": "Audyt porównań"
+}