@classytic/crm 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -1,363 +1,493 @@
-# Changelog
-
-All notable changes to `@classytic/crm` are documented here.
-
-## [0.9.0] — unpublished (2026-07-15)
-
-### Changed — mongokit 3.22 adopted (peer floors: mongokit >=3.22.0, repo-core >=0.13.0, primitives >=0.11.0)
-
-- **Seven transition verbs ride `applyTransition`** (activity, campaign,
-  enrollment exit + generic, lead, sequence, subscription, opportunity):
-  machine pre-flight + CAS + accurate race diagnosis via the machines'
-  existing errorFactories. All `this as any` casts at those sites are gone
-  (native method).
-- **FIXED a real concurrency defect**: five sites built `statusHistory` by
-  read-modify-write (`[...(existing.statusHistory ?? []), entry]`) inside
-  the CAS patch — concurrent writers could drop history entries. Entries
-  now ride `$push` via the `push` arg, byte-identical shapes preserved.
-- **`EmailEvent` log fence enforced** — "append-only" was a doc comment;
-  `appendOnlyPlugin` now refuses every mutation path (405
-  `APPEND_ONLY_VIOLATION`), with `deleteMany` allowed for host-gated GDPR
-  erasure of a recipient's rows.
-- DELIBERATELY unchanged: `enrollment.advanceStep` (non-status
-  `currentStepIndex` CAS with null semantics) and opportunity's stage-move
-  claim — correct raw `claim` usage, not transition boilerplate.
-
-## [0.8.0] — 2026-07-11
-
-### Added — engagement-based lead scoring
-- **`ILeadEngagement` on the Lead** (`{ opens, clicks, replies, activities, lastEngagedAt? }`, nested default `{}` so old rows read as zeros). Behavioural counters, distinct from firmographic fields.
-- **`LeadRepository.recordEngagement(id, signal, ctx)`** where `signal ∈ 'open'|'click'|'reply'|'activity'` (`LeadEngagementSignal`). Atomic `$inc` on the matching counter + `lastEngagedAt` via `findOneAndUpdate`, then `recomputeScore`. Hosts feed it off `crm:message.received` (reply), `crm:activity.*` (activity), and email open/click tracking.
-- **`defaultLeadScorer` now weighs engagement** on top of firmographic fit: reply ×25 · click ×8 · open ×2 · activity ×5, capped at +80. `LeadInput` picks up `engagement`. Pure/deterministic — no wall-clock. Absent engagement scores as zero (score unchanged for pre-existing leads until a signal lands).
-
-## [0.7.0] — 2026-07-05
-
-### Added — org-wide email suppression list
-
-- **`Suppression` entity** (`crm.repositories.suppression`, model
-  `Suppression`): global per-org "never email this address again" list —
-  the gate hosts consult before EVERY outbound email. Unsubscribes on
-  `Subscription` stay per-campaign; suppression is org-wide.
-  - `suppress(email, { reason, source?, subjectKind?, subjectId?, metadata? }, ctx?)`
-    — idempotent `getOrCreate` on the unique `(organizationId, email)`
-    index (no check-then-save); emits `crm:suppression.added` only when
-    THIS call inserted the row.
-  - `isSuppressed(email, ctx?)` → boolean.
-  - `filterSuppressed(emails, ctx?)` → `Set<string>` of the suppressed
-    subset — ONE `$in` query for the campaign-fanout hot path.
-  - `unsuppress(email, ctx?)` — atomic delete; emits
-    `crm:suppression.removed` only when a row was actually removed.
-  - All verbs normalize emails (trim + lowercase; schema stores lowercase).
-- **`SUPPRESSION_REASONS`** (`'bounce' | 'complaint' | 'unsubscribe' |
-  'manual'`) — the first three `satisfies readonly EmailEventKind[]` (P6),
-  so a rename in `EMAIL_EVENT_KINDS` fails compilation here.
-- **Events** `crm:suppression.added` / `crm:suppression.removed` — Zod
-  catalog definitions included (no-drift invariant stays green);
-  `organizationId` rides event meta as usual.
-- **Validators** `suppressSchema` / `unsuppressSchema` /
-  `suppressionFilterSchema`.
-
-### Added — reply-detection exit verb
-
-- **`EnrollmentRepository.exitActiveOnReply(subjects, ctx?)`** — the ONE
-  method a host's `crm:message.received` subscriber calls: finds ACTIVE
-  enrollments for the given `{ subjectKind, subjectId }` list, batch-loads
-  their sequences in a single `$in` query, skips those with
-  `replyDetectionEnabled === false`, and exits the rest via `exit(id,
-  'reply')` (each exit emits `crm:enrollment.exited`). Lost CAS races
-  (concurrent pause/complete/exit) are skipped, not failed. Returns the
-  enrollments this call exited.
-- `EnrollmentRepositoryDeps` now carries `sequences: SequenceRepository`
-  (same cross-repo deps idiom as `OpportunityRepository.pipelines` /
-  `MessageRepository.conversations`) — wired automatically by
-  `createCrm()`; only hosts constructing `EnrollmentRepository` by hand
-  need to pass it.
-
-## [0.6.0] — 2026-07-02
-
-Breaking-in-behavior release (ships as MINOR per house convention):
-outbox-first, session-safe event dispatch — the previously deferred
-PACKAGE_RULES §P8/§P8.1 work.
-
-### Added — unit-of-work contract (P8.1, shared with refit/review/cart/invoice)
-
-- **`engine.withTransaction(ctx, body)`** — runs `body` inside a MongoDB
-  transaction with post-commit event discipline: events dispatched through
-  `txCtx` are queued under `ctx[PENDING_EVENTS]` and flushed to the
-  transport only AFTER commit; the queue resets on retry attempts; an abort
-  leaks nothing to in-process subscribers. Reuses the caller's session (and
-  queue) when `ctx.session` is already set. Standalone-Mongo dev boots opt
-  in via the existing `allowNonTransactional: true`.
-- **`PENDING_EVENTS`** (`Symbol.for('@classytic/crm:pendingEvents')`) +
-  **`flushPending(transport, queue, logger?)`** + **`runUnit`** exported
-  from the root for hosts composing their own outer transaction.
-- **`CrmConfig.outbox?: OutboxStore`** (from `@classytic/primitives/outbox`)
-  — 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. Outbox save failures
-  PROPAGATE (P8: a swallowed save means the write persists while its event
-  vanishes).
-- **`CrmEventDispatcher`** — EventTransport-compatible wrapper repositories
-  route every event through (`engine.events` is now this wrapper; the host
-  `publish`/`subscribe` surface is unchanged).
-- **`UnmanagedSessionError`** (`code: 'UNMANAGED_SESSION'`) — a host-owned
-  `ctx.session` arriving with neither an outbox nor a `PENDING_EVENTS`
-  queue now throws instead of ghost-publishing mid-transaction.
-  **Behavioral break:** callers that previously threaded a bare session and
-  tolerated ghost events must switch to `engine.withTransaction` (or wire
-  an outbox / attach a queue).
-
-### Added — timezone-aware forecasting
-
-- **`ForecastOptions.timeZone`** — IANA zone for the default month bucket
-  (e.g. `'Asia/Dhaka'`). Without it, months cut at UTC boundaries: a deal
-  expected to close July 1, 02:00 Dhaka time (June 30, 20:00 UTC) files
-  under JUNE. Uses `civilDateOf` from `@classytic/primitives/timezone`.
-  Peer floor bumped: `@classytic/primitives >=0.9.0`.
-
-### Fixed — sequence/enrollment (completes the 0.6.0 WIP)
-
-- **Event catalog no-drift restored**: 10 missing Zod definitions added
-  (`crm:sequence.{created,active,paused,archived}`,
-  `crm:enrollment.{created,step_sent,paused,resumed,completed,exited}`) —
-  `crm:sequence.created` and `crm:enrollment.step_sent` are host-emitted
-  (create via `def.create()`), the rest publish in-repo.
-- **`EnrollmentRepository.setWorkflowRunId` / `advanceStep` no longer
-  bypass the repository**: both used raw `model.findOneAndUpdate` with a
-  manual tenant filter — escaping `multiTenantPlugin` scoping AND
-  `ctx.session` (a call inside `withTransaction` would commit outside the
-  transaction). `advanceStep` is now a `claim()` CAS on `currentStepIndex`
-  with `where: { status: 'active' }`; `setWorkflowRunId` goes through
-  `repo.update`.
-
-### Tests
-
-- 14 new: `tests/unit/dispatch.test.ts` (6 — outbox propagation/session
-  routing/guard/swallow), `tests/integration/unit-of-work.test.ts` (3 —
-  convert() on a replica set: zero mid-tx events, post-commit flush, abort
-  leaks nothing, bare-session guard), `tests/unit/forecast-timezone.test.ts`
-  (5 — the +06:00 month-boundary trap). 110/110 total.
-
-## [0.5.1] — 2026-06-14
-
-### Fixed — declaration bundle
-
-- **fix: declaration bundle exported mangled aliases; consumer named imports
-  now resolve.** The published `dist/index.d.ts` re-exported every public
-  symbol under a minified alias (`export { AccountRepository as A, CRM_EVENTS
-  as Rr, … }`), so downstream `import { AccountRepository, CRM_EVENTS } from
-  '@classytic/crm'` failed with TS2305 / TS2460. Root cause: the `./events`
-  entry re-exports a strict subset of the `index` barrel, which made
-  `rolldown-plugin-dts` alias every name on the superset (`index`) entry when
-  both were emitted in a single pass. Build now runs `index` and `events` as
-  two independent tsdown passes (array config) so each `.d.ts` exports real
-  names. `tsdown` bumped `^0.14.2` → `^0.21.10` to match sibling packages.
-  No runtime/API change.
-
-## [0.5.0] — 2026-06-14
-
-Stack upgrade + verified correctness fixes + PACKAGE_RULES compliance. No
-new features. Clean break — no deprecation aliases.
-
-### Changed — stack currency
-
-- Peers bumped: `@classytic/mongokit` `>=3.16.0`, `@classytic/repo-core`
-  `>=0.6.0`, `@classytic/primitives` `>=0.7.1`, `mongoose` `>=9.4.1`.
-  Clean-installed from npm and verified resolved (3.16.0 / 0.6.0 / 0.7.2).
-
-### Added — PACKAGE_RULES compliance
-
-- **Zod event catalog (rule 18).** New `crmEventDefinitions[]` (56 events,
-  one Zod schema each) exported from the package root and a new `./events`
-  subpath. Timestamps are `z.iso.datetime()`. A no-drift invariant test
-  asserts every `CRM_EVENTS` constant has a definition. Hosts wire these
-  into arc's `EventRegistry` for publish-time validation + OpenAPI.
-- **Model-collision policy (rule 21).** `createCrm()` now throws
-  `CrmModelCollisionError` when a model name is already registered; pass
-  `forceRecreate: true` (test/hot-reload) to delete + re-register.
-- **Index management (rule 35).** New `autoIndex` config flag (default
-  `true`) and `engine.syncIndexes()` for `autoIndex: false` production
-  boots.
-- **Capability boot gate.** `createCrm()` asserts the backend supports
-  `upsert` / `getOrCreate` / `duplicateKeyError` (and `transactions`,
-  unless `allowNonTransactional: true`) so misconfigured deployments fail
-  loud at boot instead of mid-convert.
-
-### Fixed — domain correctness
-
-- **Lead / Subscription / Campaign dedup are now race-safe.** Added
-  authoritative partial-unique indexes — lead `(organizationId, email)`,
-  campaign `(organizationId, name)`, subscription `(organizationId,
-  contactId, campaignId)` scoped to live statuses — and catch the
-  residual `E11000` via `isDuplicateKeyError`, re-throwing the same typed
-  domain error the pre-check emits. The prior check-then-save left a
-  TOCTOU window.
-- **Owner reassignment is now atomic.** `assign()` on lead / account /
-  contact / opportunity / conversation uses a single `findOneAndUpdate`
-  CAS (`{ ownerId: { $ne } }` guard, `returnDocument: 'before'`) — no
-  read-modify-write lost-update window, and the emitted `previousOwnerId`
-  is the true pre-image under concurrency.
-- **Cross-tenant leak in dashboard/feed reads closed.** `findRecentForFeed`,
-  `countCreatedSince`, `countOpen`, `sumWonSince`, `countOverduePlanned`
-  dropped raw `Model.find` / `countDocuments` with a manual
-  `if (ctx) organizationId` filter (which read ALL tenants when ctx was
-  absent) for the tenant-scoped `findAll` / `count` repository methods.
-
-### Build hygiene
-
-- Sourcemaps and declaration maps are no longer emitted (`sourceMap` /
-  `declarationMap` off in tsconfig; `sourcemap: false` in tsdown) — both
-  leak source.
-- Removed `@deprecated` markers from `ConvertResult` convenience id fields
-  (kept the fields; they were never deprecated, just mislabelled).
-- Dropped the stale pnpm lockfile/workspace and the bundled `.tgz`;
-  installs are npm-from-registry only.
-
-### Docs
-
-- Rewrote the README to the engine-factory API (`createCrm` + repository
-  domain verbs). The previous README documented the abandoned v0.1
-  port/adapter design (`AccountService`, `InMemory*Repository`,
-  `OutreachPort`) that no longer exists.
-
-### Tests
-
-- Added `tests/integration/invariants.test.ts` (tenant probe, lead +
-  subscription dedup races, atomic reassignment) and
-  `tests/unit/event-catalog.test.ts` (no-drift + round-trip). 87 → 96
-  tests.
-
-## [0.4.0] — 2026-05-22
-
-### Changed — Subscription model renamed to `EmailSubscription`
-
-**Breaking at the Mongo identity level.** The CRM's email opt-in resource
-now registers as Mongoose model `EmailSubscription` (was `Subscription`)
-and persists into the `email_subscriptions` collection (was
-`subscriptions`).
-
-**Why:** the previous name collided with `@classytic/revenue`'s
-`Subscription` model when both packages were loaded on the same
-Mongoose connection — `RevenueModelCollisionError` at boot. Renaming
-gives the two concepts distinct identities at the DB level and lets
-revenue + CRM coexist without the host having to split connections.
-
-**TypeScript surface is unchanged.** `ISubscriptionDocument`,
-`SubscriptionRepository`, `subscription.handlers.ts`,
-`CrmModels.Subscription`, etc. all keep their existing names — only
-the Mongoose model name string and the underlying collection name
-changed. Consumers that import from `@classytic/crm` need no source
-changes; the host only needs to migrate existing data (see below).
-
-### Migration
-
-For DBs with existing CRM subscription rows in the legacy `subscriptions`
-collection (distinguishable from revenue rows by `contactId` presence):
-
-```js
-// MongoDB shell — one-time migration
-db.subscriptions.aggregate([
-  { $match: { contactId: { $exists: true } } },
-  { $out: 'email_subscriptions' },
-]);
-// Then remove the migrated docs from the legacy collection:
-db.subscriptions.deleteMany({ contactId: { $exists: true } });
-```
-
-Hosts using only CRM (no revenue) can also run this — leftover rows in
-`subscriptions` won't cause boot errors because there's no collision
-without revenue.
-
-## [0.3.0] — 2026-05-17
-
-### Added — `EmailEvent` domain
-
-Closes the loop between outbound CRM sends and recipient engagement.
-Hosts can now record opens, clicks, bounces, complaints, and unsubscribes
-against a Contact / Subscription / Campaign tuple — and downstream
-services (drip-sequence "if opened" branches, lead scoring, suppression
-lists) consume the same events without polling the email transport.
-
-- **Entity & enum** — `EmailEvent` (append-only) plus the
-  `EmailEventKind` enum (`open` / `click` / `bounce` / `complaint` /
-  `unsubscribe`) split into `ENGAGEMENT_KINDS` and `SUPPRESSION_KINDS`
-  helper sets for classification at call sites.
-- **Port** — `EmailEventRepository` with filtered list, per-subject
-  timeline, per-campaign aggregates (`uniqueOpens`, `uniqueClicks`,
-  `bounces`, `complaints`, `unsubscribes`, `totalEvents`), and a
-  GDPR-style `deleteForSubject()` purge.
-- **Service** — `EmailEventService.recordOpen()` /
-  `.recordClick({ url })` / `.recordBounce()` / `.recordComplaint()` /
-  `.recordUnsubscribe()` + read-side `.listForSubject()`,
-  `.aggregateForCampaign()`, and `.hasEngaged(subjectId, campaignId,
-  kind)` for drip-condition checks.
-- **Events** — `crm:email_event.opened` / `.clicked` / `.bounced` /
-  `.complained` / `.unsubscribed` with Zod-validated payloads in
-  `event-catalog`, wired into `crmEventDefinitions[]`.
-- **In-memory adapter** — `InMemoryEmailEventRepository` (tests +
-  dev). Hosts implement against Mongo / Postgres / etc.
-
-### Added — re-exports from `@classytic/primitives@0.6.0`
-
-To eliminate duplicate type imports at consumer call sites:
-
-```ts
-import {
-  appendStatus,
-  StatusChangeEntry,
-  StatusHistory,
-  timeInStatus,
-  lastTransitionTo,
-} from '@classytic/crm';
-```
-
-These pass through from `@classytic/primitives/status-history`. The
-existing entity-specific `LeadStatusEntry` / `OpportunityStatusEntry` /
-etc. names are still exported for back-compat — they remain structurally
-compatible with `StatusChangeEntry<TStatus>`.
-
-### Changed
-
-- Peer dep `@classytic/primitives` bumped from `>=0.5.0` to `>=0.6.0`
-  to access the new `status-history` subpath and value-typed primitives.
-- Test harness `buildHarness()` now also exposes an
-  `emailEvents: EmailEventService` and `emailEventRepo` for integration
-  tests that exercise the engagement → drip path.
-
-### Dependencies
-
-- `@classytic/primitives@>=0.6.0` (peer, was `>=0.5.0`)
-- `zod@>=4.0.0` (peer, unchanged)
-
-## [0.1.0] — 2026-04-18
-
-Initial release.
-
-### Added
-
-- **Eight domain entities.** `Contact`, `Account`, `Lead`, `Opportunity`, `Pipeline` (+ nested `Stage`), `Activity`, `Note`, `LossReason`.
-- **Three state machines.** Lead (`new` → `contacted` → `qualified` → `converted`, + `disqualified` / `nurturing` branches), Opportunity (`open` → `won` / `lost` / `abandoned` with in-pipeline Stage movement), Activity (`planned` → `in_progress` → `completed` / `cancelled`). All transitions CAS-guarded with explicit `*_TRANSITIONS` maps and `canTransition*` guards.
-- **Six services.**
-  - `ContactService` — CRUD + tag filtering + email lookup.
-  - `AccountService` — CRUD + domain lookup.
-  - `PipelineService` — create, archive, stage helpers (`getStage`, `getFirstStage`, `getNextStage`).
-  - `OpportunityService` — create at first stage (or specified), `moveToStage` with advance/regress event disambiguation, `win` / `lose` (with `lostReasonId`) / `abandon`.
-  - `LeadService` — CRUD + full lifecycle (`markContacted`, `qualify`, `disqualify`, `nurture`) + `convert()` — the crown-jewel verb that atomically creates Contact + Account + Opportunity and transitions the lead to `converted`.
-  - `ActivityService` — polymorphic activities (`plan`, `start`, `complete`, `cancel`) + notes (`addNote`, `listNotesBySubject`).
-- **Pure calculators.**
-  - `defaultLeadScorer` + `composeScorers(...rules)` — host injects whatever rubric (firmographics, in-app signals, ML prediction, enrichment) via a `(lead: Lead) => number` function.
-  - `forecast(opportunities, options?)` — committed + weighted pipeline by bucket (default ISO month), with custom bucket function support. Currency-mismatch detection.
-  - `pipelineConversion(opportunities, stageIds)` — where do deals die? returns per-stage current count + won/lost counts + conversion rate.
-- **Nine repository ports** — one per entity (plus `EventTransport`, `IdGenerator`, `Clock`, optional `OutreachPort`). Full in-memory reference implementations shipped.
-- **Typed error hierarchy** rooted at `CrmError`: `NotFoundError`, `InvalidLeadTransitionError`, `InvalidOpportunityTransitionError`, `InvalidActivityTransitionError`, `StageNotInPipelineError`, `LeadAlreadyConvertedError`, `DuplicateLeadError`, `EmptyPipelineError`.
-- **Nineteen lifecycle events** (`CRM_EVENTS`): covering lead/account/contact/opportunity/pipeline/activity/note verbs, all following `crm:<resource>.<verb>` per PACKAGE_RULES rule 12.
-- **Optional `OutreachPort`** — one-method (`send`) + `NullOutreachPort` + `InMemoryOutreachPort` (recording). Host subscribes to `crm:activity.*` events and drives the port from their automation layer (keeps pacing / retry / bounce handling out of the core).
-- **Testing.** `vitest.config.ts` projects split `unit` + `integration` per [testing-infrastructure.md](../../testing-infrastructure.md). 48 tests (7 files) — all green in <1.5s.
-
-### Design choices
-
-- Pure-TS port-based pattern — consistent with `@classytic/manufacturing`, `@classytic/assets`, `@classytic/fleet`, `@classytic/carrier-*`.
-- Separate Lead + Opportunity models (erpnext style) rather than unified (odoo style) — cleaner semantics for pre-qualification vs in-pipeline data and enables distinct analytics.
-- Polymorphic Activity / Note via `subjectKind` + `subjectId` so hosts can extend without schema changes.
-- `LeadService.convert()` is atomic in intent and sequenced for auditability — it creates Account, then Contact, then Opportunity, then transitions the lead. If a downstream repo fails, the ones that succeeded persist (hosts using Mongoose sessions get atomicity at their layer).
-- Campaigns, appointment booking, competitors, contracts, team routing, RBAC, custom-field validation, email-thread parsing deferred to v0.2+ to keep the surface focused.
+# Changelog
+
+All notable changes to `@classytic/crm` are documented here.
+
+## 1.0.0 - 2026-07-29 (unpublished — last published is 0.9.0)
+
+### Fixed — Lead and Contact forked one mailbox into two rows (BEHAVIOURAL, 2026-08-08)
+
+Same bug class as the suppression fix below, in the two collections that hold live
+customer identity. Neither had a private normalizer — they had **no** canonicaliser
+at all, and relied on a partial-unique `(organizationId, email)` /
+`(organizationId, contact.email)` index over a field whose only folding was mongoose
+`lowercase: true`. That does not IDNA-fold, so `ada@bücher.de` and
+`ada@xn--bcher-kva.de` were two distinct strings, the index admitted both, and one
+mailbox became two leads with no error. Reproduced before the fix; the case control
+(`ADA@…` → refused) proves the index itself always worked — the KEY was wrong.
+
+**The fix is at the SCHEMA, not only at the repository verbs.** `@spinekit/crm`
+mounts both resources through arc's mongoose CRUD adapter, so `POST /crm/leads`
+calls the inherited `Repository.create()` and `createLead`'s pre-check never runs. A
+verb-only fix would have left the live HTTP route forking while the verb tests went
+green. `Lead.email`, `Contact.contact.email` and `Contact.contact.personalEmail` now
+carry a `canonicalEmailSetter` (`src/core/email-identity.ts`) that applies
+`normalizeEmail` from **`@classytic/contact/email`**, imported directly. Mongoose
+runs string setters on query filters too, so reads fold with writes.
+
+- The setter **never throws** — it degrades to the legacy `trim().toLowerCase()`
+  for anything the kernel refuses. A throw inside a setter surfaces during query
+  casting as an opaque `CastError`, i.e. a 500 on a READ, and degrading also means
+  nothing already stored is re-keyed by a rule that cannot explain its output.
+- `createLead` / `createContact` **do throw** — new `LeadEmailFormatError`
+  (`LEAD_EMAIL_INVALID`) and `ContactEmailFormatError` (`CONTACT_EMAIL_INVALID`),
+  both 400, nothing written. An uncanonicalisable address defeats the very index it
+  is meant to arm: broken spellings never collide, so the same input inserts
+  without limit while every call reports success.
+- Both verbs canonicalise **explicitly** before querying rather than relying on the
+  schema setter to fold the filter. A pre-check resting on an invisible field option
+  silently WIDENS the day someone edits the schema, and a widened filter does not
+  fail — it matches nothing and answers "no duplicate".
+
+**Behaviour change worth naming:** `LeadService.convert()` passes the lead's stored
+email into `createContact`, so converting a lead whose address cannot be
+canonicalised now fails instead of minting a Contact whose only identity field is
+unusable. Dropping the address silently would be the worse half of that trade.
+Reachability was checked, not assumed: be-prod gates CRM writes with `requireAuth()`
+and there is no public lead-capture route, so the 400 reaches an operator or an
+importer, never an anonymous form visitor.
+
+New export `crmEmailKey(email): string | null`. The setter and the two throwing
+helpers stay internal — a host must not re-apply either.
+
+**Stored rows are NOT migrated.** `scripts/lead-contact-email-key-drift.mjs`
+(shipped, read-only; `npm run drift:email-keys`) classifies both collections as
+`unchanged` / `rekey` / `collision` / `uncanonicalisable`, prints a distinct banner
+for an absent collection and for one with rows but no emails, and writes nothing.
+`collision` is the fork: two rows, one mailbox, and the unique index means a naive
+`$set` fails outright — merging them and re-pointing the loser's opportunities,
+activities and subscriptions is a human decision.
+
+Pinned by `tests/integration/lead-contact-email-idna.scenario.test.ts` (15 cases,
+covering both the verb path and the arc-CRUD path) and
+`tests/integration/email-key-drift-tool.test.ts` (7 cases that falsify the report
+itself against planted rows of every class).
+
+**Not done here (deliberate):** no schema `validate` on the email fields, so the
+arc-CRUD route still accepts an uncanonicalisable address and stores it
+legacy-folded. Adding one would turn a currently-succeeding admin write into a 400
+and would break `convert()` on rows that already exist. That is a separate decision.
+
+### Fixed — the suppression list keyed one mailbox as two (BEHAVIOURAL)
+
+`SuppressionRepository` held a private `email.trim().toLowerCase()`. It does not
+IDNA-canonicalise, so `ada@bücher.de` and `ada@xn--bcher-kva.de` — one host in two
+encodings — were two keys: an address suppressed under one spelling stayed
+**sendable** under the other, and nothing errored. The send succeeded and looked
+correct. A do-not-contact list is frequently a legal obligation, so this is worse
+than an ordinary dedup miss.
+
+All four verbs (`suppress`, `isSuppressed`, `filterSuppressed`, `unsuppress`) now
+canonicalise through `normalizeEmail` from **`@classytic/contact/email`**, imported
+directly — no re-export, no local wrapper. `@classytic/contact >=0.1.0` is a new
+**peer** dependency.
+
+`normalizeEmail` refuses what it cannot canonicalise, and the two sides spend that
+refusal differently:
+
+- **Writes throw** the new `SuppressionEmailFormatError` (400,
+  `SUPPRESSION_EMAIL_INVALID`) and store nothing. A malformed row is a suppression
+  that can never match — it suppresses nothing while reporting success. `unsuppress`
+  throws too: it re-enables sending, so a `false` would read as "already removed".
+- **Reads fail CLOSED.** `isSuppressed()` returns `true` and `filterSuppressed()`
+  reports as blocked for an address with no canonical form. They do not throw —
+  `filterSuppressed` is a batch verb, and one malformed recipient must not abort a
+  fanout to thousands of valid ones.
+
+New export `suppressionEmailKey(email): string | null` — the key a caller must test
+`filterSuppressed()` membership against, and the only way to tell "unparseable"
+apart from "on the list".
+
+**Stored rows are NOT migrated.** A row written under the old rule in a
+non-canonical form is now unreachable. `scripts/suppression-key-drift.mjs` (shipped,
+read-only) classifies every row as `unchanged` / `rekey` / `collision` /
+`uncanonicalisable` and writes nothing; `collision` rows cannot be moved by an
+`updateOne` at all, because `(organizationId, email)` is unique and another row
+already holds the target key. Rewriting a suppression list has legal consequences —
+run the report, decide by hand.
+
+Pinned by `tests/integration/suppression-idna.scenario.test.ts` (12 cases).
+
+### Changed
+- **License:** relicensed from MIT to the **Classytic Source-Available License** (Community & Commercial). Evaluation/development use remains free; production use now requires a commercial license from Classytic LLC. See `LICENSE`.
+- Major bump marks the license change; versions published before 1.0.0 remain under their original MIT terms.
+
+## 0.10.1 - 2026-07-22 (unpublished)
+
+### Changed
+- Internal: `InProcess*Bus` is now a thin subclass of `@classytic/primitives/event-infra`'s shared `InProcessEventBus` (dedup / error-isolation / close semantics unchanged); `MemoryOutboxStore` re-exported from the shared runtime where applicable. No public API, event-name, or wire-envelope change. Requires `@classytic/primitives >=0.13.0`.
+
+## [0.10.0] — unpublished (2026-07-22)
+
+### Changed — `dispose()` renamed to `destroy()` (fleet lifecycle convention)
+
+- **`engine.destroy()`** is the canonical teardown verb (matches
+  manufacturing / purchase / order / catalog / cart). `dispose()` remains
+  as a deprecated one-line alias delegating to `destroy()` so hosts don't
+  break mid-migration; it will be removed in a future minor.
+- **Behavioral fix**: teardown now closes the transport ONLY when the
+  engine created it itself (`InProcessCrmBus`). Previously `dispose()`
+  closed a host-injected `eventTransport` too — the host's bus is the
+  host's to close.
+- Destroy is idempotent — a second call (or `dispose()` after `destroy()`)
+  is a no-op. Mongoose models/connection are untouched (host-owned).
+- Lifecycle coverage in `tests/integration/engine-lifecycle.test.ts`.
+
+## [0.9.0] — unpublished (2026-07-15)
+
+### Changed — mongokit 3.22 adopted (peer floors: mongokit >=3.22.0, repo-core >=0.13.0, primitives >=0.11.0)
+
+- **Seven transition verbs ride `applyTransition`** (activity, campaign,
+  enrollment exit + generic, lead, sequence, subscription, opportunity):
+  machine pre-flight + CAS + accurate race diagnosis via the machines'
+  existing errorFactories. All `this as any` casts at those sites are gone
+  (native method).
+- **FIXED a real concurrency defect**: five sites built `statusHistory` by
+  read-modify-write (`[...(existing.statusHistory ?? []), entry]`) inside
+  the CAS patch — concurrent writers could drop history entries. Entries
+  now ride `$push` via the `push` arg, byte-identical shapes preserved.
+- **`EmailEvent` log fence enforced** — "append-only" was a doc comment;
+  `appendOnlyPlugin` now refuses every mutation path (405
+  `APPEND_ONLY_VIOLATION`), with `deleteMany` allowed for host-gated GDPR
+  erasure of a recipient's rows.
+- DELIBERATELY unchanged: `enrollment.advanceStep` (non-status
+  `currentStepIndex` CAS with null semantics) and opportunity's stage-move
+  claim — correct raw `claim` usage, not transition boilerplate.
+
+## [0.8.0] — 2026-07-11
+
+### Added — engagement-based lead scoring
+- **`ILeadEngagement` on the Lead** (`{ opens, clicks, replies, activities, lastEngagedAt? }`, nested default `{}` so old rows read as zeros). Behavioural counters, distinct from firmographic fields.
+- **`LeadRepository.recordEngagement(id, signal, ctx)`** where `signal ∈ 'open'|'click'|'reply'|'activity'` (`LeadEngagementSignal`). Atomic `$inc` on the matching counter + `lastEngagedAt` via `findOneAndUpdate`, then `recomputeScore`. Hosts feed it off `crm:message.received` (reply), `crm:activity.*` (activity), and email open/click tracking.
+- **`defaultLeadScorer` now weighs engagement** on top of firmographic fit: reply ×25 · click ×8 · open ×2 · activity ×5, capped at +80. `LeadInput` picks up `engagement`. Pure/deterministic — no wall-clock. Absent engagement scores as zero (score unchanged for pre-existing leads until a signal lands).
+
+## [0.7.0] — 2026-07-05
+
+### Added — org-wide email suppression list
+
+- **`Suppression` entity** (`crm.repositories.suppression`, model
+  `Suppression`): global per-org "never email this address again" list —
+  the gate hosts consult before EVERY outbound email. Unsubscribes on
+  `Subscription` stay per-campaign; suppression is org-wide.
+  - `suppress(email, { reason, source?, subjectKind?, subjectId?, metadata? }, ctx?)`
+    — idempotent `getOrCreate` on the unique `(organizationId, email)`
+    index (no check-then-save); emits `crm:suppression.added` only when
+    THIS call inserted the row.
+  - `isSuppressed(email, ctx?)` → boolean.
+  - `filterSuppressed(emails, ctx?)` → `Set<string>` of the suppressed
+    subset — ONE `$in` query for the campaign-fanout hot path.
+  - `unsuppress(email, ctx?)` — atomic delete; emits
+    `crm:suppression.removed` only when a row was actually removed.
+  - All verbs normalize emails (trim + lowercase; schema stores lowercase).
+- **`SUPPRESSION_REASONS`** (`'bounce' | 'complaint' | 'unsubscribe' |
+  'manual'`) — the first three `satisfies readonly EmailEventKind[]` (P6),
+  so a rename in `EMAIL_EVENT_KINDS` fails compilation here.
+- **Events** `crm:suppression.added` / `crm:suppression.removed` — Zod
+  catalog definitions included (no-drift invariant stays green);
+  `organizationId` rides event meta as usual.
+- **Validators** `suppressSchema` / `unsuppressSchema` /
+  `suppressionFilterSchema`.
+
+### Added — reply-detection exit verb
+
+- **`EnrollmentRepository.exitActiveOnReply(subjects, ctx?)`** — the ONE
+  method a host's `crm:message.received` subscriber calls: finds ACTIVE
+  enrollments for the given `{ subjectKind, subjectId }` list, batch-loads
+  their sequences in a single `$in` query, skips those with
+  `replyDetectionEnabled === false`, and exits the rest via `exit(id,
+  'reply')` (each exit emits `crm:enrollment.exited`). Lost CAS races
+  (concurrent pause/complete/exit) are skipped, not failed. Returns the
+  enrollments this call exited.
+- `EnrollmentRepositoryDeps` now carries `sequences: SequenceRepository`
+  (same cross-repo deps idiom as `OpportunityRepository.pipelines` /
+  `MessageRepository.conversations`) — wired automatically by
+  `createCrm()`; only hosts constructing `EnrollmentRepository` by hand
+  need to pass it.
+
+## [0.6.0] — 2026-07-02
+
+Breaking-in-behavior release (ships as MINOR per house convention):
+outbox-first, session-safe event dispatch — the previously deferred
+PACKAGE_RULES §P8/§P8.1 work.
+
+### Added — unit-of-work contract (P8.1, shared with refit/review/cart/invoice)
+
+- **`engine.withTransaction(ctx, body)`** — runs `body` inside a MongoDB
+  transaction with post-commit event discipline: events dispatched through
+  `txCtx` are queued under `ctx[PENDING_EVENTS]` and flushed to the
+  transport only AFTER commit; the queue resets on retry attempts; an abort
+  leaks nothing to in-process subscribers. Reuses the caller's session (and
+  queue) when `ctx.session` is already set. Standalone-Mongo dev boots opt
+  in via the existing `allowNonTransactional: true`.
+- **`PENDING_EVENTS`** (`Symbol.for('@classytic/crm:pendingEvents')`) +
+  **`flushPending(transport, queue, logger?)`** + **`runUnit`** exported
+  from the root for hosts composing their own outer transaction.
+- **`CrmConfig.outbox?: OutboxStore`** (from `@classytic/primitives/outbox`)
+  — 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. Outbox save failures
+  PROPAGATE (P8: a swallowed save means the write persists while its event
+  vanishes).
+- **`CrmEventDispatcher`** — EventTransport-compatible wrapper repositories
+  route every event through (`engine.events` is now this wrapper; the host
+  `publish`/`subscribe` surface is unchanged).
+- **`UnmanagedSessionError`** (`code: 'UNMANAGED_SESSION'`) — a host-owned
+  `ctx.session` arriving with neither an outbox nor a `PENDING_EVENTS`
+  queue now throws instead of ghost-publishing mid-transaction.
+  **Behavioral break:** callers that previously threaded a bare session and
+  tolerated ghost events must switch to `engine.withTransaction` (or wire
+  an outbox / attach a queue).
+
+### Added — timezone-aware forecasting
+
+- **`ForecastOptions.timeZone`** — IANA zone for the default month bucket
+  (e.g. `'Asia/Dhaka'`). Without it, months cut at UTC boundaries: a deal
+  expected to close July 1, 02:00 Dhaka time (June 30, 20:00 UTC) files
+  under JUNE. Uses `civilDateOf` from `@classytic/primitives/timezone`.
+  Peer floor bumped: `@classytic/primitives >=0.9.0`.
+
+### Fixed — sequence/enrollment (completes the 0.6.0 WIP)
+
+- **Event catalog no-drift restored**: 10 missing Zod definitions added
+  (`crm:sequence.{created,active,paused,archived}`,
+  `crm:enrollment.{created,step_sent,paused,resumed,completed,exited}`) —
+  `crm:sequence.created` and `crm:enrollment.step_sent` are host-emitted
+  (create via `def.create()`), the rest publish in-repo.
+- **`EnrollmentRepository.setWorkflowRunId` / `advanceStep` no longer
+  bypass the repository**: both used raw `model.findOneAndUpdate` with a
+  manual tenant filter — escaping `multiTenantPlugin` scoping AND
+  `ctx.session` (a call inside `withTransaction` would commit outside the
+  transaction). `advanceStep` is now a `claim()` CAS on `currentStepIndex`
+  with `where: { status: 'active' }`; `setWorkflowRunId` goes through
+  `repo.update`.
+
+### Tests
+
+- 14 new: `tests/unit/dispatch.test.ts` (6 — outbox propagation/session
+  routing/guard/swallow), `tests/integration/unit-of-work.test.ts` (3 —
+  convert() on a replica set: zero mid-tx events, post-commit flush, abort
+  leaks nothing, bare-session guard), `tests/unit/forecast-timezone.test.ts`
+  (5 — the +06:00 month-boundary trap). 110/110 total.
+
+## [0.5.1] — 2026-06-14
+
+### Fixed — declaration bundle
+
+- **fix: declaration bundle exported mangled aliases; consumer named imports
+  now resolve.** The published `dist/index.d.ts` re-exported every public
+  symbol under a minified alias (`export { AccountRepository as A, CRM_EVENTS
+  as Rr, … }`), so downstream `import { AccountRepository, CRM_EVENTS } from
+  '@classytic/crm'` failed with TS2305 / TS2460. Root cause: the `./events`
+  entry re-exports a strict subset of the `index` barrel, which made
+  `rolldown-plugin-dts` alias every name on the superset (`index`) entry when
+  both were emitted in a single pass. Build now runs `index` and `events` as
+  two independent tsdown passes (array config) so each `.d.ts` exports real
+  names. `tsdown` bumped `^0.14.2` → `^0.21.10` to match sibling packages.
+  No runtime/API change.
+
+## [0.5.0] — 2026-06-14
+
+Stack upgrade + verified correctness fixes + PACKAGE_RULES compliance. No
+new features. Clean break — no deprecation aliases.
+
+### Changed — stack currency
+
+- Peers bumped: `@classytic/mongokit` `>=3.16.0`, `@classytic/repo-core`
+  `>=0.6.0`, `@classytic/primitives` `>=0.7.1`, `mongoose` `>=9.4.1`.
+  Clean-installed from npm and verified resolved (3.16.0 / 0.6.0 / 0.7.2).
+
+### Added — PACKAGE_RULES compliance
+
+- **Zod event catalog (rule 18).** New `crmEventDefinitions[]` (56 events,
+  one Zod schema each) exported from the package root and a new `./events`
+  subpath. Timestamps are `z.iso.datetime()`. A no-drift invariant test
+  asserts every `CRM_EVENTS` constant has a definition. Hosts wire these
+  into arc's `EventRegistry` for publish-time validation + OpenAPI.
+- **Model-collision policy (rule 21).** `createCrm()` now throws
+  `CrmModelCollisionError` when a model name is already registered; pass
+  `forceRecreate: true` (test/hot-reload) to delete + re-register.
+- **Index management (rule 35).** New `autoIndex` config flag (default
+  `true`) and `engine.syncIndexes()` for `autoIndex: false` production
+  boots.
+- **Capability boot gate.** `createCrm()` asserts the backend supports
+  `upsert` / `getOrCreate` / `duplicateKeyError` (and `transactions`,
+  unless `allowNonTransactional: true`) so misconfigured deployments fail
+  loud at boot instead of mid-convert.
+
+### Fixed — domain correctness
+
+- **Lead / Subscription / Campaign dedup are now race-safe.** Added
+  authoritative partial-unique indexes — lead `(organizationId, email)`,
+  campaign `(organizationId, name)`, subscription `(organizationId,
+  contactId, campaignId)` scoped to live statuses — and catch the
+  residual `E11000` via `isDuplicateKeyError`, re-throwing the same typed
+  domain error the pre-check emits. The prior check-then-save left a
+  TOCTOU window.
+- **Owner reassignment is now atomic.** `assign()` on lead / account /
+  contact / opportunity / conversation uses a single `findOneAndUpdate`
+  CAS (`{ ownerId: { $ne } }` guard, `returnDocument: 'before'`) — no
+  read-modify-write lost-update window, and the emitted `previousOwnerId`
+  is the true pre-image under concurrency.
+- **Cross-tenant leak in dashboard/feed reads closed.** `findRecentForFeed`,
+  `countCreatedSince`, `countOpen`, `sumWonSince`, `countOverduePlanned`
+  dropped raw `Model.find` / `countDocuments` with a manual
+  `if (ctx) organizationId` filter (which read ALL tenants when ctx was
+  absent) for the tenant-scoped `findAll` / `count` repository methods.
+
+### Build hygiene
+
+- Sourcemaps and declaration maps are no longer emitted (`sourceMap` /
+  `declarationMap` off in tsconfig; `sourcemap: false` in tsdown) — both
+  leak source.
+- Removed `@deprecated` markers from `ConvertResult` convenience id fields
+  (kept the fields; they were never deprecated, just mislabelled).
+- Dropped the stale pnpm lockfile/workspace and the bundled `.tgz`;
+  installs are npm-from-registry only.
+
+### Docs
+
+- Rewrote the README to the engine-factory API (`createCrm` + repository
+  domain verbs). The previous README documented the abandoned v0.1
+  port/adapter design (`AccountService`, `InMemory*Repository`,
+  `OutreachPort`) that no longer exists.
+
+### Tests
+
+- Added `tests/integration/invariants.test.ts` (tenant probe, lead +
+  subscription dedup races, atomic reassignment) and
+  `tests/unit/event-catalog.test.ts` (no-drift + round-trip). 87 → 96
+  tests.
+
+## [0.4.0] — 2026-05-22
+
+### Changed — Subscription model renamed to `EmailSubscription`
+
+**Breaking at the Mongo identity level.** The CRM's email opt-in resource
+now registers as Mongoose model `EmailSubscription` (was `Subscription`)
+and persists into the `email_subscriptions` collection (was
+`subscriptions`).
+
+**Why:** the previous name collided with `@classytic/revenue`'s
+`Subscription` model when both packages were loaded on the same
+Mongoose connection — `RevenueModelCollisionError` at boot. Renaming
+gives the two concepts distinct identities at the DB level and lets
+revenue + CRM coexist without the host having to split connections.
+
+**TypeScript surface is unchanged.** `ISubscriptionDocument`,
+`SubscriptionRepository`, `subscription.handlers.ts`,
+`CrmModels.Subscription`, etc. all keep their existing names — only
+the Mongoose model name string and the underlying collection name
+changed. Consumers that import from `@classytic/crm` need no source
+changes; the host only needs to migrate existing data (see below).
+
+### Migration
+
+For DBs with existing CRM subscription rows in the legacy `subscriptions`
+collection (distinguishable from revenue rows by `contactId` presence):
+
+```js
+// MongoDB shell — one-time migration
+db.subscriptions.aggregate([
+  { $match: { contactId: { $exists: true } } },
+  { $out: 'email_subscriptions' },
+]);
+// Then remove the migrated docs from the legacy collection:
+db.subscriptions.deleteMany({ contactId: { $exists: true } });
+```
+
+Hosts using only CRM (no revenue) can also run this — leftover rows in
+`subscriptions` won't cause boot errors because there's no collision
+without revenue.
+
+## [0.3.0] — 2026-05-17
+
+### Added — `EmailEvent` domain
+
+Closes the loop between outbound CRM sends and recipient engagement.
+Hosts can now record opens, clicks, bounces, complaints, and unsubscribes
+against a Contact / Subscription / Campaign tuple — and downstream
+services (drip-sequence "if opened" branches, lead scoring, suppression
+lists) consume the same events without polling the email transport.
+
+- **Entity & enum** — `EmailEvent` (append-only) plus the
+  `EmailEventKind` enum (`open` / `click` / `bounce` / `complaint` /
+  `unsubscribe`) split into `ENGAGEMENT_KINDS` and `SUPPRESSION_KINDS`
+  helper sets for classification at call sites.
+- **Port** — `EmailEventRepository` with filtered list, per-subject
+  timeline, per-campaign aggregates (`uniqueOpens`, `uniqueClicks`,
+  `bounces`, `complaints`, `unsubscribes`, `totalEvents`), and a
+  GDPR-style `deleteForSubject()` purge.
+- **Service** — `EmailEventService.recordOpen()` /
+  `.recordClick({ url })` / `.recordBounce()` / `.recordComplaint()` /
+  `.recordUnsubscribe()` + read-side `.listForSubject()`,
+  `.aggregateForCampaign()`, and `.hasEngaged(subjectId, campaignId,
+  kind)` for drip-condition checks.
+- **Events** — `crm:email_event.opened` / `.clicked` / `.bounced` /
+  `.complained` / `.unsubscribed` with Zod-validated payloads in
+  `event-catalog`, wired into `crmEventDefinitions[]`.
+- **In-memory adapter** — `InMemoryEmailEventRepository` (tests +
+  dev). Hosts implement against Mongo / Postgres / etc.
+
+### Added — re-exports from `@classytic/primitives@0.6.0`
+
+To eliminate duplicate type imports at consumer call sites:
+
+```ts
+import {
+  appendStatus,
+  StatusChangeEntry,
+  StatusHistory,
+  timeInStatus,
+  lastTransitionTo,
+} from '@classytic/crm';
+```
+
+These pass through from `@classytic/primitives/status-history`. The
+existing entity-specific `LeadStatusEntry` / `OpportunityStatusEntry` /
+etc. names are still exported for back-compat — they remain structurally
+compatible with `StatusChangeEntry<TStatus>`.
+
+### Changed
+
+- Peer dep `@classytic/primitives` bumped from `>=0.5.0` to `>=0.6.0`
+  to access the new `status-history` subpath and value-typed primitives.
+- Test harness `buildHarness()` now also exposes an
+  `emailEvents: EmailEventService` and `emailEventRepo` for integration
+  tests that exercise the engagement → drip path.
+
+### Dependencies
+
+- `@classytic/primitives@>=0.6.0` (peer, was `>=0.5.0`)
+- `zod@>=4.0.0` (peer, unchanged)
+
+## [0.1.0] — 2026-04-18
+
+Initial release.
+
+### Added
+
+- **Eight domain entities.** `Contact`, `Account`, `Lead`, `Opportunity`, `Pipeline` (+ nested `Stage`), `Activity`, `Note`, `LossReason`.
+- **Three state machines.** Lead (`new` → `contacted` → `qualified` → `converted`, + `disqualified` / `nurturing` branches), Opportunity (`open` → `won` / `lost` / `abandoned` with in-pipeline Stage movement), Activity (`planned` → `in_progress` → `completed` / `cancelled`). All transitions CAS-guarded with explicit `*_TRANSITIONS` maps and `canTransition*` guards.
+- **Six services.**
+  - `ContactService` — CRUD + tag filtering + email lookup.
+  - `AccountService` — CRUD + domain lookup.
+  - `PipelineService` — create, archive, stage helpers (`getStage`, `getFirstStage`, `getNextStage`).
+  - `OpportunityService` — create at first stage (or specified), `moveToStage` with advance/regress event disambiguation, `win` / `lose` (with `lostReasonId`) / `abandon`.
+  - `LeadService` — CRUD + full lifecycle (`markContacted`, `qualify`, `disqualify`, `nurture`) + `convert()` — the crown-jewel verb that atomically creates Contact + Account + Opportunity and transitions the lead to `converted`.
+  - `ActivityService` — polymorphic activities (`plan`, `start`, `complete`, `cancel`) + notes (`addNote`, `listNotesBySubject`).
+- **Pure calculators.**
+  - `defaultLeadScorer` + `composeScorers(...rules)` — host injects whatever rubric (firmographics, in-app signals, ML prediction, enrichment) via a `(lead: Lead) => number` function.
+  - `forecast(opportunities, options?)` — committed + weighted pipeline by bucket (default ISO month), with custom bucket function support. Currency-mismatch detection.
+  - `pipelineConversion(opportunities, stageIds)` — where do deals die? returns per-stage current count + won/lost counts + conversion rate.
+- **Nine repository ports** — one per entity (plus `EventTransport`, `IdGenerator`, `Clock`, optional `OutreachPort`). Full in-memory reference implementations shipped.
+- **Typed error hierarchy** rooted at `CrmError`: `NotFoundError`, `InvalidLeadTransitionError`, `InvalidOpportunityTransitionError`, `InvalidActivityTransitionError`, `StageNotInPipelineError`, `LeadAlreadyConvertedError`, `DuplicateLeadError`, `EmptyPipelineError`.
+- **Nineteen lifecycle events** (`CRM_EVENTS`): covering lead/account/contact/opportunity/pipeline/activity/note verbs, all following `crm:<resource>.<verb>` per PACKAGE_RULES rule 12.
+- **Optional `OutreachPort`** — one-method (`send`) + `NullOutreachPort` + `InMemoryOutreachPort` (recording). Host subscribes to `crm:activity.*` events and drives the port from their automation layer (keeps pacing / retry / bounce handling out of the core).
+- **Testing.** `vitest.config.ts` projects split `unit` + `integration` per [testing-infrastructure.md](../../testing-infrastructure.md). 48 tests (7 files) — all green in <1.5s.
+
+### Design choices
+
+- Pure-TS port-based pattern — consistent with `@classytic/manufacturing`, `@classytic/assets`, `@classytic/fleet`, `@classytic/carrier-*`.
+- Separate Lead + Opportunity models (erpnext style) rather than unified (odoo style) — cleaner semantics for pre-qualification vs in-pipeline data and enables distinct analytics.
+- Polymorphic Activity / Note via `subjectKind` + `subjectId` so hosts can extend without schema changes.
+- `LeadService.convert()` is atomic in intent and sequenced for auditability — it creates Account, then Contact, then Opportunity, then transitions the lead. If a downstream repo fails, the ones that succeeded persist (hosts using Mongoose sessions get atomicity at their layer).
+- Campaigns, appointment booking, competitors, contracts, team routing, RBAC, custom-field validation, email-thread parsing deferred to v0.2+ to keep the surface focused.