@endora-commerce/mod-carts 0.100.0

package/dist/manifest.js

@@ -0,0 +1,224 @@
+import { defineModuleManifest, defineModuleSettingsManifest, } from '@endora-commerce/contracts';
+/**
+ * Carts module — feature 027 consolidation pass.
+ *
+ * Settings (`carts.abandonment.*`) declared here are seeded by the module-
+ * lifecycle ManifestReconciler on backend boot. No raw INSERT in the
+ * migration; the reconciler is the single seed path (matches the
+ * `inventory.*` and `organizations.*` patterns).
+ */
+export const CARTS_SETTING_CODES = {
+    ABANDONMENT_INACTIVITY_MINUTES: 'carts.abandonment.inactivity_minutes',
+    ABANDONMENT_NOTIFICATION_RECIPIENT: 'carts.abandonment.notification_recipient',
+};
+/**
+ * The manifest defaults, exported so a read that has to degrade degrades to
+ * *this* binding rather than to a literal invented at the call site (feature
+ * 072, D-43).
+ *
+ * The two used to diverge: the manifest said 10080 while both readers' `catch`
+ * answered `0`, and `CartAbandonmentWorker` treats `<= 0` as "sweep nothing".
+ * The divergence did not merely lose the configured value — it inverted the
+ * feature, and it would still have been off after the channel was fixed. A
+ * compiled-in fallback is a second source of truth consulted only when the
+ * first is unreachable, i.e. exactly when nobody is watching.
+ */
+export const DEFAULT_ABANDONMENT_INACTIVITY_MINUTES = 10080;
+export const DEFAULT_ABANDONMENT_NOTIFICATION_RECIPIENT = '';
+const settings = defineModuleSettingsManifest({
+    moduleCode: 'carts',
+    groups: [{ code: 'carts', name: 'Carts' }],
+    settings: [
+        {
+            code: CARTS_SETTING_CODES.ABANDONMENT_INACTIVITY_MINUTES,
+            name: 'Cart abandonment threshold (minutes)',
+            description: 'Minutes of inactivity before an Active cart is considered Abandoned. Default 10080 (7 days).',
+            groupCode: 'carts',
+            valueType: 'number',
+            defaultValue: DEFAULT_ABANDONMENT_INACTIVITY_MINUTES,
+        },
+        {
+            code: CARTS_SETTING_CODES.ABANDONMENT_NOTIFICATION_RECIPIENT,
+            name: 'Abandonment notification recipient',
+            description: 'Single e-mail address that receives an abandonment notification on every Active → Abandoned transition. Empty = no notification.',
+            groupCode: 'carts',
+            valueType: 'string',
+            defaultValue: DEFAULT_ABANDONMENT_NOTIFICATION_RECIPIENT,
+        },
+    ],
+});
+export const manifest = defineModuleManifest({
+    id: 'carts',
+    name: 'Carts',
+    description: 'Shopping cart aggregation, pricing, lifecycle, and approval gate.',
+    version: '2.0.0',
+    // Feature 075, Phase C adds `catalog`. Six files read the `Product`,
+    // `ProductPackagingUnit` and `ProductLink` entities directly — the cart line,
+    // the cart serializer, the admin detail, the up-sell strip, the pricing
+    // recompute and the quote-to-cart conversion — so an operator who switched
+    // `catalog` off still had carts naming, pricing and accepting products the
+    // platform had stopped serving, out of tables deactivation leaves in place.
+    // Binding rather than non-binding: a basket that cannot resolve what is in it
+    // must refuse, not quote a figure it cannot justify (issue #124's rule, which
+    // `price_lists` already stands on here).
+    //
+    // D-94.1 adds `orders`, for the foreign key `carts_completed_order_fk`
+    // (`carts.completed_order_id` -> `orders.id`, `on delete set null`) — the
+    // pointer this table has always had for its *other* terminal transition
+    // (`carts_converted_to_qr_fk`) and never for this one. AGENTS.md
+    // § Migrations item 4: a cross-module foreign key is declared here or the
+    // build fails.
+    //
+    // D-94.3 moves `promotions` out, to `acknowledgedDependencies` below. The
+    // edge is unchanged and still binds — what is withdrawn is the install
+    // ordering, which `promotion_usages_order_fk` now says runs the other way:
+    // `promotions` declares `orders`, `orders` is declared here, so keeping
+    // `promotions` in `dependencies` would close `carts -> promotions -> orders
+    // -> carts`.
+    dependencies: [
+        'catalog',
+        'customer_accounts',
+        'orders',
+        'organizations',
+        'price_lists',
+        'quote_requests',
+        'sales_channels',
+        'settings',
+    ],
+    // Feature 073, Amendment A1 — a real port edge whose `dependencies` entry
+    // would close a cycle. Read by the flip-time refusals and by
+    // `check-port-dependencies`; read by neither the install order nor the
+    // migration order.
+    acknowledgedDependencies: [
+        {
+            moduleId: 'promotions',
+            port: 'promotionService',
+            reason: 'The basket prices through `PromotionApplyPort.applyToCart`, which is a real bind: a ' +
+                'cart that cannot resolve its discount must not quote a figure it cannot justify. ' +
+                'The edge cannot go in `dependencies` since D-94.1, because ' +
+                '`promotion_usages_order_fk` obliges `promotions` to declare `orders`, this module ' +
+                'declares `orders` for `carts_completed_order_fk`, and the three together close ' +
+                '`carts -> promotions -> orders -> carts`. Acknowledging it withdraws the install ' +
+                'ordering the constraint says is backwards and withdraws nothing else — `promotions` ' +
+                'stays exactly as (un)deactivatable under this module as it was.',
+        },
+        {
+            moduleId: 'promotions',
+            port: 'promotionCodePort',
+            reason: 'The coupon a buyer typed, resolved through the three-step lookup `promotions` owns — ' +
+                'the legacy inline code, then the coupon table, then the promotion behind it, each ' +
+                'filtered on `isActive`. It shares the cycle of `promotionService` above and is ' +
+                'acknowledged for the same reason and with the same effect: the bind is kept, the ' +
+                'ordering claim the foreign key contradicts is dropped.',
+        },
+    ],
+    /**
+     * The three error codes this module owns — feature 090 Phase 3
+     * (`specs/090-module-owned-error-codes/contracts/error-code-declaration.md`
+     * §1.1). This is where each sentence is looked up from: `errors.<CODE>` in this
+     * module's own `i18n/{en,pl}.json`, which already holds all three in both
+     * languages.
+     *
+     * The list is answer-preserving, not a judgement (§6.2 and §6.5): it is exactly
+     * what the prefix chain in `@endora-commerce/mod-i18n` routes here today,
+     * copied from the frozen capture at
+     * `backend/test/fixtures/error-code-routing/chain-answers.ts` rather than
+     * re-derived. Re-routing a code to a better owner is
+     * `specs/082-error-code-ownership/rulings.md` §9's remaining work and is
+     * deliberately not done here.
+     *
+     * **Two codes a reader will look for here and not find.** `MIN_NOT_MET` reads
+     * like a cart minimum and is `catalog`'s: it is one of three outcomes of bundle
+     * option validation (`bundle.service.ts`), and the chain routes it there.
+     * `PROMOTION_INVALID` reads like the coupon path below it and falls through the
+     * chain to the platform block; nothing in the tree raises it at all.
+     *
+     * **The tokens are the enum, not the bundle.** `CART_COUPON_REJECTED` is the
+     * one code in this module that carries refusal discriminators
+     * (`specs/082-error-code-ownership/contracts/error-code-ownership.md` §1.4):
+     * `routes.ts` puts `result.reason` in `details.code`, which the envelope reads
+     * as the tail of `errors.CART_COUPON_REJECTED.<token>`. That value's type is
+     * `CouponApplyDropped.reason` = `CouponDropReason` = `couponDropReasonSchema` in
+     * `packages/contracts/src/carts.ts`, and the seven members below are that
+     * enum's, in its order. The bundle happens to hold a sentence for each of the
+     * seven today, so reading the bundle instead would give the same answer — but
+     * only by coincidence: the bundle is a lower bound, and a reason added to the
+     * enum before its sentence is written would be missing from it. The enum is the
+     * authority because it is what the raise site can actually produce.
+     */
+    errorCodes: [
+        {
+            code: 'CART_COUPON_REJECTED',
+            tokens: [
+                'invalid_code',
+                'expired',
+                'below_min_spend',
+                'wrong_channel',
+                'wrong_customer_group',
+                'wrong_organization',
+                'coupon_format_invalid',
+            ],
+        },
+        { code: 'CART_EMPTY' },
+        { code: 'CART_LINE_CAP_EXCEEDED' },
+    ],
+    settings,
+    // Feature 074 (Constitution XVII), test C2 — functional base. This reverses
+    // the reading 073 took. The quote-only deployment that argued for a switch
+    // here is real, but it does not want the *basket* gone: checkout, quick order
+    // and the quote flow all assemble one, so switching this off removes the
+    // structure every ordering path is built on rather than one path among
+    // several. A deployment that quotes and never checks out simply does not use
+    // checkout; `quote_requests` is where that choice belongs, and it stays
+    // operator-controlled.
+    //
+    // `carts.enabled` goes with the control it backed: one of the nineteen that
+    // never accepted a deactivation. The existing rows are removed by a core data
+    // migration (feature 074, FR-010a).
+    activation: {
+        nonDeactivatable: true,
+        reason: 'The basket every ordering path assembles — checkout, quick order and the quote flow all ' +
+            'go through it.',
+    },
+    // Feature 026 checklist — `routes.admin.ts` gates on both codes and this
+    // manifest declared neither, so until T136 only a role holding `'*'` could
+    // reach the admin cart screens. The permission-inventory scanner that should
+    // have caught it read one call shape out of the several the tree writes; it
+    // now reads every shape, blanks comments and regex literals, and reports an
+    // argument it cannot resolve instead of dropping it.
+    //
+    // D-173 adds the third, and it is not this module's own code: the admin
+    // proxy for the per-Organization `requires_cart_approval` policy is gated on
+    // `customers:manage`, whose core `PERMISSION_CATALOGUE` row names
+    // `customers` — a module an operator can switch off, while this one declares
+    // itself non-deactivatable. Declaring it here makes this module a second
+    // *owner*, in the shape issue #213 gave `integrations:manage`, so the code
+    // stays grantable on `/admin-roles` while this surface is on. The label —
+    // *"Manage customer organizations"* — reads as a sentence about that
+    // endpoint, so the code is shared rather than replaced.
+    permissions: [
+        { code: 'carts:read', label: 'View customer carts' },
+        { code: 'carts:reject', label: 'Reject a cart pending organization approval' },
+        { code: 'customers:manage', label: 'Manage customer organizations' },
+    ],
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+});
+/** Legacy export retained for backward compatibility. */
+export const cartsManifest = settings;
+/**
+ * The operator command this module declares — feature 080, T042b / D-160.9.
+ *
+ * It was `scripts/abandonment-sweep.ts`, the tree's one call site of
+ * `requireModuleEnabled` and the worked example D-157 was written around. The
+ * host asks that question now, at the declaration seam, for every command; see
+ * `cli/abandonment-sweep.ts` for what the move changed and what it did not.
+ */
+export const cliCommands = [
+    {
+        name: 'abandonment-sweep',
+        summary: 'Run one pass of the cart abandonment sweep against the live database.',
+        run: async (context) => (await import('./backend/cli/abandonment-sweep.js')).abandonmentSweep(context),
+    },
+];
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/dist/migrations/20260611T140352_carts_consolidation.d.ts

@@ -0,0 +1,43 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Carts consolidation (feature 027).
+ *
+ * Brings the foundation `carts` table up to the spec defined in feature
+ * 027-carts: status lifecycle (active / abandoned / completed / rejected),
+ * sales-channel scoping, last-activity bookkeeping for the abandonment
+ * sweep, the orthogonal approval sub-state (not_required / pending /
+ * approved / rejected_by_org_admin), a coupon-code column wired to the
+ * Promotions module, a conversion-lineage column to the Quote Requests
+ * module, an abandonment-notification idempotency timestamp, and an
+ * optimistic-lock `version` column shared with feature 003 / 026.
+ *
+ * `cart_items` gains a two-layer pricing snapshot: the existing
+ * `unit_price` remains the price the line was added at, while
+ * `recomputed_unit_price` / `recomputed_at` / `recomputed_currency` cache
+ * the most recent re-resolved price (per feature 011's PricingService).
+ *
+ * `organizations` gains `requires_cart_approval` — the per-Organization
+ * policy flag that gates checkout behind an Organization Administrator's
+ * approval. Default false preserves the prior behaviour.
+ *
+ * Introduces one new table:
+ *   - cart_audit_entries — typed per-cart audit feed for the cart-detail
+ *     UI (the platform-wide audit timeline still uses audit_log_entries).
+ *
+ * Data migration: legacy `status='converted'` rows are remapped to
+ * `status='completed'`. The legacy unique partial index
+ * `carts_one_active_per_customer` (introduced by feature 001) is dropped
+ * and replaced with `carts_one_active_per_customer_per_channel` so the
+ * "one active cart per (Customer, Sales Channel)" rule from the spec is
+ * enforced at the database layer.
+ *
+ * Settings (`carts.abandonment.inactivity_minutes`,
+ * `carts.abandonment.notification_recipient`) are seeded by the module
+ * lifecycle reconciler from the `settings` declaration in
+ * `carts/manifest.ts` — not from this migration.
+ */
+export declare class Migration20260611T140352CartsConsolidation extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260611T140352_carts_consolidation.d.ts.map

package/dist/migrations/20260611T140352_carts_consolidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140352_carts_consolidation.d.ts","sourceRoot":"","sources":["../../src/migrations/20260611T140352_carts_consolidation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,0CAA2C,SAAQ,SAAS;IACxD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IA2JnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA0DrC"}

package/dist/migrations/20260611T140352_carts_consolidation.js

@@ -0,0 +1,237 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Carts consolidation (feature 027).
+ *
+ * Brings the foundation `carts` table up to the spec defined in feature
+ * 027-carts: status lifecycle (active / abandoned / completed / rejected),
+ * sales-channel scoping, last-activity bookkeeping for the abandonment
+ * sweep, the orthogonal approval sub-state (not_required / pending /
+ * approved / rejected_by_org_admin), a coupon-code column wired to the
+ * Promotions module, a conversion-lineage column to the Quote Requests
+ * module, an abandonment-notification idempotency timestamp, and an
+ * optimistic-lock `version` column shared with feature 003 / 026.
+ *
+ * `cart_items` gains a two-layer pricing snapshot: the existing
+ * `unit_price` remains the price the line was added at, while
+ * `recomputed_unit_price` / `recomputed_at` / `recomputed_currency` cache
+ * the most recent re-resolved price (per feature 011's PricingService).
+ *
+ * `organizations` gains `requires_cart_approval` — the per-Organization
+ * policy flag that gates checkout behind an Organization Administrator's
+ * approval. Default false preserves the prior behaviour.
+ *
+ * Introduces one new table:
+ *   - cart_audit_entries — typed per-cart audit feed for the cart-detail
+ *     UI (the platform-wide audit timeline still uses audit_log_entries).
+ *
+ * Data migration: legacy `status='converted'` rows are remapped to
+ * `status='completed'`. The legacy unique partial index
+ * `carts_one_active_per_customer` (introduced by feature 001) is dropped
+ * and replaced with `carts_one_active_per_customer_per_channel` so the
+ * "one active cart per (Customer, Sales Channel)" rule from the spec is
+ * enforced at the database layer.
+ *
+ * Settings (`carts.abandonment.inactivity_minutes`,
+ * `carts.abandonment.notification_recipient`) are seeded by the module
+ * lifecycle reconciler from the `settings` declaration in
+ * `carts/manifest.ts` — not from this migration.
+ */
+export class Migration20260611T140352CartsConsolidation extends Migration {
+    async up() {
+        // 1) Data backfill: rename legacy 'converted' → 'completed' before the
+        //    new CHECK constraint is installed. Foundation code that wrote
+        //    'converted' (CartService.clearForCustomer) is updated to write
+        //    'completed' in the same PR.
+        this.addSql(`update "carts" set "status" = 'completed' where "status" = 'converted';`);
+        // 2) New columns on `carts`.
+        this.addSql(`
+      alter table "carts"
+        add column "sales_channel_id" uuid null,
+        add column "last_activity_at" timestamptz not null default now(),
+        add column "approval_status" varchar(32) not null default 'not_required',
+        add column "submitted_for_approval_at" timestamptz null,
+        add column "approved_at" timestamptz null,
+        add column "approved_by_customer_account_id" uuid null,
+        add column "rejected_at" timestamptz null,
+        add column "rejected_by_actor" varchar(48) null,
+        add column "rejected_reason" text null,
+        add column "applied_promotion_code" varchar(64) null,
+        add column "converted_to_quote_request_id" uuid null,
+        add column "abandonment_notified_at" timestamptz null,
+        add column "version" int not null default 0;
+    `);
+        // 3) CHECK constraints for the two enum-like columns.
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_status_check"
+        check ("status" in ('active', 'abandoned', 'completed', 'rejected'));
+    `);
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_approval_status_check"
+        check ("approval_status" in (
+          'not_required', 'pending', 'approved', 'rejected_by_org_admin'
+        ));
+    `);
+        // 4) Foreign keys on the new columns.
+        //    sales_channel_id → sales_channels(id). ON DELETE SET NULL keeps the
+        //    cart record alive if a channel is deleted (rare; admin operation).
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_sales_channel_fk"
+        foreign key ("sales_channel_id")
+        references "sales_channels" ("id")
+        on delete set null;
+    `);
+        //    approved_by_customer_account_id → customer_accounts(id). ON DELETE
+        //    SET NULL because the approval record still matters even if the
+        //    Org-Admin's Customer account is later deleted.
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_approved_by_customer_fk"
+        foreign key ("approved_by_customer_account_id")
+        references "customer_accounts" ("id")
+        on delete set null;
+    `);
+        //    converted_to_quote_request_id → quote_requests(id). ON DELETE
+        //    SET NULL because deleting a QR (rare) does not invalidate the
+        //    fact that the cart was once converted.
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_converted_to_qr_fk"
+        foreign key ("converted_to_quote_request_id")
+        references "quote_requests" ("id")
+        on delete set null;
+    `);
+        // 5) Backfill `sales_channel_id` to the system-default sales channel
+        //    so existing rows participate in the new (customer, channel)
+        //    uniqueness rule. If no default exists (test fixture), leave
+        //    NULL — the read path treats NULL as "system-default channel"
+        //    until the next consolidation tightens it (see research.md §R3).
+        this.addSql(`
+      update "carts"
+      set "sales_channel_id" = (
+        select "id" from "sales_channels" where "system_default" = true limit 1
+      )
+      where "sales_channel_id" is null;
+    `);
+        // 6) Indexes.
+        this.addSql(`
+      create index "carts_sales_channel_customer_status_idx"
+        on "carts" ("sales_channel_id", "customer_account_id", "status");
+    `);
+        this.addSql(`
+      create index "carts_status_last_activity_idx"
+        on "carts" ("status", "last_activity_at");
+    `);
+        this.addSql(`
+      create index "carts_applied_promotion_code_idx"
+        on "carts" ("applied_promotion_code")
+        where "applied_promotion_code" is not null;
+    `);
+        this.addSql(`
+      create index "carts_org_status_updated_idx"
+        on "carts" ("organization_id", "status", "updated_at" desc);
+    `);
+        // 7) Replace the foundation's "one active cart per Customer" partial
+        //    unique index with a (Customer, Sales Channel) variant so the spec's
+        //    one-active-cart-per-(Customer, Sales Channel) rule is enforced at
+        //    the DB layer. Anonymous carts (customer_account_id is null) are
+        //    not constrained by this index — anon ownership is enforced by the
+        //    existing `anonymous_cart_token` unique index.
+        this.addSql(`drop index if exists "carts_one_active_per_customer";`);
+        this.addSql(`
+      create unique index "carts_one_active_per_customer_per_channel"
+        on "carts" ("customer_account_id", "sales_channel_id")
+        where "status" = 'active' and "customer_account_id" is not null;
+    `);
+        // 8) New columns on `cart_items` — two-layer pricing snapshot.
+        this.addSql(`
+      alter table "cart_items"
+        add column "recomputed_unit_price" numeric(12,2) null,
+        add column "recomputed_at" timestamptz null,
+        add column "recomputed_currency" varchar(3) null;
+    `);
+        // 9) New column on `organizations` — per-org cart-approval policy.
+        this.addSql(`
+      alter table "organizations"
+        add column "requires_cart_approval" boolean not null default false;
+    `);
+        // 10) Cart audit feed.
+        this.addSql(`
+      create table "cart_audit_entries" (
+        "id" uuid not null,
+        "cart_id" uuid not null,
+        "occurred_at" timestamptz not null default now(),
+        "actor_type" varchar(32) not null,
+        "actor_id" uuid null,
+        "action" varchar(64) not null,
+        "from_state" varchar(32) null,
+        "to_state" varchar(32) null,
+        "reason" text null,
+        "metadata" jsonb not null default '{}'::jsonb,
+        constraint "cart_audit_entries_pkey" primary key ("id"),
+        constraint "cart_audit_entries_cart_fk"
+          foreign key ("cart_id") references "carts" ("id") on delete cascade,
+        constraint "cart_audit_entries_actor_type_check"
+          check ("actor_type" in ('customer', 'org_admin', 'platform_admin', 'system', 'sweep'))
+      );
+    `);
+        this.addSql(`
+      create index "cart_audit_entries_cart_occurred_idx"
+        on "cart_audit_entries" ("cart_id", "occurred_at" desc);
+    `);
+    }
+    async down() {
+        // Mirror order: drop the cart audit feed first, then the organization
+        // column, then cart_items columns, then re-instate the foundation
+        // partial unique index, then drop the new carts columns / constraints
+        // / indexes.
+        this.addSql(`drop index if exists "cart_audit_entries_cart_occurred_idx";`);
+        this.addSql(`drop table if exists "cart_audit_entries" cascade;`);
+        this.addSql(`alter table "organizations" drop column if exists "requires_cart_approval";`);
+        this.addSql(`
+      alter table "cart_items"
+        drop column if exists "recomputed_unit_price",
+        drop column if exists "recomputed_at",
+        drop column if exists "recomputed_currency";
+    `);
+        // Restore foundation's partial unique index.
+        this.addSql(`drop index if exists "carts_one_active_per_customer_per_channel";`);
+        this.addSql(`
+      create unique index "carts_one_active_per_customer"
+        on "carts" ("customer_account_id")
+        where "status" = 'active' and "customer_account_id" is not null;
+    `);
+        this.addSql(`drop index if exists "carts_org_status_updated_idx";`);
+        this.addSql(`drop index if exists "carts_applied_promotion_code_idx";`);
+        this.addSql(`drop index if exists "carts_status_last_activity_idx";`);
+        this.addSql(`drop index if exists "carts_sales_channel_customer_status_idx";`);
+        this.addSql(`alter table "carts" drop constraint if exists "carts_converted_to_qr_fk";`);
+        this.addSql(`alter table "carts" drop constraint if exists "carts_approved_by_customer_fk";`);
+        this.addSql(`alter table "carts" drop constraint if exists "carts_sales_channel_fk";`);
+        this.addSql(`alter table "carts" drop constraint if exists "carts_approval_status_check";`);
+        this.addSql(`alter table "carts" drop constraint if exists "carts_status_check";`);
+        this.addSql(`
+      alter table "carts"
+        drop column if exists "sales_channel_id",
+        drop column if exists "last_activity_at",
+        drop column if exists "approval_status",
+        drop column if exists "submitted_for_approval_at",
+        drop column if exists "approved_at",
+        drop column if exists "approved_by_customer_account_id",
+        drop column if exists "rejected_at",
+        drop column if exists "rejected_by_actor",
+        drop column if exists "rejected_reason",
+        drop column if exists "applied_promotion_code",
+        drop column if exists "converted_to_quote_request_id",
+        drop column if exists "abandonment_notified_at",
+        drop column if exists "version";
+    `);
+        // Restore legacy 'converted' state for any rows the up() touched.
+        // (We cannot perfectly distinguish "converted at the time of migration"
+        // from "completed later", so the down() leaves them as 'completed';
+        // this is documented as accepted asymmetry.)
+    }
+}
+//# sourceMappingURL=20260611T140352_carts_consolidation.js.map

package/dist/migrations/20260611T140352_carts_consolidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140352_carts_consolidation.js","sourceRoot":"","sources":["../../src/migrations/20260611T140352_carts_consolidation.ts"],"names":[],"mappings":"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"}

package/dist/migrations/20260611T140413_carts_cart_item_packaging.d.ts

@@ -0,0 +1,12 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Feature 043 — packaging-unit snapshot on cart lines. When a buyer orders a
+ * packaging unit (e.g. a pallet), the line records which unit it came from so
+ * the cart/order/RFQ can display the unit name appended to the product name.
+ * All nullable — plain single-piece lines leave them empty.
+ */
+export declare class Migration20260611T140413CartsCartItemPackaging extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260611T140413_carts_cart_item_packaging.d.ts.map

package/dist/migrations/20260611T140413_carts_cart_item_packaging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140413_carts_cart_item_packaging.d.ts","sourceRoot":"","sources":["../../src/migrations/20260611T140413_carts_cart_item_packaging.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;GAKG;AACH,qBAAa,8CAA+C,SAAQ,SAAS;IAC5D,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAKrC"}

package/dist/migrations/20260611T140413_carts_cart_item_packaging.js

@@ -0,0 +1,20 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Feature 043 — packaging-unit snapshot on cart lines. When a buyer orders a
+ * packaging unit (e.g. a pallet), the line records which unit it came from so
+ * the cart/order/RFQ can display the unit name appended to the product name.
+ * All nullable — plain single-piece lines leave them empty.
+ */
+export class Migration20260611T140413CartsCartItemPackaging extends Migration {
+    async up() {
+        this.addSql('alter table "cart_items" add column "packaging_unit_id" uuid null;');
+        this.addSql('alter table "cart_items" add column "packaging_unit_name" varchar(160) null;');
+        this.addSql('alter table "cart_items" add column "packaging_unit_base_quantity" integer null;');
+    }
+    async down() {
+        this.addSql('alter table "cart_items" drop column "packaging_unit_base_quantity";');
+        this.addSql('alter table "cart_items" drop column "packaging_unit_name";');
+        this.addSql('alter table "cart_items" drop column "packaging_unit_id";');
+    }
+}
+//# sourceMappingURL=20260611T140413_carts_cart_item_packaging.js.map

package/dist/migrations/20260611T140413_carts_cart_item_packaging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260611T140413_carts_cart_item_packaging.js","sourceRoot":"","sources":["../../src/migrations/20260611T140413_carts_cart_item_packaging.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,OAAO,8CAA+C,SAAQ,SAAS;IAClE,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,oEAAoE,CAAC,CAAC;QAClF,IAAI,CAAC,MAAM,CAAC,8EAA8E,CAAC,CAAC;QAC5F,IAAI,CAAC,MAAM,CAAC,kFAAkF,CAAC,CAAC;IAClG,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,sEAAsE,CAAC,CAAC;QACpF,IAAI,CAAC,MAAM,CAAC,6DAA6D,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM,CAAC,2DAA2D,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/migrations/20260818T081253_carts_cart_completed_order_fk.d.ts

@@ -0,0 +1,50 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * `carts.completed_order_id` — the pointer this table has never had for one of
+ * its two terminal transitions (D-94.1, site 2 / D-94.4).
+ *
+ * `placeOrder` ends by deleting the cart's items and setting
+ * `status = 'completed'`, on the same `Cart` object the totals were read from
+ * and inside the placement transaction, because a placement that then fails
+ * must leave the basket exactly as the buyer left it
+ * (`test/integration/orders/place-order-failure-preserves-cart.test.ts`).
+ * D-78 point 2 rules such a seam permanent and *declared*, and there was
+ * nothing to declare it with: no foreign key existed in either direction.
+ *
+ * **The pointer goes on the cart, not on the order.** An `orders.cart_id`
+ * would satisfy the letter of D-78 point 2 and force nothing — `orders`
+ * already declares `carts`, and an implementer could still complete the cart
+ * in a separate transaction and satisfy the constraint, because the cart is
+ * already committed when the order row is written. The cart-side pointer
+ * cannot be written before the order exists, which is precisely the property
+ * `payments_order_fk`, `invoices_order_fk` and `shipments_order_fk` rely on.
+ * This table already carries exactly this shape for its *other* terminal
+ * transition — `carts_converted_to_qr_fk`, added by
+ * `20260611T140352_carts_consolidation.ts:100-109`.
+ *
+ * `null`, and `on delete set null`, for the reason that migration wrote down
+ * for its twin: deleting the target does not invalidate the fact that the cart
+ * was once completed. The completion pointer is provenance, not a dependency.
+ * The column is nullable because it cannot be backfilled — no surviving record
+ * says which order emptied which historical cart — and because three of the
+ * four paths to `completed` are not placements (`CartService.clearForCustomer`,
+ * the anonymous-merge source, and the quote-request conversion), so
+ * `status = 'completed'` will never imply it and no check constraint can be
+ * added.
+ *
+ * **No orphan report, and the asymmetry is the point.** The other three
+ * constraints of this family need one because their columns have been
+ * accepting unverified values for months. This column is new: every existing
+ * row starts `null`, so there is nothing to orphan.
+ *
+ * `carts` declares `orders` in its manifest `dependencies` for this edge
+ * (AGENTS.md § Migrations item 4). The reverse port edge — `orders` resolving
+ * `cartWritePort` — moves to `acknowledgedDependencies`, which drops the
+ * install ordering the constraint says is backwards and keeps the bind and
+ * every refusal exactly as they were (D-94.3).
+ */
+export declare class Migration20260818T081253CartsCartCompletedOrderFk extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260818T081253_carts_cart_completed_order_fk.d.ts.map

package/dist/migrations/20260818T081253_carts_cart_completed_order_fk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260818T081253_carts_cart_completed_order_fk.d.ts","sourceRoot":"","sources":["../../src/migrations/20260818T081253_carts_cart_completed_order_fk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,iDAAkD,SAAQ,SAAS;IAC/D,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAYnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAKrC"}