@endora-commerce/mod-inventory 0.100.0

package/dist/migrations/20260830T182139_inventory_organization_attribution.js

@@ -0,0 +1,178 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * D-187 — `availability_notifications` gains its organisation, and a row that
+ * names a customer account carries one.
+ *
+ * Feature 087 Group B, class 3 of 4 (`specs/087-tenant-scope-enforcement/`).
+ * `AvailabilityNotification` 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 back-in-stock subscriptions 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. This table is ownerless by construction for the
+ * storefront's anonymous "notify me when in stock" dialog — feature 010 dropped
+ * `NOT NULL` from `customer_account_id` and added `an_recipient_check`
+ * (`20260503T182812_inventory_workflow.ts`), whose whole purpose is to admit a
+ * row whose only recipient is an e-mail address — and who such a row belongs to
+ * is R-6's open question. The equivalence would answer it in the schema, which
+ * D-187 declines to do.
+ *
+ * Unlike `pwa`, nothing here can produce the opposite shape. There is no
+ * association write on this table: `customer_account_id` is written once, in
+ * `AvailabilityNotificationService.subscribe`'s `em.create`, and never assigned
+ * on an existing row (grep of `packages/modules/inventory/src` for
+ * `customerAccountId`: one write, the rest reads). So an ownerless row carrying
+ * an organisation is not reachable, and the shape the implication leaves open
+ * is empty here rather than held by a test.
+ *
+ * ## No foreign key
+ *
+ * Matching `Cart`, `Comparison` and `PushSubscription`, none of which carries
+ * one. 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. **On this table the
+ * refusal is a real branch, not a formality**, and that is why it is written
+ * with as much care as the derivation: like `push_subscriptions` and unlike
+ * `comparisons`, `availability_notifications` has **no foreign key** on
+ * `customer_account_id` — the core foundation migration
+ * (`20260424T165847_core_foundation_init.ts`) declares the column and an index
+ * and constrains nothing — so a row naming an account that is gone is
+ * representable here.
+ *
+ * It is nevertheless empty today, and the reason is worth knowing rather than
+ * hoping: a customer account is never hard-deleted in this tree.
+ * `customer-account-lifecycle-ports.ts` soft-deletes, restores and
+ * **anonymises** — the last one rewrites the e-mail and the name and keeps the
+ * row — and every one of those still satisfies `organization_id NOT NULL`
+ * (D-178), so it still derives. Change any of that 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` and
+ * `20260830T172022_pwa_organization_attribution.ts` repeated. Deleting would be
+ * particularly wrong here: a queued subscription is a promise to a customer
+ * that they will be told when the product returns, and a migration is not the
+ * place to break one.
+ *
+ * ## Ownership, and nothing to declare in the manifest
+ *
+ * `availability_notifications` is the one Group B table whose `create table` is
+ * not its module's — it comes from the core foundation migration. This column
+ * migration is still `inventory`'s, because the entity is, and module ownership
+ * is what the registry and a hard uninstall key on (D-142).
+ *
+ * `inventory` already declares both `customer_accounts` and `organizations` in
+ * its manifest `dependencies`, so the table this reads is created before this
+ * runs. No foreign key is added, so `fk-dependency-drift` has nothing to say
+ * either, and a migration naming another module's table is outside
+ * `check:module-boundary`'s population by that check's own rule.
+ *
+ * The standing guard is
+ * `backend/test/integration/tenancy/customer-scoped-organization-completeness.test.ts`,
+ * which derives its population from the ORM's metadata rather than from a list
+ * — so this class is covered by gaining the column, with no edit to that file.
+ */
+export class Migration20260830T182139InventoryOrganizationAttribution extends Migration {
+    async up() {
+        // 1. The column. Nullable, because an anonymous subscriber legitimately has
+        //    none (FR-011) and `an_recipient_check` exists to admit exactly that
+        //    row.
+        this.addSql(`alter table "availability_notifications" add column "organization_id" uuid null;`);
+        // 2. Derive the organisation from the account that owns the subscription.
+        //    Every account carries one since D-178, including a soft-deleted or
+        //    anonymised one, so this is total for every row whose account is still
+        //    there. Step 3 is about the rows for which it is not.
+        this.addSql(`
+      update "availability_notifications" an
+      set "organization_id" = ca."organization_id"
+      from "customer_accounts" ca
+      where ca."id" = an."customer_account_id"
+        and an."organization_id" is null;
+    `);
+        // 3. Count what is left and refuse. This table has no foreign key on
+        //    `customer_account_id`, so a dangling account id is representable and
+        //    this branch is real. It deletes nothing (D-184).
+        this.addSql(`
+      do $$
+      declare
+        remaining bigint;
+        sample text;
+      begin
+        select count(*) into remaining
+          from "availability_notifications"
+         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 "availability_notifications"
+             where "customer_account_id" is not null
+               and "organization_id" is null
+             order by "id" limit 20
+          ) s;
+          raise exception
+            'D-187: % availability_notifications row(s) still name a customer account with organization_id IS NULL after derivation. First ids: %. Every customer account has an organization (D-178) and none is ever hard-deleted, so these rows name an account that is gone. Do not delete them - find out how they got here.',
+            remaining, sample;
+        end if;
+      end $$;
+    `);
+        // 4. The constraint.
+        this.addSql(`
+      alter table "availability_notifications"
+        add constraint "availability_notifications_organization_attribution_chk"
+        check ("customer_account_id" is null or "organization_id" is not null);
+    `);
+        // 5. The index the entity property declares. Whole rather than partial, and
+        //    named `<table>_<column>_index`, because that is this table's own style
+        //    for an entity-declared single-column index:
+        //    `availability_notifications_customer_account_id_index` is what
+        //    `@Index()` on `customerAccountId` produced and it is unfiltered. The
+        //    `an_*` names on this table belong to the hand-written composite index
+        //    and the two check constraints, which are a different kind of object.
+        //    `pwa`'s index is partial for the same reason in reverse — it followed
+        //    `push_subscriptions_customer_idx`, which is partial.
+        this.addSql(`
+      create index "availability_notifications_organization_id_index"
+        on "availability_notifications" ("organization_id");
+    `);
+    }
+    async down() {
+        // The constraint, the index and the column. The organisations step 2
+        // derived go with the column they were written into — there is nothing to
+        // preserve, because each of them was already implied by the account its row
+        // names.
+        this.addSql(`alter table "availability_notifications" drop constraint if exists "availability_notifications_organization_attribution_chk";`);
+        this.addSql(`drop index if exists "availability_notifications_organization_id_index";`);
+        this.addSql(`alter table "availability_notifications" drop column if exists "organization_id";`);
+    }
+}
+//# sourceMappingURL=20260830T182139_inventory_organization_attribution.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"20260830T182139_inventory_organization_attribution.js","sourceRoot":"","sources":["../../src/migrations/20260830T182139_inventory_organization_attribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AACH,MAAM,OAAO,wDAAyD,SAAQ,SAAS;IAC5E,KAAK,CAAC,EAAE;QACf,4EAA4E;QAC5E,yEAAyE;QACzE,UAAU;QACV,IAAI,CAAC,MAAM,CACT,kFAAkF,CACnF,CAAC;QAEF,0EAA0E;QAC1E,wEAAwE;QACxE,2EAA2E;QAC3E,0DAA0D;QAC1D,IAAI,CAAC,MAAM,CAAC;;;;;;KAMX,CAAC,CAAC;QAEH,qEAAqE;QACrE,0EAA0E;QAC1E,sDAAsD;QACtD,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;KAsBX,CAAC,CAAC;QAEH,qBAAqB;QACrB,IAAI,CAAC,MAAM,CAAC;;;;KAIX,CAAC,CAAC;QAEH,4EAA4E;QAC5E,4EAA4E;QAC5E,iDAAiD;QACjD,oEAAoE;QACpE,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,2EAA2E;QAC3E,0DAA0D;QAC1D,IAAI,CAAC,MAAM,CAAC;;;KAGX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,qEAAqE;QACrE,0EAA0E;QAC1E,4EAA4E;QAC5E,SAAS;QACT,IAAI,CAAC,MAAM,CACT,+HAA+H,CAChI,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,0EAA0E,CAAC,CAAC;QACxF,IAAI,CAAC,MAAM,CACT,mFAAmF,CACpF,CAAC;IACJ,CAAC;CACF"}

package/dist/migrations/20260912T125716_inventory_organization_warehouses.d.ts

@@ -0,0 +1,34 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `organization_warehouses` bridge — the warehouses an organization is
+ * assigned (feature 026).
+ *
+ * It was created by `organizations`' frozen
+ * `Migration20260611T140349OrganizationsConsolidation` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3, where its
+ * `warehouses` foreign key named a table `organizations` neither owns nor
+ * declares. That is D-226's bridge rule one namespace over: a bridge between
+ * an always-present near side (`organizations`) and a switchable far side
+ * (`inventory`) belongs to the far side, because only the far side can be
+ * ordered after both tables — `inventory` declares `organizations`, and
+ * `organizations` cannot declare `inventory` without inverting an edge that
+ * already runs the other way.
+ *
+ * So an instance that does not install `inventory` no longer carries a
+ * migration whose foreign key names `warehouses`, and one that does gets the
+ * bridge with its far side. The payoff is the one the rule promises:
+ * `module:uninstall --hard inventory` now reverts this table, because a hard
+ * uninstall reverts by registry `moduleId`.
+ *
+ * `if not exists`, because every database that has already applied the
+ * frozen migration has this table. The storage keys on the class name and
+ * holds no checksum, so the reduced frozen body is not re-offered there and
+ * this migration is the no-op it reads as; on a fresh database it is the
+ * creation. The statements are the frozen ones verbatim — same columns, same
+ * primary key, same two foreign keys — so the two paths reach one schema.
+ */
+export declare class Migration20260912T125716InventoryOrganizationWarehouses extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260912T125716_inventory_organization_warehouses.d.ts.map

package/dist/migrations/20260912T125716_inventory_organization_warehouses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125716_inventory_organization_warehouses.d.ts","sourceRoot":"","sources":["../../src/migrations/20260912T125716_inventory_organization_warehouses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,uDAAwD,SAAQ,SAAS;IACrE,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260912T125716_inventory_organization_warehouses.js

@@ -0,0 +1,50 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * The `organization_warehouses` bridge — the warehouses an organization is
+ * assigned (feature 026).
+ *
+ * It was created by `organizations`' frozen
+ * `Migration20260611T140349OrganizationsConsolidation` until
+ * `specs/120-migration-closure-bridge-ownership/` Phase 3, where its
+ * `warehouses` foreign key named a table `organizations` neither owns nor
+ * declares. That is D-226's bridge rule one namespace over: a bridge between
+ * an always-present near side (`organizations`) and a switchable far side
+ * (`inventory`) belongs to the far side, because only the far side can be
+ * ordered after both tables — `inventory` declares `organizations`, and
+ * `organizations` cannot declare `inventory` without inverting an edge that
+ * already runs the other way.
+ *
+ * So an instance that does not install `inventory` no longer carries a
+ * migration whose foreign key names `warehouses`, and one that does gets the
+ * bridge with its far side. The payoff is the one the rule promises:
+ * `module:uninstall --hard inventory` now reverts this table, because a hard
+ * uninstall reverts by registry `moduleId`.
+ *
+ * `if not exists`, because every database that has already applied the
+ * frozen migration has this table. The storage keys on the class name and
+ * holds no checksum, so the reduced frozen body is not re-offered there and
+ * this migration is the no-op it reads as; on a fresh database it is the
+ * creation. The statements are the frozen ones verbatim — same columns, same
+ * primary key, same two foreign keys — so the two paths reach one schema.
+ */
+export class Migration20260912T125716InventoryOrganizationWarehouses extends Migration {
+    async up() {
+        this.addSql(`
+      create table if not exists "organization_warehouses" (
+        "organization_id" uuid not null,
+        "warehouse_id" uuid not null,
+        "created_at" timestamptz not null default now(),
+        constraint "organization_warehouses_pkey"
+          primary key ("organization_id", "warehouse_id"),
+        constraint "organization_warehouses_organization_fk"
+          foreign key ("organization_id") references "organizations" ("id") on delete cascade,
+        constraint "organization_warehouses_warehouse_fk"
+          foreign key ("warehouse_id") references "warehouses" ("id") on delete cascade
+      );
+    `);
+    }
+    async down() {
+        this.addSql('drop table if exists "organization_warehouses" cascade;');
+    }
+}
+//# sourceMappingURL=20260912T125716_inventory_organization_warehouses.js.map

package/dist/migrations/20260912T125716_inventory_organization_warehouses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260912T125716_inventory_organization_warehouses.js","sourceRoot":"","sources":["../../src/migrations/20260912T125716_inventory_organization_warehouses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,uDAAwD,SAAQ,SAAS;IAC3E,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;KAYX,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,yDAAyD,CAAC,CAAC;IACzE,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260503T182812InventoryWorkflow } from './20260503T182812_inventory_workflow.js';
+import { Migration20260611T140347InventoryWarehouseDefaultLowStockThreshold } from './20260611T140347_inventory_warehouse_default_low_stock_threshold.js';
+import { Migration20260611T140348InventoryPerWarehouseLowStockThresholds } from './20260611T140348_inventory_per_warehouse_low_stock_thresholds.js';
+import { Migration20260818T081243InventoryStockAllocationOrderItemFk } from './20260818T081243_inventory_stock_allocation_order_item_fk.js';
+import { Migration20260830T182139InventoryOrganizationAttribution } from './20260830T182139_inventory_organization_attribution.js';
+import { Migration20260912T125716InventoryOrganizationWarehouses } from './20260912T125716_inventory_organization_warehouses.js';
+export declare const migrations: (typeof Migration20260503T182812InventoryWorkflow)[];
+export { Migration20260503T182812InventoryWorkflow, Migration20260611T140347InventoryWarehouseDefaultLowStockThreshold, Migration20260611T140348InventoryPerWarehouseLowStockThresholds, Migration20260818T081243InventoryStockAllocationOrderItemFk, Migration20260830T182139InventoryOrganizationAttribution, Migration20260912T125716InventoryOrganizationWarehouses, };
+//# 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,yCAAyC,EAAE,MAAM,yCAAyC,CAAC;AACpG,OAAO,EAAE,kEAAkE,EAAE,MAAM,sEAAsE,CAAC;AAC1J,OAAO,EAAE,+DAA+D,EAAE,MAAM,mEAAmE,CAAC;AACpJ,OAAO,EAAE,2DAA2D,EAAE,MAAM,+DAA+D,CAAC;AAC5I,OAAO,EAAE,wDAAwD,EAAE,MAAM,yDAAyD,CAAC;AACnI,OAAO,EAAE,uDAAuD,EAAE,MAAM,wDAAwD,CAAC;AAEjI,eAAO,MAAM,UAAU,sDAOtB,CAAC;AAEF,OAAO,EACL,yCAAyC,EACzC,kEAAkE,EAClE,+DAA+D,EAC/D,2DAA2D,EAC3D,wDAAwD,EACxD,uDAAuD,GACxD,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,39 @@
+/**
+ * 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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260503T182812InventoryWorkflow } from './20260503T182812_inventory_workflow.js';
+import { Migration20260611T140347InventoryWarehouseDefaultLowStockThreshold } from './20260611T140347_inventory_warehouse_default_low_stock_threshold.js';
+import { Migration20260611T140348InventoryPerWarehouseLowStockThresholds } from './20260611T140348_inventory_per_warehouse_low_stock_thresholds.js';
+import { Migration20260818T081243InventoryStockAllocationOrderItemFk } from './20260818T081243_inventory_stock_allocation_order_item_fk.js';
+import { Migration20260830T182139InventoryOrganizationAttribution } from './20260830T182139_inventory_organization_attribution.js';
+import { Migration20260912T125716InventoryOrganizationWarehouses } from './20260912T125716_inventory_organization_warehouses.js';
+export const migrations = [
+    Migration20260503T182812InventoryWorkflow,
+    Migration20260611T140347InventoryWarehouseDefaultLowStockThreshold,
+    Migration20260611T140348InventoryPerWarehouseLowStockThresholds,
+    Migration20260818T081243InventoryStockAllocationOrderItemFk,
+    Migration20260830T182139InventoryOrganizationAttribution,
+    Migration20260912T125716InventoryOrganizationWarehouses,
+];
+export { Migration20260503T182812InventoryWorkflow, Migration20260611T140347InventoryWarehouseDefaultLowStockThreshold, Migration20260611T140348InventoryPerWarehouseLowStockThresholds, Migration20260818T081243InventoryStockAllocationOrderItemFk, Migration20260830T182139InventoryOrganizationAttribution, Migration20260912T125716InventoryOrganizationWarehouses, };
+//# 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,yCAAyC,EAAE,MAAM,yCAAyC,CAAC;AACpG,OAAO,EAAE,kEAAkE,EAAE,MAAM,sEAAsE,CAAC;AAC1J,OAAO,EAAE,+DAA+D,EAAE,MAAM,mEAAmE,CAAC;AACpJ,OAAO,EAAE,2DAA2D,EAAE,MAAM,+DAA+D,CAAC;AAC5I,OAAO,EAAE,wDAAwD,EAAE,MAAM,yDAAyD,CAAC;AACnI,OAAO,EAAE,uDAAuD,EAAE,MAAM,wDAAwD,CAAC;AAEjI,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,yCAAyC;IACzC,kEAAkE;IAClE,+DAA+D;IAC/D,2DAA2D;IAC3D,wDAAwD;IACxD,uDAAuD;CACxD,CAAC;AAEF,OAAO,EACL,yCAAyC,EACzC,kEAAkE,EAClE,+DAA+D,EAC/D,2DAA2D,EAC3D,wDAAwD,EACxD,uDAAuD,GACxD,CAAC"}

package/dist/ports/index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The port interfaces `inventory` 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 a service module, which exports
+ * the class 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.**
+ * `inventory` 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.
+ *
+ * The rest of this module's surface is in `@endora-commerce/contracts` and
+ * belongs there — `InventoryStockReadPort`, `InventoryFulfilmentPlanningPort`,
+ * `InventoryStockImportPort` and `InventoryProductThresholdWritePort` are
+ * contract DTOs end to end, and the planning port is pure over its arguments.
+ * This one qualifies for `./ports` on D-171's own test — *"does this signature
+ * stop the interface living in `packages/contracts`"* — and the answer is 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';
+/**
+ * What one candidate warehouse holds for one order line, under the write lock
+ * {@link InventoryReservationApplyPort.lockAvailabilityForPlacement} took — a
+ * published record and never the managed `stock_levels` row (D-77's first
+ * narrowing).
+ *
+ * `available` is `onHand - reserved` at the moment of the lock, and is `0` for
+ * a warehouse that holds no row for the line at all: an absent row and a row at
+ * zero are the same answer to *"how many can I promise"*, and the difference —
+ * whether an `insert` or an `update` follows — is this module's to know.
+ */
+export interface PlacementStockSnapshot {
+    readonly warehouseId: string;
+    readonly available: number;
+}
+/**
+ * Container name: `inventoryReservationApplyPort`. Owner: `inventory`.
+ *
+ * The stock reservation order placement performs, run on the **caller's**
+ * `EntityManager` (D-169). `orders` is the one consumer, and the four methods
+ * are the four steps of one protocol: lock the candidates, apply the plan,
+ * record the allocations once the order items exist, and release them if the
+ * order is later cancelled.
+ *
+ * **The seam is not a defect in the design, it *is* the design.**
+ * `stock_allocations_order_item_fk` (`stock_allocations.order_item_id` ->
+ * `order_items.id`, `on delete restrict`,
+ * `inventory/migrations/20260818T081243_inventory_stock_allocation_order_item_fk.ts`)
+ * means an allocation row cannot exist before its order item does, and the
+ * order items are not committed until placement returns — so a port that opened
+ * its own transaction could not satisfy a foreign key against rows it cannot
+ * see. The `PESSIMISTIC_WRITE` on `stock_levels` is the other half of the same
+ * fact: it has to be held by the transaction that writes the order, or two
+ * placements allocate the same unit
+ * (`test/contract/orders/place-stock-race.test.ts`), and a `reserved` increment
+ * committed separately would survive a placement that then rolled back. 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.
+ *
+ * **The policy half is not here, and neither is the read half.** Which
+ * warehouse a line is allocated to is `InventoryFulfilmentPlanningPort`, pure
+ * over its arguments; the channel → warehouse binding and every standalone
+ * stock read are `InventoryStockReadPort`, on this module's own
+ * `EntityManager`. Both live in `@endora-commerce/contracts` and stay there. A
+ * read handed an `EntityManager` is a write seam re-opened to serve a read
+ * (D-169), and `candidatesFor` is the worked example of the difference: it
+ * answers the richer question and answers it outside the caller's transaction,
+ * which is precisely why it cannot take the lock this port's first method
+ * takes.
+ *
+ * **Owner off:** this module is switchable (`inventory.enabled`), and `orders`
+ * declares the edge `degrades-without` rather than binding it —
+ * `stock_allocations_order_item_fk` obliges `inventory` to declare `orders`, so
+ * the edge cannot be declared back, and an acknowledged edge would keep the
+ * bind and make that control unusable, because `orders` is non-deactivatable.
+ * So placement asks the effective-state seam for this module's own id once,
+ * before the reservation block, and skips it whole; the cancellation path asks
+ * the same question before releasing. The literal is deliberately not spelled
+ * here: `check-entry-presence`'s tree proof blanks that expression out of the
+ * one file of each module that carries it, and a second file carrying it in
+ * prose makes that proof ambiguous. With this module off an order is placed without
+ * reserving stock and a cancellation releases nothing — which is what
+ * `inventory.enabled`'s own description promises an operator, and what the
+ * platform did **not** do before D-94.4, when every placement locked
+ * `stock_levels`, incremented `reserved` and inserted `stock_allocations` rows
+ * with the module switched off (issue #188).
+ */
+export interface InventoryReservationApplyPort {
+    /**
+     * Lock the line's row in each candidate warehouse under
+     * `PESSIMISTIC_WRITE` and answer what each holds.
+     *
+     * `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 lock whose whole content is that it is held until the
+     * order commits. The standalone read is a different method on a different
+     * port and takes no `EntityManager`: `InventoryStockReadPort.candidatesFor`.
+     *
+     * One entry per requested warehouse, in the order requested, so the caller
+     * can zip it against the channel binding it already holds.
+     */
+    lockAvailabilityForPlacement(em: EntityManager, input: {
+        productId: string;
+        variantId: string | null;
+        warehouseIds: readonly string[];
+    }): Promise<PlacementStockSnapshot[]>;
+    /**
+     * Apply the allocation plan: raise `reserved` by the planned quantity in each
+     * named warehouse, opening a row at `onHand = 0` where the line has none.
+     *
+     * Runs on the same `em` as the lock above, and is the write that lock exists
+     * to protect. It is not flushed here: the caller's transaction flushes it
+     * beside the order items whose foreign key holds the allocation rows, which
+     * is the statement order the reservation has always had.
+     */
+    reserveForPlacement(em: EntityManager, input: {
+        productId: string;
+        variantId: string | null;
+        allocations: ReadonlyArray<{
+            warehouseId: string;
+            quantity: number;
+        }>;
+    }): Promise<void>;
+    /**
+     * Record one allocation row per `(order item, warehouse)` pair, so an admin
+     * can trace fulfilment provenance and so cancellation has something to
+     * release.
+     *
+     * Called **after** the order items are flushed and required to be:
+     * `stock_allocations_order_item_fk` is `on delete restrict`, so the row
+     * cannot exist before its order item does.
+     */
+    recordAllocationsForOrderItems(em: EntityManager, input: {
+        allocations: ReadonlyArray<{
+            orderItemId: string;
+            warehouseId: string;
+            quantity: number;
+            isBackorder: boolean;
+        }>;
+    }): Promise<void>;
+    /**
+     * Release every un-released allocation held by the named order items,
+     * decrementing each affected `reserved` counter and stamping `released_at`.
+     *
+     * Idempotent: a second run over the same items releases nothing, because
+     * already-released rows are filtered out by `released_at is null`. `em` is
+     * the transaction the caller opened for the cancellation — a different
+     * transaction from placement's, and required for the same reason: the
+     * counter decrement and the `released_at` stamp are one operation.
+     *
+     * The caller passes the line's product and variant because `stock_allocations`
+     * records the warehouse and the order item and not the product; resolving it
+     * here would mean this module reading `order_items`, which belongs to
+     * `orders`.
+     */
+    releaseForOrderItems(em: EntityManager, input: {
+        items: ReadonlyArray<{
+            orderItemId: string;
+            productId: string;
+            variantId: string | null;
+        }>;
+    }): Promise<{
+        released: number;
+    }>;
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;;;;;;;;;OAaG;IACH,4BAA4B,CAC1B,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;KACjC,GACA,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IACrC;;;;;;;;OAQG;IACH,mBAAmB,CACjB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,WAAW,EAAE,aAAa,CAAC;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACvE,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;;;OAQG;IACH,8BAA8B,CAC5B,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QACL,WAAW,EAAE,aAAa,CAAC;YACzB,WAAW,EAAE,MAAM,CAAC;YACpB,WAAW,EAAE,MAAM,CAAC;YACpB,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,OAAO,CAAC;SACtB,CAAC,CAAC;KACJ,GACA,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAClB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE;QACL,KAAK,EAAE,aAAa,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;YACpB,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;SAC1B,CAAC,CAAC;KACJ,GACA,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClC"}

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":""}