@dainamite/cpq 0.2.2

package/src/modules/cpq/migrations/Migration20260411000000_cpq_orders.ts

@@ -0,0 +1,62 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260411000000_cpq_orders extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`create table if not exists "cpq_order_configurations" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "order_id" uuid not null,
+      "source_quote_id" uuid null,
+      "customer_id" uuid not null,
+      "cpq_status" text not null default 'draft',
+      "currency_code" text not null default 'USD',
+      "pricing_summary" jsonb null,
+      "metadata" jsonb null,
+      "activated_at" timestamptz null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "cpq_order_configurations_pkey" primary key ("id")
+    );`)
+    this.addSql(`create unique index if not exists "cpq_order_configurations_order_unique" on "cpq_order_configurations" ("organization_id", "tenant_id", "order_id");`)
+    this.addSql(`create index if not exists "cpq_order_configurations_scope_idx" on "cpq_order_configurations" ("organization_id", "tenant_id");`)
+    this.addSql(`create index if not exists "cpq_order_configurations_customer_idx" on "cpq_order_configurations" ("organization_id", "tenant_id", "customer_id");`)
+    this.addSql(`create index if not exists "cpq_order_configurations_source_quote_idx" on "cpq_order_configurations" ("organization_id", "tenant_id", "source_quote_id");`)
+    this.addSql(`create index if not exists "cpq_order_configurations_status_idx" on "cpq_order_configurations" ("organization_id", "tenant_id", "cpq_status");`)
+
+    this.addSql(`create table if not exists "cpq_order_line_configurations" (
+      "id" uuid not null default gen_random_uuid(),
+      "organization_id" uuid not null,
+      "tenant_id" uuid not null,
+      "order_line_id" uuid not null,
+      "order_configuration_id" uuid not null,
+      "offering_id" uuid null,
+      "product_id" uuid null,
+      "spec_id" uuid null,
+      "action" text not null default 'add',
+      "parent_line_id" uuid null,
+      "start_date" date null,
+      "term_months" int null,
+      "end_date" date null,
+      "configuration" jsonb not null default '{}',
+      "quantity" int not null default 1,
+      "charges" jsonb null,
+      "nrc_total" numeric(18, 4) not null default 0,
+      "mrc_total" numeric(18, 4) not null default 0,
+      "source_quote_line_id" uuid null,
+      "created_at" timestamptz not null,
+      "updated_at" timestamptz not null,
+      "deleted_at" timestamptz null,
+      constraint "cpq_order_line_configurations_pkey" primary key ("id")
+    );`)
+    this.addSql(`create unique index if not exists "cpq_olc_order_line_unique" on "cpq_order_line_configurations" ("organization_id", "tenant_id", "order_line_id");`)
+    this.addSql(`create index if not exists "cpq_olc_order_config_idx" on "cpq_order_line_configurations" ("organization_id", "tenant_id", "order_configuration_id");`)
+    this.addSql(`create index if not exists "cpq_olc_parent_line_idx" on "cpq_order_line_configurations" ("organization_id", "tenant_id", "parent_line_id");`)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop table if exists "cpq_order_line_configurations" cascade;`)
+    this.addSql(`drop table if exists "cpq_order_configurations" cascade;`)
+  }
+}

package/src/modules/cpq/migrations/Migration20260412000000_cpq_bundled_offerings.ts

@@ -0,0 +1,33 @@
+import { Migration } from '@mikro-orm/migrations'
+
+export class Migration20260412000000_cpq_bundled_offerings extends Migration {
+  async up(): Promise<void> {
+    // Extend CpqProductSpecification with spec_type and is_assetizable
+    this.addSql(`alter table "cpq_product_specifications" add column "spec_type" text not null default 'simple';`)
+    this.addSql(`alter table "cpq_product_specifications" add column "is_assetizable" boolean not null default false;`)
+
+    // Extend CpqProductOffering with offering_type
+    this.addSql(`alter table "cpq_product_offerings" add column "offering_type" text not null default 'simple';`)
+
+    // CpqBundleSlot — structural slot within a bundle specification
+    this.addSql(`create table "cpq_bundle_slots" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "spec_id" uuid not null, "target_spec_id" uuid not null, "component_group" text not null, "name" text not null, "description" text null, "cardinality_min" integer not null default 0, "cardinality_max" integer null, "sort_order" integer not null default 0, "is_active" boolean not null default true, "metadata" jsonb null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "cpq_bundle_slots_pkey" primary key ("id"));`)
+    this.addSql(`create index "cpq_bundle_slot_spec_idx" on "cpq_bundle_slots" ("organization_id", "tenant_id", "spec_id");`)
+    this.addSql(`create index "cpq_bundle_slot_target_idx" on "cpq_bundle_slots" ("organization_id", "tenant_id", "target_spec_id");`)
+    this.addSql(`create index "cpq_bundle_slot_group_idx" on "cpq_bundle_slots" ("organization_id", "tenant_id", "spec_id", "component_group");`)
+
+    // CpqOfferingComponent — links bundle offering to component offerings
+    this.addSql(`create table "cpq_offering_components" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "offering_id" uuid not null, "slot_id" uuid not null, "child_offering_id" uuid not null, "is_default" boolean not null default false, "sort_order" integer not null default 0, "is_active" boolean not null default true, "metadata" jsonb null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "cpq_offering_components_pkey" primary key ("id"));`)
+    this.addSql(`create index "cpq_off_comp_offering_idx" on "cpq_offering_components" ("organization_id", "tenant_id", "offering_id");`)
+    this.addSql(`create index "cpq_off_comp_slot_idx" on "cpq_offering_components" ("organization_id", "tenant_id", "offering_id", "slot_id");`)
+    this.addSql(`create index "cpq_off_comp_child_idx" on "cpq_offering_components" ("organization_id", "tenant_id", "child_offering_id");`)
+    this.addSql(`alter table "cpq_offering_components" add constraint "cpq_off_comp_unique" unique ("organization_id", "tenant_id", "offering_id", "child_offering_id");`)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop table if exists "cpq_offering_components" cascade;`)
+    this.addSql(`drop table if exists "cpq_bundle_slots" cascade;`)
+    this.addSql(`alter table "cpq_product_offerings" drop column if exists "offering_type";`)
+    this.addSql(`alter table "cpq_product_specifications" drop column if exists "is_assetizable";`)
+    this.addSql(`alter table "cpq_product_specifications" drop column if exists "spec_type";`)
+  }
+}

package/src/modules/cpq/migrations/Migration20260504064621_cpq_arc.ts

@@ -0,0 +1,68 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * XD-250 ARC (Amend / Renew / Cancel) — Phase 1 schema.
+ *
+ * Adds:
+ *   - `cpq_quote_target_subscriptions` (junction quote ↔ subscription target)
+ *   - `cpq_subscription_change_logs` (append-only audit per ARC operation)
+ *   - ARC discriminator + meta columns on `cpq_quote_configurations`
+ *   - per-line target / source-item columns on `cpq_quote_line_configurations`
+ *   - term-start, merged-into, last-change-log + optimistic-lock `version`
+ *     on `cpq_inventory_subscriptions`
+ */
+export class Migration20260504064621_cpq_arc extends Migration {
+
+  override async up(): Promise<void> {
+    // ── New table: cpq_quote_target_subscriptions ─────────────────
+    this.addSql(`create table "cpq_quote_target_subscriptions" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "quote_id" uuid not null, "subscription_id" uuid not null, "quote_type" text not null, "merge_action" text null, "new_term_start" date null, "new_term_end" date null, "new_term_months" int null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, constraint "cpq_quote_target_subscriptions_pkey" primary key ("id"));`)
+    this.addSql(`create index "cpq_qts_sub_type_idx" on "cpq_quote_target_subscriptions" ("organization_id", "tenant_id", "subscription_id", "quote_type");`)
+    this.addSql(`create index "cpq_qts_quote_idx" on "cpq_quote_target_subscriptions" ("organization_id", "tenant_id", "quote_id");`)
+    this.addSql(`alter table "cpq_quote_target_subscriptions" add constraint "cpq_qts_quote_sub_unique" unique ("organization_id", "tenant_id", "quote_id", "subscription_id");`)
+
+    // ── New table: cpq_subscription_change_logs (append-only audit) ──
+    this.addSql(`create table "cpq_subscription_change_logs" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "subscription_id" uuid not null, "change_type" text not null, "source_quote_id" uuid null, "source_order_id" uuid null, "performed_by_user_id" uuid null, "effective_at" timestamptz not null, "before_snapshot" jsonb null, "after_snapshot" jsonb null, "line_changes" jsonb null, "term_change" jsonb null, "merged_into_subscription_id" uuid null, "merged_from_subscription_ids" jsonb null, "reason_code" text null, "reason_text" text null, "etf_amount" numeric(18, 4) null, "etf_currency" text null, "created_at" timestamptz not null, "deleted_at" timestamptz null, constraint "cpq_subscription_change_logs_pkey" primary key ("id"));`)
+    this.addSql(`create index "cpq_scl_merged_into_idx" on "cpq_subscription_change_logs" ("merged_into_subscription_id");`)
+    this.addSql(`create index "cpq_scl_source_order_idx" on "cpq_subscription_change_logs" ("source_order_id");`)
+    this.addSql(`create index "cpq_scl_sub_history_idx" on "cpq_subscription_change_logs" ("organization_id", "tenant_id", "subscription_id", "created_at");`)
+    // Activation idempotency: PostgreSQL treats NULLs as distinct, so multiple
+    // rows with NULL source_order_id can coexist for the same subscription.
+    this.addSql(`alter table "cpq_subscription_change_logs" add constraint "cpq_scl_order_sub_unique" unique ("source_order_id", "subscription_id");`)
+
+    // ── Existing table: cpq_inventory_subscriptions ───────────────
+    // currentTermStart complements existing currentTermEnd; mergedIntoSubscriptionId
+    // is set only when this row is a merge source; lastChangeLogId is a
+    // convenience pointer; version is a MikroORM optimistic-lock counter.
+    this.addSql(`alter table "cpq_inventory_subscriptions" add column "current_term_start" date null, add column "merged_into_subscription_id" uuid null, add column "last_change_log_id" uuid null, add column "version" int not null default 1;`)
+    this.addSql(`create index "cpq_inventory_subscriptions_merged_into_idx" on "cpq_inventory_subscriptions" ("organization_id", "tenant_id", "merged_into_subscription_id");`)
+    this.addSql(`create index "cpq_inventory_subscriptions_term_end_idx" on "cpq_inventory_subscriptions" ("organization_id", "tenant_id", "current_term_end");`)
+
+    // ── Existing table: cpq_quote_configurations ──────────────────
+    // quote_type discriminates ARC quotes; arc_reason_*/etf_*/merge_* fields
+    // carry ARC meta forward to order activation.
+    this.addSql(`alter table "cpq_quote_configurations" add column "quote_type" text not null default 'new', add column "arc_reason_code" text null, add column "arc_reason_text" text null, add column "arc_etf_amount" numeric(18, 4) null, add column "arc_etf_currency" text null, add column "arc_merge_new_term_start" date null, add column "arc_merge_new_term_end" date null, add column "arc_merge_new_term_months" int null, add column "arc_merge_new_sub_code" text null, add column "arc_merge_new_sub_name" text null;`)
+    this.addSql(`create index "cpq_quote_configurations_quote_type_idx" on "cpq_quote_configurations" ("organization_id", "tenant_id", "quote_type");`)
+
+    // ── Existing table: cpq_quote_line_configurations ─────────────
+    // target_subscription_id identifies which target sub the line affects;
+    // source_subscription_item_id points at the item being changed for
+    // cancel/modify lines.
+    this.addSql(`alter table "cpq_quote_line_configurations" add column "target_subscription_id" uuid null, add column "source_subscription_item_id" uuid null;`)
+    this.addSql(`create index "cpq_qlc_target_sub_idx" on "cpq_quote_line_configurations" ("organization_id", "tenant_id", "target_subscription_id");`)
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`drop index "cpq_qlc_target_sub_idx";`)
+    this.addSql(`alter table "cpq_quote_line_configurations" drop column "target_subscription_id", drop column "source_subscription_item_id";`)
+
+    this.addSql(`drop index "cpq_quote_configurations_quote_type_idx";`)
+    this.addSql(`alter table "cpq_quote_configurations" drop column "quote_type", drop column "arc_reason_code", drop column "arc_reason_text", drop column "arc_etf_amount", drop column "arc_etf_currency", drop column "arc_merge_new_term_start", drop column "arc_merge_new_term_end", drop column "arc_merge_new_term_months", drop column "arc_merge_new_sub_code", drop column "arc_merge_new_sub_name";`)
+
+    this.addSql(`drop index "cpq_inventory_subscriptions_merged_into_idx";`)
+    this.addSql(`drop index "cpq_inventory_subscriptions_term_end_idx";`)
+    this.addSql(`alter table "cpq_inventory_subscriptions" drop column "current_term_start", drop column "merged_into_subscription_id", drop column "last_change_log_id", drop column "version";`)
+
+    this.addSql(`drop table if exists "cpq_subscription_change_logs" cascade;`)
+    this.addSql(`drop table if exists "cpq_quote_target_subscriptions" cascade;`)
+  }
+}

package/src/modules/cpq/migrations/Migration20260514000000_cpq_spec_merge_retired_deprecated.ts

@@ -0,0 +1,30 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Merge the `retired` lifecycle status into `deprecated` for product
+ * specifications. Reviewers found the two states redundant for spec
+ * semantics (`deprecated` already conveys "do not use for new work").
+ *
+ * Scope: ONLY `cpq_product_specifications`. Offerings keep four states
+ * because the user-facing semantics differ — a `retired` offering cannot
+ * be sold at all, while `deprecated` offerings can still be sold but are
+ * discouraged. That distinction does not apply at the specification
+ * level (specs describe the product shape, not the sellability).
+ *
+ * Data-only migration: the underlying column is `text` so no schema
+ * change is required. The Zod validator on the API now rejects
+ * `'retired'` for new writes.
+ */
+export class Migration20260514000000_cpq_spec_merge_retired_deprecated extends Migration {
+  async up(): Promise<void> {
+    this.addSql(
+      `update "cpq_product_specifications" set "lifecycle_status" = 'deprecated' where "lifecycle_status" = 'retired';`,
+    )
+  }
+
+  async down(): Promise<void> {
+    // Lossy: there's no way to know which rows were originally `retired`
+    // vs originally `deprecated` once the merge runs. Down() is a no-op
+    // so a rollback doesn't silently fabricate a status.
+  }
+}

package/src/modules/cpq/migrations/Migration20260514100000_cpq_offering_merge_retired_deprecated.ts

@@ -0,0 +1,27 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Merge the `retired` lifecycle status into `deprecated` for product
+ * offerings — same call as the earlier specifications merge
+ * (`Migration20260514000000`). Reviewer wanted the offering UI to mirror
+ * the specification's 3-state ladder, so we collapse the redundant state
+ * and unify both surfaces through the single `LifecycleStatus` type and
+ * `lifecycleStatusMap` in `components/statusMaps.ts`.
+ *
+ * Data-only migration: the underlying column is `text` so no schema
+ * change is required. The Zod validator on the API now rejects
+ * `'retired'` for new offering writes.
+ */
+export class Migration20260514100000_cpq_offering_merge_retired_deprecated extends Migration {
+  async up(): Promise<void> {
+    this.addSql(
+      `update "cpq_product_offerings" set "lifecycle_status" = 'deprecated' where "lifecycle_status" = 'retired';`,
+    )
+  }
+
+  async down(): Promise<void> {
+    // Lossy: there's no way to tell which rows were originally `retired`
+    // vs originally `deprecated` once merged. Same rationale as the
+    // specifications merge — leave down() as a no-op.
+  }
+}

package/src/modules/cpq/migrations/Migration20260514110000_cpq_list_search_indexes.ts

@@ -0,0 +1,82 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Scale-prep indexes for the two highest-traffic CPQ list pages
+ * (`/backend/cpq/offerings` and `/backend/cpq/specifications`).
+ *
+ * Why: both endpoints implement free-text search as
+ * `$ilike '%term%'` against `code`, `name`, and `description`, which
+ * forces a sequential scan on every request once row counts grow.
+ * The default sort (`createdAt DESC`) also has no covering index, so
+ * pagination of a filtered set degrades linearly with table size.
+ *
+ * Target: keep both lists snappy at 10k+ rows per tenant — production
+ * customers are expected to import multiple thousands of offerings on
+ * day one. Hand-written because MikroORM's schema generator does not
+ * emit `pg_trgm` GIN operator classes or partial-index predicates.
+ *
+ * Indexes added per table (`cpq_product_offerings`, `cpq_product_specifications`):
+ *  - GIN trigram on `code`, `name`, `description` (partial: `deleted_at IS NULL`)
+ *  - B-tree `(organization_id, tenant_id, deleted_at, created_at DESC)`
+ *    to cover the default-list scan + sort path.
+ */
+export class Migration20260514110000_cpq_list_search_indexes extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`create extension if not exists "pg_trgm";`)
+
+    // ── Offerings ────────────────────────────────────────────────
+    this.addSql(
+      `create index if not exists "cpq_product_offerings_code_trgm_idx"
+         on "cpq_product_offerings" using gin ("code" gin_trgm_ops)
+         where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_product_offerings_name_trgm_idx"
+         on "cpq_product_offerings" using gin ("name" gin_trgm_ops)
+         where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_product_offerings_description_trgm_idx"
+         on "cpq_product_offerings" using gin ("description" gin_trgm_ops)
+         where "deleted_at" is null and "description" is not null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_product_offerings_list_created_idx"
+         on "cpq_product_offerings" ("organization_id", "tenant_id", "deleted_at", "created_at" desc);`,
+    )
+
+    // ── Specifications ───────────────────────────────────────────
+    this.addSql(
+      `create index if not exists "cpq_product_specifications_code_trgm_idx"
+         on "cpq_product_specifications" using gin ("code" gin_trgm_ops)
+         where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_product_specifications_name_trgm_idx"
+         on "cpq_product_specifications" using gin ("name" gin_trgm_ops)
+         where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_product_specifications_description_trgm_idx"
+         on "cpq_product_specifications" using gin ("description" gin_trgm_ops)
+         where "deleted_at" is null and "description" is not null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_product_specifications_list_created_idx"
+         on "cpq_product_specifications" ("organization_id", "tenant_id", "deleted_at", "created_at" desc);`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop index if exists "cpq_product_specifications_list_created_idx";`)
+    this.addSql(`drop index if exists "cpq_product_specifications_description_trgm_idx";`)
+    this.addSql(`drop index if exists "cpq_product_specifications_name_trgm_idx";`)
+    this.addSql(`drop index if exists "cpq_product_specifications_code_trgm_idx";`)
+
+    this.addSql(`drop index if exists "cpq_product_offerings_list_created_idx";`)
+    this.addSql(`drop index if exists "cpq_product_offerings_description_trgm_idx";`)
+    this.addSql(`drop index if exists "cpq_product_offerings_name_trgm_idx";`)
+    this.addSql(`drop index if exists "cpq_product_offerings_code_trgm_idx";`)
+    // Extension left in place — other modules may also rely on it.
+  }
+}

package/src/modules/cpq/migrations/Migration20260515000000_cpq_inventory_subscriptions_search_indexes.ts

@@ -0,0 +1,52 @@
+import { Migration } from '@mikro-orm/migrations'
+
+/**
+ * Scale-prep indexes for the customer-inventory subscriptions list.
+ *
+ * `/backend/cpq/inventory` (Subscriptions tab) lets operators search by
+ * code or name with `$ilike '%term%'`, which forces a sequential scan as
+ * soon as a tenant accumulates a few thousand subscriptions. The new
+ * "Expiring within X days" perspective filters by `currentTermEnd` —
+ * already covered by `cpq_inventory_subscriptions_term_end_idx`, but
+ * the default sort path `(organization_id, tenant_id, deleted_at,
+ * created_at DESC)` had no covering index either.
+ *
+ * Target: keep the subscriptions list snappy at 10k+ subs per tenant
+ * (production telecom-style customers easily hit that).
+ *
+ * Indexes added (`cpq_inventory_subscriptions`):
+ *   - GIN trigram on `code` (partial: `deleted_at IS NULL`)
+ *   - GIN trigram on `name` (partial: `deleted_at IS NULL`)
+ *   - B-tree `(organization_id, tenant_id, deleted_at, created_at DESC)`
+ *
+ * Hand-written because MikroORM's schema generator can't emit
+ * `gin_trgm_ops` or partial-index predicates. `pg_trgm` is already
+ * installed by `Migration20260514110000_cpq_list_search_indexes`.
+ */
+export class Migration20260515000000_cpq_inventory_subscriptions_search_indexes extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`create extension if not exists "pg_trgm";`)
+
+    this.addSql(
+      `create index if not exists "cpq_inventory_subscriptions_code_trgm_idx"
+         on "cpq_inventory_subscriptions" using gin ("code" gin_trgm_ops)
+         where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_inventory_subscriptions_name_trgm_idx"
+         on "cpq_inventory_subscriptions" using gin ("name" gin_trgm_ops)
+         where "deleted_at" is null;`,
+    )
+    this.addSql(
+      `create index if not exists "cpq_inventory_subscriptions_list_created_idx"
+         on "cpq_inventory_subscriptions" ("organization_id", "tenant_id", "deleted_at", "created_at" desc);`,
+    )
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`drop index if exists "cpq_inventory_subscriptions_list_created_idx";`)
+    this.addSql(`drop index if exists "cpq_inventory_subscriptions_name_trgm_idx";`)
+    this.addSql(`drop index if exists "cpq_inventory_subscriptions_code_trgm_idx";`)
+    // pg_trgm extension left in place — owned by the earlier migration.
+  }
+}

package/src/modules/cpq/services/__tests__/_helpers/mockEm.ts

@@ -0,0 +1,59 @@
+import type { TenantScope } from '../../types'
+
+/**
+ * Shared MikroORM EntityManager mock for cpqInventoryService /
+ * cpqQuotingService / cpqOrderService unit tests.
+ *
+ * Mirrors the subset of EM surface those services touch:
+ *   findOne / find / findAndCount / count / create / persist / flush.
+ *
+ * `create` returns a shallow-cloned input with a synthetic id when none was
+ * supplied — this matches the runtime behavior of `em.create()` returning
+ * an entity instance whose primary key gets populated either by user
+ * (pre-generated UUID) or by DB default at flush time. ARC tests (which
+ * read `result.id` immediately after creation) rely on the synthetic id;
+ * pre-existing tests that only inspect `em.create.mock.calls` are unaffected.
+ */
+export interface MockEm {
+  findOne: jest.MockedFunction<(entity: unknown, where: Record<string, unknown>) => Promise<unknown>>
+  find: jest.MockedFunction<
+    (
+      entity: unknown,
+      where: Record<string, unknown>,
+      options?: Record<string, unknown>,
+    ) => Promise<unknown[]>
+  >
+  findAndCount: jest.MockedFunction<
+    (
+      entity: unknown,
+      where: Record<string, unknown>,
+      options?: Record<string, unknown>,
+    ) => Promise<[unknown[], number]>
+  >
+  count: jest.MockedFunction<(entity: unknown, where: Record<string, unknown>) => Promise<number>>
+  create: jest.MockedFunction<(entity: unknown, data: Record<string, unknown>) => unknown>
+  persist: jest.MockedFunction<(entity: unknown) => unknown>
+  flush: jest.MockedFunction<() => Promise<void>>
+}
+
+let __syntheticIdSequence = 0
+
+export function createMockEm(): MockEm {
+  return {
+    findOne: jest.fn(),
+    find: jest.fn(),
+    findAndCount: jest.fn(),
+    count: jest.fn().mockResolvedValue(0),
+    create: jest.fn().mockImplementation((_e, data: Record<string, unknown>) => ({
+      ...data,
+      id: (data.id as string | undefined) ?? `gen-${++__syntheticIdSequence}`,
+    })),
+    persist: jest.fn(),
+    flush: jest.fn().mockResolvedValue(undefined),
+  }
+}
+
+export const TEST_SCOPE: TenantScope = {
+  tenantId: '00000000-0000-0000-0000-000000000001',
+  organizationId: '00000000-0000-0000-0000-000000000002',
+}