@classytic/crm 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -124,6 +124,19 @@ interface ILeadStatusEntry {
   by?: string;
   note?: string;
 }
+/**
+ * Behavioural engagement counters — fed by the host from CRM events
+ * (email opens/clicks, inbound replies, logged activities) via
+ * `LeadRepository.recordEngagement`. Read by the lead scorer alongside
+ * the firmographic fields. Zero-valued on old rows (nested default).
+ */
+interface ILeadEngagement {
+  opens: number;
+  clicks: number;
+  replies: number;
+  activities: number;
+  lastEngagedAt?: Date;
+}
 interface ILeadDocument {
   _id: _$mongoose.Types.ObjectId;
   organizationId: _$mongoose.Types.ObjectId | string;
@@ -137,6 +150,7 @@ interface ILeadDocument {
   source?: string;
   campaignRef?: string;
   score: number;
+  engagement: ILeadEngagement;
   status: LeadStatus;
   statusHistory: ILeadStatusEntry[];
   ownerId?: string;
@@ -751,24 +765,29 @@ declare class PipelineRepository extends Repository<IPipelineDocument> {
 }
 //#endregion
 //#region src/shared/calculators/scoring.d.ts
-/** Minimal Lead shape the scorer reads. */
-type LeadInput = Pick<ILeadDocument, 'email' | 'phone' | 'companyName' | 'tags' | 'jobTitle'>;
+/** Minimal Lead shape the scorer reads — firmographic + engagement counters. */
+type LeadInput = Pick<ILeadDocument, 'email' | 'phone' | 'companyName' | 'tags' | 'jobTitle' | 'engagement'>;
 type LeadScorer = (lead: LeadInput) => number;
 /**
  * Reference implementation. Intentionally simple — hosts read it and
- * replace it.
+ * replace it. Deterministic + pure (no I/O, no wall-clock).
  *
- * +20 if email is present
- * +20 if phone is present
- * +20 if companyName is present
- * +10 per populated tag up to 40
- * +10 if jobTitle hints senior (director / manager / head / chief / vp / founder)
+ * Firmographic fit (max 110):
+ *   +20 email · +20 phone · +20 companyName
+ *   +10 per populated tag, up to +40
+ *   +10 if jobTitle hints senior (director/manager/head/chief/vp/founder)
+ *
+ * Behavioural engagement, capped at +80 so a run of opens can't dominate a
+ * genuine reply: reply ×25 · click ×8 · open ×2 · activity ×5. Counters are
+ * fed by the host via `LeadRepository.recordEngagement`; absent on old rows.
  */
 declare function defaultLeadScorer(lead: LeadInput): number;
 /** Compose multiple small rules into one scorer. */
 declare function composeScorers(...rules: readonly LeadScorer[]): LeadScorer;
 //#endregion
 //#region src/repositories/lead.repository.d.ts
+/** Behavioural engagement signals fed via `recordEngagement`. */
+type LeadEngagementSignal = 'open' | 'click' | 'reply' | 'activity';
 interface LeadRepositoryDeps {
   events: CrmEventDispatcher;
   /** Override the default lead scorer. */
@@ -813,6 +832,14 @@ declare class LeadRepository extends Repository<ILeadDocument> {
    * the previous owner so audit consumers can compute hand-off chains.
    */
   assign(id: string, ownerId: string, ctx?: CrmContext): Promise<ILeadDocument>;
+  /**
+   * Record a behavioural engagement signal, then re-score. The host feeds
+   * these off CRM events (`crm:message.received` → reply, `crm:activity.*` →
+   * activity, and email open/click tracking → open/click). Atomic `$inc`
+   * on the counter (single round-trip, no lost-update window under
+   * concurrent signals), then `recomputeScore` re-reads the fresh counters.
+   */
+  recordEngagement(id: string, signal: LeadEngagementSignal, ctx?: CrmContext): Promise<ILeadDocument>;
   /**
    * Recompute + persist the lead's score. Called from `createLead`
    * automatically; hosts also call this after enrichment writes.
@@ -2799,4 +2826,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, 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, 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, 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 };

package/dist/index.js

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./chunk.js";
 import { Schema } from "mongoose";
-import { Repository, aggregateHelpersPlugin, isDuplicateKeyError, methodRegistryPlugin, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
+import { Repository, aggregateHelpersPlugin, appendOnlyPlugin, isDuplicateKeyError, methodRegistryPlugin, multiTenantPlugin, withTransaction } from "@classytic/mongokit";
 import { createEvent as createEvent$1, matchEventPattern } from "@classytic/primitives/events";
-import { IllegalTransitionError, assertAndClaim, defineStateMachine } from "@classytic/primitives/state-machine";
+import { IllegalTransitionError, defineStateMachine } from "@classytic/primitives/state-machine";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { civilDateOf } from "@classytic/primitives/timezone";
@@ -292,6 +292,25 @@ const statusEntrySchema$5 = new Schema({
 	by: { type: String },
 	note: { type: String }
 }, { _id: false });
+const engagementSchema = new Schema({
+	opens: {
+		type: Number,
+		default: 0
+	},
+	clicks: {
+		type: Number,
+		default: 0
+	},
+	replies: {
+		type: Number,
+		default: 0
+	},
+	activities: {
+		type: Number,
+		default: 0
+	},
+	lastEngagedAt: { type: Date }
+}, { _id: false });
 function buildLeadSchema(config) {
 	const schema = new Schema({
 		organizationId: tenantFieldDef(config),
@@ -346,6 +365,10 @@ function buildLeadSchema(config) {
 			type: Number,
 			default: 0
 		},
+		engagement: {
+			type: engagementSchema,
+			default: () => ({})
+		},
 		status: {
 			type: String,
 			enum: LEAD_STATUSES,
@@ -2240,13 +2263,16 @@ const ENROLLMENT_MACHINE = defineStateMachine({
 //#region src/shared/calculators/scoring.ts
 /**
 * Reference implementation. Intentionally simple — hosts read it and
-* replace it.
+* replace it. Deterministic + pure (no I/O, no wall-clock).
 *
-* +20 if email is present
-* +20 if phone is present
-* +20 if companyName is present
-* +10 per populated tag up to 40
-* +10 if jobTitle hints senior (director / manager / head / chief / vp / founder)
+* Firmographic fit (max 110):
+*   +20 email · +20 phone · +20 companyName
+*   +10 per populated tag, up to +40
+*   +10 if jobTitle hints senior (director/manager/head/chief/vp/founder)
+*
+* Behavioural engagement, capped at +80 so a run of opens can't dominate a
+* genuine reply: reply ×25 · click ×8 · open ×2 · activity ×5. Counters are
+* fed by the host via `LeadRepository.recordEngagement`; absent on old rows.
 */
 function defaultLeadScorer(lead) {
 	let score = 0;
@@ -2255,6 +2281,11 @@ function defaultLeadScorer(lead) {
 	if (lead.companyName) score += 20;
 	score += Math.min(40, (lead.tags?.length ?? 0) * 10);
 	if (lead.jobTitle && /(director|manager|head|chief|vp|founder)/i.test(lead.jobTitle)) score += 10;
+	const e = lead.engagement;
+	if (e) {
+		const engagementPoints = (e.replies ?? 0) * 25 + (e.clicks ?? 0) * 8 + (e.opens ?? 0) * 2 + (e.activities ?? 0) * 5;
+		score += Math.min(80, engagementPoints);
+	}
 	return score;
 }
 /** Compose multiple small rules into one scorer. */
@@ -2262,7 +2293,27 @@ function composeScorers(...rules) {
 	return (lead) => rules.reduce((acc, r) => acc + r(lead), 0);
 }
 //#endregion
+//#region src/repositories/transition-support.ts
+/**
+* mongokit `applyTransition()` race-outcome detection — pure races /
+* vanished rows remap to each verb's historical error (typed transition
+* error built from a fresh read, or NotFound where that was the
+* contract); now-illegal races throw the machine's errorFactory error
+* with the on-disk status natively.
+*/
+function isTransitionRace(err) {
+	const code = err?.code;
+	return code === "TRANSITION_RACE_LOST" || code === "TRANSITION_TARGET_MISSING";
+}
+//#endregion
 //#region src/repositories/lead.repository.ts
+/** signal → engagement counter field. */
+const ENGAGEMENT_COUNTER = {
+	open: "opens",
+	click: "clicks",
+	reply: "replies",
+	activity: "activities"
+};
 var LeadRepository = class extends Repository {
 	events;
 	scorer;
@@ -2383,6 +2434,20 @@ var LeadRepository = class extends Repository {
 		return await this.getById(id, ctx) ?? before;
 	}
 	/**
+	* Record a behavioural engagement signal, then re-score. The host feeds
+	* these off CRM events (`crm:message.received` → reply, `crm:activity.*` →
+	* activity, and email open/click tracking → open/click). Atomic `$inc`
+	* on the counter (single round-trip, no lost-update window under
+	* concurrent signals), then `recomputeScore` re-reads the fresh counters.
+	*/
+	async recordEngagement(id, signal, ctx) {
+		if (!await this.findOneAndUpdate({ _id: id }, {
+			$inc: { [`engagement.${ENGAGEMENT_COUNTER[signal]}`]: 1 },
+			$set: { "engagement.lastEngagedAt": /* @__PURE__ */ new Date() }
+		}, ctx)) throw new NotFoundError("Lead", id);
+		return this.recomputeScore(id, ctx);
+	}
+	/**
 	* Recompute + persist the lead's score. Called from `createLead`
 	* automatically; hosts also call this after enrichment writes.
 	*/
@@ -2409,19 +2474,19 @@ var LeadRepository = class extends Repository {
 			...extras.by !== void 0 ? { by: extras.by } : {},
 			...extras.note !== void 0 ? { note: extras.note } : {}
 		};
-		const updated = await assertAndClaim(LEAD_MACHINE, this, id, {
+		const updated = await this.applyTransition(id, LEAD_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch: {
-				...extras.patch ?? {},
-				statusHistory: [...existing.statusHistory ?? [], entry]
-			},
-			options: ctx
-		});
-		if (!updated) throw new InvalidLeadTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			leadId: id
+			set: extras.patch ?? {},
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidLeadTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				leadId: id
+			});
 		});
 		await this.events.dispatch(ctx, createEvent(CRM_EVENTS.LEAD_STATUS_CHANGED, {
 			leadId: id,
@@ -2667,7 +2732,6 @@ var OpportunityRepository = class extends Repository {
 	async _closeStatus(id, target, patch, extras, ctx) {
 		const existing = await this.getById(id, ctx);
 		if (!existing) throw new NotFoundError("Opportunity", id);
-		OPPORTUNITY_MACHINE.assertTransition(id, existing.status, target);
 		const entry = {
 			status: target,
 			stageId: existing.stageId,
@@ -2675,21 +2739,20 @@ var OpportunityRepository = class extends Repository {
 			...extras.by !== void 0 ? { by: extras.by } : {},
 			...extras.note !== void 0 ? { note: extras.note } : {}
 		};
-		const updated = await assertAndClaim(OPPORTUNITY_MACHINE, this, id, {
+		return await this.applyTransition(id, OPPORTUNITY_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch: {
-				...patch,
-				statusHistory: [...existing.statusHistory ?? [], entry]
-			},
-			options: ctx
-		});
-		if (!updated) throw new InvalidOpportunityTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			opportunityId: id
+			set: patch,
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidOpportunityTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				opportunityId: id
+			});
 		});
-		return updated;
 	}
 	/** Count opportunities with status `open`. Used by dashboard KPI tiles. */
 	async countOpen(ctx) {
@@ -3023,28 +3086,26 @@ var CampaignRepository = class extends Repository {
 	async _transition(id, target, extras, ctx, patch = {}) {
 		const existing = await this.getById(id, ctx);
 		if (!existing) throw new NotFoundError("Campaign", id);
-		CAMPAIGN_MACHINE.assertTransition(id, existing.status, target);
 		const entry = {
 			status: target,
 			occurredAt: /* @__PURE__ */ new Date(),
 			...extras.by !== void 0 ? { by: extras.by } : {},
 			...extras.note !== void 0 ? { note: extras.note } : {}
 		};
-		const updated = await assertAndClaim(CAMPAIGN_MACHINE, this, id, {
+		return await this.applyTransition(id, CAMPAIGN_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch: {
-				...patch,
-				statusHistory: [...existing.statusHistory ?? [], entry]
-			},
-			options: ctx
-		});
-		if (!updated) throw new InvalidCampaignTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			campaignId: id
+			set: patch,
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidCampaignTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				campaignId: id
+			});
 		});
-		return updated;
 	}
 };
 //#endregion
@@ -3185,28 +3246,26 @@ var SubscriptionRepository = class extends Repository {
 	async _transition(id, target, opts, ctx) {
 		const existing = await this.getById(id, ctx);
 		if (!existing) throw new NotFoundError("Subscription", id);
-		SUBSCRIPTION_MACHINE.assertTransition(id, existing.status, target);
 		const entry = {
 			status: target,
 			occurredAt: /* @__PURE__ */ new Date(),
 			...opts.by !== void 0 ? { by: opts.by } : {},
 			...opts.note !== void 0 ? { note: opts.note } : {}
 		};
-		const updated = await assertAndClaim(SUBSCRIPTION_MACHINE, this, id, {
+		return await this.applyTransition(id, SUBSCRIPTION_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch: {
-				...opts.patch ?? {},
-				statusHistory: [...existing.statusHistory ?? [], entry]
-			},
-			options: ctx
-		});
-		if (!updated) throw new InvalidSubscriptionTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			subscriptionId: id
+			set: opts.patch ?? {},
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidSubscriptionTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				subscriptionId: id
+			});
 		});
-		return updated;
 	}
 };
 //#endregion
@@ -3375,19 +3434,19 @@ var ActivityRepository = class extends Repository {
 	async _transition(id, target, patch, ctx) {
 		const existing = await this.getById(id, ctx);
 		if (!existing) throw new NotFoundError("Activity", id);
-		ACTIVITY_MACHINE.assertTransition(id, existing.status, target);
-		const updated = await assertAndClaim(ACTIVITY_MACHINE, this, id, {
+		return await this.applyTransition(id, ACTIVITY_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch,
-			options: ctx
-		});
-		if (!updated) throw new InvalidActivityTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			activityId: id
+			set: patch,
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidActivityTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				activityId: id
+			});
 		});
-		return updated;
 	}
 	/** Count `planned` activities with `dueDate` before `asOf`. Dashboard KPI. */
 	async countOverduePlanned(asOf, ctx) {
@@ -3458,7 +3517,7 @@ const KIND_TO_EVENT = {
 var EmailEventRepository = class extends Repository {
 	events;
 	constructor(model, plugins, deps, pagination) {
-		super(model, plugins, pagination);
+		super(model, [...plugins, appendOnlyPlugin({ allow: ["deleteMany"] })], pagination);
 		this.events = deps.events;
 	}
 	async recordOpen(input, ctx) {
@@ -3683,24 +3742,24 @@ var SequenceRepository = class extends Repository {
 	async _transition(id, target, ctx) {
 		const existing = await this.getById(id, ctx);
 		if (!existing) throw new NotFoundError("Sequence", id);
-		SEQUENCE_MACHINE.assertTransition(id, existing.status, target);
 		const entry = {
 			status: target,
 			occurredAt: /* @__PURE__ */ new Date(),
 			...ctx?.actorId !== void 0 ? { by: String(ctx.actorId) } : {}
 		};
-		const updated = await assertAndClaim(SEQUENCE_MACHINE, this, id, {
+		return await this.applyTransition(id, SEQUENCE_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch: { statusHistory: [...existing.statusHistory ?? [], entry] },
-			options: ctx
-		});
-		if (!updated) throw new InvalidSequenceTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			sequenceId: id
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidSequenceTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				sequenceId: id
+			});
 		});
-		return updated;
 	}
 };
 //#endregion
@@ -3787,16 +3846,16 @@ var EnrollmentRepository = class extends Repository {
 			occurredAt: /* @__PURE__ */ new Date(),
 			...ctx?.actorId ? { by: String(ctx.actorId) } : {}
 		};
-		const updated = await assertAndClaim(ENROLLMENT_MACHINE, this, id, {
+		const updated = await this.applyTransition(id, ENROLLMENT_MACHINE, {
 			from,
 			to: "exited",
-			patch: {
-				exitReason,
-				statusHistory: [...existing.statusHistory ?? [], entry]
-			},
-			options: ctx
+			set: { exitReason },
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch((err) => {
+			if (isTransitionRace(err)) throw new NotFoundError("Enrollment", id);
+			throw err;
 		});
-		if (!updated) throw new NotFoundError("Enrollment", id);
 		await this.events.dispatch(ctx, createEvent(CRM_EVENTS.ENROLLMENT_EXITED, {
 			enrollmentId: id,
 			exitReason
@@ -3855,27 +3914,25 @@ var EnrollmentRepository = class extends Repository {
 	async _transition(id, target, ctx, patch = {}) {
 		const existing = await this.getById(id, ctx);
 		if (!existing) throw new NotFoundError("Enrollment", id);
-		ENROLLMENT_MACHINE.assertTransition(id, existing.status, target);
 		const entry = {
 			status: target,
 			occurredAt: /* @__PURE__ */ new Date(),
 			...ctx?.actorId ? { by: String(ctx.actorId) } : {}
 		};
-		const updated = await assertAndClaim(ENROLLMENT_MACHINE, this, id, {
+		return await this.applyTransition(id, ENROLLMENT_MACHINE, {
 			from: existing.status,
 			to: target,
-			patch: {
-				...patch,
-				statusHistory: [...existing.statusHistory ?? [], entry]
-			},
-			options: ctx
-		});
-		if (!updated) throw new InvalidEnrollmentTransitionError({
-			from: (await this.getById(id, ctx))?.status ?? existing.status,
-			to: target,
-			enrollmentId: id
+			set: patch,
+			push: { statusHistory: entry },
+			history: false
+		}, ctx).catch(async (err) => {
+			if (!isTransitionRace(err)) throw err;
+			throw new InvalidEnrollmentTransitionError({
+				from: (await this.getById(id, ctx))?.status ?? existing.status,
+				to: target,
+				enrollmentId: id
+			});
 		});
-		return updated;
 	}
 };
 //#endregion