ts-patch-mongoose 3.0.0 → 3.1.0

package/tests/plugin-complex-data.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import mongoose, { model, Schema } from 'mongoose'
+import em from '../src/em'
 import { patchHistoryPlugin } from '../src/index'
 import { HistoryModel } from '../src/model'
 import server from './mongo/server'
@@ -554,6 +555,10 @@ describe('plugin — complex data structures', () => {
 
 // --- All mongoose schema types ---
 
+const hasDouble = 'Double' in Schema.Types
+const hasInt32 = 'Int32' in Schema.Types
+const hasBigInt = 'BigInt' in Schema.Types
+
 const AllTypesSchema = new Schema(
   {
     str: String,
@@ -575,6 +580,141 @@ const AllTypesSchema = new Schema(
   { timestamps: true },
 )
 
+if (hasDouble) AllTypesSchema.add({ dbl: (Schema.Types as Record<string, unknown>).Double })
+if (hasInt32) AllTypesSchema.add({ int32: (Schema.Types as Record<string, unknown>).Int32 })
+if (hasBigInt) AllTypesSchema.add({ bigint: (Schema.Types as Record<string, unknown>).BigInt })
+
+// --- Realistic SaaS Organization model (e2e) ---
+
+const ContactSchema = new Schema(
+  {
+    email: { type: String, required: true },
+    phone: String,
+    website: String,
+  },
+  { _id: false },
+)
+
+const BillingSchema = new Schema(
+  {
+    plan: { type: String, enum: ['free', 'starter', 'pro', 'enterprise'], default: 'free' },
+    mrr: Schema.Types.Decimal128,
+    currency: { type: String, default: 'USD' },
+    cardLast4: String,
+    nextBillingDate: Date,
+  },
+  { _id: false },
+)
+
+const TeamMemberSchema = new Schema(
+  {
+    userId: { type: Schema.Types.ObjectId, required: true },
+    role: { type: String, enum: ['owner', 'admin', 'member', 'viewer'], required: true },
+    joinedAt: { type: Date, default: Date.now },
+  },
+  { _id: true },
+)
+
+const HeadquartersSchema = new Schema(
+  {
+    street: String,
+    city: String,
+    state: String,
+    zip: String,
+    country: { type: String, default: 'US' },
+    coords: { lat: Number, lng: Number },
+    timezone: String,
+  },
+  { _id: false },
+)
+
+interface Contact {
+  email: string
+  phone?: string
+  website?: string
+}
+
+interface Billing {
+  plan: string
+  mrr?: mongoose.Types.Decimal128
+  currency: string
+  cardLast4?: string
+  nextBillingDate?: Date
+}
+
+interface TeamMember {
+  userId: mongoose.Types.ObjectId
+  role: string
+  joinedAt?: Date
+}
+
+interface Headquarters {
+  street?: string
+  city?: string
+  state?: string
+  zip?: string
+  country?: string
+  coords?: { lat: number; lng: number }
+  timezone?: string
+}
+
+interface Organization {
+  name: string
+  slug: string
+  apiKey: mongoose.Types.UUID
+  active: boolean
+  contact: Contact
+  billing: Billing
+  headquarters: Headquarters
+  team: TeamMember[]
+  tags: string[]
+  domains: string[]
+  settings: Map<string, string>
+  featureFlags: Record<string, unknown>
+  logo?: Buffer
+  notes: string
+  seatCount: number
+  createdAt?: Date
+  updatedAt?: Date
+}
+
+const OrganizationSchema = new Schema<Organization>(
+  {
+    name: { type: String, required: true },
+    slug: { type: String, required: true, unique: true },
+    apiKey: { type: Schema.Types.UUID, required: true },
+    active: { type: Boolean, default: true },
+    contact: { type: ContactSchema, required: true },
+    billing: { type: BillingSchema, default: () => ({}) },
+    headquarters: HeadquartersSchema,
+    team: [TeamMemberSchema],
+    tags: [String],
+    domains: [String],
+    settings: { type: Map, of: String },
+    featureFlags: { type: Schema.Types.Mixed, default: {} },
+    logo: Buffer,
+    notes: String,
+    seatCount: { type: Number, default: 1 },
+  },
+  { timestamps: true },
+)
+
+const ORG_CREATED = 'org-created'
+const ORG_UPDATED = 'org-updated'
+const ORG_DELETED = 'org-deleted'
+
+OrganizationSchema.plugin(patchHistoryPlugin, {
+  eventCreated: ORG_CREATED,
+  eventUpdated: ORG_UPDATED,
+  eventDeleted: ORG_DELETED,
+  omit: ['__v', 'createdAt', 'updatedAt', 'notes'],
+  getUser: () => ({ userId: 'system', role: 'service-account' }),
+  getReason: () => 'api-call',
+  getMetadata: () => ({ service: 'org-service', requestId: 'req-123' }),
+})
+
+const OrganizationModel = model<Organization>('Organization', OrganizationSchema)
+
 AllTypesSchema.plugin(patchHistoryPlugin, {
   omit: ['__v', 'createdAt', 'updatedAt'],
 })
@@ -793,6 +933,31 @@ describe('plugin — all mongoose schema types', () => {
     expect(paths).toContain('/str')
     expect(paths).toContain('/num')
   })
+
+  it.runIf(hasDouble)('should track Double update', async () => {
+    const doc = await AllTypesModel.create({ dbl: 3.14 })
+    await AllTypesModel.updateOne({ _id: doc._id }, { dbl: 2.71 }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: doc._id })
+    expect(getPatch(update, '/dbl')?.value).toBe(2.71)
+  })
+
+  it.runIf(hasInt32)('should track Int32 update', async () => {
+    const doc = await AllTypesModel.create({ int32: 100 })
+    await AllTypesModel.updateOne({ _id: doc._id }, { int32: 200 }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: doc._id })
+    expect(getPatch(update, '/int32')?.value).toBe(200)
+  })
+
+  it.runIf(hasBigInt)('should track BigInt update', async () => {
+    const doc = await AllTypesModel.create({ bigint: BigInt(1000) })
+    await AllTypesModel.updateOne({ _id: doc._id }, { bigint: BigInt(9999) }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: doc._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/bigint'))).toBe(true)
+  })
 })
 
 // --- Populated documents ---
@@ -1330,3 +1495,1153 @@ describe('plugin — replaceOne', () => {
     expect(paths.some((p) => p?.includes('/shippingAddress'))).toBe(true)
   })
 })
+
+// --- Organization e2e lifecycle ---
+
+describe('plugin — organization e2e lifecycle', () => {
+  const instance = server('plugin-org-e2e')
+
+  beforeAll(async () => {
+    await instance.create()
+  })
+
+  afterAll(async () => {
+    await instance.destroy()
+  })
+
+  beforeEach(async () => {
+    await mongoose.connection.collection('organizations').deleteMany({})
+    await mongoose.connection.collection('history').deleteMany({})
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  const makeOrg = () => ({
+    name: 'Acme Corp',
+    slug: `acme-${Date.now()}`,
+    apiKey: '550e8400-e29b-41d4-a716-446655440000',
+    active: true,
+    contact: { email: 'admin@acme.com', phone: '+1-555-0100', website: 'https://acme.com' },
+    billing: {
+      plan: 'pro' as const,
+      mrr: mongoose.Types.Decimal128.fromString('499.00'),
+      currency: 'USD',
+      cardLast4: '4242',
+      nextBillingDate: new Date('2026-05-01'),
+    },
+    headquarters: {
+      street: '100 Innovation Dr',
+      city: 'San Francisco',
+      state: 'CA',
+      zip: '94105',
+      country: 'US',
+      coords: { lat: 37.7749, lng: -122.4194 },
+      timezone: 'America/Los_Angeles',
+    },
+    team: [
+      { userId: new mongoose.Types.ObjectId(), role: 'owner' },
+      { userId: new mongoose.Types.ObjectId(), role: 'admin' },
+      { userId: new mongoose.Types.ObjectId(), role: 'member' },
+    ],
+    tags: ['saas', 'enterprise', 'active'],
+    domains: ['acme.com', 'acme.io'],
+    settings: new Map([
+      ['theme', 'dark'],
+      ['locale', 'en-US'],
+      ['notifications', 'enabled'],
+    ]),
+    featureFlags: { betaDashboard: true, newBilling: false, aiAssistant: { enabled: true, model: 'claude' } },
+    logo: Buffer.from('fake-png-data'),
+    notes: 'Internal: VIP customer, handle with care',
+    seatCount: 25,
+  })
+
+  it('should create organization and record full history', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    const history = await HistoryModel.find({ collectionId: org._id })
+    expect(history).toHaveLength(1)
+
+    const [entry] = history
+    expect(entry?.op).toBe('create')
+    expect(entry?.version).toBe(0)
+
+    const doc = entry?.doc as Record<string, unknown>
+    expect(doc.name).toBe('Acme Corp')
+    expect(doc.active).toBe(true)
+    expect(doc.contact).toHaveProperty('email', 'admin@acme.com')
+    expect(doc.billing).toHaveProperty('plan', 'pro')
+    expect(doc.billing).toHaveProperty('cardLast4', '4242')
+    expect(doc.headquarters).toHaveProperty('city', 'San Francisco')
+    expect((doc.headquarters as Record<string, unknown>).coords).toHaveProperty('lat', 37.7749)
+    expect((doc.team as unknown[]).length).toBe(3)
+    expect(doc.tags).toEqual(['saas', 'enterprise', 'active'])
+    expect(doc.domains).toEqual(['acme.com', 'acme.io'])
+    expect(doc.settings).toBeDefined()
+    expect(doc.featureFlags).toHaveProperty('betaDashboard', true)
+    expect(doc.logo).toBeDefined()
+    expect(doc.seatCount).toBe(25)
+    expect(doc).not.toHaveProperty('notes')
+    expect(doc).not.toHaveProperty('__v')
+    expect(doc).not.toHaveProperty('createdAt')
+  })
+
+  it('should track billing plan upgrade via save', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    org.billing.plan = 'enterprise'
+    org.billing.mrr = mongoose.Types.Decimal128.fromString('1299.00')
+    org.seatCount = 100
+    await org.save()
+
+    const updates = await HistoryModel.find({ op: 'update', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.includes('/billing'))).toBe(true)
+    expect(paths).toContain('/seatCount')
+  })
+
+  it('should track team member changes via updateOne', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    const newMember = { userId: new mongoose.Types.ObjectId(), role: 'viewer' }
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $push: { team: newMember } }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/team'))).toBe(true)
+  })
+
+  it('should track featureFlags Mixed and settings Map changes', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    org.featureFlags = { betaDashboard: true, newBilling: true, aiAssistant: { enabled: true, model: 'opus' } }
+    org.settings.set('theme', 'light')
+    org.settings.set('newKey', 'newVal')
+    await org.save()
+
+    const updates = await HistoryModel.find({ op: 'update', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+
+    const paths = (updates[0]?.patch ?? []).map((p) => p.path ?? '')
+    expect(paths.some((p) => p.includes('featureFlags'))).toBe(true)
+    expect(paths.some((p) => p.includes('settings'))).toBe(true)
+  })
+
+  it('should track headquarters relocation via findOneAndUpdate', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.findOneAndUpdate(
+      { _id: org._id },
+      {
+        headquarters: {
+          street: '1 Austin Blvd',
+          city: 'Austin',
+          state: 'TX',
+          zip: '73301',
+          country: 'US',
+          coords: { lat: 30.2672, lng: -97.7431 },
+          timezone: 'America/Chicago',
+        },
+      },
+    ).exec()
+
+    const updates = await HistoryModel.find({ op: 'findOneAndUpdate', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.includes('/headquarters'))).toBe(true)
+  })
+
+  it('should track domain and tag array changes', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $addToSet: { domains: 'acme.dev' }, $pull: { tags: 'active' } }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/domains'))).toBe(true)
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+  })
+
+  it('should track deactivation and record deletion', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { active: false }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+    expect(getPatch(updates[0], '/active')?.value).toBe(false)
+
+    await OrganizationModel.deleteOne({ _id: org._id }).exec()
+
+    const allHistory = await HistoryModel.find({ collectionId: org._id }).sort('createdAt')
+    expect(allHistory.length).toBe(3)
+    expect(allHistory[0]?.op).toBe('create')
+    expect(allHistory[1]?.op).toBe('updateOne')
+    expect(allHistory[2]?.op).toBe('deleteOne')
+    expect(allHistory[2]?.doc).toHaveProperty('name', 'Acme Corp')
+    expect(allHistory[2]?.doc).not.toHaveProperty('notes')
+  })
+
+  it('should handle full lifecycle: create → multiple updates → delete with version tracking', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    org.name = 'Acme Inc'
+    org.contact.email = 'hello@acme.io'
+    await org.save()
+
+    org.billing.plan = 'enterprise'
+    org.seatCount = 200
+    await org.save()
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $addToSet: { tags: 'flagship' } }).exec()
+
+    await OrganizationModel.deleteOne({ _id: org._id }).exec()
+
+    const history = await HistoryModel.find({ collectionId: org._id }).sort('createdAt')
+    expect(history.length).toBe(5)
+
+    expect(history[0]?.op).toBe('create')
+    expect(history[0]?.version).toBe(0)
+
+    expect(history[1]?.op).toBe('update')
+    expect(history[1]?.version).toBe(1)
+
+    expect(history[2]?.op).toBe('update')
+    expect(history[2]?.version).toBe(2)
+
+    expect(history[3]?.op).toBe('updateOne')
+    expect(history[3]?.version).toBe(3)
+
+    expect(history[4]?.op).toBe('deleteOne')
+  })
+
+  it('should track insertMany with history for each document', async () => {
+    await OrganizationModel.insertMany([
+      { ...makeOrg(), slug: `bulk-a-${Date.now()}`, name: 'Bulk A' },
+      { ...makeOrg(), slug: `bulk-b-${Date.now()}`, name: 'Bulk B' },
+      { ...makeOrg(), slug: `bulk-c-${Date.now()}`, name: 'Bulk C' },
+    ])
+
+    const history = await HistoryModel.find({ op: 'create' }).sort('doc.name')
+    expect(history).toHaveLength(3)
+
+    for (const entry of history) {
+      expect(entry.version).toBe(0)
+      expect(entry.doc).toHaveProperty('name')
+      expect(entry.doc).toHaveProperty('apiKey')
+      expect(entry.doc).not.toHaveProperty('notes')
+      expect(entry.doc).not.toHaveProperty('__v')
+    }
+
+    const names = history.map((h) => (h.doc as Record<string, unknown>).name)
+    expect(names).toContain('Bulk A')
+    expect(names).toContain('Bulk B')
+    expect(names).toContain('Bulk C')
+  })
+
+  it('should track updateMany across multiple organizations', async () => {
+    await OrganizationModel.create({ ...makeOrg(), slug: `many-a-${Date.now()}`, tags: ['region-eu'] })
+    await OrganizationModel.create({ ...makeOrg(), slug: `many-b-${Date.now()}`, tags: ['region-eu'] })
+    await OrganizationModel.create({ ...makeOrg(), slug: `many-c-${Date.now()}`, tags: ['region-us'] })
+
+    await OrganizationModel.updateMany({ tags: 'region-eu' }, { $set: { active: false } }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateMany' })
+    expect(updates).toHaveLength(2)
+
+    for (const entry of updates) {
+      expect(entry.patch?.length).toBeGreaterThan(0)
+      const paths = entry.patch?.map((p) => p.path) ?? []
+      expect(paths).toContain('/active')
+    }
+  })
+
+  it('should track findByIdAndUpdate (mongoose normalizes op to findOneAndUpdate)', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.findByIdAndUpdate(org._id, { name: 'Acme Renamed' }).exec()
+
+    const updates = await HistoryModel.find({ collectionId: org._id, version: { $gt: 0 } })
+    expect(updates).toHaveLength(1)
+    expect(updates[0]?.op).toBe('findOneAndUpdate')
+    expect(updates[0]?.patch?.find((p) => p.path === '/name' && p.op === 'replace')?.value).toBe('Acme Renamed')
+  })
+
+  it('should track findOneAndReplace with full document swap', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    const replacement = makeOrg()
+    replacement.name = 'Replaced Corp'
+    replacement.slug = org.slug
+    replacement.billing.plan = 'enterprise'
+    replacement.seatCount = 500
+
+    await OrganizationModel.findOneAndReplace({ _id: org._id }, replacement).exec()
+
+    const updates = await HistoryModel.find({ op: 'findOneAndReplace', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+    expect(updates[0]?.patch?.length).toBeGreaterThan(0)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths).toContain('/name')
+    expect(paths.some((p) => p?.includes('/billing'))).toBe(true)
+    expect(paths).toContain('/seatCount')
+  })
+
+  it('should track replaceOne', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    const replacement = makeOrg()
+    replacement.name = 'ReplaceOne Corp'
+    replacement.slug = org.slug
+    replacement.active = false
+
+    await OrganizationModel.replaceOne({ _id: org._id }, replacement).exec()
+
+    const updates = await HistoryModel.find({ op: 'replaceOne', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+    expect(updates[0]?.patch?.length).toBeGreaterThan(0)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths).toContain('/name')
+    expect(paths).toContain('/active')
+  })
+
+  it('should track findOneAndDelete with full document snapshot', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.findOneAndDelete({ _id: org._id }).exec()
+
+    const history = await HistoryModel.find({ collectionId: org._id }).sort('createdAt')
+    expect(history).toHaveLength(2)
+
+    const deletion = history[1]
+    expect(deletion?.op).toBe('findOneAndDelete')
+    expect(deletion?.doc).toHaveProperty('name', 'Acme Corp')
+    expect(deletion?.doc).toHaveProperty('billing')
+    expect(deletion?.doc).toHaveProperty('team')
+    expect(deletion?.doc).not.toHaveProperty('notes')
+  })
+
+  it('should track findByIdAndDelete (mongoose normalizes op to findOneAndDelete)', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.findByIdAndDelete(org._id).exec()
+
+    const history = await HistoryModel.find({ collectionId: org._id }).sort('createdAt')
+    expect(history).toHaveLength(2)
+
+    expect(history[1]?.op).toBe('findOneAndDelete')
+    expect(history[1]?.doc).toHaveProperty('name', 'Acme Corp')
+    expect(history[1]?.doc).toHaveProperty('contact')
+    expect(history[1]?.doc).not.toHaveProperty('notes')
+  })
+
+  it('should track deleteMany with snapshots for all deleted documents', async () => {
+    await OrganizationModel.create({ ...makeOrg(), slug: `del-a-${Date.now()}`, name: 'Del A', tags: ['sunset'] })
+    await OrganizationModel.create({ ...makeOrg(), slug: `del-b-${Date.now()}`, name: 'Del B', tags: ['sunset'] })
+    await OrganizationModel.create({ ...makeOrg(), slug: `del-c-${Date.now()}`, name: 'Del C', tags: ['keep'] })
+
+    await OrganizationModel.deleteMany({ tags: 'sunset' }).exec()
+
+    const deletions = await HistoryModel.find({ op: 'deleteMany' })
+    expect(deletions).toHaveLength(2)
+
+    const names = deletions.map((d) => (d.doc as Record<string, unknown>).name)
+    expect(names).toContain('Del A')
+    expect(names).toContain('Del B')
+
+    for (const entry of deletions) {
+      expect(entry.doc).toHaveProperty('contact')
+      expect(entry.doc).toHaveProperty('billing')
+      expect(entry.doc).not.toHaveProperty('notes')
+    }
+  })
+
+  it('should track upsert creating a new organization', async () => {
+    const slug = `upsert-new-${Date.now()}`
+
+    await OrganizationModel.findOneAndUpdate(
+      { slug },
+      {
+        name: 'Upserted Corp',
+        slug,
+        apiKey: '660e8400-e29b-41d4-a716-446655440000',
+        contact: { email: 'upsert@test.com' },
+        seatCount: 5,
+      },
+      { upsert: true },
+    ).exec()
+
+    const docs = await OrganizationModel.find({ slug })
+    expect(docs).toHaveLength(1)
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(1)
+    expect(history[0]?.op).toBe('findOneAndUpdate')
+    expect(history[0]?.doc).toHaveProperty('name', 'Upserted Corp')
+  })
+
+  it('should track upsert updating an existing organization', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.findOneAndUpdate({ slug: org.slug }, { $set: { seatCount: 999 } }, { upsert: true }).exec()
+
+    const updates = await HistoryModel.find({ op: 'findOneAndUpdate', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+
+    const paths = updates[0]?.patch?.map((p) => p.path) ?? []
+    expect(paths).toContain('/seatCount')
+  })
+
+  // --- $ modifier operators ---
+
+  it('$set — should track field replacement', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $set: { name: 'Set Corp', 'contact.phone': '+1-555-9999' } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths).toContain('/name')
+    expect(paths.some((p) => p?.includes('/contact'))).toBe(true)
+  })
+
+  it('$unset — should track field removal', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $unset: { logo: '' } }).exec()
+
+    const current = await OrganizationModel.findById(org._id).lean().exec()
+    expect(current?.logo).toBeUndefined()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(update).toBeDefined()
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.includes('/logo'))).toBe(true)
+  })
+
+  it('$inc — should track numeric increment with correct post-update value', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    expect(org.seatCount).toBe(25)
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $inc: { seatCount: 10 } }).exec()
+
+    const current = await OrganizationModel.findById(org._id).lean().exec()
+    expect(current?.seatCount).toBe(35)
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(update).toBeDefined()
+    const seatPatch = update?.patch?.find((p) => p.path === '/seatCount' && p.op === 'replace')
+    expect(seatPatch?.value).toBe(35)
+  })
+
+  it('$mul — should track numeric multiply with correct post-update value', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $mul: { seatCount: 2 } }).exec()
+
+    const current = await OrganizationModel.findById(org._id).lean().exec()
+    expect(current?.seatCount).toBe(50)
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(update).toBeDefined()
+    const seatPatch = update?.patch?.find((p) => p.path === '/seatCount' && p.op === 'replace')
+    expect(seatPatch?.value).toBe(50)
+  })
+
+  it('$min — should track conditional numeric update', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $min: { seatCount: 5 } }).exec()
+
+    const current = await OrganizationModel.findById(org._id).lean().exec()
+    expect(current?.seatCount).toBe(5)
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(update).toBeDefined()
+    const seatPatch = update?.patch?.find((p) => p.path === '/seatCount' && p.op === 'replace')
+    expect(seatPatch?.value).toBe(5)
+  })
+
+  it('$pullAll — should track multiple array element removals', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $pullAll: { tags: ['saas', 'enterprise'] } }).exec()
+
+    const current = await OrganizationModel.findById(org._id).lean().exec()
+    expect(current?.tags).toEqual(['active'])
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(update).toBeDefined()
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+  })
+
+  it('$push — should track array element addition', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $push: { tags: 'new-tag' } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+  })
+
+  it('$push with $each — should track multiple array additions', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $push: { domains: { $each: ['acme.dev', 'acme.ai'] } } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/domains'))).toBe(true)
+  })
+
+  it('$addToSet — should track unique array addition', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $addToSet: { tags: 'unique-tag' } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+  })
+
+  it('$pull — should track array element removal', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $pull: { tags: 'enterprise' } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+  })
+
+  it('$pop — should track removal of last array element', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $pop: { tags: 1 } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+  })
+
+  it('$rename — should track field rename', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $rename: { 'contact.phone': 'contact.mobile' } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.includes('/contact'))).toBe(true)
+  })
+
+  it('$currentDate — should track date set to now', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $currentDate: { 'billing.nextBillingDate': true } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.includes('/billing'))).toBe(true)
+  })
+
+  it('combined $set + $inc + $push — should track all operators with correct values', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne(
+      { _id: org._id },
+      {
+        $set: { name: 'Combined Corp', active: false },
+        $inc: { seatCount: 50 },
+        $push: { tags: 'combined' },
+      },
+    ).exec()
+
+    const current = await OrganizationModel.findById(org._id).lean().exec()
+    expect(current?.name).toBe('Combined Corp')
+    expect(current?.active).toBe(false)
+    expect(current?.seatCount).toBe(75)
+    expect(current?.tags).toContain('combined')
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths).toContain('/name')
+    expect(paths).toContain('/active')
+    expect(paths).toContain('/seatCount')
+    expect(paths.some((p) => p?.startsWith('/tags'))).toBe(true)
+
+    expect(update?.patch?.find((p) => p.path === '/name' && p.op === 'replace')?.value).toBe('Combined Corp')
+    expect(update?.patch?.find((p) => p.path === '/active' && p.op === 'replace')?.value).toBe(false)
+    expect(update?.patch?.find((p) => p.path === '/seatCount' && p.op === 'replace')?.value).toBe(75)
+  })
+
+  it('$push subdocument into team array — should track nested array addition', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    const newMemberId = new mongoose.Types.ObjectId()
+
+    await OrganizationModel.updateOne({ _id: org._id }, { $push: { team: { userId: newMemberId, role: 'viewer' } } }).exec()
+
+    const [update] = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths.some((p) => p?.startsWith('/team'))).toBe(true)
+  })
+
+  // --- getUser / getReason / getMetadata ---
+
+  it('create history should contain user, reason, and metadata', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    const [entry] = await HistoryModel.find({ collectionId: org._id })
+    expect(entry?.user).toEqual({ userId: 'system', role: 'service-account' })
+    expect(entry?.reason).toBe('api-call')
+    expect(entry?.metadata).toEqual({ service: 'org-service', requestId: 'req-123' })
+  })
+
+  it('update history should contain user, reason, and metadata', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    org.name = 'Updated Corp'
+    await org.save()
+
+    const update = await HistoryModel.findOne({ op: 'update', collectionId: org._id })
+    expect(update?.user).toEqual({ userId: 'system', role: 'service-account' })
+    expect(update?.reason).toBe('api-call')
+    expect(update?.metadata).toEqual({ service: 'org-service', requestId: 'req-123' })
+  })
+
+  it('delete history should contain user, reason, and metadata', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.deleteOne({ _id: org._id }).exec()
+
+    const deletion = await HistoryModel.findOne({ op: 'deleteOne', collectionId: org._id })
+    expect(deletion?.user).toEqual({ userId: 'system', role: 'service-account' })
+    expect(deletion?.reason).toBe('api-call')
+    expect(deletion?.metadata).toEqual({ service: 'org-service', requestId: 'req-123' })
+  })
+
+  it('updateOne history should contain user, reason, and metadata', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { name: 'Query Updated' }).exec()
+
+    const update = await HistoryModel.findOne({ op: 'updateOne', collectionId: org._id })
+    expect(update?.user).toEqual({ userId: 'system', role: 'service-account' })
+    expect(update?.reason).toBe('api-call')
+    expect(update?.metadata).toEqual({ service: 'org-service', requestId: 'req-123' })
+  })
+
+  // --- History record structure ---
+
+  it('create history should contain doc snapshot, no patch array', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    const [entry] = await HistoryModel.find({ collectionId: org._id })
+    expect(entry?.op).toBe('create')
+    expect(entry?.modelName).toBe('Organization')
+    expect(entry?.collectionName).toBe('organizations')
+    expect(entry?.collectionId).toEqual(org._id)
+    expect(entry?.version).toBe(0)
+    expect(entry?.doc).toBeDefined()
+    expect(entry?.patch).toEqual([])
+    expect(entry?.createdAt).toBeDefined()
+    expect(entry?.updatedAt).toBeDefined()
+  })
+
+  it('update history should contain JSON patch, no doc snapshot', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    org.name = 'Changed'
+    await org.save()
+
+    const update = await HistoryModel.findOne({ op: 'update', collectionId: org._id })
+    expect(update?.doc).toBeUndefined()
+    expect(update?.patch).toBeDefined()
+    expect(update?.patch?.length).toBeGreaterThan(0)
+
+    const nameOp = update?.patch?.find((p) => p.path === '/name' && p.op === 'replace')
+    expect(nameOp).toBeDefined()
+    expect(nameOp?.value).toBe('Changed')
+  })
+
+  it('delete history should contain doc snapshot, no patch array', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.deleteOne({ _id: org._id }).exec()
+
+    const deletion = await HistoryModel.findOne({ op: 'deleteOne', collectionId: org._id })
+    expect(deletion?.doc).toBeDefined()
+    expect(deletion?.doc).toHaveProperty('name', 'Acme Corp')
+    expect(deletion?.patch).toEqual([])
+  })
+
+  // --- Event payloads ---
+
+  it('create event should emit with { doc } payload', async () => {
+    await OrganizationModel.create(makeOrg())
+
+    expect(em.emit).toHaveBeenCalledWith(ORG_CREATED, expect.objectContaining({ doc: expect.objectContaining({ name: 'Acme Corp' }) }))
+  })
+
+  it('update event should emit with { doc, oldDoc, patch } payload', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    vi.mocked(em.emit).mockClear()
+
+    org.name = 'New Name'
+    await org.save()
+
+    expect(em.emit).toHaveBeenCalledWith(
+      ORG_UPDATED,
+      expect.objectContaining({
+        oldDoc: expect.objectContaining({ name: 'Acme Corp' }),
+        doc: expect.objectContaining({ name: 'New Name' }),
+        patch: expect.arrayContaining([expect.objectContaining({ path: '/name', op: 'replace', value: 'New Name' })]),
+      }),
+    )
+  })
+
+  it('delete event should emit with { oldDoc } payload', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    vi.mocked(em.emit).mockClear()
+
+    await OrganizationModel.deleteOne({ _id: org._id }).exec()
+
+    expect(em.emit).toHaveBeenCalledWith(ORG_DELETED, expect.objectContaining({ oldDoc: expect.objectContaining({ name: 'Acme Corp' }) }))
+  })
+
+  // --- Omit behavior ---
+
+  it('omitted fields should never appear in create history doc', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    const [entry] = await HistoryModel.find({ collectionId: org._id })
+    expect(entry?.doc).not.toHaveProperty('notes')
+    expect(entry?.doc).not.toHaveProperty('__v')
+    expect(entry?.doc).not.toHaveProperty('createdAt')
+    expect(entry?.doc).not.toHaveProperty('updatedAt')
+  })
+
+  it('omitted fields should never appear in update patch paths', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    org.notes = 'changed internal note'
+    org.name = 'Trigger Real Change'
+    await org.save()
+
+    const update = await HistoryModel.findOne({ op: 'update', collectionId: org._id })
+    const paths = update?.patch?.map((p) => p.path) ?? []
+    expect(paths).toContain('/name')
+    expect(paths.every((p) => !p?.includes('notes'))).toBe(true)
+    expect(paths.every((p) => !p?.includes('__v'))).toBe(true)
+    expect(paths.every((p) => !p?.includes('createdAt'))).toBe(true)
+    expect(paths.every((p) => !p?.includes('updatedAt'))).toBe(true)
+  })
+
+  it('omitted fields should never appear in delete history doc', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.deleteOne({ _id: org._id }).exec()
+
+    const deletion = await HistoryModel.findOne({ op: 'deleteOne', collectionId: org._id })
+    expect(deletion?.doc).not.toHaveProperty('notes')
+    expect(deletion?.doc).not.toHaveProperty('__v')
+    expect(deletion?.doc).not.toHaveProperty('createdAt')
+    expect(deletion?.doc).not.toHaveProperty('updatedAt')
+  })
+
+  // --- Version tracking ---
+
+  it('versions should increment sequentially per document', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    for (let i = 1; i <= 5; i++) {
+      org.seatCount = i * 10
+      await org.save()
+    }
+
+    const history = await HistoryModel.find({ collectionId: org._id }).sort('version')
+    expect(history).toHaveLength(6)
+
+    for (let i = 0; i < 6; i++) {
+      expect(history[i]?.version).toBe(i)
+    }
+  })
+
+  it('versions should be independent per document', async () => {
+    const orgA = await OrganizationModel.create({ ...makeOrg(), slug: `a-${Date.now()}` })
+    const orgB = await OrganizationModel.create({ ...makeOrg(), slug: `b-${Date.now()}` })
+
+    orgA.name = 'A changed'
+    await orgA.save()
+
+    orgB.name = 'B changed'
+    await orgB.save()
+
+    const historyA = await HistoryModel.find({ collectionId: orgA._id }).sort('version')
+    const historyB = await HistoryModel.find({ collectionId: orgB._id }).sort('version')
+
+    expect(historyA[0]?.version).toBe(0)
+    expect(historyA[1]?.version).toBe(1)
+    expect(historyB[0]?.version).toBe(0)
+    expect(historyB[1]?.version).toBe(1)
+  })
+
+  // --- ignoreHook / ignoreEvent / ignorePatchHistory ---
+
+  it('ignoreHook should skip both history and events', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    vi.mocked(em.emit).mockClear()
+
+    await OrganizationModel.updateOne({ _id: org._id }, { name: 'Ignored' }).setOptions({ ignoreHook: true }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(0)
+    expect(em.emit).not.toHaveBeenCalledWith(ORG_UPDATED, expect.anything())
+  })
+
+  it('ignoreEvent should keep history but skip events', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    vi.mocked(em.emit).mockClear()
+
+    await OrganizationModel.updateOne({ _id: org._id }, { name: 'EventSkipped' }).setOptions({ ignoreEvent: true }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(1)
+    expect(em.emit).not.toHaveBeenCalledWith(ORG_UPDATED, expect.anything())
+  })
+
+  it('ignorePatchHistory should skip history but keep events', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+    vi.mocked(em.emit).mockClear()
+
+    await OrganizationModel.updateOne({ _id: org._id }, { name: 'HistorySkipped' }).setOptions({ ignorePatchHistory: true }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(0)
+    expect(em.emit).toHaveBeenCalledWith(ORG_UPDATED, expect.anything())
+  })
+
+  // --- No-op safety ---
+
+  it('update with no actual changes should not produce history', async () => {
+    const org = await OrganizationModel.create(makeOrg())
+
+    await OrganizationModel.updateOne({ _id: org._id }, { name: 'Acme Corp' }).exec()
+
+    const updates = await HistoryModel.find({ op: 'updateOne', collectionId: org._id })
+    expect(updates).toHaveLength(0)
+  })
+
+  it('update targeting non-existent document should not crash or produce history', async () => {
+    const fakeId = new mongoose.Types.ObjectId()
+
+    await OrganizationModel.updateOne({ _id: fakeId }, { name: 'Ghost' }).exec()
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(0)
+  })
+
+  it('delete targeting non-existent document should not crash or produce history', async () => {
+    const fakeId = new mongoose.Types.ObjectId()
+
+    await OrganizationModel.deleteOne({ _id: fakeId }).exec()
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(0)
+  })
+
+  // --- insertMany with user/reason/metadata ---
+
+  it('insertMany should attach user, reason, and metadata to each history record', async () => {
+    await OrganizationModel.insertMany([
+      { ...makeOrg(), slug: `ins-a-${Date.now()}`, name: 'Ins A' },
+      { ...makeOrg(), slug: `ins-b-${Date.now()}`, name: 'Ins B' },
+    ])
+
+    const history = await HistoryModel.find({ op: 'create' }).sort('doc.name')
+    expect(history).toHaveLength(2)
+
+    for (const entry of history) {
+      expect(entry.user).toEqual({ userId: 'system', role: 'service-account' })
+      expect(entry.reason).toBe('api-call')
+      expect(entry.metadata).toEqual({ service: 'org-service', requestId: 'req-123' })
+    }
+  })
+
+  // --- preDelete callback ---
+
+  it('preDelete should receive cloned documents before deletion', async () => {
+    const preDeleteDocs: unknown[][] = []
+
+    const PreDeleteSchema = new Schema<Organization>(
+      {
+        name: { type: String, required: true },
+        slug: { type: String, required: true },
+        apiKey: { type: Schema.Types.UUID, required: true },
+        active: { type: Boolean, default: true },
+        contact: { type: ContactSchema, required: true },
+        seatCount: { type: Number, default: 1 },
+      },
+      { timestamps: true },
+    )
+
+    PreDeleteSchema.plugin(patchHistoryPlugin, {
+      omit: ['__v', 'createdAt', 'updatedAt'],
+      preDelete: async (docs) => {
+        preDeleteDocs.push(docs)
+      },
+    })
+
+    if (mongoose.models.PreDeleteOrg) mongoose.deleteModel('PreDeleteOrg')
+    const PreDeleteModel = model<Organization>('PreDeleteOrg', PreDeleteSchema)
+
+    const org = await PreDeleteModel.create({
+      name: 'Doomed Corp',
+      slug: `doomed-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'bye@doomed.com' },
+    })
+
+    await PreDeleteModel.deleteOne({ _id: org._id }).exec()
+
+    expect(preDeleteDocs).toHaveLength(1)
+    expect(preDeleteDocs[0]).toHaveLength(1)
+    expect(preDeleteDocs[0]?.[0]).toHaveProperty('name', 'Doomed Corp')
+  })
+})
+
+// --- patchHistoryDisabled mode ---
+
+const EventOnlySchema = new Schema<Organization>(
+  {
+    name: { type: String, required: true },
+    slug: { type: String, required: true },
+    apiKey: { type: Schema.Types.UUID, required: true },
+    active: { type: Boolean, default: true },
+    contact: { type: ContactSchema, required: true },
+    seatCount: { type: Number, default: 1 },
+  },
+  { timestamps: true },
+)
+
+const EVENT_ONLY_CREATED = 'event-only-created'
+const EVENT_ONLY_UPDATED = 'event-only-updated'
+const EVENT_ONLY_DELETED = 'event-only-deleted'
+
+EventOnlySchema.plugin(patchHistoryPlugin, {
+  eventCreated: EVENT_ONLY_CREATED,
+  eventUpdated: EVENT_ONLY_UPDATED,
+  eventDeleted: EVENT_ONLY_DELETED,
+  patchHistoryDisabled: true,
+  omit: ['__v', 'createdAt', 'updatedAt'],
+})
+
+const EventOnlyModel = model<Organization>('EventOnlyOrg', EventOnlySchema)
+
+describe('plugin — patchHistoryDisabled (events only, no history)', () => {
+  const instance = server('plugin-events-only')
+
+  beforeAll(async () => {
+    await instance.create()
+  })
+
+  afterAll(async () => {
+    await instance.destroy()
+  })
+
+  beforeEach(async () => {
+    await mongoose.connection.collection('eventonlyorgs').deleteMany({})
+    await mongoose.connection.collection('history').deleteMany({})
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('create should emit event but not write history', async () => {
+    await EventOnlyModel.create({
+      name: 'EventOnly Corp',
+      slug: `eo-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'eo@test.com' },
+    })
+
+    expect(em.emit).toHaveBeenCalledWith(EVENT_ONLY_CREATED, expect.objectContaining({ doc: expect.objectContaining({ name: 'EventOnly Corp' }) }))
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(0)
+  })
+
+  it('update should emit event but not write history', async () => {
+    const org = await EventOnlyModel.create({
+      name: 'EventOnly Corp',
+      slug: `eo-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'eo@test.com' },
+    })
+
+    vi.mocked(em.emit).mockClear()
+
+    org.name = 'Updated EventOnly'
+    await org.save()
+
+    expect(em.emit).toHaveBeenCalledWith(
+      EVENT_ONLY_UPDATED,
+      expect.objectContaining({
+        oldDoc: expect.objectContaining({ name: 'EventOnly Corp' }),
+        doc: expect.objectContaining({ name: 'Updated EventOnly' }),
+        patch: expect.any(Array),
+      }),
+    )
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(0)
+  })
+
+  it('delete should emit event but not write history', async () => {
+    const org = await EventOnlyModel.create({
+      name: 'EventOnly Corp',
+      slug: `eo-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'eo@test.com' },
+    })
+
+    vi.mocked(em.emit).mockClear()
+
+    await EventOnlyModel.deleteOne({ _id: org._id }).exec()
+
+    expect(em.emit).toHaveBeenCalledWith(EVENT_ONLY_DELETED, expect.objectContaining({ oldDoc: expect.objectContaining({ name: 'EventOnly Corp' }) }))
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(0)
+  })
+
+  it('updateOne should emit event but not write history', async () => {
+    const org = await EventOnlyModel.create({
+      name: 'EventOnly Corp',
+      slug: `eo-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'eo@test.com' },
+    })
+
+    vi.mocked(em.emit).mockClear()
+
+    await EventOnlyModel.updateOne({ _id: org._id }, { name: 'Query Updated' }).exec()
+
+    expect(em.emit).toHaveBeenCalledWith(EVENT_ONLY_UPDATED, expect.anything())
+
+    const history = await HistoryModel.find({})
+    expect(history).toHaveLength(0)
+  })
+})
+
+// --- Async getUser/getReason/getMetadata ---
+
+const AsyncCallbackSchema = new Schema<Organization>(
+  {
+    name: { type: String, required: true },
+    slug: { type: String, required: true },
+    apiKey: { type: Schema.Types.UUID, required: true },
+    active: { type: Boolean, default: true },
+    contact: { type: ContactSchema, required: true },
+    seatCount: { type: Number, default: 1 },
+  },
+  { timestamps: true },
+)
+
+AsyncCallbackSchema.plugin(patchHistoryPlugin, {
+  omit: ['__v', 'createdAt', 'updatedAt'],
+  getUser: async () => {
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    return { userId: 'async-user', source: 'http-context' }
+  },
+  getReason: async () => {
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    return 'async-reason'
+  },
+  getMetadata: async () => {
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    return { async: true, timestamp: Date.now() }
+  },
+})
+
+const AsyncCallbackModel = model<Organization>('AsyncCallbackOrg', AsyncCallbackSchema)
+
+describe('plugin — async getUser/getReason/getMetadata', () => {
+  const instance = server('plugin-async-callbacks')
+
+  beforeAll(async () => {
+    await instance.create()
+  })
+
+  afterAll(async () => {
+    await instance.destroy()
+  })
+
+  beforeEach(async () => {
+    await mongoose.connection.collection('asynccallbackorgs').deleteMany({})
+    await mongoose.connection.collection('history').deleteMany({})
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('create should resolve async getUser/getReason/getMetadata', async () => {
+    const org = await AsyncCallbackModel.create({
+      name: 'Async Corp',
+      slug: `async-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'async@test.com' },
+    })
+
+    const [entry] = await HistoryModel.find({ collectionId: org._id })
+    expect(entry?.user).toEqual({ userId: 'async-user', source: 'http-context' })
+    expect(entry?.reason).toBe('async-reason')
+    expect(entry?.metadata).toHaveProperty('async', true)
+    expect(entry?.metadata).toHaveProperty('timestamp')
+  })
+
+  it('update should resolve async callbacks', async () => {
+    const org = await AsyncCallbackModel.create({
+      name: 'Async Corp',
+      slug: `async-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'async@test.com' },
+    })
+
+    org.name = 'Async Updated'
+    await org.save()
+
+    const update = await HistoryModel.findOne({ op: 'update', collectionId: org._id })
+    expect(update?.user).toEqual({ userId: 'async-user', source: 'http-context' })
+    expect(update?.reason).toBe('async-reason')
+    expect(update?.metadata).toHaveProperty('async', true)
+  })
+
+  it('delete should resolve async callbacks', async () => {
+    const org = await AsyncCallbackModel.create({
+      name: 'Async Corp',
+      slug: `async-${Date.now()}`,
+      apiKey: '550e8400-e29b-41d4-a716-446655440000',
+      contact: { email: 'async@test.com' },
+    })
+
+    await AsyncCallbackModel.deleteOne({ _id: org._id }).exec()
+
+    const deletion = await HistoryModel.findOne({ op: 'deleteOne', collectionId: org._id })
+    expect(deletion?.user).toEqual({ userId: 'async-user', source: 'http-context' })
+    expect(deletion?.reason).toBe('async-reason')
+    expect(deletion?.metadata).toHaveProperty('async', true)
+  })
+})