@classytic/crm 0.1.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,181 @@
 
 All notable changes to `@classytic/crm` are documented here.
 
+## [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.

package/README.md

@@ -1,37 +1,37 @@
 # @classytic/crm
 
-Framework-agnostic CRM primitive for Node.js + Bun — the base to build
-the next Pipedrive, HubSpot, Salesforce, or Buffer-style outreach
-automation on top of.
-
-- **Pure TypeScript.** No Mongo, no HTTP, no framework dep.
-- **Event-driven.** 19 lifecycle events out of the box — any
-  subscribing automation layer plugs in without modifying the core.
-- **Port-based storage.** Plug in Mongoose / Prisma / your existing
-  data store per entity (8 repo interfaces, 1 optional outreach
-  bridge). In-memory reference implementations shipped for tests +
-  standalone use.
-- **Atomic state transitions.** Every lead / opportunity / activity
-  status change goes through a CAS against the expected status.
-- **Pluggable lead scoring.** `defaultLeadScorer` is replaceable with
-  `composeScorers(...rules)` or any `(lead: Lead) => number`.
-- **Forecast + pipeline-conversion analytics.** Pure functions over
-  opportunity lists — safe to run in any context.
-- **Polymorphic activities + notes.** Attach to Lead, Opportunity,
-  Contact, or Account. Automation subscribes to `crm:activity.*` and
-  does its thing — email, SMS, calendar booking, Slack ping, LLM
-  summary.
-
-## Why this matters for the Node / Bun community
-
-Most CRMs ship as monolithic apps. This package is the **headless
-engine** — it owns the entities, state machines, events, and
-analytics, and gets out of your way on everything else. Want a
-Buffer-style scheduled-outreach app? Subscribe to `crm:activity.planned`
-with `type: 'email'`, queue the send. Want an AI-written follow-up
-layer? Subscribe to `crm:opportunity.stage_advanced`, call an LLM,
-`activities.plan(...)` the generated task. None of that lives in this
-package; all of it is unblocked by it.
+Engine-factory CRM package for the Classytic commerce stack — leads,
+accounts, contacts, opportunities, pipelines, campaigns, double-opt-in
+subscriptions, polymorphic activities + notes, email-engagement events,
+and conversation/message threads. Built on **Mongoose + @classytic/mongokit
++ @classytic/repo-core + @classytic/primitives**, PACKAGE_RULES compliant.
+
+> **Architecture (0.4.0+):** this is an engine-factory mongokit package,
+> NOT the pure-TS port-based design earlier docs described.
+> `createCrm({ connection })` returns Mongoose models, `Repository`
+> subclasses (domain verbs live on the repos), and an `EventTransport`.
+> The ports / adapters / in-memory-repo layer is gone.
+
+- **Repositories ARE the API.** Each repo `extends Repository<TDoc>` from
+  mongokit and inherits CRUD, pagination, query parsing, aggregation, and
+  transactions. Domain verbs (`qualify`, `convert`, `win`, `subscribe`,
+  `confirm`, `merge`, …) live on the same class.
+- **Atomic state transitions.** Every lifecycle move goes through
+  `assertAndClaim` (state-machine legality check + `repo.claim()` CAS).
+  Concurrent qualifiers / stage-moves / activations can't both win;
+  race-losses surface as typed transition errors.
+- **Index-backed dedup.** Lead email, campaign name, and live
+  `(contact, campaign)` subscriptions are guarded by partial-unique
+  indexes; the residual `E11000` is caught via `isDuplicateKeyError` and
+  re-thrown as the same typed domain error the pre-check emits — no
+  check-then-save TOCTOU window.
+- **Multi-tenant by default.** `multiTenantPlugin` is wired on every repo
+  with `required: true`; tenant scope is injected at POLICY priority and
+  cannot be forgotten. A read with no `organizationId` throws.
+- **Event-driven extension plane.** Every lifecycle change publishes a
+  `crm:<resource>.<verb>` event through an arc-compatible `EventTransport`.
+  Automation (outreach, AI follow-up, analytics) subscribes with globs;
+  none of it lives in this package.
 
 ## Install
 
@@ -39,283 +39,185 @@ package; all of it is unblocked by it.
 npm install @classytic/crm
 ```
 
-`@classytic/primitives` is the only peer (for `Money`).
+Peers: `@classytic/mongokit >=3.16.0`, `@classytic/repo-core >=0.6.0`,
+`@classytic/primitives >=0.7.1`, `mongoose >=9.4.1`, `zod >=4.0.0`.
 
-## Full lead-to-customer flow
+## Quick start
 
 ```ts
-import {
-  AccountService,
-  ActivityService,
-  ContactService,
-  LeadService,
-  OpportunityService,
-  PipelineService,
-  InMemoryAccountRepository,
-  InMemoryActivityRepository,
-  InMemoryContactRepository,
-  InMemoryLeadRepository,
-  InMemoryNoteRepository,
-  InMemoryOpportunityRepository,
-  InMemoryPipelineRepository,
-  InMemoryEventTransport,
-} from '@classytic/crm';
-
-const events = new InMemoryEventTransport();
-
-const accounts = new AccountService({ repo: new InMemoryAccountRepository(), events });
-const contacts = new ContactService({ repo: new InMemoryContactRepository(), events });
-const pipelines = new PipelineService({ repo: new InMemoryPipelineRepository(), events });
-const opportunities = new OpportunityService({
-  repo: new InMemoryOpportunityRepository(),
-  pipelines,
-  events,
-});
-const leads = new LeadService({
-  repo: new InMemoryLeadRepository(),
-  contacts,
-  accounts,
-  opportunities,
-  events,
-});
-const activities = new ActivityService({
-  repo: new InMemoryActivityRepository(),
-  notes: new InMemoryNoteRepository(),
-  events,
+import mongoose from 'mongoose';
+import { createCrm, LeadService } from '@classytic/crm';
+
+const crm = await createCrm({
+  connection: mongoose.connection,
+  tenantFieldType: 'objectId', // matches Better Auth orgs; 'string' for UUID hosts
 });
 
+const ctx = { organizationId: orgId };
+
 // Pipeline setup.
-const pipeline = await pipelines.create({
-  name: 'New Business',
-  stages: [
-    { name: 'Prospecting', sequence: 1, defaultProbability: 0.1 },
-    { name: 'Discovery',   sequence: 2, defaultProbability: 0.3 },
-    { name: 'Proposal',    sequence: 3, defaultProbability: 0.6 },
-    { name: 'Negotiation', sequence: 4, defaultProbability: 0.8 },
-  ],
-});
+const pipeline = await crm.repositories.pipeline.create(
+  {
+    name: 'New Business',
+    stages: [
+      { name: 'Prospecting', sequence: 1, defaultProbability: 0.1 },
+      { name: 'Discovery',   sequence: 2, defaultProbability: 0.3 },
+      { name: 'Proposal',    sequence: 3, defaultProbability: 0.6 },
+      { name: 'Negotiation', sequence: 4, defaultProbability: 0.8 },
+    ],
+  },
+  ctx,
+);
 
-// Inbound lead.
-const lead = await leads.create({
-  email: 'alex@acme.co',
-  firstName: 'Alex',
-  lastName: 'Rivera',
-  companyName: 'Acme',
-  jobTitle: 'Director',
-  source: 'web-form',
-});
+// Inbound lead — auto-scores + emits crm:lead.created.
+const lead = await crm.repositories.lead.createLead(
+  {
+    email: 'alex@acme.co',
+    firstName: 'Alex',
+    lastName: 'Rivera',
+    companyName: 'Acme',
+    jobTitle: 'Director',
+    source: 'web-form',
+  },
+  ctx,
+);
+const leadId = String(lead._id);
 
-// Qualify + convert — spawns Contact + Account + Opportunity atomically.
-await leads.markContacted(lead.id);
-await leads.qualify(lead.id);
-const { opportunityId } = await leads.convert(lead.id, {
-  pipelineId: pipeline.id,
-  amount: { amount: 120_000, currency: 'USD' },
-  expectedCloseAt: new Date('2026-06-30'),
-});
+// Qualify, then convert — spawns Account + Contact + Opportunity.
+await crm.repositories.lead.markContacted(leadId, {}, ctx);
+await crm.repositories.lead.qualify(leadId, {}, ctx);
 
-// Move through pipeline.
-await opportunities.moveToStage(opportunityId, { stageId: pipeline.stages[1]!.id });
-await opportunities.moveToStage(opportunityId, { stageId: pipeline.stages[2]!.id });
-await opportunities.moveToStage(opportunityId, { stageId: pipeline.stages[3]!.id });
+const leads = LeadService.fromEngine(crm);
+const { opportunityId } = await leads.convert(
+  leadId,
+  { pipelineId: String(pipeline._id), amount: 120_000, currency: 'USD' },
+  ctx,
+);
 
-// Close as won.
-await opportunities.win(opportunityId, { amount: { amount: 125_000, currency: 'USD' } });
+// Move through the pipeline (atomic CAS on stageId).
+const stages = pipeline.stages;
+await crm.repositories.opportunity.moveToStage(opportunityId, { stageId: String(stages[1]._id) }, ctx);
+await crm.repositories.opportunity.moveToStage(opportunityId, { stageId: String(stages[2]._id) }, ctx);
+
+// Close as won — terminal, immutable.
+await crm.repositories.opportunity.win(opportunityId, { amount: 125_000 }, ctx);
+
+// React to events from anywhere.
+crm.events.subscribe('crm:opportunity.*', (e) => console.log(e.type));
+```
+
+### Atomic conversion under a transaction
+
+`LeadService.convert()` writes across four repositories (Account, Contact,
+Opportunity, Lead). Wrap the call in `connection.transaction()` and thread
+the session through `ctx.session` so all four writes commit or roll back
+together (requires a replica set):
+
+```ts
+await mongoose.connection.transaction(async (session) => {
+  await leads.convert(leadId, { pipelineId, amount: 120_000 }, { ...ctx, session });
+});
 ```
 
 ## State machines
 
 ```
 Lead:         new → contacted → qualified → converted
-                ↘        ↘           ↘
-                 disqualified / nurturing ←──────┐
-                                                  │
-                                                  (nurturing → contacted/qualified)
+              new/contacted/qualified → disqualified | nurturing
+              nurturing → contacted | qualified
+
+Opportunity:  open → won | lost | abandoned   (terminal; stage moves while open)
 
-Opportunity:  open → won | lost | abandoned  (terminal)
-              (stage movement happens while open)
+Campaign:     draft → active ⇄ paused → completed → archived
+
+Subscription: pending → confirmed → unsubscribed | bounced | complained
 
 Activity:     planned → in_progress → completed
-                ↘            ↘
-                 cancelled (from any non-terminal)
+              planned/in_progress → cancelled
 ```
 
-Each transition is CAS-guarded and appends to the record's
-`statusHistory`. Invalid transitions throw typed errors.
-
-## Lead scoring
+Every transition is CAS-guarded and appends to the record's
+`statusHistory`. Invalid transitions throw typed errors;
+`*_TRANSITIONS` maps are the canonical source of truth.
 
-`LeadService` runs the scorer on `create` and on-demand via
-`recomputeScore(id)`. Replace the default with your own:
+## Lead scoring, forecast, conversion analytics
 
 ```ts
-import { LeadService, composeScorers } from '@classytic/crm';
+import { composeScorers, forecast, pipelineConversion } from '@classytic/crm';
 
+// Custom scorer (replaces defaultLeadScorer at repo construction):
 const scorer = composeScorers(
   (l) => (l.email ? 20 : 0),
   (l) => (l.source === 'referral' ? 30 : 0),
-  (l) => (l.tags?.includes('enterprise') ? 50 : 0),
   (l) => (/ceo|cto|founder/i.test(l.jobTitle ?? '') ? 40 : 0),
-  // Plug in ML / enrichment predictions:
-  (l) => myEnricher.scoreFor(l),
 );
 
-new LeadService({ repo, contacts, accounts, opportunities, scorer });
-```
-
-## Forecast + pipeline conversion
-
-```ts
-import { forecast, pipelineConversion } from '@classytic/crm';
-
-const open = await opportunities.list({ status: 'open' });
-const rows = forecast(open); // default: ISO-month buckets
-// [{ bucket: '2026-06', committed: 120_000, weighted: 96_000, count: 1, currency: 'USD' }]
-
-// Custom buckets (quarters, fiscal years, per-team, …):
-forecast(open, { bucket: (o) => quarterOf(o.expectedCloseAt!) });
-
-// Funnel analysis: where do deals die?
-const all = await opportunities.list();
-const conv = pipelineConversion(all, pipeline.stages.map((s) => s.id));
+// Pure analytics over opportunity lists (no I/O):
+const open = await crm.repositories.opportunity.findAll({ status: 'open' }, ctx);
+const rows = forecast(open); // ISO-month buckets: committed / weighted / count
+const conv = pipelineConversion(open, pipeline.stages.map((s) => String(s._id)));
 ```
 
-## Activities + notes (polymorphic)
+## Events catalog (rule 18)
 
-Attach to any entity via `subjectKind` + `subjectId`:
+Every `CRM_EVENTS` constant has a Zod definition in `crmEventDefinitions`,
+exported from the package root and the `./events` subpath:
 
 ```ts
-await activities.plan({
-  type: 'email',
-  subjectKind: 'lead',
-  subjectId: lead.id,
-  subject: 'Follow-up on demo',
-  scheduledAt: new Date('2026-04-20T15:00:00Z'),
-  ownerId: 'ae_1',
-});
-
-// Quick note on an opportunity:
-await activities.addNote({
-  subjectKind: 'opportunity',
-  subjectId: opp.id,
-  body: 'Champion confirmed — legal review starts Monday.',
-  authorId: 'ae_1',
-});
+import { crmEventDefinitions, CRM_EVENTS } from '@classytic/crm/events';
 
-// Pull everything for an entity:
-const allActivities = await activities.listBySubject('opportunity', opp.id);
-const allNotes = await activities.listNotesBySubject('opportunity', opp.id);
+for (const def of crmEventDefinitions) registry.register(def); // arc EventRegistry
 ```
 
-## Events catalog
-
-Subscribe via `EventTransport` from `@classytic/primitives/events`
-(the same contract mirrored from Arc) — Arc's bus, Redis, in-memory,
-Kafka, or any transport implementing that shape works.
-
-| Event | When |
-|---|---|
-| `crm:lead.created` | new lead |
-| `crm:lead.status_changed` | any transition |
-| `crm:lead.scored` | score recomputed |
-| `crm:lead.converted` | spawns Contact + Account + Opportunity |
-| `crm:lead.disqualified` | with reason |
-| `crm:account.created` / `updated` | |
-| `crm:contact.created` / `updated` | |
-| `crm:opportunity.created` | |
-| `crm:opportunity.stage_advanced` | forward motion |
-| `crm:opportunity.stage_regressed` | backward motion (slip) |
-| `crm:opportunity.won` / `lost` / `abandoned` | |
-| `crm:pipeline.created` / `archived` | |
-| `crm:activity.planned` / `completed` / `cancelled` | |
-| `crm:note.added` | |
-
-This event surface is the extension plane — automation tools
-subscribe with globs (`crm:*`, `crm:lead.*`) and do their thing
-without touching the core package.
-
-## Optional outreach bridge
-
-`OutreachPort` is a one-method interface for sending email / SMS /
-social. The package doesn't call it automatically — wire it in your
-automation layer:
+Hosts wire these into arc's `EventRegistry` for publish-time validation and
+OpenAPI introspection. Subscribe glob-style with any arc transport (Memory,
+Redis, Kafka, BullMQ):
 
 ```ts
-import { CRM_EVENTS } from '@classytic/crm';
-
-events.subscribe(CRM_EVENTS.ACTIVITY_PLANNED, async (event) => {
-  const { activityId } = event.payload as { activityId: string };
-  const activity = await activities.findById(activityId);
-  if (activity?.type !== 'email' || !activity.metadata?.toAddress) return;
-  await outreach.send({
-    channel: 'email',
-    toAddress: activity.metadata.toAddress,
-    subject: activity.subject,
-    body: activity.body!,
-    activityId: activity.id,
-  });
-  await activities.complete(activity.id);
-});
+crm.events.subscribe('crm:lead.*',          (e) => routeLead(e));
+crm.events.subscribe('crm:opportunity.won', (e) => createOrder(e));
 ```
 
-`InMemoryOutreachPort` records sends for tests; `NullOutreachPort` is
-a no-op; real integrations wrap SendGrid, Postmark, Twilio, or an
-in-house provider.
+Event families: `crm:lead.*`, `crm:account.*`, `crm:contact.*`,
+`crm:opportunity.*`, `crm:pipeline.*`, `crm:campaign.*`,
+`crm:subscription.*`, `crm:activity.*`, `crm:note.*`, `crm:email_event.*`,
+`crm:conversation.*`, `crm:message.*`.
 
-## What v0.1 does NOT include
+## Production boot
 
-Kept off v0.1 to ship a focused surface — each is small to bolt on
-via the event system:
+```ts
+// Build indexes from a deploy script, not on cold boot (rule 35):
+const crm = await createCrm({ connection, autoIndex: false });
+// once per deploy:
+await crm.syncIndexes();
+```
 
-- Campaigns / sequences (build via activity templates + cron).
-- Territory / team routing (ownership fields are there — use them).
-- Appointment booking (host integrates calendar).
-- Email thread parsing (host integrates inbox).
-- Custom-field schema validation (host owns the `metadata` map).
-- Role-based access control (host owns auth).
-- Audit log (host subscribes to events + persists).
-- Competitor tracking (free-form metadata for now).
-- Contract management (out of scope — use an invoicing package).
+The engine asserts the backend's required capabilities at boot
+(`upsert`, `getOrCreate`, `duplicateKeyError`, and `transactions` unless
+`allowNonTransactional: true`) so a misconfigured deployment fails loud
+instead of mid-convert.
 
-## Architecture
+## What this package does NOT do
 
-```
-src/
-├── index.ts                          ← main barrel
-├── domain/
-│   ├── entities/                     ← Account, Contact, Lead, Opportunity, Pipeline,
-│   │                                    Activity, Note, LossReason
-│   ├── enums/                        ← lead-status, opportunity-status, activity (+ subject-kinds)
-│   ├── ports/                        ← 8 repo ports + OutreachPort + Clock + Ids
-│   └── errors.ts
-├── adapters/in-memory/               ← reference repos + null/recording outreach + events + ids
-├── services/
-│   ├── account.service.ts
-│   ├── activity.service.ts           ← activities + notes
-│   ├── contact.service.ts
-│   ├── lead.service.ts               ← includes convert() — crown-jewel verb
-│   ├── opportunity.service.ts        ← stage movement + win/lose/abandon
-│   ├── pipeline.service.ts
-│   ├── scoring.ts                    ← pure lead scorer + composeScorers
-│   └── forecast.ts                   ← pure forecast() + pipelineConversion()
-└── events/
-    └── event-constants.ts            ← CRM_EVENTS
-```
+- No HTTP routes / auth / RBAC — the host (arc) owns those.
+- No calendar / inbox integration — bridge at the host.
+- No outreach sending — subscribe to `crm:activity.planned` and call your
+  own provider, then `activities.complete(id)`.
+- No custom-field validation — `metadata` is `Record<string, unknown>`.
+- Cross-entity re-pointing on contact merge is the host's job (subscribe to
+  `crm:contact.merged`).
 
 ## Tests
 
-48 tests across unit + integration:
-
 ```bash
-npm test                    # unit + integration (default)
-npm run test:unit
-npm run test:integration
+npm run test:unit          # pure: scoring, forecast, state machines, event-catalog no-drift
+npm test                   # unit + integration (mongodb-memory-server replica set)
 ```
 
-The integration scenario in [tests/integration/lead-to-customer.test.ts](tests/integration/lead-to-customer.test.ts)
-is the MOVEMENTS.md §7 gate: **lead → opportunity → customer end-to-end** —
-walks the full happy path, the lost-path, and the nurture-then-requalify
-path, asserting cross-entity links, event order, and forecast roll-up.
+Integration coverage includes the lead → opportunity → customer scenario,
+opportunity pipeline, subscription DOI, conversation/message threads,
+agentic verbs, multi-tenant isolation, and `invariants.test.ts` (tenant
+probe + lead/subscription dedup races + atomic owner reassignment).
 
 ## License