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

package/dist/manifest.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Built-in settings manifest for the comparisons module — feature 007.
+ *
+ * Reserves the `compare` group. The single `compare.max_products`
+ * setting is added in T013 (foundational), so US1 has a real cap to
+ * read from day one. Range bounds (`1..16`) are enforced by
+ * `ComparisonService.addProduct(...)` per research.md R-7, not by the
+ * manifest — the Settings module's value-type registry only recognises
+ * primitive shapes.
+ */
+export declare const COMPARE_SETTING_CODES: {
+    readonly MAX_PRODUCTS: "compare.max_products";
+};
+export declare const DEFAULT_COMPARE_MAX_PRODUCTS = 4;
+/** Module-lifecycle manifest (feature 018). */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("email" | "invoice" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("email" | "invoice" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+/** Legacy export retained for backward compatibility. */
+export declare const comparisonsManifest: {
+    moduleCode: string;
+    groups: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[] | undefined;
+        isSystemProtected?: boolean | undefined;
+    }[];
+    settings: {
+        code: string;
+        name: string;
+        valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+        defaultValue: unknown;
+        description?: string | undefined;
+        groupCode?: string | undefined;
+        previousDefaultValues?: unknown[] | undefined;
+        salesChannelCodes?: string[] | undefined;
+        enumOptions?: string[] | undefined;
+        configurationType?: string | undefined;
+        hidden?: boolean | undefined;
+    }[];
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;CAExB,CAAC;AAEX,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAiC9C,+CAA+C;AAC/C,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoInB,CAAC;AAEH,yDAAyD;AACzD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;CAAW,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,179 @@
+import { defineModuleManifest, defineModuleSettingsManifest, } from '@endora-commerce/contracts';
+/**
+ * Built-in settings manifest for the comparisons module — feature 007.
+ *
+ * Reserves the `compare` group. The single `compare.max_products`
+ * setting is added in T013 (foundational), so US1 has a real cap to
+ * read from day one. Range bounds (`1..16`) are enforced by
+ * `ComparisonService.addProduct(...)` per research.md R-7, not by the
+ * manifest — the Settings module's value-type registry only recognises
+ * primitive shapes.
+ */
+export const COMPARE_SETTING_CODES = {
+    MAX_PRODUCTS: 'compare.max_products',
+};
+export const DEFAULT_COMPARE_MAX_PRODUCTS = 4;
+const settings = defineModuleSettingsManifest({
+    moduleCode: 'comparisons',
+    groups: [
+        {
+            code: 'compare',
+            name: 'Compare',
+        },
+    ],
+    settings: [
+        {
+            // Feature 073 — the operator's activation control. Platform-wide.
+            code: 'comparisons.enabled',
+            name: 'Product comparison enabled',
+            description: 'Switches the product-comparison feature on or off: the storefront compare list, the shareable comparison links and the admin screens. Nothing is dropped — saved comparisons stay in the database and their share links work again when you switch it back on. While it is off, a comparison list an anonymous visitor built is no longer adopted when they sign in, and expires with its own cookie.',
+            groupCode: 'compare',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+        {
+            code: COMPARE_SETTING_CODES.MAX_PRODUCTS,
+            name: 'Maximum products per comparison',
+            description: 'Upper bound on how many products a customer can place in a single Comparison. The Compare page and PDF export are sized for this number; the storefront refuses to add a (max+1)-th product. Sensible range 1..16; defaults to 4.',
+            groupCode: 'compare',
+            valueType: 'number',
+            defaultValue: DEFAULT_COMPARE_MAX_PRODUCTS,
+        },
+    ],
+});
+/** Module-lifecycle manifest (feature 018). */
+export const manifest = defineModuleManifest({
+    id: 'comparisons',
+    name: 'Compare Products',
+    description: 'Customer-facing product comparison feature with shareable links and PDF export.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port the admin routes are gated by; feature
+    // 072 made it a container resolution rather than an optional argument that
+    // decided whether the admin surface existed at all.
+    //
+    // `price_lists` joined in issue #132: a comparison column shows a price, and
+    // it now resolves that price through the `pricingService` port instead of
+    // projecting the catalogue's legacy attribute. The edge binds — comparing
+    // products on prices the platform is refusing to serve is exactly the
+    // failure the port gate exists to prevent.
+    //
+    // `organizations` joined with the viewer-priced comparison: the columns are
+    // resolved for whoever is looking, and the engine selects a group-targeted
+    // price list by the buyer's customer group, which is a field on the
+    // organisation row.
+    dependencies: [
+        'catalog',
+        'customer_accounts',
+        'organizations',
+        'price_lists',
+        'sales_channels',
+        'settings',
+        'auth',
+    ],
+    settings,
+    /**
+     * The operator-visible error codes this module owns — feature 090, Phase 3
+     * (`specs/090-module-owned-error-codes/migration-runbook.md`).
+     *
+     * The list is the incumbent prefix chain's *answer* for `comparisons`, copied
+     * from the frozen capture at
+     * `backend/test/fixtures/error-code-routing/chain-answers.ts`
+     * (`grep -oE "^  [A-Z0-9_]+: 'comparisons'," …`). It is a transcription, not a
+     * judgement: the migration is answer-preserving over all 289 codes and
+     * re-routing is out of scope (§6.2, §6.5).
+     *
+     * **Trap T1 does not bite here, and that was measured rather than assumed.**
+     * The chain answers `comparisons` from one prefix and one identity —
+     * `code.startsWith('COMPARISON_') || code === ERROR_CODES.PDF_GENERATION_FAILED`.
+     * Three enumeration members carry the prefix and all three survive to this
+     * rule; no earlier rule names `PDF_GENERATION_FAILED`. So reading the chain's
+     * source would have given the same four as reading its answer. `inventory` and
+     * `assets_library` are where it does bite; this is another module where the two
+     * agree, which is worth recording so the next reader knows the question was
+     * asked.
+     *
+     * **One code a reader will look for here and not find: `PRODUCT_NOT_IN_COMPARISON`.**
+     * It names this module's own noun, it is raised in this package and nowhere
+     * else — `routes.public.ts`' `translate()` converts
+     * `ProductNotInComparisonError` into a 404 with it — and it is `catalog`'s,
+     * declared there in !1117. The chain never reaches the `COMPARISON_` rule with
+     * it, because the `PRODUCT_` prefix runs first and wins; the runbook's trap T2
+     * names this exact code as a routing decision an earlier feature made
+     * deliberately. Do not move it here.
+     *
+     * **The inverse: this package raises four codes it does not own.** All four are
+     * in `routes.public.ts` — `PRODUCT_NOT_IN_COMPARISON` and `PRODUCT_NOT_FOUND`
+     * are `catalog`'s (both from `translate()`), and `INTERNAL` and
+     * `VALIDATION_FAILED` are the platform's. That is D-95.2 from the thrower's
+     * side: routing follows the domain noun, and "the product does not exist" stays
+     * a catalogue noun however it is reached. None is declared here.
+     *
+     * **No code is raised by nothing.** All four have a live raise site in this
+     * package, on routes mounted unconditionally: `COMPARISON_EMPTY` and
+     * `PDF_GENERATION_FAILED` in the `GET /api/v1/comparisons/me/pdf` handler
+     * (`index.ts` always supplies a real `ComparisonPdfRenderer`, so the `if
+     * (pdfRenderer)` guard around them is not a closed door), `COMPARISON_FULL`
+     * from `translate()` over `ComparisonFullError`, and `COMPARISON_NOT_FOUND`
+     * three times — the `notFoundComparison()` / `notFound()` factories in
+     * `routes.public.ts` and `routes.share.ts`, and an inline throw in
+     * `routes.admin.ts`. So this module contributes nothing to the deferred-defect
+     * register's entry on codes no client can receive.
+     *
+     * Both spellings were searched, which trap T12 asks for: `ERROR_CODES.<CODE>`
+     * and the bare quoted literal, over `packages` and `backend/src`. This package
+     * writes no bare-literal `new HttpError(<status>, '<CODE>', …)` at all.
+     *
+     * No `tokens`, derived rather than assumed. `refusalToken`
+     * (`packages/platform/src/http/error-envelope.ts`) reads `details.code` and
+     * nothing else; every raise site above was read and not one passes a fourth
+     * argument, so no `details.code` can exist. The runbook's §5 raise-site scan
+     * attributes the tree's ten token-carrying codes over 41 sites to `core`,
+     * `invoices` and `carts` and names none of these; in the other direction the
+     * module's bundles hold exactly four `errors.<CODE>` sentences in each language
+     * and no `errors.<CODE>.<token>` key, so there is no dead sentence either.
+     */
+    errorCodes: [
+        { code: 'COMPARISON_EMPTY' },
+        { code: 'COMPARISON_FULL' },
+        { code: 'COMPARISON_NOT_FOUND' },
+        { code: 'PDF_GENERATION_FAILED' },
+    ],
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    permissions: [{ code: 'comparisons:read', label: 'View product comparisons' }],
+    /**
+     * The module's command-palette entry — feature 091, Phase 4 (the plan's
+     * batch 6), and one of the fifteen Principle XVI entries
+     * `specs/deferred-defects.md` records as owed.
+     *
+     * It arrives with the drain rather than before it, by the mechanism that
+     * register predicts: the batch owes an off-state proof over every surface the
+     * module contributes, and until this declaration existed the `AppShell.tsx`
+     * `PALETTE_ITEMS` row that advertised /comparisons was the admin's own — a
+     * hand-written copy no server-side presence check was ever asked about, so it
+     * went on offering the screen to an operator who had switched the module off.
+     * The Actions group is resolved by `AdminActionsService` against the effective
+     * enabled-set, which is what makes the withdrawal real.
+     *
+     * `requiredPermission` is the code the target route enforces, which
+     * `check:action-route-permissions` compares against the registration on
+     * `GET /api/v1/admin/comparisons` itself. The admin side of this module is read-only, so the read
+     * code is the whole of what it gates.
+     */
+    actions: [
+        {
+            id: 'open-comparisons',
+            labelKey: 'actions.openComparisons.label',
+            descriptionKey: 'actions.openComparisons.description',
+            icon: 'Scale',
+            targetRoute: '/comparisons',
+            requiredPermission: 'comparisons:read',
+            keywords: ['compare', 'comparison', 'comparisons', 'porównanie', 'porównania'],
+            weight: 600,
+        },
+    ],
+    activation: { settingCode: 'comparisons.enabled', default: true },
+});
+/** Legacy export retained for backward compatibility. */
+export const comparisonsManifest = settings;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,YAAY,EAAE,sBAAsB;CAC5B,CAAC;AAEX,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,MAAM,QAAQ,GAAG,4BAA4B,CAAC;IAC5C,UAAU,EAAE,aAAa;IACzB,MAAM,EAAE;QACN;YACE,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,SAAS;SAChB;KACF;IACD,QAAQ,EAAE;QACR;YACE,kEAAkE;YAClE,IAAI,EAAE,qBAAqB;YAC3B,IAAI,EAAE,4BAA4B;YAClC,WAAW,EACT,uYAAuY;YACzY,SAAS,EAAE,SAAS;YACpB,SAAS,EAAE,SAAS;YACpB,YAAY,EAAE,IAAI;SACnB;QACD;YACE,IAAI,EAAE,qBAAqB,CAAC,YAAY;YACxC,IAAI,EAAE,iCAAiC;YACvC,WAAW,EACT,mOAAmO;YACrO,SAAS,EAAE,SAAS;YACpB,SAAS,EAAE,QAAQ;YACnB,YAAY,EAAE,4BAA4B;SAC3C;KACF;CACF,CAAC,CAAC;AAEH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,aAAa;IACjB,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,iFAAiF;IACnF,OAAO,EAAE,OAAO;IAChB,6EAA6E;IAC7E,2EAA2E;IAC3E,oDAAoD;IACpD,EAAE;IACF,6EAA6E;IAC7E,0EAA0E;IAC1E,0EAA0E;IAC1E,sEAAsE;IACtE,2CAA2C;IAC3C,EAAE;IACF,4EAA4E;IAC5E,2EAA2E;IAC3E,oEAAoE;IACpE,oBAAoB;IACpB,YAAY,EAAE;QACZ,SAAS;QACT,mBAAmB;QACnB,eAAe;QACf,aAAa;QACb,gBAAgB;QAChB,UAAU;QACV,MAAM;KACP;IACD,QAAQ;IACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4DG;IACH,UAAU,EAAE;QACV,EAAE,IAAI,EAAE,kBAAkB,EAAE;QAC5B,EAAE,IAAI,EAAE,iBAAiB,EAAE;QAC3B,EAAE,IAAI,EAAE,sBAAsB,EAAE;QAChC,EAAE,IAAI,EAAE,uBAAuB,EAAE;KAClC;IACD,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IAC5B,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,0BAA0B,EAAE,CAAC;IAC9E;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,EAAE;QACP;YACE,EAAE,EAAE,kBAAkB;YACtB,QAAQ,EAAE,+BAA+B;YACzC,cAAc,EAAE,qCAAqC;YACrD,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,cAAc;YAC3B,kBAAkB,EAAE,kBAAkB;YACtC,QAAQ,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,CAAC;YAC9E,MAAM,EAAE,GAAG;SACZ;KACF;IACD,UAAU,EAAE,EAAE,WAAW,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,EAAE;CAClE,CAAC,CAAC;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC"}

package/dist/migrations/20260501T185834_comparisons_init.d.ts

@@ -0,0 +1,32 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Comparisons module — feature 007 / T010 / data-model.md §1.1 + §1.2.
+ *
+ * Single migration owning both tables of the comparisons module:
+ *
+ *   - `comparisons` — the Comparison resource. Owner is exclusively a
+ *     customer account OR an anonymous browser session (CHECK enforces
+ *     mutual exclusivity). `share_token` is a 22-char base64url string
+ *     unique across all live comparisons; the share-token endpoint
+ *     resolves it in O(1).
+ *   - `comparison_products` — ordered bridge between a Comparison and
+ *     the Products it holds. Composite PK on (comparison_id, product_id);
+ *     `position` defines column order on the comparison page and PDF.
+ *     Cascades on both parents: removing a Product removes it from every
+ *     Comparison that referenced it; removing a Comparison removes its
+ *     bridge rows.
+ *
+ * Indexing rationale comes from the data model:
+ *   - UNIQUE(share_token) supports findByShareToken in O(1) (R-4 share
+ *     tokens are unguessable; this is the lookup path).
+ *   - Partial indexes on (customer_account_id) WHERE NOT NULL and on
+ *     (anonymous_token) WHERE NOT NULL support "find my comparison" for
+ *     each owner kind without bloating the index for the unused column.
+ *   - (created_at desc) and (sales_channel_id, created_at desc) support
+ *     the admin overview's default sort and channel filter (US5).
+ */
+export declare class Migration20260501T185834ComparisonsInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260501T185834_comparisons_init.d.ts.map

package/dist/migrations/20260501T185834_comparisons_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260501T185834_comparisons_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260501T185834_comparisons_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,uCAAwC,SAAQ,SAAS;IACrD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAyEnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAIrC"}

package/dist/migrations/20260501T185834_comparisons_init.js

@@ -0,0 +1,102 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Comparisons module — feature 007 / T010 / data-model.md §1.1 + §1.2.
+ *
+ * Single migration owning both tables of the comparisons module:
+ *
+ *   - `comparisons` — the Comparison resource. Owner is exclusively a
+ *     customer account OR an anonymous browser session (CHECK enforces
+ *     mutual exclusivity). `share_token` is a 22-char base64url string
+ *     unique across all live comparisons; the share-token endpoint
+ *     resolves it in O(1).
+ *   - `comparison_products` — ordered bridge between a Comparison and
+ *     the Products it holds. Composite PK on (comparison_id, product_id);
+ *     `position` defines column order on the comparison page and PDF.
+ *     Cascades on both parents: removing a Product removes it from every
+ *     Comparison that referenced it; removing a Comparison removes its
+ *     bridge rows.
+ *
+ * Indexing rationale comes from the data model:
+ *   - UNIQUE(share_token) supports findByShareToken in O(1) (R-4 share
+ *     tokens are unguessable; this is the lookup path).
+ *   - Partial indexes on (customer_account_id) WHERE NOT NULL and on
+ *     (anonymous_token) WHERE NOT NULL support "find my comparison" for
+ *     each owner kind without bloating the index for the unused column.
+ *   - (created_at desc) and (sales_channel_id, created_at desc) support
+ *     the admin overview's default sort and channel filter (US5).
+ */
+export class Migration20260501T185834ComparisonsInit extends Migration {
+    async up() {
+        this.addSql(`
+      create table "comparisons" (
+        "id" uuid not null,
+        "share_token" varchar(32) not null,
+        "customer_account_id" uuid null,
+        "anonymous_token" varchar(32) null,
+        "sales_channel_id" uuid not null,
+        "display_mode" varchar(16) not null default 'all',
+        "created_at" timestamptz not null default now(),
+        "updated_at" timestamptz not null default now(),
+        constraint "comparisons_pkey" primary key ("id"),
+        constraint "comparisons_share_token_uq" unique ("share_token"),
+        constraint "comparisons_owner_xor_chk"
+          check ((customer_account_id is null) <> (anonymous_token is null)),
+        constraint "comparisons_customer_account_fk"
+          foreign key ("customer_account_id") references "customer_accounts" ("id")
+          on delete cascade,
+        constraint "comparisons_sales_channel_fk"
+          foreign key ("sales_channel_id") references "sales_channels" ("id")
+          on delete restrict
+      );
+    `);
+        // Partial owner indexes — only one of the two columns is set per row;
+        // partial indexes keep them tight without a useless second key.
+        this.addSql(`
+      create index "idx_comparisons_owner_customer"
+        on "comparisons" ("customer_account_id")
+        where "customer_account_id" is not null;
+    `);
+        this.addSql(`
+      create index "idx_comparisons_owner_anon"
+        on "comparisons" ("anonymous_token")
+        where "anonymous_token" is not null;
+    `);
+        // Admin overview sort + channel filter (US5).
+        this.addSql(`
+      create index "idx_comparisons_admin_listing"
+        on "comparisons" ("created_at" desc);
+    `);
+        this.addSql(`
+      create index "idx_comparisons_channel_recent"
+        on "comparisons" ("sales_channel_id", "created_at" desc);
+    `);
+        // Bridge — ordered set of products in a comparison.
+        this.addSql(`
+      create table "comparison_products" (
+        "comparison_id" uuid not null,
+        "product_id" uuid not null,
+        "position" smallint not null,
+        "added_at" timestamptz not null default now(),
+        constraint "comparison_products_pkey"
+          primary key ("comparison_id", "product_id"),
+        constraint "comparison_products_comparison_fk"
+          foreign key ("comparison_id") references "comparisons" ("id")
+          on delete cascade,
+        constraint "comparison_products_product_fk"
+          foreign key ("product_id") references "products" ("id")
+          on delete cascade
+      );
+    `);
+        // Reverse lookup — supports "is this product in any comparison?" and
+        // makes the products → CASCADE deletion path efficient.
+        this.addSql(`
+      create index "idx_comparison_products_product"
+        on "comparison_products" ("product_id");
+    `);
+    }
+    async down() {
+        this.addSql('drop table if exists "comparison_products" cascade;');
+        this.addSql('drop table if exists "comparisons" cascade;');
+    }
+}
+//# sourceMappingURL=20260501T185834_comparisons_init.js.map

package/dist/migrations/20260501T185834_comparisons_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260501T185834_comparisons_init.js","sourceRoot":"","sources":["../../src/migrations/20260501T185834_comparisons_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,uCAAwC,SAAQ,SAAS;IAC3D,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;KAqBX,CAAC,CAAC;QAEH,sEAAsE;QACtE,gEAAgE;QAChE,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QAEH,8CAA8C;QAC9C,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;QAEH,oDAAoD;QACpD,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;KAeX,CAAC,CAAC;QAEH,qEAAqE;QACrE,wDAAwD;QACxD,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,qDAAqD,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,6CAA6C,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/migrations/20260830T163143_comparisons_organization_attribution.d.ts

@@ -0,0 +1,84 @@
+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 declare class Migration20260830T163143ComparisonsOrganizationAttribution extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260830T163143_comparisons_organization_attribution.d.ts.map

package/dist/migrations/20260830T163143_comparisons_organization_attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260830T163143_comparisons_organization_attribution.d.ts","sourceRoot":"","sources":["../../src/migrations/20260830T163143_comparisons_organization_attribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,qBAAa,0DAA2D,SAAQ,SAAS;IACxE,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IA6DnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAWrC"}