@classytic/crm 0.8.0 → 1.0.0

package/dist/index.d.ts

@@ -1,13 +1,12 @@
-import * as _$mongoose from "mongoose";
+import { ModelBlueprint, PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 import { Connection, Model, Schema, SchemaDefinitionProperty } from "mongoose";
-import { PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 import { DomainEvent, EventHandler, EventMeta, EventTransport } from "@classytic/primitives/events";
-import * as _$_classytic_primitives_state_machine0 from "@classytic/primitives/state-machine";
+import { InProcessEventBus } from "@classytic/primitives/event-infra";
 import { z } from "zod";
 import { StatusChangeEntry, StatusHistory, appendStatus, lastTransitionTo, latestEntry, timeInStatus } from "@classytic/primitives/status-history";
 import { OperationContext } from "@classytic/primitives/context";
 import { OutboxStore } from "@classytic/primitives/outbox";
-
+import { HttpError } from "@classytic/repo-core/errors";
 //#region src/events/dispatch.d.ts
 /**
  * Context key for the post-commit event queue. `Symbol.for` so the host
@@ -59,12 +58,39 @@ declare class CrmEventDispatcher implements EventTransport {
  */
 declare function flushPending(transport: Pick<EventTransport, 'publish'> | undefined, events: DomainEvent[], logger?: CrmLogger): Promise<void>;
 //#endregion
+//#region src/engine/modules.d.ts
+/** Coarse CRM feature bundles. Keep entity-level switches out of the API. */
+interface CrmModulesConfig {
+  /** Operational sales CRM: leads, accounts, contacts, opportunities and follow-up. */
+  sales?: boolean | undefined;
+  /** Customer communication: conversations, messages, consent and email events. */
+  engagement?: boolean | undefined;
+  /** Campaign and sequence automation. Implies engagement and sales. */
+  automation?: boolean | undefined;
+}
+interface ResolvedCrmModules {
+  readonly sales: boolean;
+  readonly engagement: boolean;
+  readonly automation: boolean;
+}
+declare const ALL_CRM_MODULES: ResolvedCrmModules;
+/**
+ * Resolve module dependencies once at boot.
+ *
+ * Omitting `modules` preserves the pre-module package behaviour (everything
+ * enabled). Supplying it is opt-in: unspecified modules are disabled.
+ */
+declare function resolveCrmModules(modules: CrmModulesConfig | undefined): ResolvedCrmModules;
+//#endregion
 //#region src/models/tenant-field.d.ts
 type TenantFieldType = 'objectId' | 'string';
 interface SchemaBuildConfig {
   /** Schema type for the tenant column. Engine plumbs this everywhere. */
   tenantFieldType: TenantFieldType;
+  /** Optional Mongoose model namespace for hosts with generic model names. */
+  modelPrefix?: string | undefined;
 }
+declare function crmModelName(config: SchemaBuildConfig, base: string): string;
 /**
  * Tenant-column schema definition. Use this anywhere a model has
  * `organizationId` — never write the raw type in a schema file.
@@ -74,7 +100,7 @@ declare function tenantFieldDef(config: SchemaBuildConfig): SchemaDefinitionProp
 //#region src/models/pipeline.schema.d.ts
 /** Mongoose document shape for a single embedded stage. */
 interface IStageDocument {
-  _id: _$mongoose.Types.ObjectId;
+  _id: import('mongoose').Types.ObjectId;
   name: string;
   /** Ascending order in the pipeline. Treated as identifier on `moveToStage`. */
   sequence: number;
@@ -85,8 +111,8 @@ interface IStageDocument {
 }
 /** Mongoose document shape for a Pipeline. */
 interface IPipelineDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: string;
   /** Deprecates the pipeline — existing opps still move, no new ones created. */
   isArchived: boolean;
@@ -138,8 +164,8 @@ interface ILeadEngagement {
   lastEngagedAt?: Date;
 }
 interface ILeadDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   fullName: string;
   firstName?: string;
   lastName?: string;
@@ -155,11 +181,13 @@ interface ILeadDocument {
   statusHistory: ILeadStatusEntry[];
   ownerId?: string;
   tags: string[];
-  convertedContactId?: _$mongoose.Types.ObjectId | string;
-  convertedAccountId?: _$mongoose.Types.ObjectId | string;
-  convertedOpportunityId?: _$mongoose.Types.ObjectId | string;
+  convertedContactId?: import('mongoose').Types.ObjectId | string;
+  convertedAccountId?: import('mongoose').Types.ObjectId | string;
+  convertedOpportunityId?: import('mongoose').Types.ObjectId | string;
   convertedAt?: Date;
   disqualifyReason?: string;
+  /** GDPR tombstone — set by `anonymize()` when PII was scrubbed. */
+  anonymizedAt?: Date;
   metadata?: Record<string, unknown>;
   createdAt: Date;
   updatedAt: Date;
@@ -189,12 +217,12 @@ interface IOpportunityStatusEntry {
   note?: string;
 }
 interface IOpportunityDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: string;
-  accountId?: _$mongoose.Types.ObjectId | string;
-  primaryContactId?: _$mongoose.Types.ObjectId | string;
-  pipelineId: _$mongoose.Types.ObjectId | string;
+  accountId?: import('mongoose').Types.ObjectId | string;
+  primaryContactId?: import('mongoose').Types.ObjectId | string;
+  pipelineId: import('mongoose').Types.ObjectId | string;
   stageId: string;
   status: OpportunityStatus;
   statusHistory: IOpportunityStatusEntry[];
@@ -203,9 +231,9 @@ interface IOpportunityDocument {
   probability: number;
   expectedCloseAt?: Date;
   closedAt?: Date;
-  lostReasonId?: _$mongoose.Types.ObjectId | string;
+  lostReasonId?: import('mongoose').Types.ObjectId | string;
   ownerId?: string;
-  sourceLeadId?: _$mongoose.Types.ObjectId | string;
+  sourceLeadId?: import('mongoose').Types.ObjectId | string;
   tags: string[];
   metadata?: Record<string, unknown>;
   createdAt: Date;
@@ -234,15 +262,17 @@ interface IContactInfoEmbedded {
   instagram?: string;
 }
 interface IContactDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: IContactName;
   contact: IContactInfoEmbedded;
   jobTitle?: string;
-  accountId?: _$mongoose.Types.ObjectId | string;
+  accountId?: import('mongoose').Types.ObjectId | string;
   ownerId?: string;
   tags: string[];
   metadata?: Record<string, unknown>;
+  /** GDPR tombstone — set by `anonymize()` when PII was scrubbed. */
+  anonymizedAt?: Date;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -251,8 +281,8 @@ declare function createContactModel(connection: Connection, config: SchemaBuildC
 //#endregion
 //#region src/models/account.schema.d.ts
 interface IAccountDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: string;
   domain?: string;
   industry?: string;
@@ -291,8 +321,8 @@ interface ICampaignStatusEntry {
   note?: string;
 }
 interface ICampaignDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: string;
   description?: string;
   status: CampaignStatus;
@@ -342,10 +372,10 @@ interface ISubscriptionStatusEntry {
   note?: string;
 }
 interface ISubscriptionDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
-  contactId: _$mongoose.Types.ObjectId | string;
-  campaignId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
+  contactId: import('mongoose').Types.ObjectId | string;
+  campaignId: import('mongoose').Types.ObjectId | string;
   status: SubscriptionStatus;
   statusHistory: ISubscriptionStatusEntry[];
   source?: string;
@@ -376,9 +406,17 @@ type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
 //#endregion
 //#region src/models/suppression.schema.d.ts
 interface ISuppressionDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
-  /** Stored lowercase-normalized (schema `lowercase: true` + repo trims). */
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
+  /**
+   * The CANONICAL address, as `@classytic/contact/email` defines it: trimmed,
+   * both sides lowercased, and the domain IDNA-folded to punycode. The
+   * repository canonicalises before every read and write — the schema's
+   * `lowercase: true` is a backstop for a direct model write, not the rule.
+   *
+   * `ada@bücher.de` is stored as `ada@xn--bcher-kva.de`. Two spellings of one
+   * host stored as two rows is a suppression that silently never matches.
+   */
   email: string;
   reason: SuppressionReason;
   /** Free-form origin: 'campaign:<id>', 'sequence:<id>', 'api', 'import', … */
@@ -415,12 +453,12 @@ type SubjectKind = (typeof SUBJECT_KINDS)[number];
 //#endregion
 //#region src/models/activity.schema.d.ts
 interface IActivityDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   type: ActivityType;
   status: ActivityStatus;
   subjectKind: SubjectKind;
-  subjectId: _$mongoose.Types.ObjectId | string;
+  subjectId: import('mongoose').Types.ObjectId | string;
   title: string;
   description?: string;
   ownerId?: string;
@@ -437,10 +475,10 @@ declare function createActivityModel(connection: Connection, config: SchemaBuild
 //#endregion
 //#region src/models/note.schema.d.ts
 interface INoteDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   subjectKind: SubjectKind;
-  subjectId: _$mongoose.Types.ObjectId | string;
+  subjectId: import('mongoose').Types.ObjectId | string;
   body: string;
   authorId?: string;
   pinned: boolean;
@@ -453,8 +491,8 @@ declare function createNoteModel(connection: Connection, config: SchemaBuildConf
 //#endregion
 //#region src/models/loss-reason.schema.d.ts
 interface ILossReasonDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: string;
   description?: string;
   isActive: boolean;
@@ -501,12 +539,12 @@ type EmailEventKind = (typeof EMAIL_EVENT_KINDS)[number];
 declare const EMAIL_EVENT_SUBJECT_KINDS: readonly ["contact", "subscription"];
 type EmailEventSubjectKind = (typeof EMAIL_EVENT_SUBJECT_KINDS)[number];
 interface IEmailEventDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   kind: EmailEventKind;
   subjectKind: EmailEventSubjectKind;
-  subjectId: _$mongoose.Types.ObjectId | string;
-  campaignId?: _$mongoose.Types.ObjectId | string;
+  subjectId: import('mongoose').Types.ObjectId | string;
+  campaignId?: import('mongoose').Types.ObjectId | string;
   messageId?: string;
   url?: string;
   userAgent?: string;
@@ -540,11 +578,11 @@ type MessageDeliveryStatus = (typeof MESSAGE_DELIVERY_STATUSES)[number];
 //#endregion
 //#region src/models/conversation.schema.d.ts
 interface IConversationDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   channel: ConversationChannel;
   participantKind: ConversationParticipantKind;
-  participantId: _$mongoose.Types.ObjectId | string;
+  participantId: import('mongoose').Types.ObjectId | string;
   /** Channel-side identifier (e.g. WhatsApp wa_id, Telegram chat id). */
   channelUserId?: string;
   status: ConversationStatus;
@@ -571,9 +609,9 @@ interface IMessageAttachment {
   mimeType?: string;
 }
 interface IMessageDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
-  conversationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
+  conversationId: import('mongoose').Types.ObjectId | string;
   direction: MessageDirection;
   body: string;
   attachments: IMessageAttachment[];
@@ -635,8 +673,8 @@ interface ISequenceStatusEntry {
   note?: string;
 }
 interface ISequenceDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
   name: string;
   description?: string;
   status: SequenceStatus;
@@ -687,11 +725,11 @@ interface IEnrollmentStatusEntry {
   by?: string;
 }
 interface IEnrollmentDocument {
-  _id: _$mongoose.Types.ObjectId;
-  organizationId: _$mongoose.Types.ObjectId | string;
-  sequenceId: _$mongoose.Types.ObjectId | string;
+  _id: import('mongoose').Types.ObjectId;
+  organizationId: import('mongoose').Types.ObjectId | string;
+  sequenceId: import('mongoose').Types.ObjectId | string;
   subjectKind: EnrollmentSubjectKind;
-  subjectId: _$mongoose.Types.ObjectId | string;
+  subjectId: import('mongoose').Types.ObjectId | string;
   status: EnrollmentStatus;
   /** Index into sequence.steps[] — 0-based. */
   currentStepIndex: number;
@@ -730,19 +768,27 @@ interface CrmModels {
   Sequence: Model<ISequenceDocument>;
   Enrollment: Model<IEnrollmentDocument>;
 }
-/** Mongoose model names this package registers — drives the §21 collision check. */
+type ModularCrmModels = Partial<CrmModels>;
+/** Mongoose model names this package can register (before `modelPrefix`). Reference/documentation. */
 declare const CRM_MODEL_NAMES: readonly ["Pipeline", "Lead", "Opportunity", "Contact", "Account", "Campaign", "EmailSubscription", "Suppression", "Activity", "Note", "LossReason", "EmailEvent", "Conversation", "Message", "Sequence", "Enrollment"];
-interface CreateModelsOptions extends SchemaBuildConfig {
+interface DefineCrmModelsConfig extends SchemaBuildConfig {
+  /** Which model families to describe. A disabled family contributes no spec. */
+  modules: ResolvedCrmModules;
   /**
-   * On a model-name collision: `false` (default) throws
-   * `CrmModelCollisionError`; `true` deletes + re-registers (test
-   * fixtures / hot reload only).
+   * On a model-name collision: `false` (default) uses mongokit's `throw`
+   * policy (`ModelCollisionError`); `true` uses `replace` (test fixtures /
+   * hot reload only — mongokit refuses `replace` under `NODE_ENV=production`).
    */
   forceRecreate?: boolean;
-  /** Mongoose auto-index builds. Default `true` (dev); `false` in prod. */
+  /** Mongoose auto-index builds. Default `true` (dev); `false` in prod (§35). */
   autoIndex?: boolean;
 }
-declare function createCrmModels(connection: Connection, config: CreateModelsOptions): CrmModels;
+/**
+ * Describe the CRM model set as a connection-free blueprint. Pure — builds no
+ * schema and registers nothing until `.bind(connection)`. Only the enabled
+ * module families contribute `ModelSpec` entries.
+ */
+declare function defineCrmModels(config: DefineCrmModelsConfig): ModelBlueprint<ModularCrmModels>;
 //#endregion
 //#region src/repositories/pipeline.repository.d.ts
 interface PipelineRepositoryDeps {
@@ -809,6 +855,11 @@ declare class LeadRepository extends Repository<ILeadDocument> {
    * Create a Lead. Auto-scores on insert so hosts can route immediately.
    * Rejects duplicate emails inside the same tenant unless
    * `rejectDuplicates: false` was set at engine boot.
+   *
+   * Throws `LeadEmailFormatError` (400) on an email that cannot be canonicalised
+   * — nothing is written. The reason lives beside the helper in
+   * `core/email-identity.ts`, which also explains why the SCHEMA setter degrades
+   * where this verb refuses.
    */
   createLead(input: Partial<ILeadDocument>, ctx?: CrmContext): Promise<ILeadDocument>;
   markContacted(id: string, extras?: TransitionExtras, ctx?: CrmContext): Promise<ILeadDocument>;
@@ -845,6 +896,29 @@ declare class LeadRepository extends Repository<ILeadDocument> {
    * automatically; hosts also call this after enrichment writes.
    */
   recomputeScore(id: string, ctx?: CrmContext): Promise<ILeadDocument>;
+  /**
+   * The `converted` hop, owned by `LeadService.convert()` (the only caller
+   * — the four cross-repo writes make it a service concern). Kept on the
+   * repo so the atomic state write goes through `applyTransition` — a
+   * machine-guarded CAS that `$push`es the history entry instead of
+   * read-then-replacing the whole `statusHistory` array (no lost-update
+   * window). Deliberately emits NO `lead.status_changed`: `lead.converted`
+   * is the canonical signal for this transition and is dispatched by the
+   * service alongside the cross-repo refs.
+   */
+  markConverted(id: string, from: LeadStatus, patch: Partial<ILeadDocument>, entry: ILeadStatusEntry, ctx?: CrmContext): Promise<ILeadDocument>;
+  /**
+   * GDPR right-to-erasure for a Lead. Scrubs the PII fields
+   * (`fullName`/`firstName`/`lastName`/`email`/`phone`) in place while
+   * preserving non-PII aggregates (`score`, `status`, `statusHistory`,
+   * `engagement`, firmographic `companyName`/`source`) and the id. Sets
+   * `anonymizedAt` and emits `crm:lead.anonymized`.
+   *
+   * `fullName` is `required`, so it becomes the `'[redacted]'` sentinel;
+   * the optional PII scalars are nulled (dropping `email` out of the
+   * partial-unique email index). Idempotent.
+   */
+  anonymize(id: string, ctx?: CrmContext): Promise<ILeadDocument>;
   private _transition;
   /**
    * Count leads created on or after `since`. Used by dashboard KPI tiles.
@@ -937,15 +1011,21 @@ declare class OpportunityRepository extends Repository<IOpportunityDocument> {
   /** Count opportunities with status `open`. Used by dashboard KPI tiles. */
   countOpen(ctx?: CrmContext): Promise<number>;
   /**
-   * Sum `amount` on won opportunities updated within `since`.
-   * Goes through the tenant-scoped `findAll()` — the multiTenant plugin
-   * injects `organizationId`, so a missing ctx can't leak other tenants'
-   * revenue (a manual `if (ctx)` filter would).
+   * Sum `amount` on won opportunities updated on/after `since`, grouped by
+   * currency. Returns one row per currency (descending by total) — a deal
+   * book is multi-currency, so collapsing to a single total would silently
+   * drop every non-top currency's revenue.
+   *
+   * Uses `aggregatePipeline` (a DB-side `$group`) instead of loading every
+   * won opp into memory: the multiTenant + soft-delete policy hooks prepend
+   * their `$match` so a missing ctx can't leak other tenants' revenue, and
+   * the row count is bounded by the number of distinct currencies, not the
+   * number of deals.
    */
-  sumWonSince(since: Date, ctx?: CrmContext): Promise<{
+  sumWonSince(since: Date, ctx?: CrmContext): Promise<Array<{
+    currency: string;
     total: number;
-    currency?: string;
-  } | null>;
+  }>>;
   /** Latest `limit` opportunities — lightweight projection for the activity feed. */
   findRecentForFeed(limit: number, ctx?: CrmContext): Promise<IOpportunityDocument[]>;
 }
@@ -953,7 +1033,23 @@ declare class OpportunityRepository extends Repository<IOpportunityDocument> {
 //#region src/repositories/contact.repository.d.ts
 interface ContactRepositoryDeps {
   events: CrmEventDispatcher;
+  /** Reject `createContact()` when an email already exists in-tenant (default true). */
+  rejectDuplicates?: boolean;
 }
+/**
+ * Optional synchronous re-point hook fired INSIDE `merge()`, BEFORE the
+ * secondary is deleted — inside the caller's `ctx.session` when one is
+ * passed. Use it to move the doomed secondary's FKs onto the primary
+ * (EmailSubscription
+ * `.contactId` is `required`, plus Opportunity `.primaryContactId`,
+ * Activity/Note `.subjectId`) so the delete never orphans a required
+ * reference. Throwing here aborts the merge — nothing is deleted.
+ */
+type ContactMergeRepoint = (args: {
+  primaryId: string;
+  secondaryId: string;
+  ctx?: CrmContext;
+}) => Promise<void> | void;
 interface MergeContactInput {
   /** Surviving contact id. Receives merged fields. */
   primaryId: string;
@@ -965,13 +1061,30 @@ interface MergeContactInput {
    * for the reverse. `tags` are always unioned.
    */
   strategy?: 'preferPrimary' | 'preferSecondary';
+  /**
+   * Optional FK re-point seam — see {@link ContactMergeRepoint}. Pass this
+   * to atomically move the secondary's required references onto the primary
+   * before it is deleted. When omitted, re-pointing stays the host's job
+   * via the async `crm:contact.merged` event (the legacy contract).
+   */
+  repoint?: ContactMergeRepoint;
 }
 declare class ContactRepository extends Repository<IContactDocument> {
   private readonly events;
+  private readonly rejectDuplicates;
   constructor(model: Model<IContactDocument>, plugins: PluginType[], deps: ContactRepositoryDeps, pagination?: PaginationConfig);
   /**
    * Create + emit `crm:contact.created`. Hosts call this instead of
    * `create()` when they want the event side-effect (e.g. webhook fan-out).
+   *
+   * Rejects duplicate emails inside the same tenant unless
+   * `rejectDuplicates: false` was set — mirrors `LeadRepository.createLead`.
+   * The partial-unique `(organizationId, contact.email)` index is the
+   * authoritative guard; the pre-check only closes the fast path.
+   *
+   * Throws `ContactEmailFormatError` (400) on an email that cannot be
+   * canonicalised — nothing is written. See `core/email-identity.ts` for the
+   * reason, including what it means for `LeadService.convert()`.
    */
   createContact(input: Partial<IContactDocument>, ctx?: CrmContext): Promise<IContactDocument>;
   /**
@@ -997,6 +1110,22 @@ declare class ContactRepository extends Repository<IContactDocument> {
    * from there.
    */
   merge(input: MergeContactInput, ctx?: CrmContext): Promise<IContactDocument>;
+  /**
+   * GDPR right-to-erasure. Scrubs every PII field on the contact in place —
+   * the structured `name` and ALL `contact.*` channels (email,
+   * personalEmail, phone, alternatePhone, whatsapp, telegram, linkedin,
+   * instagram) — while preserving the id and non-PII aggregates
+   * (`accountId`, `ownerId`, `tags`, timestamps) so historical rollups and
+   * relationships survive. Sets `anonymizedAt` as a tombstone and emits
+   * `crm:contact.anonymized`. Idempotent: a second call re-scrubs to the
+   * same sentinel.
+   *
+   * `name.given` is `required`, so it becomes the `'[redacted]'` sentinel
+   * rather than empty; every other name part and the whole `contact`
+   * subdocument are cleared. Unsetting `contact.email` also drops the row
+   * out of the partial-unique email index, freeing the address for reuse.
+   */
+  anonymize(id: string, ctx?: CrmContext): Promise<IContactDocument>;
 }
 //#endregion
 //#region src/repositories/account.repository.d.ts
@@ -1084,6 +1213,15 @@ interface SuppressInput {
   subjectId?: string;
   metadata?: Record<string, unknown>;
 }
+/**
+ * The suppression key for `email`, or `null` when it cannot be canonicalised.
+ *
+ * Exported because it is the ONLY way a caller can distinguish "this address is on
+ * the list" from "this address is not an address" — the read verbs collapse both
+ * to `true` on purpose (see the fail-closed rule in the module docblock), and a
+ * caller that needs the distinction should not re-derive the rule to get it.
+ */
+declare function suppressionEmailKey(email: string): string | null;
 declare class SuppressionRepository extends Repository<ISuppressionDocument> {
   private readonly events;
   constructor(model: Model<ISuppressionDocument>, plugins: PluginType[], deps: SuppressionRepositoryDeps, pagination?: PaginationConfig);
@@ -1092,18 +1230,36 @@ declare class SuppressionRepository extends Repository<ISuppressionDocument> {
    * `getOrCreate` on the unique (org, email) index — of N concurrent
    * calls exactly one inserts. Emits `crm:suppression.added` only for
    * the inserting call; an existing row is returned unchanged, no event.
+   *
+   * Throws `SuppressionEmailFormatError` (400) on an address that cannot be
+   * canonicalised — nothing is written.
    */
   suppress(email: string, input: SuppressInput, ctx?: CrmContext): Promise<ISuppressionDocument>;
-  /** True when `email` is on the org's suppression list. */
+  /**
+   * True when `email` is on the org's suppression list — **or when it cannot be
+   * canonicalised at all**, which is the fail-closed half of the module rule
+   * above. Never throws on a malformed address: the safe answer is "do not send",
+   * and this verb's job is to produce that answer, not to police the input.
+   */
   isSuppressed(email: string, ctx?: CrmContext): Promise<boolean>;
   /**
-   * Return the suppressed subset of `emails` (normalized) as a Set —
-   * ONE `$in` query, built for the campaign-fanout hot path:
+   * Return the suppressed subset of `emails` as a Set — ONE `$in` query, built for
+   * the campaign-fanout hot path:
    *
    * ```ts
    * const blocked = await suppression.filterSuppressed(recipients, ctx);
-   * const sendable = recipients.filter((e) => !blocked.has(e.toLowerCase()));
+   * const sendable = recipients.filter((e) => !blocked.has(suppressionEmailKey(e) ?? e));
    * ```
+   *
+   * The Set is keyed CANONICALLY, so a caller must canonicalise its own recipient
+   * before testing membership — matching on the raw spelling is how the punycode
+   * miss came back. `suppressionEmailKey` is exported for exactly that, and returns
+   * `null` for an address with no canonical form.
+   *
+   * An address that cannot be canonicalised is reported as BLOCKED, keyed by the
+   * caller's original spelling (there is no canonical form to key it by, and the
+   * caller has to be able to find it). It is not thrown: one malformed recipient
+   * must not abort a fanout to thousands of valid ones.
    */
   filterSuppressed(emails: string[], ctx?: CrmContext): Promise<Set<string>>;
   /**
@@ -1111,6 +1267,11 @@ declare class SuppressionRepository extends Repository<ISuppressionDocument> {
    * `deleteMany` on the (unique) email key — emits
    * `crm:suppression.removed` only when a row was actually removed.
    * Returns whether a row was removed.
+   *
+   * Throws `SuppressionEmailFormatError` (400) on an address that cannot be
+   * canonicalised, rather than answering `false`. This is the verb that re-enables
+   * sending, and `false` would read as "already removed" when the truth is "that
+   * was never an address" — an operator would close the ticket either way.
    */
   unsuppress(email: string, ctx?: CrmContext): Promise<boolean>;
 }
@@ -1342,56 +1503,78 @@ interface CrmLogger {
   error?(msg: string, meta?: Record<string, unknown>): void;
   debug?(msg: string, meta?: Record<string, unknown>): void;
 }
-interface CrmConfig {
-  /** Mongoose connection — package creates models on this connection. */
-  connection: Connection;
+/**
+ * DESCRIBE-time shape (Kernel Construction Standard §6.2) — everything that
+ * determines the persistence SHAPE and needs no connection or I/O to inspect.
+ * Passed to `defineCrm(shape)`; nothing here opens a socket or reads a secret.
+ */
+interface CrmShape {
   /**
    * Tenant column shape. `'objectId'` (default) matches Better Auth orgs
    * and unlocks `$lookup` / `.populate()`; `'string'` matches UUID hosts.
    * Threaded into both schemas and `multiTenantPlugin` so they stay in
    * sync (PACKAGE_RULES §9.2).
    */
-  tenantFieldType?: TenantFieldType;
+  tenantFieldType?: TenantFieldType | undefined;
+  /**
+   * Prefix for Mongoose model registry names (for example `Crm` produces
+   * `CrmAccount`). Use in large hosts where generic names such as `Account`
+   * are already owned by accounting or identity modules.
+   */
+  modelPrefix?: string | undefined;
   /**
    * When `true` (default), wire `multiTenantPlugin` on every repository
    * with `required: true`. Set `false` only for fixtures / smoke tests
    * that intentionally drop the scope.
    */
-  multiTenant?: boolean;
-  /** Arc-compatible event transport. Default: in-process bus. */
-  eventTransport?: EventTransport;
+  multiTenant?: boolean | undefined;
   /**
-   * Transactional outbox (PACKAGE_RULES §P8). When wired, every domain
-   * event is persisted via `outbox.save(event, { session })` in the SAME
-   * session as the business write — the host's relay publishes committed
-   * rows. Without it, events publish post-write (or defer to a
-   * `ctx[PENDING_EVENTS]` queue inside `engine.withTransaction`).
+   * Progressive feature bundles (PACKAGE_RULES §22). Omit for the
+   * all-enabled engine. When provided, unspecified modules are disabled;
+   * dependencies are enabled automatically.
    */
-  outbox?: OutboxStore;
-  /** Logger surface used by the in-process bus + repositories. */
-  logger?: CrmLogger;
-  /** Pagination defaults for every repository (mongokit). */
-  pagination?: PaginationConfig;
-  /** Extra mongokit plugins applied to every repository (after defaults). */
-  plugins?: PluginType[];
+  modules?: CrmModulesConfig | undefined;
   /**
    * On a Mongoose model-name collision (another engine / hot reload owns
-   * the name): `false` (default) throws `CrmModelCollisionError`; `true`
-   * deletes + re-registers. Test fixtures / hot reload only (§21).
+   * the name): `false` (default) throws mongokit's `ModelCollisionError`;
+   * `true` re-registers. Test fixtures / hot reload only (§21).
    */
-  forceRecreate?: boolean;
+  forceRecreate?: boolean | undefined;
   /**
    * Mongoose auto-index builds. Default `true` (dev). Set `false` in
    * production and run `engine.syncIndexes()` from a deploy script so
    * cold-boot index builds don't blow Fastify's plugin timeout (§35).
    */
-  autoIndex?: boolean;
+  autoIndex?: boolean | undefined;
+}
+/**
+ * BIND-time runtime collaborators (Kernel Construction Standard §6.2). The live
+ * connection is the first `bind` arg; these are the rest. A transport, outbox,
+ * logger or plugin set belongs here, not in the shape.
+ */
+interface CrmRuntime {
+  /** Arc-compatible event transport. Default: in-process bus (owned + closed by the engine). */
+  eventTransport?: EventTransport | undefined;
+  /**
+   * Transactional outbox (PACKAGE_RULES §P8). When wired, every domain
+   * event is persisted via `outbox.save(event, { session })` in the SAME
+   * session as the business write — the host's relay publishes committed
+   * rows. Without it, events publish post-write (or defer to a
+   * `ctx[PENDING_EVENTS]` queue inside `engine.withTransaction`).
+   */
+  outbox?: OutboxStore | undefined;
+  /** Logger surface used by the in-process bus + repositories. */
+  logger?: CrmLogger | undefined;
+  /** Pagination defaults for every repository (mongokit). */
+  pagination?: PaginationConfig | undefined;
+  /** Extra mongokit plugins applied to every repository (after defaults). */
+  plugins?: PluginType[] | undefined;
   /**
    * Skip the boot-time `transactions` capability requirement, downgrading
    * it to a warning. Set only when the host never calls
    * `LeadService.convert()` inside a transaction (standalone Mongo).
    */
-  allowNonTransactional?: boolean;
+  allowNonTransactional?: boolean | undefined;
 }
 interface ResolvedCrmConfig extends SchemaBuildConfig {
   connection: Connection;
@@ -1399,8 +1582,9 @@ interface ResolvedCrmConfig extends SchemaBuildConfig {
   multiTenant: boolean;
   forceRecreate: boolean;
   autoIndex: boolean;
-  logger?: CrmLogger;
-  pagination?: PaginationConfig;
+  modules: ResolvedCrmModules;
+  logger?: CrmLogger | undefined;
+  pagination?: PaginationConfig | undefined;
   plugins: PluginType[];
 }
 interface CrmRepositories {
@@ -1421,9 +1605,30 @@ interface CrmRepositories {
   sequence: SequenceRepository;
   enrollment: EnrollmentRepository;
 }
-interface CrmEngine {
+type ModularCrmRepositories = Partial<CrmRepositories>;
+type SalesCrmModels = Pick<CrmModels, 'Pipeline' | 'Lead' | 'Opportunity' | 'Contact' | 'Account' | 'Activity' | 'Note' | 'LossReason'>;
+type SalesCrmRepositories = Pick<CrmRepositories, 'pipeline' | 'lead' | 'opportunity' | 'contact' | 'account' | 'activity' | 'note' | 'lossReason'>;
+type EngagementCrmModels = Pick<CrmModels, 'Subscription' | 'Suppression' | 'EmailEvent' | 'Conversation' | 'Message'>;
+type EngagementCrmRepositories = Pick<CrmRepositories, 'subscription' | 'suppression' | 'emailEvent' | 'conversation' | 'message'>;
+type AutomationCrmModels = Pick<CrmModels, 'Campaign' | 'Sequence' | 'Enrollment'>;
+type AutomationCrmRepositories = Pick<CrmRepositories, 'campaign' | 'sequence' | 'enrollment'>;
+interface CrmModuleView<TModels, TRepositories> {
+  readonly models: Readonly<TModels>;
+  readonly repositories: Readonly<TRepositories>;
+}
+interface ModularCrmModuleViews {
+  readonly sales?: CrmModuleView<SalesCrmModels, SalesCrmRepositories> | undefined;
+  readonly engagement?: CrmModuleView<EngagementCrmModels, EngagementCrmRepositories> | undefined;
+  readonly automation?: CrmModuleView<AutomationCrmModels, AutomationCrmRepositories> | undefined;
+}
+interface FullCrmModuleViews {
+  readonly sales: CrmModuleView<SalesCrmModels, SalesCrmRepositories>;
+  readonly engagement: CrmModuleView<EngagementCrmModels, EngagementCrmRepositories>;
+  readonly automation: CrmModuleView<AutomationCrmModels, AutomationCrmRepositories>;
+}
+interface CrmEngineBase<TModels, TRepositories, TModules> {
   /** Repositories ARE the API surface (PACKAGE_RULES §1). */
-  readonly repositories: Readonly<CrmRepositories>;
+  readonly repositories: Readonly<TRepositories>;
   /**
    * Arc-compatible event transport (a `CrmEventDispatcher` wrapping the
    * configured transport — `publish`/`subscribe` behave exactly like the
@@ -1431,7 +1636,9 @@ interface CrmEngine {
    */
   readonly events: CrmEventDispatcher;
   /** Mongoose models — for arc adapter wiring. */
-  readonly models: Readonly<CrmModels>;
+  readonly models: Readonly<TModels>;
+  /** Capability-oriented views for hosts that opt into progressive modules. */
+  readonly modules: Readonly<TModules>;
   /** Resolved configuration (frozen). */
   readonly config: Readonly<ResolvedCrmConfig>;
   /**
@@ -1453,8 +1660,34 @@ interface CrmEngine {
    * deploy when booted with `autoIndex: false` (§35). Idempotent.
    */
   syncIndexes(): Promise<void>;
-  /** Release resources. Safe to call multiple times. */
-  dispose(): Promise<void>;
+  /**
+   * Tear the engine down (Kernel Construction Standard §6.4 — the sole teardown
+   * name). Closes the event bus ONLY when the engine created it itself
+   * (`InProcessCrmBus`); a host-injected `eventTransport` is the host's to
+   * close. Idempotent — a second call is a no-op. Mongoose
+   * models/connection are untouched.
+   */
+  close(): Promise<void>;
+}
+/** All-enabled engine returned when `shape.modules` is omitted. */
+type CrmEngine = CrmEngineBase<CrmModels, CrmRepositories, FullCrmModuleViews>;
+/** Progressive engine returned when a `modules` selection is supplied. */
+type ModularCrmEngine = CrmEngineBase<ModularCrmModels, ModularCrmRepositories, ModularCrmModuleViews>;
+/**
+ * The connection-free description produced by `defineCrm(shape)` (Kernel
+ * Construction Standard §6.1). `defineCrm` is the SOLE construction API — there
+ * is no `createCrm` wrapper. `bind` compiles the schemas on the supplied
+ * connection, wires the engine, verifies capabilities, and returns the engine.
+ */
+interface CrmBlueprint<TEngine extends CrmEngine | ModularCrmEngine = ModularCrmEngine> {
+  readonly id: 'crm';
+  /** The model names this blueprint registers — known without a connection. */
+  readonly modelNames: readonly string[];
+  /**
+   * Compile + register the models on `connection`, wire repositories/transport,
+   * verify capabilities, and return the frozen engine.
+   */
+  bind(connection: Connection, runtime?: CrmRuntime): TEngine;
 }
 /**
  * Operation context threaded through every domain verb. Extends
@@ -1463,22 +1696,28 @@ interface CrmEngine {
  * `metadata?` field — keep the typed surface tight.
  */
 interface CrmContext extends OperationContext {
-  organizationId?: string | _$mongoose.Types.ObjectId;
-  actorId?: string | _$mongoose.Types.ObjectId;
+  organizationId?: string | import('mongoose').Types.ObjectId;
+  actorId?: string | import('mongoose').Types.ObjectId;
   /** Mongo transaction session (passed through to mongokit). */
   session?: unknown;
 }
 type _ModelTypes = Model<unknown>;
 //#endregion
-//#region src/engine/create-crm.d.ts
-declare function createCrm(config: CrmConfig): Promise<CrmEngine>;
+//#region src/engine/define-crm.d.ts
+declare function defineCrm(shape: CrmShape & {
+  modules: CrmModulesConfig;
+}): CrmBlueprint<ModularCrmEngine>;
+declare function defineCrm(shape?: CrmShape & {
+  modules?: undefined;
+}): CrmBlueprint<CrmEngine>;
+declare function defineCrm(shape?: CrmShape): CrmBlueprint<ModularCrmEngine>;
 //#endregion
 //#region src/repositories/create-repositories.d.ts
 interface CreateCrmRepositoriesDeps {
   events: CrmEventDispatcher;
   config: ResolvedCrmConfig;
 }
-declare function createCrmRepositories(models: CrmModels, deps: CreateCrmRepositoriesDeps): CrmRepositories;
+declare function createCrmRepositories(models: ModularCrmModels, deps: CreateCrmRepositoriesDeps): ModularCrmRepositories;
 //#endregion
 //#region src/services/lead.service.d.ts
 interface ConvertLeadInput {
@@ -1598,9 +1837,11 @@ declare const CRM_EVENTS: {
   readonly EMAIL_EVENT_UNSUBSCRIBED: "crm:email_event.unsubscribed";
   readonly LEAD_ENRICHED: "crm:lead.enriched";
   readonly LEAD_ASSIGNED: "crm:lead.assigned";
+  readonly LEAD_ANONYMIZED: "crm:lead.anonymized";
   readonly CONTACT_ENRICHED: "crm:contact.enriched";
   readonly CONTACT_ASSIGNED: "crm:contact.assigned";
   readonly CONTACT_MERGED: "crm:contact.merged";
+  readonly CONTACT_ANONYMIZED: "crm:contact.anonymized";
   readonly ACCOUNT_ENRICHED: "crm:account.enriched";
   readonly ACCOUNT_ASSIGNED: "crm:account.assigned";
   readonly ACCOUNT_MERGED: "crm:account.merged";
@@ -1666,6 +1907,10 @@ declare const LeadAssigned: CrmEventDefinition<z.ZodObject<{
   ownerId: z.ZodString;
   previousOwnerId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
+declare const LeadAnonymized: CrmEventDefinition<z.ZodObject<{
+  leadId: z.ZodString;
+  fields: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;
 declare const AccountCreated: CrmEventDefinition<z.ZodObject<{
   accountId: z.ZodString;
   name: z.ZodString;
@@ -1716,6 +1961,10 @@ declare const ContactMerged: CrmEventDefinition<z.ZodObject<{
     preferSecondary: "preferSecondary";
   }>;
 }, z.core.$strip>>;
+declare const ContactAnonymized: CrmEventDefinition<z.ZodObject<{
+  contactId: z.ZodString;
+  fields: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;
 declare const OpportunityCreated: CrmEventDefinition<z.ZodObject<{
   opportunityId: z.ZodString;
   pipelineId: z.ZodString;
@@ -1984,16 +2233,10 @@ declare const crmEventDefinitions: ReadonlyArray<CrmEventDefinition>;
 declare function createEvent<T>(type: string, payload: T, ctx?: CrmContext, meta?: Partial<EventMeta>): DomainEvent<T>;
 //#endregion
 //#region src/events/in-process-bus.d.ts
-declare class InProcessCrmBus implements EventTransport {
-  readonly name = "in-process-crm";
-  private subs;
-  private logger?;
+declare class InProcessCrmBus extends InProcessEventBus {
   constructor(options?: {
     logger?: CrmLogger;
   });
-  publish(event: DomainEvent): Promise<void>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
 }
 //#endregion
 //#region src/engine/run-unit.d.ts
@@ -2023,27 +2266,40 @@ declare function runUnit<T>(config: RunUnitConfig, ctx: CrmContext, body: (inner
  * Built on `@classytic/primitives/state-machine` so the same shape lights
  * up across kits (mongokit's `claim()` pairing, sqlitekit follow-ups).
  */
-declare const LEAD_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"new" | "contacted" | "qualified" | "converted" | "disqualified" | "nurturing">;
-declare const OPPORTUNITY_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"open" | "won" | "lost" | "abandoned">;
-declare const CAMPAIGN_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"draft" | "active" | "paused" | "completed" | "archived">;
-declare const SUBSCRIPTION_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"pending" | "confirmed" | "unsubscribed" | "bounced" | "complained">;
-declare const ACTIVITY_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"completed" | "planned" | "in_progress" | "cancelled">;
-declare const SEQUENCE_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"draft" | "active" | "paused" | "archived">;
-declare const ENROLLMENT_MACHINE: _$_classytic_primitives_state_machine0.StateMachine<"active" | "paused" | "completed" | "exited">;
+declare const LEAD_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"new" | "contacted" | "qualified" | "converted" | "disqualified" | "nurturing">;
+declare const OPPORTUNITY_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"open" | "won" | "lost" | "abandoned">;
+declare const CAMPAIGN_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"draft" | "active" | "paused" | "completed" | "archived">;
+declare const SUBSCRIPTION_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"pending" | "confirmed" | "unsubscribed" | "bounced" | "complained">;
+declare const ACTIVITY_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"completed" | "planned" | "in_progress" | "cancelled">;
+declare const SEQUENCE_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"draft" | "active" | "paused" | "archived">;
+declare const ENROLLMENT_MACHINE: import("@classytic/primitives/state-machine").StateMachine<"active" | "paused" | "completed" | "exited">;
 //#endregion
 //#region src/core/errors.d.ts
 /**
- * CRM error vocabulary. Hosts catch `CrmError` at API edges.
+ * `status` makes every CRM throwable satisfy `HttpError` from
+ * `@classytic/repo-core/errors` (PACKAGE_RULES "Errors and wire envelopes"),
+ * so arc's global handler serializes it natively with the right code AND the
+ * right status — no per-host `errorMapper`. Without it every CRM error
+ * reached the client as `arc.internal_error` / 500: `NotFoundError` answered
+ * 500 instead of 404, which tells a caller "the server broke" when the truth
+ * was "that lead doesn't exist".
+ *
+ * Defaults to 422 (well-formed request, violates a domain invariant) —
+ * the common case here. Subclasses override with `readonly status = N`;
+ * the subclass field initializer runs after this constructor, so it wins.
  */
-declare class CrmError extends Error {
+declare class CrmError extends Error implements HttpError {
   readonly code: string;
+  readonly status: number;
   readonly details?: Record<string, unknown>;
   constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 declare class NotFoundError extends CrmError {
+  readonly status = 404;
   constructor(kind: string, id: string);
 }
 declare class InvalidLeadTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2051,6 +2307,7 @@ declare class InvalidLeadTransitionError extends CrmError {
   });
 }
 declare class InvalidOpportunityTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2058,6 +2315,7 @@ declare class InvalidOpportunityTransitionError extends CrmError {
   });
 }
 declare class InvalidActivityTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2065,27 +2323,39 @@ declare class InvalidActivityTransitionError extends CrmError {
   });
 }
 declare class StageNotInPipelineError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     pipelineId: string;
     stageId: string;
   });
 }
 declare class LeadAlreadyConvertedError extends CrmError {
+  readonly status = 409;
   constructor(leadId: string);
 }
 declare class DuplicateLeadError extends CrmError {
+  readonly status = 409;
   constructor(details: {
     email?: string;
     phone?: string;
   });
 }
+declare class DuplicateContactError extends CrmError {
+  readonly status = 409;
+  constructor(details: {
+    email: string;
+  });
+}
 declare class UnmanagedSessionError extends CrmError {
+  readonly status = 500;
   constructor(eventType?: string);
 }
 declare class EmptyPipelineError extends CrmError {
+  readonly status = 422;
   constructor(pipelineId: string);
 }
 declare class InvalidCampaignTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2093,9 +2363,11 @@ declare class InvalidCampaignTransitionError extends CrmError {
   });
 }
 declare class DuplicateCampaignError extends CrmError {
+  readonly status = 409;
   constructor(name: string);
 }
 declare class InvalidSubscriptionTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2103,18 +2375,22 @@ declare class InvalidSubscriptionTransitionError extends CrmError {
   });
 }
 declare class DuplicateSubscriptionError extends CrmError {
+  readonly status = 409;
   constructor(details: {
     contactId: string;
     campaignId: string;
   });
 }
 declare class InvalidConfirmationTokenError extends CrmError {
+  readonly status = 422;
   constructor();
 }
 declare class InvalidUnsubscribeTokenError extends CrmError {
+  readonly status = 422;
   constructor();
 }
 declare class InvalidSequenceTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2122,6 +2398,7 @@ declare class InvalidSequenceTransitionError extends CrmError {
   });
 }
 declare class InvalidEnrollmentTransitionError extends CrmError {
+  readonly status = 422;
   constructor(details: {
     from: string;
     to: string;
@@ -2129,11 +2406,111 @@ declare class InvalidEnrollmentTransitionError extends CrmError {
   });
 }
 declare class AlreadyEnrolledError extends CrmError {
+  readonly status = 409;
   constructor(details: {
     sequenceId: string;
     subjectId: string;
   });
 }
+/**
+ * An address handed to a suppression-list WRITE could not be canonicalised.
+ *
+ * 400, not 422 — the request itself is malformed at the field, no domain
+ * invariant was consulted. This is `@classytic/contact`'s `EmailFormatError`
+ * re-thrown as a CRM error so arc serializes it natively; the same shape party
+ * uses for `PartyPhoneFormatError`. `contact` sits below every domain kernel
+ * and knows nothing about HTTP, so the mapping has to happen here.
+ *
+ * Only WRITES throw. Reads fail closed instead — see
+ * `suppression.repository.ts`, which writes the asymmetry down.
+ */
+declare class SuppressionEmailFormatError extends CrmError {
+  readonly status = 400;
+  constructor(details: {
+    email: string;
+    reason: string;
+  });
+}
+/**
+ * An address handed to `LeadRepository.createLead` could not be canonicalised.
+ *
+ * 400, same shape and same reason as `SuppressionEmailFormatError`: the field is
+ * malformed, no domain invariant was consulted. Thrown from
+ * `core/email-identity.ts`, which owns the write-throws / setter-degrades
+ * asymmetry and writes down why each side goes the way it does.
+ */
+declare class LeadEmailFormatError extends CrmError {
+  readonly status = 400;
+  constructor(details: {
+    email: string;
+    reason: string;
+  });
+}
+/** As {@link LeadEmailFormatError}, for `ContactRepository.createContact`. */
+declare class ContactEmailFormatError extends CrmError {
+  readonly status = 400;
+  constructor(details: {
+    email: string;
+    reason: string;
+  });
+}
+//#endregion
+//#region src/core/email-identity.d.ts
+/**
+ * WHERE the email key rule is applied inside CRM. **Not a second copy of the
+ * rule** — the rule is `normalizeEmail` from `@classytic/contact/email`, imported
+ * directly here as it is in `suppression.repository.ts`. What this module owns is
+ * the two things a shared kernel cannot decide for us: which mongoose fields carry
+ * the key, and what happens when the kernel refuses an input.
+ *
+ * It exists as a module rather than a copy-paste because Lead and Contact both
+ * carry an email identity. Two schemas hand-rolling the same setter is the drift
+ * this package already paid for once.
+ *
+ * ## Why the SETTER, and not only the repository verbs
+ *
+ * `LeadRepository.createLead` / `ContactRepository.createContact` are NOT on the
+ * HTTP path. `@spinekit/crm` mounts both resources through arc's mongoose CRUD
+ * adapter, so `POST /crm/leads` calls the inherited `Repository.create()` and the
+ * verbs' pre-check never runs. A fix that lived only on the verbs would leave the
+ * live route forking one mailbox into two rows, and the tests for the verbs would
+ * be green while it did.
+ *
+ * The narrowest boundary EVERY write must cross is the schema field, so the key
+ * rule is applied there. That is also what makes the partial-unique
+ * `(organizationId, email)` index authoritative: an index can only dedup what the
+ * key already folded, and `lowercase: true` does not IDNA-fold. `ada@bücher.de`
+ * and `ada@xn--bcher-kva.de` are one host in two encodings — the index saw two
+ * strings and admitted both, no error, one mailbox as two leads.
+ *
+ * Mongoose runs string setters on QUERY FILTERS as well as on writes (this is why
+ * `lowercase: true` already made `getOne({ email: 'ADA@x.com' })` match a stored
+ * `ada@x.com`), so the setter fixes the read side in the same stroke. The
+ * repository verbs still canonicalise EXPLICITLY before querying — see
+ * `requireLeadEmailKey`'s call sites. That is not redundancy for its own sake:
+ * a pre-check that depends on an invisible schema option silently WIDENS the day
+ * someone edits the field, and a widened filter does not fail, it matches nothing
+ * and reports "no duplicate".
+ *
+ * ## The setter must NEVER throw, and it does not
+ *
+ * A throw inside a setter surfaces during query casting as an opaque `CastError`,
+ * which would turn a malformed filter into a 500 on a READ. So the setter degrades
+ * to the LEGACY folding (`trim().toLowerCase()`) for anything the kernel refuses —
+ * exactly the behaviour those values have today, so nothing already stored is
+ * re-keyed by a rule that cannot explain itself.
+ *
+ * Refusing is the WRITE VERBS' job, where a typed 400 can be thrown and the caller
+ * is a deliberate domain call rather than a filter. Same asymmetry, same reason as
+ * `suppression.repository.ts`: the safe direction differs per side.
+ */
+/**
+ * The canonical key for `email`, or `null` when it has none.
+ *
+ * Exported so a host can tell "not on file" apart from "not an address" without
+ * re-deriving the rule — the same reason `suppressionEmailKey` is exported.
+ */
+declare function crmEmailKey(email: string): string | null;
 //#endregion
 //#region src/shared/calculators/forecast.d.ts
 type OpportunityForecast = Pick<IOpportunityDocument, 'amount' | 'currency' | 'probability' | 'status' | 'expectedCloseAt' | 'stageId' | 'statusHistory'>;
@@ -2826,4 +3203,4 @@ declare namespace index_d_exports {
   export { AddNoteDto, CancelActivityDto, CloseLossDto, CloseWinDto, CompleteCampaignDto, ConfirmSubscriptionDto, ConvertLeadDto, CreateAccountDto, CreateCampaignDto, CreateContactDto, CreateLeadDto, CreateLossReasonDto, CreatePipelineDto, CreateSequenceInput, LeadFilterDto, MoveStageDto, OpenOpportunityDto, OpportunityFilterDto, PlanActivityDto, RecordEmailEventDto, SequenceFilterInput, StageInputDto, SubscribeDto, SuppressDto, UnsubscribeDto, UnsuppressDto, UpdateAccountDto, UpdateCampaignDto, UpdateContactDto, UpdateLeadDto, UpdateLossReasonDto, UpdateNoteDto, UpdatePipelineDto, UpdateSequenceInput, accountFilterSchema, activityFilterSchema, addNoteSchema, campaignFilterSchema, cancelActivitySchema, closeLossSchema, closeWinSchema, completeCampaignSchema, confirmSubscriptionSchema, contactFilterSchema, convertLeadSchema, createAccountSchema, createCampaignSchema, createContactSchema, createLeadSchema, createLossReasonSchema, createPipelineSchema, createSequenceSchema, currencyCodeSchema, emailEventFilterSchema, leadFilterSchema, lossReasonFilterSchema, metadataSchema, moneyAmountSchema, moveStageSchema, noteFilterSchema, objectIdLike, openOpportunitySchema, opportunityFilterSchema, pipelineFilterSchema, planActivitySchema, recordEmailEventSchema, sequenceFilterSchema, sequenceStepSchema, stageInputSchemaExport, subscribeSchema, subscriptionFilterSchema, suppressSchema, suppressionFilterSchema, tagsSchema, unsubscribeSchema, unsuppressSchema, updateAccountSchema, updateActivitySchema, updateCampaignSchema, updateContactSchema, updateLeadSchema, updateLossReasonSchema, updateNoteSchema, updatePipelineSchema, updateSequenceSchema };
 }
 //#endregion
-export { ACTIVITY_MACHINE, ACTIVITY_STATUSES, ACTIVITY_TRANSITIONS, ACTIVITY_TYPES, AccountAssigned, AccountCreated, AccountEnriched, AccountMerged, AccountRepository, AccountRepositoryDeps, AccountUpdated, ActivityCancelled, ActivityCompleted, ActivityOutcomeRecorded, ActivityPlanned, ActivityRepository, ActivityRepositoryDeps, ActivityRescheduled, type ActivityStatus, type ActivityType, AlreadyEnrolledError, CAMPAIGN_MACHINE, CAMPAIGN_STATUSES, CAMPAIGN_TRANSITIONS, CONVERSATION_CHANNELS, CONVERSATION_PARTICIPANT_KINDS, CONVERSATION_STATUSES, CRM_EVENTS, CRM_MODEL_NAMES, CampaignActivated, CampaignArchived, CampaignCompleted, CampaignCreated, CampaignPaused, CampaignRepository, CampaignRepositoryDeps, CampaignResumed, type CampaignStatus, CloseInput, ContactAssigned, ContactCreated, ContactEnriched, ContactMerged, ContactRepository, ContactRepositoryDeps, ContactUpdated, ConversationAssigned, type ConversationChannel, ConversationCreated, type ConversationParticipantKind, ConversationReopened, ConversationRepository, ConversationRepositoryDeps, ConversationResolved, type ConversationStatus, ConversionRow, ConvertLeadInput, ConvertResult, CreateCrmRepositoriesDeps, CreateModelsOptions, CrmConfig, CrmContext, CrmEngine, CrmError, CrmEventDefinition, CrmEventDispatcher, type CrmEventDispatcherOptions, CrmEventName, CrmEventSchema, CrmLogger, CrmModels, CrmRepositories, DuplicateCampaignError, DuplicateLeadError, DuplicateSubscriptionError, EMAIL_EVENT_KINDS, EMAIL_EVENT_SUBJECT_KINDS, ENROLLMENT_MACHINE, ENROLLMENT_STATUSES, ENROLLMENT_SUBJECT_KINDS, ENROLLMENT_TRANSITIONS, EVENT_DERIVED_SUPPRESSION_REASONS, EmailEventBounced, EmailEventClicked, EmailEventComplained, type EmailEventKind, EmailEventOpened, EmailEventRepository, EmailEventRepositoryDeps, EmailEventSubjectKind, EmailEventUnsubscribed, EmptyPipelineError, EnrollInput, EnrollmentCompleted, EnrollmentCreated, EnrollmentExitReason, EnrollmentExited, EnrollmentPaused, EnrollmentRepository, EnrollmentRepositoryDeps, EnrollmentResumed, type EnrollmentStatus, EnrollmentStepSent, EnrollmentSubjectKind, ForecastOptions, ForecastRow, type IAccountDocument, type IActivityDocument, type ICampaignDocument, ICampaignStatusEntry, type IContactDocument, IContactInfoEmbedded, IContactName, type IConversationDocument, IDelayStep, type IEmailEventDocument, type IEnrollmentDocument, IEnrollmentStatusEntry, type ILeadDocument, ILeadEngagement, ILeadStatusEntry, type ILossReasonDocument, IMessageAttachment, type IMessageDocument, type INoteDocument, type IOpportunityDocument, IOpportunityStatusEntry, type IPipelineDocument, ISendEmailStep, type ISequenceDocument, ISequenceStatusEntry, IStageDocument, IStepResult, type ISubscriptionDocument, ISubscriptionStatusEntry, type ISuppressionDocument, InProcessCrmBus, type InternalCrmContext, InvalidActivityTransitionError, InvalidCampaignTransitionError, InvalidConfirmationTokenError, InvalidEnrollmentTransitionError, InvalidLeadTransitionError, InvalidOpportunityTransitionError, InvalidSequenceTransitionError, InvalidSubscriptionTransitionError, InvalidUnsubscribeTokenError, LEAD_MACHINE, LEAD_STATUSES, LEAD_TRANSITIONS, LeadAlreadyConvertedError, LeadAssigned, LeadConverted, LeadCreated, LeadDisqualified, LeadEngagementSignal, LeadEnriched, LeadInput, LeadRepository, LeadRepositoryDeps, LeadScored, LeadScorer, LeadService, LeadServiceDeps, type LeadStatus, LeadStatusChanged, LossReasonRepository, LossReasonRepositoryDeps, MESSAGE_DELIVERY_STATUSES, MESSAGE_DIRECTIONS, MergeAccountInput, MergeContactInput, type MessageDeliveryStatus, type MessageDirection, MessageReceived, MessageRepository, MessageRepositoryDeps, MessageSent, MoveStageInput, NotFoundError, NoteAdded, NoteRepository, NoteRepositoryDeps, OPPORTUNITY_MACHINE, OPPORTUNITY_STATUSES, OPPORTUNITY_TRANSITIONS, OpenConversationInput, OpenOpportunityInput, OpportunityAbandoned, OpportunityAmountChanged, OpportunityAssigned, OpportunityCreated, OpportunityExtended, OpportunityForecast, OpportunityLost, OpportunityRepository, OpportunityRepositoryDeps, OpportunityStageAdvanced, OpportunityStageRegressed, type OpportunityStatus, OpportunityWon, PENDING_EVENTS, PipelineArchived, PipelineCreated, PipelineRepository, PipelineRepositoryDeps, RecordEmailEventInput, RecordMessageInput, ReplySubject, ResolvedCrmConfig, type RunUnitConfig, SEQUENCE_MACHINE, SEQUENCE_STATUSES, SEQUENCE_TRANSITIONS, SUBJECT_KINDS, SUBSCRIPTION_MACHINE, SUBSCRIPTION_STATUSES, SUBSCRIPTION_TRANSITIONS, SUPPRESSION_REASONS, SchemaBuildConfig, SequenceActivated, SequenceArchived, SequenceCreated, SequencePaused, SequenceRepository, SequenceRepositoryDeps, type SequenceStatus, SequenceStep, StageNotInPipelineError, type StatusChangeEntry, type StatusHistory, StepResultStatus, type SubjectKind, SubscribeInput, SubscriptionBounced, SubscriptionComplained, SubscriptionConfirmed, SubscriptionCreated, SubscriptionRepository, SubscriptionRepositoryDeps, type SubscriptionStatus, SubscriptionUnsubscribed, SuppressInput, SuppressionAdded, type SuppressionReason, SuppressionRemoved, SuppressionRepository, SuppressionRepositoryDeps, TenantFieldType, UnmanagedSessionError, _ModelTypes, appendStatus, buildAccountSchema, buildActivitySchema, buildCampaignSchema, buildContactSchema, buildConversationSchema, buildEmailEventSchema, buildEnrollmentSchema, buildLeadSchema, buildLossReasonSchema, buildMessageSchema, buildNoteSchema, buildOpportunitySchema, buildPipelineSchema, buildSequenceSchema, buildSubscriptionSchema, buildSuppressionSchema, canTransitionActivity, canTransitionCampaign, canTransitionEnrollment, canTransitionLead, canTransitionOpportunity, canTransitionSequence, canTransitionSubscription, composeScorers, createAccountModel, createActivityModel, createCampaignModel, createContactModel, createConversationModel, createCrm, createCrmModels, createCrmRepositories, createEmailEventModel, createEvent, createLeadModel, createLossReasonModel, createMessageModel, createNoteModel, createOpportunityModel, createPipelineModel, createSubscriptionModel, crmEventDefinitions, defaultLeadScorer, flushPending, forecast, lastTransitionTo, latestEntry, pipelineConversion, runUnit, tenantFieldDef, timeInStatus, index_d_exports as validators };
+export { ACTIVITY_MACHINE, ACTIVITY_STATUSES, ACTIVITY_TRANSITIONS, ACTIVITY_TYPES, ALL_CRM_MODULES, AccountAssigned, AccountCreated, AccountEnriched, AccountMerged, AccountRepository, AccountRepositoryDeps, AccountUpdated, ActivityCancelled, ActivityCompleted, ActivityOutcomeRecorded, ActivityPlanned, ActivityRepository, ActivityRepositoryDeps, ActivityRescheduled, type ActivityStatus, type ActivityType, AlreadyEnrolledError, AutomationCrmModels, AutomationCrmRepositories, CAMPAIGN_MACHINE, CAMPAIGN_STATUSES, CAMPAIGN_TRANSITIONS, CONVERSATION_CHANNELS, CONVERSATION_PARTICIPANT_KINDS, CONVERSATION_STATUSES, CRM_EVENTS, CRM_MODEL_NAMES, CampaignActivated, CampaignArchived, CampaignCompleted, CampaignCreated, CampaignPaused, CampaignRepository, CampaignRepositoryDeps, CampaignResumed, type CampaignStatus, CloseInput, ContactAnonymized, ContactAssigned, ContactCreated, ContactEmailFormatError, ContactEnriched, ContactMergeRepoint, ContactMerged, ContactRepository, ContactRepositoryDeps, ContactUpdated, ConversationAssigned, type ConversationChannel, ConversationCreated, type ConversationParticipantKind, ConversationReopened, ConversationRepository, ConversationRepositoryDeps, ConversationResolved, type ConversationStatus, ConversionRow, ConvertLeadInput, ConvertResult, CreateCrmRepositoriesDeps, CrmBlueprint, CrmContext, CrmEngine, CrmEngineBase, CrmError, CrmEventDefinition, CrmEventDispatcher, type CrmEventDispatcherOptions, CrmEventName, CrmEventSchema, CrmLogger, CrmModels, CrmModuleView, CrmModulesConfig, CrmRepositories, CrmRuntime, CrmShape, DefineCrmModelsConfig, DuplicateCampaignError, DuplicateContactError, DuplicateLeadError, DuplicateSubscriptionError, EMAIL_EVENT_KINDS, EMAIL_EVENT_SUBJECT_KINDS, ENROLLMENT_MACHINE, ENROLLMENT_STATUSES, ENROLLMENT_SUBJECT_KINDS, ENROLLMENT_TRANSITIONS, EVENT_DERIVED_SUPPRESSION_REASONS, EmailEventBounced, EmailEventClicked, EmailEventComplained, type EmailEventKind, EmailEventOpened, EmailEventRepository, EmailEventRepositoryDeps, EmailEventSubjectKind, EmailEventUnsubscribed, EmptyPipelineError, EngagementCrmModels, EngagementCrmRepositories, EnrollInput, EnrollmentCompleted, EnrollmentCreated, EnrollmentExitReason, EnrollmentExited, EnrollmentPaused, EnrollmentRepository, EnrollmentRepositoryDeps, EnrollmentResumed, type EnrollmentStatus, EnrollmentStepSent, EnrollmentSubjectKind, ForecastOptions, ForecastRow, FullCrmModuleViews, IAccountDocument, IActivityDocument, ICampaignDocument, ICampaignStatusEntry, IContactDocument, IContactInfoEmbedded, IContactName, IConversationDocument, IDelayStep, IEmailEventDocument, IEnrollmentDocument, IEnrollmentStatusEntry, ILeadDocument, ILeadEngagement, ILeadStatusEntry, ILossReasonDocument, IMessageAttachment, IMessageDocument, INoteDocument, IOpportunityDocument, IOpportunityStatusEntry, IPipelineDocument, ISendEmailStep, ISequenceDocument, ISequenceStatusEntry, IStageDocument, IStepResult, ISubscriptionDocument, ISubscriptionStatusEntry, ISuppressionDocument, InProcessCrmBus, type InternalCrmContext, InvalidActivityTransitionError, InvalidCampaignTransitionError, InvalidConfirmationTokenError, InvalidEnrollmentTransitionError, InvalidLeadTransitionError, InvalidOpportunityTransitionError, InvalidSequenceTransitionError, InvalidSubscriptionTransitionError, InvalidUnsubscribeTokenError, LEAD_MACHINE, LEAD_STATUSES, LEAD_TRANSITIONS, LeadAlreadyConvertedError, LeadAnonymized, LeadAssigned, LeadConverted, LeadCreated, LeadDisqualified, LeadEmailFormatError, LeadEngagementSignal, LeadEnriched, LeadInput, LeadRepository, LeadRepositoryDeps, LeadScored, LeadScorer, LeadService, LeadServiceDeps, type LeadStatus, LeadStatusChanged, LossReasonRepository, LossReasonRepositoryDeps, MESSAGE_DELIVERY_STATUSES, MESSAGE_DIRECTIONS, MergeAccountInput, MergeContactInput, type MessageDeliveryStatus, type MessageDirection, MessageReceived, MessageRepository, MessageRepositoryDeps, MessageSent, ModularCrmEngine, ModularCrmModels, ModularCrmModuleViews, ModularCrmRepositories, MoveStageInput, NotFoundError, NoteAdded, NoteRepository, NoteRepositoryDeps, OPPORTUNITY_MACHINE, OPPORTUNITY_STATUSES, OPPORTUNITY_TRANSITIONS, OpenConversationInput, OpenOpportunityInput, OpportunityAbandoned, OpportunityAmountChanged, OpportunityAssigned, OpportunityCreated, OpportunityExtended, OpportunityForecast, OpportunityLost, OpportunityRepository, OpportunityRepositoryDeps, OpportunityStageAdvanced, OpportunityStageRegressed, type OpportunityStatus, OpportunityWon, PENDING_EVENTS, PipelineArchived, PipelineCreated, PipelineRepository, PipelineRepositoryDeps, RecordEmailEventInput, RecordMessageInput, ReplySubject, ResolvedCrmConfig, ResolvedCrmModules, type RunUnitConfig, SEQUENCE_MACHINE, SEQUENCE_STATUSES, SEQUENCE_TRANSITIONS, SUBJECT_KINDS, SUBSCRIPTION_MACHINE, SUBSCRIPTION_STATUSES, SUBSCRIPTION_TRANSITIONS, SUPPRESSION_REASONS, SalesCrmModels, SalesCrmRepositories, SchemaBuildConfig, SequenceActivated, SequenceArchived, SequenceCreated, SequencePaused, SequenceRepository, SequenceRepositoryDeps, type SequenceStatus, SequenceStep, StageNotInPipelineError, type StatusChangeEntry, type StatusHistory, StepResultStatus, type SubjectKind, SubscribeInput, SubscriptionBounced, SubscriptionComplained, SubscriptionConfirmed, SubscriptionCreated, SubscriptionRepository, SubscriptionRepositoryDeps, type SubscriptionStatus, SubscriptionUnsubscribed, SuppressInput, SuppressionAdded, SuppressionEmailFormatError, type SuppressionReason, SuppressionRemoved, SuppressionRepository, SuppressionRepositoryDeps, TenantFieldType, UnmanagedSessionError, _ModelTypes, appendStatus, buildAccountSchema, buildActivitySchema, buildCampaignSchema, buildContactSchema, buildConversationSchema, buildEmailEventSchema, buildEnrollmentSchema, buildLeadSchema, buildLossReasonSchema, buildMessageSchema, buildNoteSchema, buildOpportunitySchema, buildPipelineSchema, buildSequenceSchema, buildSubscriptionSchema, buildSuppressionSchema, canTransitionActivity, canTransitionCampaign, canTransitionEnrollment, canTransitionLead, canTransitionOpportunity, canTransitionSequence, canTransitionSubscription, composeScorers, createAccountModel, createActivityModel, createCampaignModel, createContactModel, createConversationModel, createCrmRepositories, createEmailEventModel, createEvent, createLeadModel, createLossReasonModel, createMessageModel, createNoteModel, createOpportunityModel, createPipelineModel, createSubscriptionModel, crmEmailKey, crmEventDefinitions, crmModelName, defaultLeadScorer, defineCrm, defineCrmModels, flushPending, forecast, lastTransitionTo, latestEntry, pipelineConversion, resolveCrmModules, runUnit, suppressionEmailKey, tenantFieldDef, timeInStatus, index_d_exports as validators };