@endora-commerce/mod-carts 0.100.0

package/dist/migrations/20260818T081253_carts_cart_completed_order_fk.js

@@ -0,0 +1,62 @@
+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 class Migration20260818T081253CartsCartCompletedOrderFk extends Migration {
+    async up() {
+        this.addSql(`alter table "carts" add column "completed_order_id" uuid null;`);
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_completed_order_fk" foreign key ("completed_order_id")
+          references "orders" ("id") on delete set null;
+    `);
+        this.addSql(`create index "carts_completed_order_idx" on "carts" ("completed_order_id") where "completed_order_id" is not null;`);
+    }
+    async down() {
+        this.addSql(`drop index if exists "carts_completed_order_idx";`);
+        this.addSql(`alter table "carts" drop constraint if exists "carts_completed_order_fk";`);
+        this.addSql(`alter table "carts" drop column if exists "completed_order_id";`);
+    }
+}
+//# sourceMappingURL=20260818T081253_carts_cart_completed_order_fk.js.map

package/dist/migrations/20260818T081253_carts_cart_completed_order_fk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260818T081253_carts_cart_completed_order_fk.js","sourceRoot":"","sources":["../../src/migrations/20260818T081253_carts_cart_completed_order_fk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAO,iDAAkD,SAAQ,SAAS;IACrE,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,gEAAgE,CAAC,CAAC;QAC9E,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,oHAAoH,CACrH,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,mDAAmD,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,2EAA2E,CAAC,CAAC;QACzF,IAAI,CAAC,MAAM,CAAC,iEAAiE,CAAC,CAAC;IACjF,CAAC;CACF"}

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

@@ -0,0 +1,67 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * D-187 — a `carts` row that names a customer account carries an organisation.
+ *
+ * `Cart` is the one `@CustomerScoped` class that already has the column
+ * (feature 087, Group B), and it has had it since before the granting arm of
+ * `customerFilterCond` went live. Nothing structural has held the pair
+ * together: `customerOrganizationColumn` reads the ORM's metadata per query, so
+ * the moment the property existed a sales representative's list was filtered on
+ * `organization_id` — and MikroORM applies no filter to `INSERT`
+ * (`r1-spike.md` §4, measured), so a row written with an account and no
+ * organisation is simply invisible to the representative who serves that
+ * organisation, on a screen that has stopped saying anything is missing.
+ *
+ * **The constraint is the only refusal an `INSERT` has**, which is the same
+ * sentence `20260825T141659_customer_accounts_organization_required.ts` opens
+ * with, and the same reason.
+ *
+ * ## 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 — an anonymous basket is a representable state and
+ * this table is full of them. The equivalence
+ * (`(customer_account_id is null) = (organization_id is null)`) would close one
+ * further shape, an ownerless row still carrying an organisation, at the price
+ * of writing R-6's answer into the schema while R-6 is open. D-187 takes the
+ * implication for that reason: do not encode an open question in a constraint.
+ *
+ * ## No foreign key
+ *
+ * Deliberately, and matching what this column has always been. 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 exactly the state below being made unreachable, and under this constraint
+ * 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
+ *
+ * These rows are buyers' baskets. The derivation is the account's own
+ * organisation, which is total since D-178 made `customer_accounts.organization_id`
+ * `NOT NULL`, so the only way to survive it is a `customer_account_id` pointing
+ * at a row that is gone — this table carries no foreign key on that column, so
+ * that is a real branch and not a formality. The migration raises with the
+ * count and up to twenty ids and deletes nothing (D-184), in the shape the
+ * D-178 migration established.
+ *
+ * `carts` does not declare `customer_accounts` in its manifest `dependencies`
+ * and needs no entry for this: `customer_accounts` is created by
+ * `organizations/20260424T205317_organizations_init.ts`, 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.
+ *
+ * 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 the next `@CustomerScoped` class to gain this column is covered by
+ * gaining it.
+ */
+export declare class Migration20260830T112911CartsOrganizationAttributionCheck extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260830T112911_carts_organization_attribution_check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260830T112911_carts_organization_attribution_check.d.ts","sourceRoot":"","sources":["../../src/migrations/20260830T112911_carts_organization_attribution_check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,qBAAa,yDAA0D,SAAQ,SAAS;IACvE,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAqDnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAQrC"}

package/dist/migrations/20260830T112911_carts_organization_attribution_check.js

@@ -0,0 +1,121 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * D-187 — a `carts` row that names a customer account carries an organisation.
+ *
+ * `Cart` is the one `@CustomerScoped` class that already has the column
+ * (feature 087, Group B), and it has had it since before the granting arm of
+ * `customerFilterCond` went live. Nothing structural has held the pair
+ * together: `customerOrganizationColumn` reads the ORM's metadata per query, so
+ * the moment the property existed a sales representative's list was filtered on
+ * `organization_id` — and MikroORM applies no filter to `INSERT`
+ * (`r1-spike.md` §4, measured), so a row written with an account and no
+ * organisation is simply invisible to the representative who serves that
+ * organisation, on a screen that has stopped saying anything is missing.
+ *
+ * **The constraint is the only refusal an `INSERT` has**, which is the same
+ * sentence `20260825T141659_customer_accounts_organization_required.ts` opens
+ * with, and the same reason.
+ *
+ * ## 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 — an anonymous basket is a representable state and
+ * this table is full of them. The equivalence
+ * (`(customer_account_id is null) = (organization_id is null)`) would close one
+ * further shape, an ownerless row still carrying an organisation, at the price
+ * of writing R-6's answer into the schema while R-6 is open. D-187 takes the
+ * implication for that reason: do not encode an open question in a constraint.
+ *
+ * ## No foreign key
+ *
+ * Deliberately, and matching what this column has always been. 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 exactly the state below being made unreachable, and under this constraint
+ * 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
+ *
+ * These rows are buyers' baskets. The derivation is the account's own
+ * organisation, which is total since D-178 made `customer_accounts.organization_id`
+ * `NOT NULL`, so the only way to survive it is a `customer_account_id` pointing
+ * at a row that is gone — this table carries no foreign key on that column, so
+ * that is a real branch and not a formality. The migration raises with the
+ * count and up to twenty ids and deletes nothing (D-184), in the shape the
+ * D-178 migration established.
+ *
+ * `carts` does not declare `customer_accounts` in its manifest `dependencies`
+ * and needs no entry for this: `customer_accounts` is created by
+ * `organizations/20260424T205317_organizations_init.ts`, 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.
+ *
+ * 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 the next `@CustomerScoped` class to gain this column is covered by
+ * gaining it.
+ */
+export class Migration20260830T112911CartsOrganizationAttributionCheck extends Migration {
+    async up() {
+        // 1. Derive the organisation from the account that owns the cart. Expected
+        //    to move nothing: `CartService` has stamped it on the owned-create
+        //    branch since the column existed, and the anonymous branch never
+        //    becomes owned (the merge completes the anonymous cart rather than
+        //    re-owning it). "Expected" is not "measured on your database", which is
+        //    why the statement runs and step 2 counts what it left.
+        this.addSql(`
+      update "carts" c
+      set "organization_id" = ca."organization_id"
+      from "customer_accounts" ca
+      where ca."id" = c."customer_account_id"
+        and c."organization_id" is null;
+    `);
+        // 2. Count what is left and refuse. A cart can only be here if its
+        //    `customer_account_id` names an account that no longer exists — the
+        //    account's own organisation is `NOT NULL` since D-178 — so the row is
+        //    owned by nobody the platform can name. The merge request that hits
+        //    this decides what to do with it; deleting a buyer's basket is never
+        //    it.
+        this.addSql(`
+      do $$
+      declare
+        remaining bigint;
+        sample text;
+      begin
+        select count(*) into remaining
+          from "carts"
+         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 "carts"
+             where "customer_account_id" is not null
+               and "organization_id" is null
+             order by "id" limit 20
+          ) s;
+          raise exception
+            'D-187: % carts row(s) still name a customer account with organization_id IS NULL after derivation. First ids: %. Every customer account has an organization (D-178), so these rows name an account that is gone. Do not delete them - decide what they belong to.',
+            remaining, sample;
+        end if;
+      end $$;
+    `);
+        // 3. The constraint.
+        this.addSql(`
+      alter table "carts"
+        add constraint "carts_organization_attribution_chk"
+        check ("customer_account_id" is null or "organization_id" is not null);
+    `);
+    }
+    async down() {
+        // Drop the constraint, and nothing else. The organisations step 1 derived
+        // were a defect rather than data — a row that named an account already
+        // belonged to that account's organisation — so there is nothing to undo.
+        this.addSql(`alter table "carts" drop constraint if exists "carts_organization_attribution_chk";`);
+    }
+}
+//# sourceMappingURL=20260830T112911_carts_organization_attribution_check.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260830T112911_carts_organization_attribution_check.js","sourceRoot":"","sources":["../../src/migrations/20260830T112911_carts_organization_attribution_check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,OAAO,yDAA0D,SAAQ,SAAS;IAC7E,KAAK,CAAC,EAAE;QACf,2EAA2E;QAC3E,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,4EAA4E;QAC5E,4DAA4D;QAC5D,IAAI,CAAC,MAAM,CAAC;;;;;;KAMX,CAAC,CAAC;QAEH,mEAAmE;QACnE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,SAAS;QACT,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;KAsBX,CAAC,CAAC;QAEH,qBAAqB;QACrB,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,0EAA0E;QAC1E,uEAAuE;QACvE,yEAAyE;QACzE,IAAI,CAAC,MAAM,CACT,qFAAqF,CACtF,CAAC;IACJ,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { Migration20260611T140352CartsConsolidation } from './20260611T140352_carts_consolidation.js';
+import { Migration20260611T140413CartsCartItemPackaging } from './20260611T140413_carts_cart_item_packaging.js';
+import { Migration20260818T081253CartsCartCompletedOrderFk } from './20260818T081253_carts_cart_completed_order_fk.js';
+import { Migration20260830T112911CartsOrganizationAttributionCheck } from './20260830T112911_carts_organization_attribution_check.js';
+export declare const migrations: (typeof Migration20260611T140352CartsConsolidation)[];
+export { Migration20260611T140352CartsConsolidation, Migration20260611T140413CartsCartItemPackaging, Migration20260818T081253CartsCartCompletedOrderFk, Migration20260830T112911CartsOrganizationAttributionCheck, };
+//# 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,0CAA0C,EAAE,MAAM,0CAA0C,CAAC;AACtG,OAAO,EAAE,8CAA8C,EAAE,MAAM,gDAAgD,CAAC;AAChH,OAAO,EAAE,iDAAiD,EAAE,MAAM,oDAAoD,CAAC;AACvH,OAAO,EAAE,yDAAyD,EAAE,MAAM,2DAA2D,CAAC;AAEtI,eAAO,MAAM,UAAU,uDAKtB,CAAC;AAEF,OAAO,EACL,0CAA0C,EAC1C,8CAA8C,EAC9C,iDAAiD,EACjD,yDAAyD,GAC1D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,35 @@
+/**
+ * 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 { Migration20260611T140352CartsConsolidation } from './20260611T140352_carts_consolidation.js';
+import { Migration20260611T140413CartsCartItemPackaging } from './20260611T140413_carts_cart_item_packaging.js';
+import { Migration20260818T081253CartsCartCompletedOrderFk } from './20260818T081253_carts_cart_completed_order_fk.js';
+import { Migration20260830T112911CartsOrganizationAttributionCheck } from './20260830T112911_carts_organization_attribution_check.js';
+export const migrations = [
+    Migration20260611T140352CartsConsolidation,
+    Migration20260611T140413CartsCartItemPackaging,
+    Migration20260818T081253CartsCartCompletedOrderFk,
+    Migration20260830T112911CartsOrganizationAttributionCheck,
+];
+export { Migration20260611T140352CartsConsolidation, Migration20260611T140413CartsCartItemPackaging, Migration20260818T081253CartsCartCompletedOrderFk, Migration20260830T112911CartsOrganizationAttributionCheck, };
+//# 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,0CAA0C,EAAE,MAAM,0CAA0C,CAAC;AACtG,OAAO,EAAE,8CAA8C,EAAE,MAAM,gDAAgD,CAAC;AAChH,OAAO,EAAE,iDAAiD,EAAE,MAAM,oDAAoD,CAAC;AACvH,OAAO,EAAE,yDAAyD,EAAE,MAAM,2DAA2D,CAAC;AAEtI,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0CAA0C;IAC1C,8CAA8C;IAC9C,iDAAiD;IACjD,yDAAyD;CAC1D,CAAC;AAEF,OAAO,EACL,0CAA0C,EAC1C,8CAA8C,EAC9C,iDAAiD,EACjD,yDAAyD,GAC1D,CAAC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The port interfaces `carts` publishes whose signature carries a MikroORM
+ * `EntityManager`, and **nothing that exists at runtime** (feature 080, T048;
+ * D-169, D-171).
+ *
+ * `tsc` compiles this file to `export {};`. That is the property D-171 makes
+ * the boundary decision on — *a subpath is contract surface iff the module it
+ * resolves to exports no runtime binding* — and it is why this declaration has
+ * its own file rather than sitting on top of `services/cart-read-port.ts`,
+ * which exports the read service and the write-port factory beside it. A
+ * consumer naming that file names the owner's implementation, whatever
+ * `import type` erases; a consumer naming this one names a declaration and can
+ * name nothing else.
+ *
+ * **This is not yet a supported specifier and the ledger still counts it.**
+ * `carts` is not a workspace package, so there is no `exports` map for this to
+ * be a subpath of, and `check:module-boundary` reads `orders`' relative import
+ * exactly as it read the two entity imports it replaces — D-171 says so in as
+ * many words: `resolveModulePackage` returns `null` for any specifier starting
+ * with `.`, so an unconverted reach has no subpath for the exemption to apply
+ * to, and reaching the exempt state takes three separable edits (package the
+ * owner, publish the interface, rewrite the specifier). This file is the second
+ * of those three, taken early because it is the one that does not need the
+ * module to move.
+ *
+ * Everything else this module publishes is in `@endora-commerce/contracts` and
+ * belongs there: `CartReadPort` and `CartWritePort` are contract DTOs end to
+ * end, so by D-171's qualifying test — *"does this signature stop the interface
+ * living in `packages/contracts`"* — neither belongs here. This one does, and
+ * for one reason: its `EntityManager` parameter, which that package may not
+ * name because `admin` and `storefront` both compile it (FR-034).
+ *
+ * No entity class leaves by this door, type-only included (D-168).
+ */
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { CartCustomerContext, CartWithItems } from '@endora-commerce/contracts';
+/**
+ * Container name: `cartPlacementApplyPort`. Owner: `carts`.
+ *
+ * The basket half of order placement, run on the **caller's** `EntityManager`
+ * (D-169). `orders` is the one consumer, and it has exactly two questions: what
+ * is on the basket I am turning into an order, and — once that order exists —
+ * finish the basket off against it.
+ *
+ * **The seam is not a defect in the design, it *is* the design.**
+ * `carts_completed_order_fk` (`carts.completed_order_id` -> `orders.id`, `on
+ * delete set null`, D-94.1) is what says so in the schema: the pointer cannot
+ * be written before the order exists, and the order does not commit until
+ * placement returns. A port that opened its own transaction would commit the
+ * completion for a placement that then failed, which is precisely the property
+ * `test/integration/orders/place-order-failure-preserves-cart.test.ts` asserts
+ * the opposite of — a buyer whose placement fails finds their basket exactly as
+ * they left it. The **cart-side** column is what forces that: an
+ * `orders.cart_id` would have been satisfiable by completing the cart in a
+ * second transaction, because the cart is already committed when the order row
+ * is written. A foreign key needs the **table** and never the class (D-169), so
+ * that constraint stands while this module publishes no entity class by name.
+ *
+ * **Why the read takes an `EntityManager` too**, when D-169 says a read handed
+ * one is a write seam re-opened to serve a read. Because it is not a read this
+ * module offers anybody — it is the first step of *this* protocol, and the rows
+ * it returns are the rows {@link CartPlacementApplyPort.completeForOrder} then
+ * writes. Reading them on a second `EntityManager` would put a commit boundary
+ * between the totals a placement quotes and the basket it clears. The
+ * standalone read is a different method on a different port and takes no
+ * `EntityManager`: `CartReadPort.findActiveForCustomer` in
+ * `@endora-commerce/contracts`, which is what `orders`' non-transactional
+ * total preview resolves.
+ *
+ * **Owner off:** unreachable. `carts` declares `activation.nonDeactivatable`,
+ * so it never enters an absent state, and there is no deactivation-consequence
+ * to state for an owner the platform refuses to switch off. The port is
+ * registered with `providePort` like every other name this module publishes, so
+ * that the answer stays the manifest's to give and not this line's.
+ */
+export interface CartPlacementApplyPort {
+    /**
+     * The customer's active basket and its lines, read on `em`.
+     *
+     * `em` is **required** (D-169). Its one caller is `placeOrder`, which always
+     * passes the `EntityManager` its own transaction runs on; an optional
+     * parameter is what lets the same method double as a standalone read, and
+     * that is a lie about a seam whose whole content is that the read and the
+     * write share a transaction.
+     *
+     * `null` when the customer has no active basket — the state the caller
+     * answers `409 CART_EMPTY` for, together with an empty line list.
+     */
+    readActiveForPlacement(em: EntityManager, ctx: CartCustomerContext): Promise<CartWithItems | null>;
+    /**
+     * Finish the basket the order was placed from: remove its lines, move it to
+     * `completed`, stamp `completed_order_id` and release the anonymous-cart
+     * token.
+     *
+     * Runs on the same `em` as the read above and as the order's own writes, for
+     * the reason `carts_completed_order_fk` gives. It is a no-op for a cart that
+     * is not there, which cannot happen on the placement path — the caller read
+     * it one transaction-step ago — and is the honest answer rather than a throw
+     * if it ever does.
+     */
+    completeForOrder(em: EntityManager, input: {
+        cartId: string;
+        orderId: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,sBAAsB,CACpB,EAAE,EAAE,aAAa,EACjB,GAAG,EAAE,mBAAmB,GACvB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACjC;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/ports/index.js

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

package/dist/ports/index.js.map

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